doc/syslinux.txt

   1                          The Syslinux Project
   2
   3                    A suite of bootloaders for Linux
   4
   5          Copyright 1994-2011 H. Peter Anvin and contributors
   6
   7 This program is provided under the terms of the GNU General Public
   8 License, version 2 or, at your option, any later version.  There is no
   9 warranty, neither expressed nor implied, to the function of this
  10 program.  Please see the included file COPYING for details.
  11
  12 ----------------------------------------------------------------------
  13
  14       Syslinux now has a home page at http://syslinux.zytor.com/
  15
  16 ----------------------------------------------------------------------
  17
  18 The Syslinux suite contains the following boot loaders
  19 ("derivatives"), for their respective boot media:
  20
  21         SYSLINUX - MS-DOS/Windows FAT filesystem
  22         PXELINUX - PXE network booting
  23         ISOLINUX - ISO9660 CD-ROM
  24         EXTLINUX - Linux ext2/ext3 filesystem
  25
  26 For historical reasons, some of the sections in this document applies
  27 to the FAT loader (SYSLINUX) only; see pxelinux.txt, isolinux.txt and
  28 extlinux.txt for what differs in these versions.  The all-caps term
  29 "SYSLINUX" generally refers to the FAT loader, whereas "Syslinux"
  30 refers to the project as a whole.
  31
  32 Help with cleaning up the docs would be greatly appreciated.
  33
  34
  35    ++++ Options ++++
  36
  37 These are the options common to all versions of Syslinux:
  38
  39         -s      Safe, slow, stupid; uses simpler code that boots better
  40         -f      Force installing
  41         -r      Raid mode.  If boot fails, tell the BIOS to boot the next
  42                 device in the boot sequence (usually the next hard disk)
  43                 instead of stopping with an error message.
  44                 This is useful for RAID-1 booting.
  45
  46 These are only in the Windows version:
  47
  48         -m      Mbr; install a bootable MBR sector to the beginning of the
  49                 drive.
  50         -a      Active; marks the partition used active (=bootable)
  51
  52
  53    ++++ CREATING A BOOTABLE LINUX FLOPPY +++
  54
  55 In order to create a bootable Linux floppy using SYSLINUX, prepare a
  56 normal MS-DOS formatted floppy.  Copy one or more Linux kernel files to
  57 it, then execute the DOS command:
  58
  59         syslinux [-sfrma][-d directory] a: [bootsecfile]
  60
  61 (or whichever drive letter is appropriate; the [] meaning optional.)
  62
  63 Use "syslinux.com" (in the dos subdirectory of the distribution) for
  64 plain DOS (MS-DOS, DR-DOS, PC-DOS, FreeDOS...) or Win9x/ME.
  65
  66 Use "syslinux.exe" (in the win32 subdirectory of the distribution) for
  67 WinNT/2000/XP.
  68
  69 Under Linux, execute the command:
  70
  71         syslinux [-sfr][-d directory][-o offset] /dev/fd0
  72
  73 (or, again, whichever device is the correct one.)
  74
  75 This will alter the boot sector on the disk and copy a file named
  76 LDLINUX.SYS into its root directory (or a subdirectory, if the -d
  77 option is specified.)
  78
  79 The -s option, if given, will install a "safe, slow and stupid"
  80 version of SYSLINUX.  This version may work on some very buggy BIOSes
  81 on which SYSLINUX would otherwise fail.  If you find a machine on
  82 which the -s option is required to make it boot reliably, please send
  83 as much info about your machine as you can, and include the failure
  84 mode.
  85
  86 The -o option is used with a disk image file and specifies the byte
  87 offset of the filesystem image in the file.
  88
  89 For the DOS and Windows installers, the -m and -a options can be used
  90 on hard drives to write a Master Boot Record (MBR), and to mark the
  91 specific partition active.
  92
  93 If the Shift or Alt keys are held down during boot, or the Caps or Scroll
  94 locks are set, Syslinux will display a LILO-style "boot:" prompt.  The
  95 user can then type a kernel file name followed by any kernel parameters.
  96 The Syslinux loader does not need to know about the kernel file in
  97 advance; all that is required is that it is a file located in the root
  98 directory on the disk.
  99
 100 There are two versions of the Linux installer; one in the "mtools"
 101 directory which requires no special privilege (other than write
 102 permission to the device where you are installing) but requires the
 103 mtools program suite to be available, and one in the "unix" directory
 104 which requires root privilege.
 105
 106
 107    ++++ CONFIGURATION FILE ++++
 108
 109 All options here apply to PXELINUX, ISOLINUX and EXTLINUX as well as
 110 SYSLINUX unless otherwise noted.  See the respective .txt files.
 111
 112 All the configurable defaults in SYSLINUX can be changed by putting a
 113 file called "syslinux.cfg" in the root directory of the boot disk.
 114
 115 Starting with version 3.35, the configuration file can also be in
 116 either the /boot/syslinux or /syslinux directories (searched in that
 117 order.)  If that is the case, then all filenames are assumed to be
 118 relative to that same directory, unless preceded with a slash or
 119 backslash.
 120
 121 The configuration file is a text file in either UNIX or DOS format,
 122 containing one or more of the following items, each on its own line with
 123 optional leading whitespace.  Case is insensitive for keywords; upper
 124 case is used here to indicate that a word should be typed verbatim.
 125
 126 #comment
 127         A comment line.
 128
 129 INCLUDE filename
 130         Inserts the contents of another file at this point in the
 131         configuration file. Files can currently be nested up to 16
 132         levels deep, but it is not guaranteed that more than 8 levels
 133         will be supported in the future.
 134
 135 DEFAULT kernel options...
 136         Sets the default command line.  If Syslinux boots automatically,
 137         it will act just as if the entries after DEFAULT had been typed
 138         in at the "boot:" prompt.
 139
 140         If no configuration file is present, or no DEFAULT entry is
 141         present in the config file, an error message is displayed and
 142         the boot: prompt is shown.
 143
 144 UI module options...
 145         Selects a specific user interface module (typically menu.c32
 146         or vesamenu.c32).  The command-line interface treats this as a
 147         directive that overrides the DEFAULT and PROMPT directives.
 148
 149 APPEND options...
 150         Add one or more options to the kernel command line.  These are
 151         added both for automatic and manual boots.  The options are
 152         added at the very beginning of the kernel command line,
 153         usually permitting explicitly entered kernel options to override
 154         them.  This is the equivalent of the LILO "append" option.
 155
 156 IPAPPEND flag_val                       [PXELINUX only]
 157         The IPAPPEND option is available only on PXELINUX.  The
 158         flag_val is an OR of the following options:
 159
 160         1: indicates that an option of the following format
 161         should be generated and added to the kernel command line:
 162
 163                 ip=<client-ip>:<boot-server-ip>:<gw-ip>:<netmask>
 164
 165         ... based on the input from the DHCP/BOOTP or PXE boot server.
 166
 167         NOTE: The use of this option is no substitute for running a
 168         DHCP client in the booted system.  Without regular renewals,
 169         the lease acquired by the PXE BIOS will expire, making the
 170         IP address available for reuse by the DHCP server.
 171
 172         2: indicates that an option of the following format
 173         should be generated and added to the kernel command line:
 174
 175                 BOOTIF=<hardware-address-of-boot-interface>
 176
 177         ... in dash-separated hexadecimal with leading hardware type
 178         (same as for the configuration file; see pxelinux.txt.)
 179
 180         This allows an initrd program to determine from which
 181         interface the system booted.
 182
 183         4: indicates that an option of the following format
 184         should be generated and added to the kernel command line:
 185
 186                 SYSUUID=<system uuid>
 187
 188         ... in lower case hexadecimal in the format normally used for
 189         UUIDs (same as for the configuration file; see pxelinux.txt.)
 190
 191 LABEL label
 192     KERNEL image
 193     APPEND options...
 194     IPAPPEND flag_val                   [PXELINUX only]
 195         Indicates that if "label" is entered as the kernel to boot,
 196         Syslinux should instead boot "image", and the specified APPEND
 197         and IPAPPEND options should be used instead of the ones
 198         specified in the global section of the file (before the first
 199         LABEL command.)  The default for "image" is the same as
 200         "label", and if no APPEND is given the default is to use the
 201         global entry (if any).
 202
 203         Starting with version 3.62, the number of LABEL statements is
 204         virtually unlimited.
 205
 206         Note that LILO uses the syntax:
 207         image = mykernel
 208           label = mylabel
 209           append = "myoptions"
 210
 211         ... whereas Syslinux uses the syntax:
 212         label mylabel
 213           kernel mykernel
 214           append myoptions
 215
 216         Note: The "kernel" doesn't have to be a Linux kernel; it can
 217               be a boot sector or a COMBOOT file (see below.)
 218
 219         Since version 3.32 label names are no longer mangled into DOS
 220         format (for SYSLINUX.)
 221
 222     The following commands are available after a LABEL statement:
 223
 224     LINUX image                 - Linux kernel image (default)
 225     BOOT image                  - Bootstrap program (.bs, .bin)
 226     BSS image                   - BSS image (.bss)
 227     PXE image                   - PXE Network Bootstrap Program (.0)
 228     FDIMAGE image               - Floppy disk image (.img)
 229     COMBOOT image               - COMBOOT program (.com, .cbt)
 230     COM32 image                 - COM32 program (.c32)
 231     CONFIG image                - New configuration file
 232         Using one of these keywords instead of KERNEL forces the
 233         filetype, regardless of the filename.
 234
 235         CONFIG means restart the boot loader using a different
 236         configuration file.  The configuration file is read, the
 237         working directory is changed (if specified via an APPEND), then
 238         the configuration file is parsed.
 239
 240     APPEND -
 241         Append nothing.  APPEND with a single hyphen as argument in a
 242         LABEL section can be used to override a global APPEND.
 243
 244     LOCALBOOT type
 245         Attempt a different local boot method.  The special value -1
 246         causes the boot loader to report failure to the BIOS, which, on
 247         recent BIOSes, should mean that the next boot device in the
 248         boot sequence should be activated.  Values other than those
 249         documented may produce undesired results.
 250
 251         On PXELINUX, "type" 0 means perform a normal boot.  "type" 4
 252         will perform a local boot with the Universal Network Driver
 253         Interface (UNDI) driver still resident in memory.  Finally,
 254         "type" 5 will perform a local boot with the entire PXE
 255         stack, including the UNDI driver, still resident in memory.
 256         All other values are undefined.  If you don't know what the
 257         UNDI or PXE stacks are, don't worry -- you don't want them,
 258         just specify 0.
 259
 260         On ISOLINUX, the "type" specifies the local drive number to
 261         boot from; 0x00 is the primary floppy drive and 0x80 is the
 262         primary hard drive.
 263
 264     INITRD initrd_file
 265         Starting with version 3.71, an initrd can be specified in a
 266         separate statement (INITRD) instead of as part of the APPEND
 267         statement; this functionally appends "initrd=initrd_file" to
 268         the kernel command line.
 269
 270         It supports multiple filenames separated by commas.
 271         This is mostly useful for initramfs, which can be composed of
 272         multiple separate cpio or cpio.gz archives.
 273         Note: all files except the last one are zero-padded to a
 274         4K page boundary.  This should not affect initramfs.
 275
 276 IMPLICIT flag_val
 277         If flag_val is 0, do not load a kernel image unless it has been
 278         explicitly named in a LABEL statement.  The default is 1.
 279
 280 ALLOWOPTIONS flag_val
 281         If flag_val is 0, the user is not allowed to specify any
 282         arguments on the kernel command line.  The only options
 283         recognized are those specified in an APPEND statement.  The
 284         default is 1.
 285
 286 TIMEOUT timeout
 287         Indicates how long to wait at the boot: prompt until booting
 288         automatically, in units of 1/10 s.  The timeout is cancelled as
 289         soon as the user types anything on the keyboard, the assumption
 290         being that the user will complete the command line already
 291         begun.  A timeout of zero will disable the timeout completely,
 292         this is also the default.
 293
 294 TOTALTIMEOUT timeout
 295         Indicates how long to wait until booting automatically, in
 296         units of 1/10 s.  This timeout is *not* cancelled by user
 297         input, and can thus be used to deal with serial port glitches
 298         or "the user walked away" type situations.  A timeout of zero
 299         will disable the timeout completely, this is also the default.
 300
 301         Both TIMEOUT and TOTALTIMEOUT can be used together, for
 302         example:
 303
 304                 # Wait 5 seconds unless the user types something, but
 305                 # always boot after 15 minutes.
 306                 TIMEOUT 50
 307                 TOTALTIMEOUT 9000
 308
 309 ONTIMEOUT kernel options...
 310         Sets the command line invoked on a timeout.  Normally this is
 311         the same thing as invoked by "DEFAULT".  If this is specified,
 312         then "DEFAULT" is used only if the user presses <Enter> to
 313         boot.
 314
 315 ONERROR kernel options...
 316         If a kernel image is not found (either due to it not existing,
 317         or because IMPLICIT is set), run the specified command.  The
 318         faulty command line is appended to the specified options, so
 319         if the ONERROR directive reads as:
 320
 321                 ONERROR xyzzy plugh
 322
 323         ... and the command line as entered by the user is:
 324
 325                 foo bar baz
 326
 327         ... Syslinux will execute the following as if entered by the
 328         user:
 329
 330                 xyzzy plugh foo bar baz
 331
 332 SERIAL port [[baudrate] flowcontrol]
 333         Enables a serial port to act as the console.  "port" is a
 334         number (0 = /dev/ttyS0 = COM1, etc.) or an I/O port address
 335         (e.g. 0x3F8); if "baudrate" is omitted, the baud rate defaults
 336         to 9600 bps.  The serial parameters are hardcoded to be 8
 337         bits, no parity, 1 stop bit.
 338
 339         "flowcontrol" is a combination of the following bits:
 340         0x001 - Assert DTR
 341         0x002 - Assert RTS
 342         0x008 - Enable interrupts
 343         0x010 - Wait for CTS assertion
 344         0x020 - Wait for DSR assertion
 345         0x040 - Wait for RI assertion
 346         0x080 - Wait for DCD assertion
 347         0x100 - Ignore input unless CTS asserted
 348         0x200 - Ignore input unless DSR asserted
 349         0x400 - Ignore input unless RI asserted
 350         0x800 - Ignore input unless DCD asserted
 351
 352         All other bits are reserved.
 353
 354         Typical values are:
 355
 356             0 - No flow control (default)
 357         0x303 - Null modem cable detect
 358         0x013 - RTS/CTS flow control
 359         0x813 - RTS/CTS flow control, modem input
 360         0x023 - DTR/DSR flow control
 361         0x083 - DTR/DCD flow control
 362
 363         For the SERIAL directive to be guaranteed to work properly, it
 364         should be the first directive in the configuration file.
 365
 366         NOTE: "port" values from 0 to 3 means the first four serial
 367         ports detected by the BIOS.  They may or may not correspond to
 368         the legacy port values 0x3F8, 0x2F8, 0x3E8, 0x2E8.
 369
 370         Enabling interrupts (setting the 0x008 bit) may give better
 371         responsiveness without setting the NOHALT option, but could
 372         potentially cause problems with buggy BIOSes.
 373
 374 NOHALT flag_val
 375         If flag_val is 1, don't halt the processor while idle.
 376         Halting the processor while idle significantly reduces the
 377         power consumption, but can cause poor responsiveness to the
 378         serial console, especially when using scripts to drive the
 379         serial console, as opposed to human interaction.
 380
 381 CONSOLE flag_val
 382         If flag_val is 0, disable output to the normal video console.
 383         If flag_val is 1, enable output to the video console (this is
 384         the default.)
 385
 386         Some BIOSes try to forward this to the serial console and
 387         sometimes make a total mess thereof, so this option lets you
 388         disable the video console on these systems.
 389
 390 FONT filename
 391         Load a font in .psf format before displaying any output
 392         (except the copyright line, which is output as ldlinux.sys
 393         itself is loaded.)  Syslinux only loads the font onto the
 394         video card; if the .psf file contains a Unicode table it is
 395         ignored.  This only works on EGA and VGA cards; hopefully it
 396         should do nothing on others.
 397
 398 KBDMAP keymap
 399         Install a simple keyboard map.  The keyboard remapper used is
 400         *very* simplistic (it simply remaps the keycodes received from
 401         the BIOS, which means that only the key combinations relevant
 402         in the default layout -- usually U.S. English -- can be
 403         mapped) but should at least help people with AZERTY keyboard
 404         layout and the locations of = and , (two special characters
 405         used heavily on the Linux kernel command line.)
 406
 407         The included program keytab-lilo.pl from the LILO distribution
 408         can be used to create such keymaps.  The file keytab-lilo.txt
 409         contains the documentation for this program.
 410
 411 DISPLAY filename
 412         Displays the indicated file on the screen at boot time (before
 413         the boot: prompt, if displayed).  Please see the section below
 414         on DISPLAY files.
 415
 416         NOTE: If the file is missing, this option is simply ignored.
 417
 418 SAY message
 419         Prints the message on the screen.
 420
 421 PROMPT flag_val
 422         If flag_val is 0, display the boot: prompt only if the Shift or Alt
 423         key is pressed, or Caps Lock or Scroll lock is set (this is the
 424         default).  If flag_val is 1, always display the boot: prompt.
 425
 426 NOESCAPE flag_val
 427         If flag_val is set to 1, ignore the Shift/Alt/Caps Lock/Scroll
 428         Lock escapes.  Use this (together with PROMPT 0) to force the
 429         default boot alternative.
 430
 431 NOCOMPLETE flag_val
 432         If flag_val is set to 1, the Tab key does not display labels
 433         at the boot: prompt.
 434
 435 F1 filename
 436 F2 filename
 437    ...etc...
 438 F9 filename
 439 F10 filename
 440 F11 filename
 441 F12 filename
 442         Displays the indicated file on the screen when a function key is
 443         pressed at the boot: prompt.  This can be used to implement
 444         pre-boot online help (presumably for the kernel command line
 445         options.)  Please see the section below on DISPLAY files.
 446
 447         When using the serial console, press <Ctrl-F><digit> to get to
 448         the help screens, e.g. <Ctrl-F><2> to get to the F2 screen.
 449         For F10-F12, hit <Ctrl-F><A>, <Ctrl-F>B, <Ctrl-F>C.  For
 450         compatibility with earlier versions, F10 can also be entered as
 451         <Ctrl-F>0.
 452
 453 Blank lines are ignored.
 454
 455 Note that the configuration file is not completely decoded.  Syntax
 456 different from the one described above may still work correctly in this
 457 version of Syslinux, but may break in a future one.
 458
 459
 460    ++++ DISPLAY FILE FORMAT ++++
 461
 462 DISPLAY and function-key help files are text files in either DOS or UNIX
 463 format (with or without <CR>).  In addition, the following special codes
 464 are interpreted:
 465
 466 <FF>                                    <FF> = <Ctrl-L> = ASCII 12
 467         Clear the screen, home the cursor.  Note that the screen is
 468         filled with the current display color.
 469
 470 <SI><bg><fg>                            <SI> = <Ctrl-O> = ASCII 15
 471         Set the display colors to the specified background and
 472         foreground colors, where <bg> and <fg> are hex digits,
 473         corresponding to the standard PC display attributes:
 474
 475         0 = black               8 = dark grey
 476         1 = dark blue           9 = bright blue
 477         2 = dark green          a = bright green
 478         3 = dark cyan           b = bright cyan
 479         4 = dark red            c = bright red
 480         5 = dark purple         d = bright purple
 481         6 = brown               e = yellow
 482         7 = light grey          f = white
 483
 484         Picking a bright color (8-f) for the background results in the
 485         corresponding dark color (0-7), with the foreground flashing.
 486
 487         Colors are not visible over the serial console.
 488
 489 <CAN>filename<newline>                  <CAN> = <Ctrl-X> = ASCII 24
 490         If a VGA display is present, enter graphics mode and display
 491         the graphic included in the specified file.  The file format
 492         is an ad hoc format called LSS16; the included Perl program
 493         "ppmtolss16" can be used to produce these images.  This Perl
 494         program also includes the file format specification.
 495
 496         The image is displayed in 640x480 16-color mode.  Once in
 497         graphics mode, the display attributes (set by <SI> code
 498         sequences) work slightly differently: the background color is
 499         ignored, and the foreground colors are the 16 colors specified
 500         in the image file.  For that reason, ppmtolss16 allows you to
 501         specify that certain colors should be assigned to specific
 502         color indicies.
 503
 504         Color indicies 0 and 7, in particular, should be chosen with
 505         care: 0 is the background color, and 7 is the color used for
 506         the text printed by Syslinux itself.
 507
 508 <EM>                                    <EM> = <Ctrl-Y> = ASCII 25
 509         If we are currently in graphics mode, return to text mode.
 510
 511 <DLE>..<ETB>                            <Ctrl-P>..<Ctrl-W> = ASCII 16-23
 512         These codes can be used to select which modes to print a
 513         certain part of the message file in.  Each of these control
 514         characters select a specific set of modes (text screen,
 515         graphics screen, serial port) for which the output is actually
 516         displayed:
 517
 518         Character                       Text    Graph   Serial
 519         ------------------------------------------------------
 520         <DLE> = <Ctrl-P> = ASCII 16     No      No      No
 521         <DC1> = <Ctrl-Q> = ASCII 17     Yes     No      No
 522         <DC2> = <Ctrl-R> = ASCII 18     No      Yes     No
 523         <DC3> = <Ctrl-S> = ASCII 19     Yes     Yes     No
 524         <DC4> = <Ctrl-T> = ASCII 20     No      No      Yes
 525         <NAK> = <Ctrl-U> = ASCII 21     Yes     No      Yes
 526         <SYN> = <Ctrl-V> = ASCII 22     No      Yes     Yes
 527         <ETB> = <Ctrl-W> = ASCII 23     Yes     Yes     Yes
 528
 529         For example:
 530
 531         <DC1>Text mode<DC2>Graphics mode<DC4>Serial port<ETB>
 532
 533         ... will actually print out which mode the console is in!
 534
 535 <SUB>                                   <SUB> = <Ctrl-Z> = ASCII 26
 536         End of file (DOS convention).
 537
 538 <BEL>                                   <BEL> = <Ctrl-G> = ASCII 7
 539         Beep the speaker.
 540
 541
 542    ++++ COMMAND LINE KEYSTROKES ++++
 543
 544 The command line prompt supports the following keystrokes:
 545
 546 <Enter>         boot specified command line
 547 <BackSpace>     erase one character
 548 <Ctrl-U>        erase the whole line
 549 <Ctrl-V>        display the current Syslinux version
 550 <Ctrl-W>        erase one word
 551 <Ctrl-X>        force text mode
 552 <Tab>           list matching labels
 553 <F1>..<F12>     help screens (if configured)
 554 <Ctrl-F><digit> equivalent to F1..F10
 555 <Ctrl-C>        interrupt boot in progress
 556 <Esc>           interrupt boot in progress
 557 <Ctrl-N>        display network information (PXELINUX only)
 558
 559
 560    ++++ COMBOOT IMAGES AND OTHER OPERATING SYSTEMS ++++
 561
 562 This version of Syslinux supports chain loading of other operating
 563 systems (such as MS-DOS and its derivatives, including Windows 95/98),
 564 as well as COMBOOT-style standalone executables (a subset of DOS .COM
 565 files; see separate section below.)
 566
 567 Chain loading requires the boot sector of the foreign operating system
 568 to be stored in a file in the root directory of the filesystem.
 569 Because neither Linux kernels, boot sector images, nor COMBOOT files
 570 have reliable magic numbers, Syslinux will look at the file extension.
 571 The following extensions are recognized (case insensitive):
 572
 573   none or other Linux kernel image
 574   .0            PXE bootstrap program (NBP) [PXELINUX only]
 575   .bin          "CD boot sector" [ISOLINUX only]
 576   .bs           Boot sector [SYSLINUX only]
 577   .bss          Boot sector, DOS superblock will be patched in [SYSLINUX only]
 578   .c32          COM32 image (32-bit COMBOOT)
 579   .cbt          COMBOOT image (not runnable from DOS)
 580   .com          COMBOOT image (runnable from DOS)
 581   .img          Disk image [ISOLINUX only]
 582
 583 For filenames given on the command line, Syslinux will search for the
 584 file by adding extensions in the order listed above if the plain
 585 filename is not found.  Filenames in KERNEL statements must be fully
 586 qualified.
 587
 588 If this is specified with one of the keywords LINUX, BOOT, BSS,
 589 FDIMAGE, COMBOOT, COM32, or CONFIG instead of KERNEL, the filetype is
 590 considered to be the one specified regardless of the filename.
 591
 592
 593       ++++ BOOTING DOS (OR OTHER SIMILAR OPERATING SYSTEMS) ++++
 594
 595 This section applies to SYSLINUX only, not to PXELINUX or ISOLINUX.
 596 See isolinux.txt for an equivalent procedure for ISOLINUX.
 597
 598 This is the recommended procedure for creating a SYSLINUX disk that
 599 can boot either DOS or Linux.  This example assumes the drive is A: in
 600 DOS and /dev/fd0 in Linux; for other drives, substitute the
 601 appropriate drive designator.
 602
 603    ---- Linux procedure ----
 604
 605 1. Make a DOS bootable disk.  This can be done either by specifying
 606    the /s option when formatting the disk in DOS, or by running the
 607    DOS command SYS (this can be done under DOSEMU if DOSEMU has
 608    direct device access to the relevant drive):
 609
 610         format a: /s
 611    or
 612         sys a:
 613
 614 2. Boot Linux.  Copy the DOS boot sector from the disk into a file:
 615
 616         dd if=/dev/fd0 of=dos.bss bs=512 count=1
 617
 618 3. Run SYSLINUX on the disk:
 619
 620         syslinux /dev/fd0
 621
 622 4. Mount the disk and copy the DOS boot sector file to it.  The file
 623    *must* have extension .bss:
 624
 625         mount -t msdos /dev/fd0 /mnt
 626         cp dos.bss /mnt
 627
 628 5. Copy the Linux kernel image(s), initrd(s), etc to the disk, and
 629    create/edit syslinux.cfg and help files if desired:
 630
 631         cp vmlinux /mnt
 632         cp initrd.gz /mnt
 633
 634 6. Unmount the disk (if applicable.)
 635
 636         umount /mnt
 637
 638    ---- DOS/Windows procedure ----
 639
 640 To make this installation in DOS only, you need the utility copybs.com
 641 (included with Syslinux) as well as the syslinux.com installer.  If
 642 you are on an WinNT-based system (WinNT, Win2k, WinXP or later), use
 643 syslinux.exe instead.
 644
 645 1. Make a DOS bootable disk.  This can be done either by specifying
 646    the /s option when formatting the disk in DOS, or by running the
 647    DOS command SYS:
 648
 649         format a: /s
 650    or
 651         sys a:
 652
 653 2. Copy the DOS boot sector from the disk into a file.  The file
 654    *must* have extension .bss:
 655
 656         copybs a: a:dos.bss
 657
 658 3. Run SYSLINUX on the disk:
 659
 660         syslinux a:
 661
 662 4. Copy the Linux kernel image(s), initrd(s), etc to the disk, and
 663    create/edit syslinux.cfg and help files if desired:
 664
 665         copy vmlinux a:
 666         copy initrd.gz a:
 667
 668
 669    ++++ COMBOOT EXECUTABLES ++++
 670
 671 Syslinux supports simple standalone programs, using a file format
 672 similar to DOS ".com" files.  A 32-bit version, called COM32, is also
 673 provided.  A simple API provides access to a limited set of filesystem
 674 and console functions.
 675
 676 See the file comboot.txt for more information on COMBOOT and COM32
 677 programs.
 678
 679
 680    ++++ NOVICE PROTECTION ++++
 681
 682 Syslinux will attempt to detect booting on a machine with too little
 683 memory, which means the Linux boot sequence cannot complete.  If so, a
 684 message is displayed and the boot sequence aborted.  Holding down the
 685 Ctrl key while booting disables this feature.
 686
 687 Any file that SYSLINUX uses can be marked hidden, system or readonly
 688 if so is convenient; SYSLINUX ignores all file attributes.  The
 689 SYSLINUX installed automatically sets the readonly/hidden/system
 690 attributes on LDLINUX.SYS.
 691
 692
 693    ++++ NOTES ON BOOTABLE CD-ROMS ++++
 694
 695 SYSLINUX can be used to create bootdisk images for El
 696 Torito-compatible bootable CD-ROMs.  However, it appears that many
 697 BIOSes are very buggy when it comes to booting CD-ROMs.  Some users
 698 have reported that the following steps are helpful in making a CD-ROM
 699 that is bootable on the largest possible number of machines:
 700
 701         a) Use the -s (safe, slow and stupid) option to SYSLINUX;
 702         b) Put the boot image as close to the beginning of the
 703            ISO 9660 filesystem as possible.
 704
 705 A CD-ROM is so much faster than a floppy that the -s option shouldn't
 706 matter from a speed perspective.
 707
 708 Of course, you probably want to use ISOLINUX instead.  See isolinux.txt.
 709
 710
 711    ++++ BOOTING FROM A FAT FILESYSTEM PARTITION ON A HARD DISK ++++
 712
 713 SYSLINUX can boot from a FAT filesystem partition on a hard disk
 714 (including FAT32).  The installation procedure is identical to the
 715 procedure for installing it on a floppy, and should work under either
 716 DOS or Linux.  To boot from a partition, SYSLINUX needs to be launched
 717 from a Master Boot Record or another boot loader, just like DOS itself
 718 would.
 719
 720 Under DOS, you can install a standard simple MBR on the primary hard
 721 disk by running the command:
 722
 723         FDISK /MBR
 724
 725 Then use the FDISK command to mark the appropriate partition active.
 726
 727 A simple MBR, roughly on par with the one installed by DOS (but
 728 unencumbered), is included in the SYSLINUX distribution.  To install
 729 it under Linux, simply type:
 730
 731         cat mbr.bin > /dev/XXX
 732
 733 ... where /dev/XXX is the device you wish to install it on.
 734
 735 Under DOS or Win32, you can install the SYSLINUX MBR with the -m
 736 option to the SYSLINUX installer, and use the -a option to mark the
 737 current partition active:
 738
 739         syslinux -ma c:
 740
 741 Note that this will also install SYSLINUX on the specified partition.
 742
 743
 744    ++++ HARDWARE INFORMATION +++
 745
 746 I have started to maintain a web page of hardware with known
 747 problems.  There are, unfortunately, lots of broken hardware out
 748 there; especially early PXE stacks (for PXELINUX) have lots of
 749 problems.
 750
 751 A list of problems, and workarounds (if known), is maintained at:
 752
 753         http://syslinux.zytor.com/hardware.php
 754
 755
 756    ++++ BOOT LOADER IDS USED ++++
 757
 758 The Linux boot protocol supports a "boot loader ID", a single byte
 759 where the upper nybble specifies a boot loader family (3 = Syslinux)
 760 and the lower nybble is version or, in the case of Syslinux, media:
 761
 762         0x31 (49) = SYSLINUX
 763         0x32 (50) = PXELINUX
 764         0x33 (51) = ISOLINUX
 765         0x34 (52) = EXTLINUX
 766
 767 In recent versions of Linux, this ID is available as
 768 /proc/sys/kernel/bootloader_type.
 769
 770
 771    ++++ BUG REPORTS ++++
 772
 773 I would appreciate hearing of any problems you have with Syslinux.  I
 774 would also like to hear from you if you have successfully used Syslinux,
 775 *especially* if you are using it for a distribution.
 776
 777 If you are reporting problems, please include all possible information
 778 about your system and your BIOS; the vast majority of all problems
 779 reported turn out to be BIOS or hardware bugs, and I need as much
 780 information as possible in order to diagnose the problems.
 781
 782 There is a mailing list for discussion among Syslinux users and for
 783 announcements of new and test versions.  To join, or to browse the
 784 archive, go to:
 785
 786    http://www.zytor.com/mailman/listinfo/syslinux
 787
 788 Please DO NOT send HTML messages or attachments to the mailing list
 789 (including multipart/alternative or similar.)  All such messages will
 790 be bounced.