| SYSLINUX |
| Version 1.48 |
| September 26, 1999 |
| |
| A bootloader for Linux using MS-DOS floppies |
| |
| Copyright (C) 1994-1999 H. Peter Anvin |
| |
| This program is provided under the terms of the GNU General Public |
| License, version 2 or, at your option, any later version. There is no |
| warranty, neither expressed nor implied, to the function of this |
| program. Please see the included file COPYING for details. |
| |
| ---------------------------------------------------------------------- |
| |
| SYSLINUX is a boot loader for the Linux operating system which |
| operates off an MS-DOS/Windows FAT filesystem. It is intended to |
| simplify first-time installation of Linux, and for creation of rescue- |
| and other special-purpose boot disks. |
| |
| SYSLINUX can be used, when properly set up, completely eliminate the |
| need for distribution of raw diskette images for boot floppies. A |
| SYSLINUX floppy can be manipulated using standard MS-DOS (or any other |
| OS that can access an MS-DOS filesystem) tools once it has been |
| created. |
| |
| |
| ++++ WHAT SYSLINUX IS NOT ++++ |
| |
| SYSLINUX is probably not suitable as a general purpose boot loader. |
| It can only boot Linux from a FAT filesystem, and not, for example, |
| ext2. Since a native Linux implementation will typically use ext2, |
| another boot loader (e.g. LILO) is probably more suitable. In a |
| system which actually contains DOS or Windows, LOADLIN may be simpler |
| to use. |
| |
| However, SYSLINUX has shown itself to be quite useful in a number of |
| special-purpose applications. |
| |
| |
| ++++ CREATING A BOOTABLE LINUX FLOPPY +++ |
| |
| In order to create a bootable Linux floppy using SYSLINUX, prepare a |
| normal MS-DOS formatted floppy. Copy one or more Linux kernel files to |
| it, then execute the DOS command: |
| |
| syslinux [-s] a: |
| |
| (or whichever drive letter is appropriate; the [] meaning -s is optional) |
| |
| or the Linux command: |
| |
| syslinux [-s] /dev/fd0 |
| |
| (or, again, whichever device is the correct one.) |
| |
| This will alter the boot sector on the disk and copy a file named |
| LDLINUX.SYS into its root directory. |
| |
| The -s option, if given, will install a "safe, slow and stupid" |
| version of SYSLINUX. This version may work on some very buggy BIOSes |
| on which SYSLINUX would otherwise fail. If you find a machine on |
| which the -s option is required to make it boot reliably, please send |
| as much info about your machine as you can, and include the failure |
| mode. |
| |
| WARNING: There seems to be a bug in some recent experimental Linux |
| kernels that causes floppy disk corruption when using the |
| Linux syslinux installer. This bug exists in kernels |
| 2.1.79-2.1.86; as far as I know the bug is fixed in 2.1.87. |
| |
| On boot time, by default, the kernel will be loaded from the image named |
| LINUX on the boot floppy. This default can be changed, see the section |
| on the SYSLINUX config file. |
| |
| If the Shift or Alt keys are held down during boot, or the Caps or Scroll |
| locks are set, SYSLINUX will display a LILO-style "boot:" prompt. The |
| user can then type a kernel file name followed by any kernel parameters. |
| The SYSLINUX loader does not need to know about the kernel file in |
| advance; all that is required is that it is a file located in the root |
| directory on the disk. |
| |
| |
| ++++ CONFIGURATION FILE ++++ |
| |
| All the configurable defaults in SYSLINUX can be changed by putting a |
| file called SYSLINUX.CFG in the root directory of the boot floppy. This |
| is a text file in either UNIX or DOS format, containing one or more of |
| the following items (case is insensitive for keywords; upper case is used |
| here to indicate that a word should be typed verbatim): |
| |
| DEFAULT kernel options... |
| Sets the default command line. If SYSLINUX boots automatically, |
| it will act just as if the entries after DEFAULT had been typed |
| in at the "boot:" prompt, except that the option "auto" is |
| automatically added, indicating an automatic boot. |
| |
| If no configuration file is present, or no DEFAULT entry is |
| present in the config file, the default is kernel name "linux", |
| with no options. |
| |
| APPEND options... |
| Add one or more options to the kernel command line. These are |
| added both for automatic and manual boots. The options are |
| added at the very beginning of the kernel command line, |
| usually permitting explicitly entered kernel options to override |
| them. This is the equivalent of the LILO "append" option. |
| |
| LABEL label |
| KERNEL image |
| APPEND options... |
| Indicates that if "label" is entered as the kernel to boot, |
| SYSLINUX should instead boot "image", and the specified APPEND |
| options should be used instead of the ones specified in the |
| global section of the file (before the first LABEL command.) |
| The default for "image" is the same as "label", and if no |
| APPEND is given the default is to use the global entry (if any). |
| Up to 128 LABEL entries are permitted. |
| |
| Note that LILO uses the syntax: |
| image = mykernel |
| label = mylabel |
| append = "myoptions" |
| |
| corresponding to the SYSLINUX: |
| label mylabel |
| kernel mykernel |
| append myoptions |
| |
| Notes: Labels are mangled as if they were DOS filenames, and must be |
| unique after mangling. For example, two labels |
| "v2.1.30" and "v2.1.31" will not be distinguishable. |
| |
| The "image" doesn't have to be a Linux kernel; it can |
| be a boot sector or a COMBOOT file (see below.) |
| |
| APPEND - |
| Append nothing. APPEND with a single hyphen as argument in a |
| LABEL section can be used to override a global APPEND. |
| |
| IMPLICIT flag_val |
| If flag_val is 0, do not load a kernel image unless it has been |
| explicitly named in a LABEL statement. The default is 1. |
| |
| TIMEOUT timeout |
| Indicates how long to wait at the boot: prompt until booting |
| automatically, in units of 1/10 s. The timeout is cancelled as |
| soon as the user types anything on the keyboard, the assumption |
| being that the user will complete the command line already |
| begun. A timeout of zero will disable the timeout completely, |
| this is also the default. |
| |
| NOTE: The maximum possible timeout value is 35996; corresponding to |
| just below one hour. |
| |
| SERIAL port [baudrate] |
| Enables a serial port to act as the console. "port" is a |
| number (0 = /dev/ttyS0 = COM1, etc.); if "baudrate" is |
| omitted, the baud rate defaults to 9600 bps. The serial |
| parameters are hardcoded to be 8 bits, no parity, 1 stop bit. |
| |
| For this directive to be guaranteed to work properly, it |
| should be the first directive in the configuration file. |
| |
| FONT filename |
| Load a font in .psf format before displaying any output |
| (except the copyright line, which is output as ldlinux.sys |
| itself is loaded.) SYSLINUX only loads the font onto the |
| video card; if the .psf file contains a Unicode table it is |
| ignored. This only works on EGA and VGA cards; hopefully it |
| should do nothing on others. |
| |
| KBDMAP keymap |
| Install a simple keyboard map. The keyboard remapper used is |
| *very* simplistic (it simply remaps the keycodes received from |
| the BIOS, which means that only the key combinations relevant |
| in the default layout -- usually U.S. English -- can be |
| mapped) but should at least help people with AZERTY keyboard |
| layout and the locations of = and , (two special characters |
| used heavily on the Linux kernel command line.) |
| |
| The included program keytab-lilo.pl from the LILO distribution |
| can be used to create such keymaps. The file keytab-lilo.doc |
| contains the documentation for this program. |
| |
| DISPLAY filename |
| Displays the indicated file on the screen at boot time (before |
| the boot: prompt, if displayed). This option takes the place of |
| the LINUXMSG.TXT and BOOTMSG.TXT files in SYSLINUX 1.0. Please |
| see the section below on DISPLAY files. |
| |
| NOTE: If the file is missing, this option is simply ignored. |
| |
| PROMPT flag_val |
| If flag_val is 0, display the boot: prompt only if the Shift or Alt |
| key is pressed, or Caps Lock or Scroll lock is set (this is the |
| default). If flag_val is 1, always display the boot: prompt. This |
| option takes the place of testing for the LINUXMSG.TXT file in |
| SYSLINUX 1.0. |
| |
| F1 filename |
| F2 filename |
| ...etc... |
| F9 filename |
| F0 filename |
| Displays the indicated file on the screen when a function key is |
| pressed at the boot: prompt. This can be used to implement |
| pre-boot online help (presumably for the kernel command line |
| options.) Note that F10 MUST be entered in the config file as |
| "F0", not "F10", and that there is currently no way to bind |
| file names to F11 and F12. Please see the section below on |
| DISPLAY files. |
| |
| When using the serial console, press <Ctrl-F><digit> to get to |
| the help screens, e.g. <Ctrl-F><2> to get to the F2 screen, |
| and <Ctrl-F><0> for the F10 one. |
| |
| In the configuration file blank lines and comment lines beginning |
| with a hash mark (#) are ignored. |
| |
| Note that the configuration file is not completely decoded. Syntax |
| different from the one described above may still work correctly in this |
| version of SYSLINUX, but may break in a future one. |
| |
| |
| ++++ LARGE KERNELS AND INITIAL RAMDISK SUPPORT ++++ |
| |
| This version of SYSLINUX supports large kernels (bzImage format), |
| eliminating the 500K size limit of the zImage kernel format. bzImage |
| format kernels are detected automatically and handled transparently to |
| the user. |
| |
| This version of SYSLINUX also supports a boot-time-loaded ramdisk |
| (initrd). An initrd is loaded from a DOS file if the option |
| "initrd=filename" (where filename is the filename of the initrd image; |
| the file must be located in the root directory on the boot floppy) is |
| present on the processed command line (after APPEND's have been added, |
| etc.). If several initrd options are present, the last one has |
| precedence; this permits user-entered options to override a config |
| file APPEND. Specifying "initrd=" without a filename inhibits initrd |
| loading. The file specified by the initrd= option will typically be a |
| gzipped filesystem image. |
| |
| NOTE: One of the main advantages with SYSLINUX is that it makes it |
| very easy to support users with new or unexpected configurations, |
| especially in a distribution setting. If initrd is used to |
| extensively modularize the distribution kernel, it is strongly |
| recommended that a simple way of adding drivers to the boot floppy be |
| provided. The suggested manner is to let the initrd system mount the |
| boot floppy and look for additional drivers in a predetermined |
| location. |
| |
| To bzImage and recent zImage kernels, SYSLINUX 1.30 and higher will |
| identify using the ID byte 0x31. The ID range 0x32-0x3f is reserved |
| for future versions of SYSLINUX. |
| |
| |
| ++++ DISPLAY FILE FORMAT ++++ |
| |
| DISPLAY and function-key help files are text files in either DOS or UNIX |
| format (with or without <CR>). In addition, the following special codes |
| are interpreted: |
| |
| <FF> <FF> = <Ctrl-L> = ASCII 12 |
| Clear the screen, home the cursor. Note that the screen is |
| filled with the current display color. |
| |
| <SI><bg><fg> <SI> = <Ctrl-O> = ASCII 15 |
| Set the display colors to the specified background and |
| foreground colors, where <bg> and <fg> are hex digits, |
| corresponding to the standard PC display attributes: |
| |
| 0 = black 8 = dark grey |
| 1 = dark blue 9 = bright blue |
| 2 = dark green a = bright green |
| 3 = dark cyan b = bright cyan |
| 4 = dark red c = bright red |
| 5 = dark purple d = bright purple |
| 6 = brown e = yellow |
| 7 = light grey f = white |
| |
| Picking a bright color (8-f) for the background results in the |
| corresponding dark color (0-7), with the foreground flashing. |
| |
| Colors are not visible over the serial console. |
| |
| <SUB> <SUB> = <Ctrl-Z> = ASCII 26 |
| End of file (DOS convention). |
| |
| |
| ++++ COMBOOT IMAGES AND OTHER OPERATING SYSTEMS ++++ |
| |
| This version of SYSLINUX supports chain loading of other operating |
| systems (such as MS-DOS and its derivatives, including Windows 95/98), |
| as well as COMBOOT-style standalone executables (a subset of DOS .COM |
| files; see separate section below.) |
| |
| Chain loading requires the boot sector of the foreign operating system |
| to be stored in a file in the root directory of the filesystem. |
| Because neither Linux kernels, boot sector images, nor COMBOOT files |
| have reliable magic numbers, SYSLINUX will look at the file |
| extension. The following extensions are recognized: |
| |
| none or other Linux kernel image |
| .CBT COMBOOT image (not runnable from DOS) |
| .BSS Boot sector (DOS superblock will be patched in) |
| .BS Boot sector |
| .COM COMBOOT image (runnable from DOS) |
| |
| For filenames given on the command line, SYSLINUX will search for the |
| file by adding extensions in the order listed above if the plain |
| filename is not found. Filenames in KERNEL statements must be fully |
| qualified. |
| |
| |
| ++++ BOOTING DOS (OR OTHER SIMILAR OPERATING SYSTEMS) ++++ |
| |
| This is the recommended procedure for creating a SYSLINUX disk that |
| can boot either DOS or Linux. This example assumes the drive is A: in |
| DOS and /dev/fd0 in Linux; for other drives, substitute the |
| appropriate drive designator. |
| |
| ---- Linux procedure ---- |
| |
| 1. Make a DOS bootable disk. This can be done either by specifying |
| the /s option when formatting the disk in DOS, or by running the |
| DOS command SYS (this can be done under DOSEMU if DOSEMU has |
| direct device access to the relevant drive): |
| |
| format a: /s |
| or |
| sys a: |
| |
| 2. Boot Linux. Copy the DOS boot sector from the disk into a file: |
| |
| dd if=/dev/fd0 of=dos.bss bs=512 count=1 |
| |
| 3. Run SYSLINUX on the disk: |
| |
| syslinux /dev/fd0 |
| |
| 4. Mount the disk and copy the DOS boot sector file to it. The file |
| *must* have extension .bss: |
| |
| mount -t msdos /dev/fd0 /mnt |
| cp dos.bss /mnt |
| |
| 5. Copy the Linux kernel image(s), initrd(s), etc to the disk, and |
| create/edit syslinux.cfg and help files if desired: |
| |
| cp vmlinux /mnt |
| cp initrd.gz /mnt |
| |
| 6. Unmount the disk (if applicable.) |
| |
| umount /mnt |
| |
| ---- DOS procedure ---- |
| |
| To make this installation in DOS only, you need the utility copybs.com |
| (included with SYSLINUX) as well as the syslinux.com installer. |
| |
| 1. Make a DOS bootable disk. This can be done either by specifying |
| the /s option when formatting the disk in DOS, or by running the |
| DOS command SYS: |
| |
| format a: /s |
| or |
| sys a: |
| |
| 2. Copy the DOS boot sector from the disk into a file. The file |
| *must* have extension .bss: |
| |
| copybs a: a:dos.bss |
| |
| 3. Run SYSLINUX on the disk: |
| |
| syslinux a: |
| |
| 4. Copy the Linux kernel image(s), initrd(s), etc to the disk, and |
| create/edit syslinux.cfg and help files if desired: |
| |
| copy vmlinux a: |
| copy initrd.gz a: |
| |
| |
| ++++ COMBOOT EXECUTABLES ++++ |
| |
| A COMBOOT file is a standalone executable in DOS .COM format. They |
| can, among other things, be produced by the Etherboot package by |
| Markus Gutschke and Ken Yap. The following requirements apply for |
| these files to be sufficiently "standalone" for SYSLINUX to be able to |
| load and run them: |
| |
| * The program must not execute any DOS calls (since there is no |
| DOS), although it may call the BIOS. The only exception is that |
| the program may execute INT 20h (Terminate Program) to return to |
| the SYSLINUX prompt. Note especially that INT 21h AH=4Ch, INT 21h |
| AH=31h or INT 27h are *not* supported. |
| * Only the following fields in the PSP are supported: |
| - pspInt20 at offset 00h; |
| - pspNextParagraph at offset 02h; |
| - pspCommandTail at offset 80h (contains the arguments from the |
| SYSLINUX command line). |
| |
| All other fields will contain zero. |
| * The program must not modify any main memory outside its 64K |
| segment if it returns to SYSLINUX via INT 20h. |
| |
| SYSLINUX requires that COMBOOT files end in ".COM" or ".CBT". Files |
| ending in .COM can be run from the DOS command line, files ending in |
| .CBT cannot, otherwise there is no difference. SYSLINUX will prefer a |
| .CBT file over a similarly named .COM. |
| |
| SYSLINUX currently doesn't provide any form of API for the use of |
| COMBOOT files. If there is need, a future version may contain an INT |
| interface to some SYSLINUX functions; please contact me if you have a |
| need or ideas for such an API. |
| |
| |
| ++++ NOVICE PROTECTION ++++ |
| |
| SYSLINUX will attempt to detect if the user is trying to boot on a 286 |
| or lower class machine, or a machine with less than 608K of low ("DOS") |
| RAM (which means the Linux boot sequence cannot complete). If so, a |
| message is displayed and the boot sequence aborted. Holding down the |
| Ctrl key while booting disables this feature. |
| |
| The compile time and date of a specific SYSLINUX version can be obtained |
| by the DOS command "type ldlinux.sys". This is also used as the |
| signature for the LDLINUX.SYS file, which must match the boot sector. |
| |
| Any file that SYSLINUX uses can be marked hidden, system or readonly if |
| so is convenient; SYSLINUX ignores all file attributes. The SYSLINUX |
| installed automatically sets the readonly attribute on LDLINUX.SYS. |
| |
| |
| ++++ NOTES ON BOOTABLE CD-ROMS ++++ |
| |
| SYSLINUX can be used to create bootdisk images for El |
| Torito-compatible bootable CD-ROMs. However, it appears that many |
| BIOSes are very buggy when it comes to booting CD-ROMs. Some users |
| have reported that the following steps are helpful in making a CD-ROM |
| that is bootable on the largest possible number of machines: |
| |
| a) Use the -s (safe, slow and stupid) option to SYSLINUX; |
| b) Put the boot image as close to the beginning of the |
| ISO 9660 filesystem as possible. |
| |
| A CD-ROM is so much faster than a floppy that the -s option shouldn't |
| matter from a speed perspective. |
| |
| |
| ++++ BOOTING FROM A FAT FILESYSTEM PARTITION ON A HARD DISK ++++ |
| |
| SYSLINUX can boot from a FAT12 or FAT16 filesystem partition on a hard |
| disk (FAT32, introduced in Windows 95 OSR-2, is not supported, |
| however.) The installation procedure is identical to the procedure |
| for installing it on a floppy, and should work under either DOS or |
| Linux. To boot from a partition, SYSLINUX needs to be launched from a |
| Master Boot Record or another boot loader, just like DOS itself would. |
| |
| Under DOS, you can install a standard simple MBR on the primary hard |
| disk by running the command: |
| |
| FDISK /MBR |
| |
| Then use the FDISK command to mark the appropriate partition active. |
| |
| |
| ++++ KNOWN BUGS ++++ |
| |
| SYSLINUX is unsafe to use on any filesystem that extends past cylinder |
| 1024. This is a fundamental limitation of the standard BIOS API. |
| |
| SYSLINUX will not work (and will refuse to install) on filesystems |
| with a cluster size of more than 16K (typically means a filesystem of |
| more than 1 GB.) |
| |
| |
| ++++ COMPATIBILITY WITH SYSLINUX 1.0 ++++ |
| |
| The following combinations of options can be used to mimic the behaviour |
| of SYSLINUX 1.0 with LINUXMSG.TXT or BOOTMSG.TXT present, respectively: |
| |
| # Mimic SYSLINUX 1.0 with LINUXMSG.TXT file present: |
| display linuxmsg.txt |
| prompt 1 |
| |
| # Mimic SYSLINUX 1.0 with BOOTMSG.TXT file present: |
| display bootmsg.txt |
| |
| |
| ++++ BUG REPORTS ++++ |
| |
| I would appreciate hearing of any problems you have with SYSLINUX. I |
| would also like to hear from you if you have successfully used SYSLINUX, |
| *especially* if you are using it for a distribution. |
| |
| If you are reporting problems, please include all possible information |
| about your system and your BIOS; the vast majority of all problems |
| reported turn out to be BIOS or hardware bugs, and I need as much |
| information as possible in order to diagnose the problems. |
| |
| There is a mailing list for discussion among SYSLINUX users and for |
| announcements of new and test versions. To join, send a message to |
| majordomo@linux.kernel.org with the line: |
| |
| subscribe syslinux |
| |
| in the body of the message. The submission address is |
| syslinux@linux.kernel.org. |