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