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