txt/syslinux.txt

   1 = syslinux(1) =
   2 :doctype: manpage
   3 :revdate: 2013-06-12
   4 :author: H. Peter Anvin
   5 :author-email: hpa@zytor.com
   6 :editor1: Gene Cumm
   7 :editor1-email: gene.cumm@gmail.com
   8 :editor1-revlast: 2013-06-12
   9
  10
  11 == NAME ==
  12 syslinux - Install SYSLINUX to a file system
  13
  14
  15 == SYNOPSIS ==
  16 [verse]
  17 *syslinux* ['OPTIONS'] 'DEVICE'
  18 *extlinux* ['OPTIONS'] 'PATH'
  19 *syslinux* [-h | --help | -v | --version]
  20 *extlinux* [-h | --help | -v | --version]
  21
  22
  23 == DESCRIPTION ==
  24 Install *SYSLINUX* to the 'DEVICE'/'PATH', altering the boot sector and
  25 installing the 'ldlinux.sys' boot loader file.  For the Linux installer
  26 extlinux, 'PATH' is the desired path for the control files on a mounted,
  27 supported file system and sets the install-time working directory.  For
  28 all others, 'DEVICE' must specify a FAT12/FAT16/FAT32 file system.  For
  29 the Linux installers syslinux and syslinux-mtools, 'DEVICE' should be an
  30 unmounted file system.  For the DOS/Win32/Win64 installers, 'DEVICE'
  31 should be a drive like 'a:' (case insensitive).
  32
  33 For versions ~4.00 and later, either *-i*/*--install* or *-U*/*--update*
  34 must be specified unless modifying the ADV of an existing install
  35 (options tagged with 'ADV') or requesting the help/usage or version
  36 info.
  37
  38 If, during boot, the Shift or Alt keys are held down, or the Caps or
  39 Scroll locks are set, *Syslinux* will display a *lilo*(8) -style "boot:"
  40 prompt. The user can then type a kernel file name followed by any kernel
  41 parameters. The *Syslinux* bootloader does not need to know about the
  42 kernel or config files in advance.
  43
  44 *Syslinux* supports the loading of initial ramdisks (initrd) and the
  45 bzImage kernel format.
  46
  47 Please note, the ldlinux.sys boot loader file is flagged as immutable
  48 (where applicable) and is modified after copying in to help ensure
  49 boot-time integrity.  File systems with a sufficiently large boot loader
  50 reserved area, like btrfs, will have ldlinux.sys installed there rather
  51 than as a normal file.  Prior to version 4.00, extlinux would install a
  52 file extlinux.sys which versions 4.00 and later installers will replace
  53 with ldlinux.sys.
  54
  55
  56 == OPTIONS ==
  57 // "See"/"See also" notes should reference long options.
  58 === Standalone options ===
  59 *-i*, *--install*::
  60 (~4.00+) Install SYSLINUX, regardless of an existing install.
  61
  62 *-U*, *--update*::
  63 (~4.00+) Update an existing SYSLINUX/EXTLINUX install.  If no Syslinux
  64 boot loader is present, return an error.
  65
  66 *-h*, *--help*::
  67 Display help/usage information.
  68
  69 *-v*, *--version*::
  70 Display version information and exit immediately.
  71
  72 === Regular Options ===
  73 // Sorted generally by short argument
  74 *-a*, *--active*::
  75 (DOS/Win32/Win64 ONLY) Mark the install target file system's partition
  76 active.
  77
  78 *-d*, *--directory* 'subdirectory'::
  79 (Not necessary for extlinux as it is implied by 'PATH') Install the
  80 *SYSLINUX* control files in a subdirectory with the specified name
  81 (relative to the root directory on the device).
  82
  83 *--device* 'DEVICE'::
  84 (extlinux ONLY; 4.06+) Force use of a specific block device (experts
  85 only).
  86
  87 *-f*, *--force*::
  88 Force install even if it appears unsafe.
  89
  90 *-H*, *--heads* 'head-count'::
  91 Override the detected number of heads for the geometry.  See also
  92 *--sector*.
  93
  94 *-m*, *--mbr*:
  95 (DOS/Win32/Win64 ONLY) Install the regular Syslinux MBR code to the MBR.
  96
  97 *-M*, *--menu-save*::
  98 (4.00+; ADV) Set the label to select as default on the next boot.
  99
 100 *--once* 'command'::
 101 (ADV) Declare a boot command to be tried on the first boot only.  The
 102 use of *-o* for the Linux installers syslinux or syslinux-mtools has
 103 been deprecated as of \~4.00 and is no longer valid as of ~4.02.
 104
 105 *-O*, *--clear-once*::
 106 Clear the boot-once command.  See also *--once*.
 107
 108 *-r*, *--raid*::
 109 (ADV) RAID mode.  If boot fails, tell the BIOS to boot the next device
 110 in the boot sequence (usually the next hard disk) instead of stopping
 111 with an error message.  This is useful for RAID-1 booting.
 112
 113 *--reset-adv*::
 114 (ADV) Reset auxiliary data vector.
 115
 116 *-S*, *--sectors* 'sector-count'::
 117 Override the detected number of sectors for the geometry.  See also
 118 *--head*.
 119
 120 *-s*, *--stupid*::
 121 Install a "safe, slow and stupid" version of *SYSLINUX*. This version
 122 may work on some very buggy BIOSes on which *SYSLINUX* would otherwise
 123 fail. If you find a machine on which the *-s* option is required to make
 124 it boot reliably, please send as much info about your machine as you
 125 can, and include the failure mode.
 126
 127 *-t*, *--offset* 'offset'::
 128 (Linux syslinux/syslinux-mtools ONLY) Indicates that the filesystem is
 129 at an offset from the base of the device or file. Some older versions
 130 did not accept the short format, *-t*.
 131
 132 *-z*, *--zipdrive*
 133 Assume zipdrive geometry ('--heads 64 --sectors 32').  See also *--head*
 134 and *--sector*.
 135
 136
 137 == EXAMPLES ==
 138 === Booting DOS ===
 139 For booting DOS and other similar operating systems, there is an easy
 140 and generally reliable solution to substitute in SYSLINUX as the primary
 141 boot loader.
 142
 143 - Make a DOS-bootable disk;  The following are possible commands:
 144
 145         format a: /s
 146         sys a:
 147
 148 - Copy the DOS boot sector off using Linux or copybs.com:
 149
 150         dd if=/dev/fd0 of=dos.bss bs=512 count=1
 151         copybs a: a:dos.bss
 152
 153 - Install SYSLINUX using one of:
 154
 155         syslinux a:
 156         syslinux /dev/fd0               (before 4.00)
 157         syslinux -i /dev/fd0            (4.00+)
 158
 159 - For Linux, mount the disk and copy the dos.bss to the disk:
 160
 161         mount -t msdos /dev/fd0 /mnt
 162         cp dos.bss /mnt
 163
 164 - Copy a Linux kernel image and initrd payload files:
 165 *Linux:*::
 166         cp vmlinux /mnt
 167         cp initrd.gz /mnt
 168 *DOS/Windows:*::
 169         copy vmlinux a:
 170         copy initrd.gz a:
 171
 172 - For Linux, umount the disk (if applicable):
 173
 174         umount /mnt
 175
 176 === MBR ===
 177 In order to boot from a hard disk (or hard disk-like device) in BIOS
 178 mode, an appropriate MBR boot block must also be installed in the MBR
 179 (first sector or 512 bytes of the disk), occupying at most 440 bytes.
 180
 181 *DOS/Windows:*::
 182 If using FDISK, FDISK or a similar application must also be used to mark
 183 the partition as active.
 184 +
 185         fdisk /mbr
 186     OR
 187         syslinux -ma c:
 188
 189 *Linux:*::
 190 +
 191         dd bs=440 count=1 conv=notrunc if=mbr/mbr.bin of=/dev/sda
 192 +
 193 For altmbr.bin, an easy way to overwrite the MBR boot block and specify
 194 the partion number is:
 195 +
 196   printf '\1' | cat altmbr.bin - | dd bs=440 count=1 \
 197     iflag=fullblock conv=notrunc of=/dev/sda
 198 +
 199 Note: using 'cat' for writing the MBR can under some circumstances cause
 200 data loss or overwriting.  For this reason, using 'dd' is recommended
 201 for all situations.
 202
 203 //[FIXME]: any clean way to handle the above long command for manpage?
 204
 205
 206 == SEE ALSO ==
 207 *syslinux.cfg*(5), *syslinux-cli*(1), *lilo*(8), *keytab-lilo.pl*(8),
 208 *fdisk*(8), *mkfs*(8), *superformat*(1).
 209
 210
 211 == AUTHOR ==
 212 This AsciiDoc derived document is a modified version of the original
 213 *SYSLINUX* documentation by {author} <{author-email}>. The conversion to
 214 a manpage was made by Arthur Korn <arthur@korn.ch>.  The conversion to
 215 an AsciiDoc was made by {editor1} <{editor1-email}>
 216
 217
 218 == COPYRIGHT ==
 219 Copyright \(C) 1994-2012 {author}. Free use of this software is granted
 220 under the terms of the GNU General Public License (GPL), version 2
 221 (GPLv2) (or, at your option, any later version).