home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 February / CHIP_2_98.iso / misc / src / trees / syslinux / readme < prev    next >
Text File  |  1996-10-31  |  11KB  |  256 lines
  1.                                 SYSLINUX
  2.                   Version 1.30
  3.  
  4.               A bootloader for Linux using MS-DOS floppies
  5.  
  6.                   Copyright (C) 1994-96 H. Peter Anvin
  7.  
  8. This program is provided under the terms of the GNU General Public
  9. License, version 2 or, at your option, any later version.  There is no
  10. warranty, neither expressed nor implied, to the function of this
  11. program.  Please see the included file COPYING for details.
  12.  
  13. SYSLINUX is a boot loader for the Linux operating system which operates
  14. off MS-DOS floppies.  It is intended to simplify first-time installation
  15. of Linux.  It is *not* intended to be used as a general purpose boot
  16. loader; once the operating system is installed I recommend LILO as the
  17. boot loader, except for people whose root filesystem is a UMSDOS
  18. filesystem (where a DOS defragmenter could wreck havoc with LILO's
  19. carefully set up block tables) -- for them I recommend Loadlin (which
  20. loads Linux from the DOS command line).
  21.  
  22. SYSLINUX could, however, in conjunction with the UMSDOS filesystem,
  23. completely eliminate the need for distribution of raw diskette images
  24. for boot floppies.  A SYSLINUX floppy can be manipulated using standard
  25. MS-DOS (or any other OS that can access an MS-DOS filesystem) tools once
  26. it has been created.
  27.  
  28.    ++++ CREATING A BOOTABLE LINUX FLOPPY +++
  29.  
  30. In order to create a bootable Linux floppy using SYSLINUX, prepare a
  31. normal MS-DOS formatted floppy.  Copy one or more Linux kernel files to
  32. it, then execute the DOS command:
  33.  
  34.         SYSLINUX drive:
  35.  
  36. This will alter the boot sector on the disk and copy a file named
  37. LDLINUX.SYS into its root directory.
  38.  
  39. On boot time, by default, the kernel will be loaded from the image named
  40. LINUX on the boot floppy.  This default can be changed, see the section
  41. on the SYSLINUX config file.
  42.  
  43. If the Shift or Alt keys are held down during boot, or the Caps or Scroll
  44. locks are set, SYSLINUX will display a LILO-style "boot:" prompt.  The
  45. user can then type a kernel file name followed by any kernel parameters.
  46. The SYSLINUX loader does not need to know about the kernel file in
  47. advance; all that is required is that it is a file located in the root
  48. directory on the disk.
  49.  
  50.    ++++ CONFIGURATION FILE ++++
  51.  
  52. All the configurable defaults in SYSLINUX can be changed by putting a
  53. file called SYSLINUX.CFG in the root directory of the boot floppy.  This
  54. is a text file in either UNIX or DOS format, containing one or more of
  55. the following items (case is insensitive for keywords; upper case is used
  56. here to indicate that a word should be typed verbatim):
  57.  
  58. DEFAULT kernel options...
  59.  
  60.         Sets the default command line.  If SYSLINUX boots automatically,
  61.         it will act just as if the entries after DEFAULT had been typed
  62.         in at the "boot:" prompt, except that the option "auto" is
  63.         automatically added, indicating an automatic boot.
  64.  
  65.         If no configuration file is present, or no DEFAULT entry is
  66.         present in the config file, the default is kernel name "linux",
  67.         with no options.
  68.  
  69. APPEND options...
  70.  
  71.         Add one or more options to the kernel command line.  These are
  72.         added both for automatic and manual boots.  The options are
  73.         added at the very beginning of the kernel command line,
  74.         usually permitting explicitly entered kernel options to override
  75.         them.  This is the equivalent of the LILO "append" option.
  76.  
  77. LABEL label
  78.   KERNEL kernel
  79.   APPEND options...
  80.  
  81.         Indicates that if "label" is entered as the kernel to boot,
  82.         SYSLINUX should instead boot "kernel", and the specified APPEND
  83.         options should be used instead of the ones specified in the
  84.         global section of the file (before the first LABEL command.)
  85.         The default for "kernel" is the same as "label", and if no
  86.         APPEND is given the default is to use the global entry (if any).
  87.         Up to 16 LABEL entries are permitted.
  88.  
  89.         Note that LILO uses the syntax:
  90.         image = mykernel
  91.           label = mylabel
  92.           append = "myoptions"
  93.  
  94.         corresponding to the SYSLINUX:
  95.         label mylabel
  96.           kernel mykernel
  97.           append myoptions
  98.  
  99.   APPEND -
  100.  
  101.         Append nothing.  APPEND with a single hyphen as argument in a
  102.         LABEL section can be used to override a global APPEND.
  103.  
  104. IMPLICIT flag_val
  105.  
  106.         If flag_val is 0, do not load a kernel image unless it has been
  107.         explicitly named in a LABEL statement.  The default is 1.
  108.  
  109. TIMEOUT timeout
  110.  
  111.         Indicates how long to wait at the boot: prompt until booting
  112.         automatically, in units of 1/10 s.  The timeout is cancelled as
  113.         soon as the user types anything on the keyboard, the assumption
  114.         being that the user will complete the command line already
  115.         begun.  A timeout of zero will disable the timeout completely,
  116.         this is also the default.
  117.  
  118.         NOTE: The maximum possible timeout value is 35996; corresponding to
  119.         just below one hour.
  120.  
  121. DISPLAY filename
  122.  
  123.         Displays the indicated file on the screen at boot time (before
  124.         the boot: prompt, if displayed).  This option takes the place of
  125.         the LINUXMSG.TXT and BOOTMSG.TXT files in SYSLINUX 1.0.  Please
  126.         see the section below on DISPLAY files.
  127.  
  128.         NOTE: If the file is missing, this option is simply ignored.
  129.  
  130. PROMPT flag_val
  131.  
  132.         If flag_val is 0, display the boot: prompt only if the Shift or Alt
  133.         key is pressed, or Caps Lock or Scroll lock is set (this is the
  134.         default).  If flag_val is 1, always display the boot: prompt.  This
  135.         option takes the place of testing for the LINUXMSG.TXT file in
  136.         SYSLINUX 1.0.
  137.  
  138. F1 filename
  139. F2 filename
  140.    ...etc...
  141. F9 filename
  142. F0 filename
  143.  
  144.         Displays the indicated file on the screen when a function key is
  145.         pressed at the boot: prompt.  This can be used to implement
  146.         pre-boot online help (presumably for the kernel command line
  147.         options.)  Note that F10 MUST be entered in the config file as
  148.         "F0", not "F10", and that there is currently no way to bind
  149.         file names to F11 and F12.  Please see the section below on
  150.         DISPLAY files.
  151.  
  152. Blank lines, and comment lines beginning with a hash mark (#) are ignored.
  153.  
  154. Note that the configuration file is not completely decoded.  Syntax
  155. different from the one described above may still work correctly in this
  156. version of SYSLINUX, but may break in a future one.
  157.  
  158. The following combinations of options can be used to mimic the behaviour
  159. of SYSLINUX 1.0 with LINUXMSG.TXT or BOOTMSG.TXT present, respectively:
  160.  
  161. # Mimic SYSLINUX 1.0 with LINUXMSG.TXT file present:
  162. display linuxmsg.txt
  163. prompt 1
  164.  
  165. # Mimic SYSLINUX 1.0 with BOOTMSG.TXT file present:
  166. display bootmsg.txt
  167.  
  168.    ++++ LARGE KERNELS AND INITIAL RAMDISK SUPPORT ++++
  169.  
  170. This version of SYSLINUX supports large kernels (bzImage format),
  171. eliminating the 500K size limit of the zImage kernel format.  bzImage
  172. format kernels are detected automatically and handled transparently to
  173. the user.
  174.  
  175. This version of SYSLINUX also supports a boottime-loaded ramdisk
  176. (initrd).  An initrd is loaded from a DOS file if the option
  177. "initrd=filename" (where filename is the filename of the initrd image;
  178. the file must be located in the root directory on the boot floppy) is
  179. present on the processed command line (after APPEND's have been added,
  180. etc.).  If several initrd options are present, the last one has
  181. precedence; this permits user-entered options to override a config
  182. file APPEND.  Specifying "initrd=" without a filename inhibits initrd
  183. loading.  The file specified by the initrd= option will typically be a
  184. gzipped filesystem image.
  185.  
  186. NOTE: One of the main advantages with SYSLINUX is that it makes it
  187. very easy to support users with new or unexpected configurations,
  188. especially in a distribution setting.  If initrd is used to
  189. extensively modularize the distribution kernel, it is strongly
  190. recommended that a simple way of adding drivers to the boot floppy be
  191. provided.  The suggested manner is to let the initrd system mount the
  192. boot floppy and look for additional drivers in a predetermined
  193. location.
  194.  
  195. To bzImage and recent zImage kernels, SYSLINUX 1.30 will identify
  196. using the ID byte 0x31.  The ID range 0x32-0x3f is reserved for future
  197. versions of SYSLINUX.
  198.  
  199.    ++++ DISPLAY FILE FORMAT ++++
  200.  
  201. DISPLAY and function-key help files are text files in either DOS or UNIX
  202. format (with or without <CR>).  In addition, the following special codes
  203. are interpreted:
  204.  
  205. <FF>                                    <FF> = <Ctrl-L> = ASCII 12
  206.         Clear the screen, home the cursor.  Note that the screen is
  207.         filled with the current display color.
  208.  
  209. <SI><bg><fg>                            <SI> = <Ctrl-O> = ASCII 15
  210.         Set the display colors to the specified background and
  211.         foreground colors, where <bg> and <fg> are hex digits,
  212.         corresponding to the standard PC display attributes:
  213.  
  214.         0 = black               8 = dark grey
  215.         1 = dark blue           9 = bright blue
  216.         2 = dark green          a = bright green
  217.         3 = dark cyan           b = bright cyan
  218.         4 = dark red            c = bright red
  219.         5 = dark purple         d = bright purple
  220.         6 = brown               e = yellow
  221.         7 = light grey          f = white
  222.  
  223.         Picking a bright color (8-f) for the background results in the
  224.         corresponding dark color (0-7), with the foreground flashing.
  225.  
  226. <SUB>                                   <SUB> = <Ctrl-Z> = ASCII 26
  227.         End of file (DOS convention).
  228.  
  229.    ++++ NOVICE PROTECTION ++++
  230.  
  231. SYSLINUX will attempt to detect if the user is trying to boot on a 286
  232. or lower class machine, or a machine with less than 608K of low ("DOS")
  233. RAM (which means the Linux boot sequence cannot complete).  If so, a
  234. message is displayed and the boot sequence aborted.  Holding down the
  235. Ctrl key while booting disables this feature.
  236.  
  237. The compile time and date of a specific SYSLINUX version can be obtained
  238. by the DOS command "type ldlinux.sys".  This is also used as the
  239. signature for the LDLINUX.SYS file, which must match the boot sector.
  240.  
  241. Any file that SYSLINUX uses can be marked hidden, system or readonly if
  242. so is convenient; SYSLINUX ignores all file attributes.  The SYSLINUX
  243. installed automatically sets the readonly attribute on LDLINUX.SYS.
  244.  
  245.    ++++ BUG REPORTS ++++
  246.  
  247. I would appreciate hearing of any problems you have with SYSLINUX.  I
  248. would also like to hear from you if you have successfully used SYSLINUX,
  249. *especially* if you are using it for a distribution.
  250.  
  251. Please contact me at email <hpa@zytor.com>.
  252.  
  253. Sincerely,
  254.  
  255.                 H. Peter Anvin                  November 2, 1996
  256.