txt/syslinux.txt

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