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