1SYSLINUX(1)                 General Commands Manual                SYSLINUX(1)
2
3
4

NAME

6       syslinux - install the SYSLINUX bootloader on a FAT filesystem
7

SYNOPSIS

9       syslinux [OPTIONS] device
10

DESCRIPTION

12       Syslinux is a boot loader for the Linux operating system which operates
13       off an MS-DOS/Windows FAT filesystem. It is intended to simplify first-
14       time  installation  of Linux, and for creation of rescue and other spe‐
15       cial-purpose boot disks.
16
17       In order to create a bootable Linux floppy using  Syslinux,  prepare  a
18       normal  MS-DOS formatted floppy. Copy one or more Linux kernel files to
19       it, then execute the command:
20
21              syslinux --install /dev/fd0
22
23       This will alter the boot sector on the  disk  and  copy  a  file  named
24       ldlinux.sys into its root directory.
25
26       On  boot  time,  by  default,  the kernel will be loaded from the image
27       named LINUX on the boot floppy.  This default can be changed,  see  the
28       section on the syslinux configuration file.
29
30       If  the  Shift  or  Alt  keys are held down during boot, or the Caps or
31       Scroll locks are set, syslinux will display a  lilo(8)  -style  "boot:"
32       prompt.  The user can then type a kernel file name followed by any ker‐
33       nel parameters. The SYSLINUX bootloader does not need to know about the
34       kernel  file  in  advance;  all  that  is required is that it is a file
35       located in the root directory on the disk.
36
37       Syslinux supports the loading of  initial  ramdisks  (initrd)  and  the
38       bzImage kernel format.
39

OPTIONS

41       -i, --install
42              Install  SYSLINUX  on  a  new medium, overwriting any previously
43              installed bootloader.
44
45       -U, --update
46              Install SYSLINUX on a new medium if and only  if  a  version  of
47              SYSLINUX is already installed.
48
49       -s, --stupid
50              Install a "safe, slow and stupid" version of SYSLINUX. This ver‐
51              sion may work on some very buggy BIOSes on which SYSLINUX  would
52              otherwise fail.  If you find a machine on which the -s option is
53              required to make it boot reliably,  please  send  as  much  info
54              about your machine as you can, and include the failure mode.
55
56       -f, --force
57              Force install even if it appears unsafe.
58
59       -r, --raid
60              RAID mode.  If boot fails, tell the BIOS to boot the next device
61              in the boot sequence (usually the next  hard  disk)  instead  of
62              stopping with an error message.  This is useful for RAID-1 boot‐
63              ing.
64
65       -d, --directory subdirectory
66              Install the SYSLINUX control files in a  subdirectory  with  the
67              specified name (relative to the root directory on the device).
68
69       -t, --offset offset
70              Indicates  that  the filesystem is at an offset from the base of
71              the device or file.
72
73       --once command
74              Declare a boot command to be tried on the first boot only.
75
76       -O, --clear-once
77              Clear the boot-once command.
78
79       -H, --heads head-count
80              Override the detected number of heads for the geometry.
81
82       -S, --sectors sector-count
83              Override the detected number of sectors for the geometry.
84
85       -z, --zipdrive
86              Assume zipdrive geometry (--heads 64 --sectors 32).
87

FILES

89   Configuration file
90       All the configurable defaults in SYSLINUX can be changed by  putting  a
91       file  called  syslinux.cfg  in  the install directory of the boot disk.
92       This is a text file in either UNIX or DOS  format,  containing  one  or
93       more of the following items (case is insensitive for keywords).
94
95       This list is out of date.
96
97       In  the configuration file blank lines and comment lines beginning with
98       a hash mark (#) are ignored.
99
100       default kernel [ options ... ]
101              Sets the default command line. If syslinux boots  automatically,
102              it  will  act  just  as  if the entries after "default" had been
103              typed in at the "boot:" prompt.
104
105              If no DEFAULT or UI statement is  found,  or  the  configuration
106              file  is  missing  entirely,  SYSLINUX drops to the boot: prompt
107              with an error message (if NOESCAPE is set, it stops with a "boot
108              failed"  message; this is also the case for PXELINUX if the con‐
109              figuration file is not found.)
110
111       NOTE: Until SYSLINUX 3.85, if no configuration file is present, or no
112              "default" entry  is  present  in  the  configuration  file,  the
113              default is "linux auto".
114
115       Even earlier versions of SYSLINUX used to automatically
116              append  the  string  "auto" to whatever the user specified using
117              the DEFAULT command.  As of version  1.54,  this  is  no  longer
118              true,  as  it caused problems when using a shell as a substitute
119              for "init."  You may want to include this option manually.
120
121       append options ...
122              Add one or more options to the kernel command  line.  These  are
123              added both for automatic and manual boots. The options are added
124              at the very beginning of the kernel command line,  usually  per‐
125              mitting explicitly entered kernel options to override them. This
126              is the equivalent of the lilo(8)
127               "append" option.
128
129       label label
130         kernel image
131         append options ...
132              Indicates that if label is entered as the kernel to  boot,  sys‐
133              linux  should  instead  boot  image,  and the specified "append"
134              options should be used instead of  the  ones  specified  in  the
135              global  section  of the file (before the first "label" command.)
136              The default for image is the same as label, and if  no  "append"
137              is  given  the default is to use the global entry (if any).  Use
138              "append -" to use no options at all.  Up to 128 "label"  entries
139              are permitted.
140
141                     The  "image" doesn't have to be a Linux kernel; it can be
142                     a boot sector or a COMBOOT file (see below.)
143
144       implicit flag_val
145              If flag_val is 0, do not load a kernel image unless it has  been
146              explicitly named in a "label" statement.  The default is 1.
147
148       timeout timeout
149              Indicates  how  long to wait at the "boot:" prompt until booting
150              automatically, in units of 1/10 s. The timeout is  cancelled  as
151              soon  as the user types anything on the keyboard, the assumption
152              being that the user  will  complete  the  command  line  already
153              begun.  A  timeout  of zero will disable the timeout completely,
154              this is also the default. The maximum possible timeout value  is
155              35996; corresponding to just below one hour.
156
157       serial port [ baudrate ]
158              Enables  a serial port to act as the console. "port" is a number
159              (0 = /dev/ttyS0 = COM1, etc.); if  "baudrate"  is  omitted,  the
160              baud rate defaults to 9600 bps.  The serial parameters are hard‐
161              coded to be 8 bits, no parity, 1 stop bit.
162
163              For this directive to be guaranteed to work properly, it  should
164              be the first directive in the configuration file.
165
166       font filename
167              Load  a font in .psf format before displaying any output (except
168              the copyright line, which is output  as  ldlinux.sys  itself  is
169              loaded.)  syslinux  only  loads the font onto the video card; if
170              the .psf file contains a Unicode table it is ignored.  This only
171              works  on  EGA  and VGA cards; hopefully it should do nothing on
172              others.
173
174       kbdmap keymap
175              Install a simple keyboard map. The  keyboard  remapper  used  is
176              very simplistic (it simply remaps the keycodes received from the
177              BIOS, which means that only the key combinations relevant in the
178              default  layout  -  usually  U.S.   English - can be mapped) but
179              should at least help people with AZERTY keyboard layout and  the
180              locations of = and , (two special characters used heavily on the
181              Linux kernel command line.)
182
183              The included program keytab-lilo.pl(8) from the lilo(8)
184               distribution can be used to create such keymaps.
185
186       display filename
187              Displays the indicated file on the screen at boot  time  (before
188              the boot: prompt, if displayed). Please see the section below on
189              DISPLAY files. If the file is missing,  this  option  is  simply
190              ignored.
191
192       prompt flag_val
193              If  flag_val  is 0, display the "boot:" prompt only if the Shift
194              or Alt key is pressed, or Caps Lock or Scroll lock is set  (this
195              is  the  default).  If flag_val is 1, always display the "boot:"
196              prompt.
197
198       f1 filename
199       f2 filename
200       ...
201       f9 filename
202       f10 filename
203       f11 filename
204       f12 filename
205              Displays the indicated file on the screen when a function key is
206              pressed  at  the  "boot:"  prompt. This can be used to implement
207              pre-boot online help (presumably for  the  kernel  command  line
208              options.)
209
210              When  using  the serial console, press <Ctrl-F><digit> to get to
211              the help screens, e.g. <Ctrl-F>2 to get to the f2  screen.   For
212              f10-f12,  hit <Ctrl-F>A, <Ctrl-F>B, <Ctrl-F>C.  For compatiblity
213              with earlier versions, f10 can also be entered as <Ctrl-F>0.
214
215   Display file format
216       DISPLAY and function-key help files are text files  in  either  DOS  or
217       UNIX  format (with or without <CR>). In addition, the following special
218       codes are interpreted:
219
220       <FF> = <Ctrl-L> = ASCII 12
221              Clear the screen, home the cursor.   Note  that  the  screen  is
222              filled with the current display color.
223
224       <SI><bg><fg>, <SI> = <Ctrl-O> = ASCII 15
225              Set  the  display  colors  to the specified background and fore‐
226              ground colors, where <bg> and <fg> are hex digits, corresponding
227              to the standard PC display attributes:
228
229              0 = black          8 = dark grey
230              1 = dark blue      9 = bright blue
231              2 = dark green     a = bright green
232              3 = dark cyan      b = bright cyan
233              4 = dark red       c = bright red
234              5 = dark purple    d = bright purple
235              6 = brown          e = yellow
236              7 = light grey     f = white
237
238              Picking  a  bright color (8-f) for the background results in the
239              corresponding dark color (0-7), with the foreground flashing.
240
241              colors are not visible over the serial console.
242
243       <CAN>filename<newline>, <CAN> = <Ctrl-X> = ASCII 24
244              If a VGA display is present, enter graphics mode and display the
245              graphic  included  in the specified file.  The file format is an
246              ad hoc format called LSS16;  the  included  Perl  program  "ppm‐
247              tolss16" can be used to produce these images.  This Perl program
248              also includes the file format specification.
249
250              The image is displayed in 640x480 16-color mode.  Once in graph‐
251              ics  mode,  the  display attributes (set by <SI> code sequences)
252              work slightly differently: the background color is ignored,  and
253              the  foreground  colors are the 16 colors specified in the image
254              file.  For that reason, ppmtolss16 allows you  to  specify  that
255              certain colors should be assigned to specific color indicies.
256
257              Color  indicies  0  and  7, in particular, should be chosen with
258              care: 0 is the background color, and 7 is the color used for the
259              text printed by SYSLINUX itself.
260
261       <EM>, <EM> = <Ctrl-U> = ASCII 25
262              If we are currently in graphics mode, return to text mode.
263
264       <DLE>..<ETB>, <Ctrl-P>..<Ctrl-W> = ASCII 16-23
265              These codes can be used to select which modes to print a certain
266              part of the message file in.  Each of these  control  characters
267              select  a  specific  set of modes (text screen, graphics screen,
268              serial port) for which the output is actually displayed:
269
270              Character                       Text    Graph   Serial
271              ------------------------------------------------------
272              <DLE> = <Ctrl-P> = ASCII 16     No      No      No
273              <DC1> = <Ctrl-Q> = ASCII 17     Yes     No      No
274              <DC2> = <Ctrl-R> = ASCII 18     No      Yes     No
275              <DC3> = <Ctrl-S> = ASCII 19     Yes     Yes     No
276              <DC4> = <Ctrl-T> = ASCII 20     No      No      Yes
277              <NAK> = <Ctrl-U> = ASCII 21     Yes     No      Yes
278              <SYN> = <Ctrl-V> = ASCII 22     No      Yes     Yes
279              <ETB> = <Ctrl-W> = ASCII 23     Yes     Yes     Yes
280
281              For example:
282              <DC1>Text mode<DC2>Graphics mode<DC4>Serial port<ETB>
283               ... will actually print out which mode the console is in!
284
285       <SUB> = <Ctrl-Z> = ASCII 26
286              End of file (DOS convention).
287
288   Comboot Images and other operating systems
289       This version of syslinux supports chain loading of other operating sys‐
290       tems  (such as MS-DOS and its derivatives, including Windows 95/98), as
291       well as COMBOOT-style standalone executables  (a  subset  of  DOS  .COM
292       files; see separate section below.)
293
294       Chain  loading requires the boot sector of the foreign operating system
295       to be stored in a  file  in  the  root  directory  of  the  filesystem.
296       Because  neither  Linux  kernels, boot sector images, nor COMBOOT files
297       have reliable magic numbers, syslinux will look at the file  extension.
298       The following extensions are recognised:
299
300       none or other    Linux kernel image
301       CBT              COMBOOT image (not runnable from DOS)
302       BSS              Boot sector (DOS superblock will be patched in)
303       BS               Boot sector
304       COM              COMBOOT image (runnable from DOS)
305
306       For  filenames  given on the command line, syslinux will search for the
307       file by adding extensions in the order listed above if the plain  file‐
308       name  is not found. Filenames in KERNEL statements must be fully quali‐
309       fied.
310
311       A COMBOOT file is a standalone executable in DOS .COM format. They can,
312       among  other  things,  be  produced  by the Etherboot package by Markus
313       Gutschke and Ken Yap. The following requirements apply for these  files
314       to be sufficiently "standalone" for syslinux to be able to load and run
315       them:
316
317       ·      The program must not execute any DOS calls (since  there  is  no
318              DOS),  although it may call the BIOS. The only exception is that
319              the program may execute INT 20h (Terminate Program) to return to
320              the  syslinux  prompt.  Note especially that INT 21h AH=4Ch, INT
321              21h AH=31h or INT 27h are not supported.
322
323       ·      Only the fields pspInt20 at offset 00h, pspNextParagraph at off‐
324              set 02h and pspCommandTail at offset 80h (contains the arguments
325              from the syslinux command line) in the PSP  are  supported.  All
326              other fields will contain zero.
327
328       ·      The program must not modify any main memory outside its 64K seg‐
329              ment if it returns to syslinux via INT 20h.
330
331       Syslinux currently doesn't provide any form of API for the use of  COM‐
332       BOOT  files.   If  there  is  need, a future version may contain an INT
333       interface to some syslinux functions; please contact me if you  have  a
334       need or ideas for such an API.
335
336   Novice protection
337       Syslinux  will attempt to detect if the user is trying to boot on a 286
338       or lower class machine, or a machine with less than 608K of low ("DOS")
339       RAM  (which  means  the Linux boot sequence cannot complete).  If so, a
340       message is displayed and the boot sequence aborted.  Holding  down  the
341       Ctrl key while booting disables this feature.
342
343       The  compile  time  and  date  of  a  specific  syslinux version can be
344       obtained by the DOS command "type ldlinux.sys". This is  also  used  as
345       the  signature for the LDLINUX.SYS file, which must match the boot sec‐
346       tor
347
348       Any file that syslinux uses can be marked hidden, system or readonly if
349       so  is  convenient; syslinux ignores all file attributes.  The SYSLINUX
350       installed automatically sets the readonly attribute on LDLINUX.SYS.
351
352   Bootable CD-ROMs
353       SYSLINUX can be used to create bootdisk images for El Torito-compatible
354       bootable  CD-ROMs.  However, it appears that many BIOSes are very buggy
355       when it comes to booting CD-ROMs. Some users  have  reported  that  the
356       following  steps are helpful in making a CD-ROM that is bootable on the
357       largest possible number of machines:
358
359       ·      Use the -s (safe, slow and stupid) option to SYSLINUX
360
361       ·      Put the boot image as close to the beginning  of  the  ISO  9660
362              filesystem as possible.
363
364       A  CD-ROM  is so much faster than a floppy that the -s option shouldn't
365       matter from a speed perspective.
366
367       Of course, you probably want to use ISOLINUX instead.  See the documen‐
368       tation file isolinux.doc.
369
370   Booting from a FAT partition on a hard disk
371       SYSLINUX  can  boot  from  a  FAT  filesystem  partition on a hard disk
372       (including FAT32). The installation procedure is identical to the  pro‐
373       cedure  for installing it on a floppy, and should work under either DOS
374       or Linux. To boot from a partition, SYSLINUX needs to be launched  from
375       a  Master  Boot  Record  or  another  boot loader, just like DOS itself
376       would. A sample master boot sector (mbr.bin) is included with SYSLINUX.
377

BUGS

379       I would appreciate hearing of any problems you have with  SYSLINUX.   I
380       would  also  like  to  hear from you if you have successfully used SYS‐
381       LINUX, especially if you are using it for a distribution.
382
383       If you are reporting problems, please include all possible  information
384       about  your  system  and  your  BIOS; the vast majority of all problems
385       reported turn out to be BIOS or hardware  bugs,  and  I  need  as  much
386       information as possible in order to diagnose the problems.
387
388       There  is  a  mailing  list for discussion among SYSLINUX users and for
389       announcements of new and test versions. To  join,  send  a  message  to
390       majordomo@linux.kernel.org with the line:
391
392       subscribe syslinux
393
394       in   the   body   of  the  message.  The  submission  address  is  sys‐
395       linux@linux.kernel.org.
396

SEE ALSO

398       lilo(8), keytab-lilo.pl(8), fdisk(8), mkfs(8), superformat(1).
399

AUTHOR

401       This manual page is a modified version of the original  syslinux  docu‐
402       mentation  by  H. Peter Anvin <hpa@zytor.com>. The conversion to a man‐
403       page was made by Arthur Korn <arthur@korn.ch>.
404
405
406
407SYSLINUX                         19 July 2010                      SYSLINUX(1)
Impressum