| blob | ddbd5debe73d296963a50455528fbe8789dc4a63 |
1 = syslinux.cfg(5) =
2 :doctype: manpage
3 :revdate: 2012-10-28
4 :author: H. Peter Anvin
5 :author-email: hpa@zytor.com
6 :editor1: Gene Cumm
7 :editor1-email: gene.cumm@gmail.com
8 :editor1-revlast: 2012-10-28
9 :nbsp8:         
10 :nbsp32: {nbsp8}{nbsp8}{nbsp8}{nbsp8}
11 :data-uri:
13 == NAME ==
14 syslinux.cfg - *Syslinux* configuration file
17 == DESCRIPTION ==
18 Configuration for the boot behavior and user experience of *Syslinux*
19 boot loaders, the format of display files and the boot prompt behavior.
21 Blank lines are ignored.
23 Note that the configuration file is not completely decoded. Syntax
24 different from the one described above may still work correctly in this
25 version of *Syslinux*, but may break in a future one.
28 == LOCATION/NAME ==
29 *SYSLINUX* (before 4.00) used the configuration filename of
30 syslinux.cfg. *EXTLINUX* (merged into *SYSLINUX* as of 4.00) used the
31 filename extlinux.conf. Both default to searching for the config file
32 in the installed directory (containing ldlinux.sys/extlinux.sys). As of
33 4.00, *SYSLINUX* will search for extlinux.conf then syslinux.cfg in each
34 directory before falling back to the next directory.
36 As of 3.35, *SYSLINUX* also searches /boot/syslinux, /syslinux and /.
38 *ISOLINUX* (before 4.02) used the configuration filename of
39 isolinux.cfg, searching /boot/isolinux (starting 2.00), then /isolinux
40 and /. As of 4.02, *ISOLINUX* will search for isolinux.cfg then
41 syslinux.cfg in /boot/isolinux before searching for the same files in
42 /isolinux, /boot/syslinux, /syslinux, and /.
45 == GLOBAL DIRECTIVES - MAIN ==
46 *#* comment::
47 A line comment. As of version 3.10, the space between the *#* and the
48 comment is no longer required.
50 *MENU* any string::
51 (3.00+) A directive for the simple menu system, treated as a comment
52 outside the menu. See menu.txt.
54 *INCLUDE* 'filename'::
55 Inserts the contents of another file at this point in the configuration
56 file. Files can currently be nested up to 16 levels deep, but it is not
57 guaranteed that more than 8 levels will be supported in the future.
59 *DEFAULT* 'kernel' 'options...'::
60 Sets the default command line. If *Syslinux* boots automatically, it
61 will act just as if the entries after *DEFAULT* had been typed in at the
62 'boot:' prompt. Multiple uses will result in an override.
63 +
64 If no configuration file is present, or no *DEFAULT* or *UI* entry is
65 present in the config file, an error message is displayed and the
66 'boot:' prompt is shown (3.85+).
68 *UI* 'module' 'options...'::
69 Selects a specific user interface 'module' (typically menu.c32 or
70 vesamenu.c32). The command-line interface treats this as a directive
71 that overrides the *DEFAULT* directive to load this module instead at
72 startup and for an empty command line and *PROMPT* directive to not
73 prompt. Multiple uses will result in an override.
75 *LABEL* 'mylabel'::
76 Begin a new *LABEL* clause. If 'mylabel' is entered as the kernel to
77 boot, *Syslinux* should instead boot "image" (specified by a directive
78 from *KERNEL-LIKE DIRECTIVES*) with any specified *DUAL-PURPOSE
79 DIRECTIVES* being used instead of the global instance.
80 +
81 'mylabel' must be unique. Currently the first instance is used but may
82 result in an error or undesired behavior. 'mylabel' ends at the first
83 character that is not a non-white-space printable character and should
84 be restricted to non-white-space typeable characters. Prior to version
85 3.32, this would transformed to a DOS compatible format of 8.3 with a
86 restricted character set. A *LABEL* clause must contain exactly 1 of
87 the *KERNEL-LIKE DIRECTIVES* and may contain 1 each of the *LABEL-ONLY
88 DIRECTIVES* or *DUAL-PURPOSE DIRECTIVES*.
89 +
90 Within a *LABEL*, using multiple *KERNEL-LIKE DIRECTIVES* or reuse of
91 *LABEL-ONLY DIRECTIVES* or *DUAL-PURPOSE DIRECTIVES* will result in an
92 override. Otherwise, multiple instances of the same directive will
93 result in the last being effective.
96 == DUAL-PURPOSE DIRECTIVES ==
97 Use of any of the *DUAL-PURPOSE DIRECTIVES* as *GLOBAL DIRECTIVES* is
98 discouraged if there will be any non-Linux images loaded as *ALL* images
99 will get these, including those manually entered at the 'boot:' prompt.
101 *APPEND* 'options...'::
102 Add one or more options to the kernel command line. These are added
103 both for automatic and manual boots. The options are added at the very
104 beginning of the kernel command line, usually permitting explicitly
105 entered kernel options to override them. This is the equivalent of the
106 LILO "append" option.
107 +
108 Use of the parameter 'initrd=' supports multiple filenames separated by
109 commas (ie 'initrd=initrd_file1,initrd_file2') within a single instance.
110 This is mostly useful for initramfs, which can be composed of multiple
111 separate cpio or cpio.gz archives.
112 +
113 Note: all initrd files except the last one are zero-padded to a 4K page
114 boundary. This should not affect initramfs.
115 +
116 Note: Only the last effective 'initrd=' parameter is used for loading
117 initrd files.
119 *APPEND* -::
120 Append nothing. *APPEND* with a single hyphen as argument in a *LABEL*
121 section can be used to override a global *APPEND*.
123 //[FIXME: Shorten subdefinitions]
124 *IPAPPEND* 'flag_val'::
125 (*PXELINUX* only) The *IPAPPEND* option is available only on *PXELINUX*.
126 The flag_val is an OR (sum) of the following integer options:
128 ifndef::doctype-manpage[[horizontal]]
129 *1*::: An option of the following format should be generated, based on
130 the input from the DHCP/BOOTP or PXE boot server and added to the kernel
131 command line(see note below):
132 +
133 ----
134 ip=<client-ip>:<boot-server-ip>:<gw-ip>:<netmask>
135 ----
136 +
137 NOTE: The use of option 1 is no substitute for running a DHCP client in
138 the booted system and should instead only be used to seed the client for
139 a request. Without regular renewals, the lease acquired by the PXE BIOS
140 will expire, making the IP address available for reuse by the DHCP
141 server.
142 +
143 *2*::: An option of the following format should be generated, in
144 dash-separated hexadecimal with leading hardware type (same as for the
145 configuration file; see pxelinux.txt.) and added to the kernel command
146 line, allowing an initrd program to determine from which interface the
147 system booted:
148 +
149 ----
150 BOOTIF=<hardware-address-of-boot-interface>
151 ----
152 +
153 *4*::: An option of the following format should be generated, in lower
154 case hexadecimal in the format normally used for UUIDs (same as for the
155 configuration file; see pxelinux.txt.) and added to the kernel command
156 line:
157 +
158 ----
159 SYSUUID=<system uuid>
160 ----
163 == KERNEL-LIKE DIRECTIVES ==
164 // Alpha sort after KERNEL and LINUX
165 *KERNEL* 'image'::
166 Load a kernel-like file 'image' with automatic filetype detection based
167 on file extension, listed under the non-auto-detecting directives,
168 defaulting to *LINUX*.
170 //[FIXME: Should "'image' as " be removed entirely or added to all?
171 *LINUX* is used as an example]
172 *LINUX* 'image'::
173 Load 'image' as a Linux-like kernel. MEMDISK is an example of a
174 non-Linux kernel loaded in a Linux-like fashion.
176 *BOOT* 'image'::
177 (*ISOLINUX* only: .bin; *SYSLINUX* only: .bs) Load a boot sector. .bin
178 is a "CD boot sector" and .bs is a regular disk boot sector.
180 *BSS* 'image'::
181 (*SYSLINUX* only: .bss) Load a BSS image, a .bs image with the DOS
182 superblock patched in.
184 *COMBOOT* 'image'::
185 (.com, .cbt; Removed as of 5.00) Load a *Syslinux* COMBOOT image. .com
186 images may also be runnable from DOS while .cbt images are not. See
187 also *comboot.txt*
189 *COM32* 'image'::
190 (.c32) Load a *Syslinux* COM32 (32-bit *COMBOOT*) image. See also
191 *comboot.txt*
193 *CONFIG* 'image'::
194 Load a new configuration file. The configuration file is read, the
195 working directory is changed (if specified via an *APPEND*), then the
196 configuration file is parsed.
198 *FDIMAGE* 'image'::
199 (Removed as of 4.05, added 1.65; *ISOLINUX* only: .img) Load a disk
200 image.
202 *LOCALBOOT* 'type'::
203 (*PXELINUX* 1.53+; *ISOLINUX* ??3.10+; *SYSLINUX* 3.70+)Attempt a
204 different local boot method. The special value -1 causes the boot
205 loader to report failure to the BIOS, which, on recent BIOSes, should
206 mean that the next boot device in the boot sequence should be activated.
207 Values other than those documented may produce undesired results.
208 +
209 On *PXELINUX*, 'type' 0 means perform a normal boot. 'type' 4 will
210 perform a local boot with the Universal Network Driver Interface (UNDI)
211 driver still resident in memory. Finally, 'type' 5 will perform a local
212 boot with the entire PXE stack, including the UNDI driver, still
213 resident in memory. All other values are undefined. If you don't know
214 what the UNDI or PXE stacks are, don't worry -- you don't want them,
215 just specify 0.
216 +
217 On *ISOLINUX*/*SYSLINUX*, the 'type' specifies the local drive number to
218 boot from; 0x00 is the primary floppy drive and 0x80 is the primary hard
219 drive.
221 *PXE* 'image'::
222 (*PXELINUX* only: .0) Load a PXE NBP (Network Boot Program) image. The
223 PXE protocol does not provide any means for specifiying or using a
224 command line or initrd.
227 == LABEL-ONLY DIRECTIVES ==
228 *INITRD* 'initrd_file'::
229 (3.71+) An initrd can be specified in a separate statement (INITRD)
230 instead of as part of the *APPEND* statement; this functionally appends
231 "initrd=initrd_file" to the kernel command line. Like 'initrd=', this
232 also supports multiple comma separated file names (see *APPEND*).
235 == GLOBAL DIRECTIVES - SECONDARY ==
236 These are global directives that are of lesser importance, often
237 affecting the user experience and not the boot process.
239 *ALLOWOPTIONS* 'flag_val'::
240 If 'flag_val' is 0, the user is not allowed to specify any arguments on
241 the kernel command line. The only options recognized are those
242 specified in an *APPEND*) statement. The default is 1.
244 *IMPLICIT* 'flag_val'::
245 If 'flag_val' is 0, do not load a kernel image unless it has been
246 explicitly named in a *LABEL* statement. The default is 1.
248 *TIMEOUT* 'timeout'::
249 Indicates how long to wait at the 'boot:' prompt until booting
250 automatically, in units of 1/10 s. The timeout is cancelled as soon as
251 the user types anything on the keyboard, the assumption being that the
252 user will complete the command line already begun. A timeout of zero
253 (the default) will disable the timeout completely.
255 *TOTALTIMEOUT* 'timeout'::
256 Indicates how long to wait until booting automatically, in units of
257 1/10 s. This timeout is *not* cancelled by user input, and can thus be
258 used to deal with serial port glitches or "the user walked away" type
259 situations. A timeout of zero will disable the timeout completely, this
260 is also the default.
261 +
262 Both *TIMEOUT* and *TOTALTIMEOUT* can be used together, for example:
263 +
264 ----
265 # Wait 5 seconds unless the user types something, but
266 # always boot after 15 minutes.
267 TIMEOUT 50
268 TOTALTIMEOUT 9000
269 ----
271 // FIXME: be consistent
272 *ONTIMEOUT* 'kernel options...'::
273 Sets the command line invoked on a timeout. Normally this is the same
274 thing as invoked by 'DEFAULT'. If this is specified, then 'DEFAULT' is
275 used only if the user presses <Enter> to boot.
277 *ONERROR* 'kernel options...'::
278 If a kernel image is not found (either due to it not existing, or
279 because *IMPLICIT* is set), run the specified command. The faulty
280 command line is appended to the specified options, so if the *ONERROR*
281 directive reads as:
282 +
283 ----
284 ONERROR xyzzy plugh
285 ----
286 +
287 and the command line as entered by the user is:
288 +
289 ----
290 foo bar baz
291 ----
292 +
293 *Syslinux* will execute the following as if entered by the user:
294 +
295 ----
296 xyzzy plugh foo bar baz
297 ----
299 *SERIAL* 'port [baudrate [flowcontrol]]'::
300 Enables a serial port to act as the console. 'port' is a number (0 =
301 /dev/ttyS0 = COM1, etc.) or an I/O port address (e.g. 0x3F8); if
302 'baudrate' is omitted, the baud rate defaults to 9600 bps. The serial
303 parameters are hardcoded to be 8 bits, no parity, 1 stop bit.
304 +
305 'flowcontrol' is a combination of the following bits:
306 +
307 ....
308 0x001 - Assert DTR
309 0x002 - Assert RTS
310 0x008 - Enable interrupts
311 0x010 - Wait for CTS assertion
312 0x020 - Wait for DSR assertion
313 0x040 - Wait for RI assertion
314 0x080 - Wait for DCD assertion
315 0x100 - Ignore input unless CTS asserted
316 0x200 - Ignore input unless DSR asserted
317 0x400 - Ignore input unless RI asserted
318 0x800 - Ignore input unless DCD asserted
319 ....
320 +
321 All other bits are reserved.
322 +
323 Typical values are:
324 +
325 ....
326 0 - No flow control (default)
327 0x303 - Null modem cable detect
328 0x013 - RTS/CTS flow control
329 0x813 - RTS/CTS flow control, modem input
330 0x023 - DTR/DSR flow control
331 0x083 - DTR/DCD flow control
332 ....
333 +
334 For the *SERIAL* directive to be guaranteed to work properly, it should
335 be the first directive in the configuration file.
336 +
337 NOTE: 'port' values from 0 to 3 means the first four serial ports
338 detected by the BIOS. They may or may not correspond to the legacy port
339 values 0x3F8, 0x2F8, 0x3E8, 0x2E8.
340 +
341 Enabling interrupts (setting the 0x008 bit) may give better
342 responsiveness without setting the *NOHALT* option, but could
343 potentially cause problems with buggy BIOSes.
345 *NOHALT* 'flag_val'::
346 If 'flag_val' is 1, don't halt the processor while idle. Halting the
347 processor while idle significantly reduces the power consumption, but
348 can cause poor responsiveness to the serial console, especially when
349 using scripts to drive the serial console, as opposed to human
350 interaction.
352 *CONSOLE* 'flag_val'::
353 If 'flag_val' is 0, disable output to the normal video console. If
354 'flag_val' is 1, enable output to the video console (this is the
355 default.)
356 +
357 Some BIOSes try to forward this to the serial console and sometimes make
358 a total mess thereof, so this option lets you disable the video console
359 on these systems.
361 *FONT* 'filename'::
362 Load a font in .psf format before displaying any output (except the
363 copyright line, which is output as ldlinux.sys itself is loaded.)
364 *Syslinux* only loads the font onto the video card; if the .psf file
365 contains a Unicode table it is ignored. This only works on EGA and VGA
366 cards; hopefully it should do nothing on others.
368 *KBDMAP* 'keymap'::
369 Install a simple keyboard map. The keyboard remapper used is *very*
370 simplistic (it simply remaps the keycodes received from the BIOS, which
371 means that only the key combinations relevant in the default layout --
372 usually U.S. English -- can be mapped) but should at least help people
373 with AZERTY keyboard layout and the locations of = and , (two special
374 characters used heavily on the Linux kernel command line.)
375 +
376 The included program keytab-lilo.pl from the LILO distribution can be
377 used to create such keymaps. The file keytab-lilo.txt contains the
378 documentation for this program.
380 *DISPLAY* 'filename'::
381 Displays the indicated file on the screen at boot time (before the boot:
382 prompt, if displayed). Please see the section below on *DISPLAY* files.
383 +
384 NOTE: If the file is missing, this option is simply ignored.
386 *SAY* 'message'::
387 Prints the message on the screen.
389 *PROMPT* 'flag_val'::
390 If 'flag_val' is 0, display the boot: prompt only if the Shift or Alt
391 key is pressed, or Caps Lock or Scroll lock is set (this is the
392 default). If 'flag_val' is 1, always display the boot: prompt.
394 *NOESCAPE* 'flag_val'::
395 If 'flag_val' is set to 1, ignore the Shift/Alt/Caps Lock/Scroll Lock
396 escapes. Use this (together with PROMPT 0) to force the default boot
397 alternative.
399 *NOCOMPLETE* 'flag_val'::
400 If 'flag_val' is set to 1, the Tab key does not display labels at the
401 boot: prompt.
403 // ...etc...
404 *F1* 'filename'::
405 *F2* 'filename'::
406 *F3* 'filename'::
407 *F4* 'filename'::
408 *F5* 'filename'::
409 *F6* 'filename'::
410 *F7* 'filename'::
411 *F8* 'filename'::
412 *F9* 'filename'::
413 *F10* 'filename'::
414 *F11* 'filename'::
415 *F12* 'filename'::
416 Displays the indicated file on the screen when a function key is pressed
417 at the boot: prompt. This can be used to implement pre-boot online help
418 (presumably for the kernel command line options.) Please see the
419 section below on DISPLAY files.
420 +
421 When using the serial console, press <Ctrl-F><digit> to get to the help
422 screens, e.g. <Ctrl-F><2> to get to the F2 screen. For F10-F12, hit
423 <Ctrl-F><A>, <Ctrl-F>B, <Ctrl-F>C. For compatibility with earlier
424 versions, F10 can also be entered as <Ctrl-F>0.
426 *PATH* 'path'::
427 (5.00+) Specify a colon-separated (':') list of directories to search when
428 attempting to load modules. This directive is useful for specifying the
429 directories containing the lib*.c32 library files as other modules may
430 be dependent on these files, but may not reside in the same directory.
433 == DISPLAY FILE FORMAT ==
434 DISPLAY and function-key help files are text files in either DOS or UNIX
435 format (with or without <CR>). In addition, the following special codes
436 are interpreted:
438 //[FIXME]: #1 doesn't break; #2 as-is; #3 broken but not on right; #4
439 identical to #3
440 // horizontal extends the line's label, reducing the definition
441 // tab or space to shift explanation ? align beginning or end?
443 // ifndef::doctype-manpage[[horizontal]]
444 *<FF>*:: {nbsp32} = <Ctrl-L> = ASCII 12 +
445 Clear the screen, home the cursor. Note that the screen is filled with
446 the current display color.
448 *<FF>*::
449 = <Ctrl-L> = ASCII 12; Clear the screen, home the cursor. Note that the
450 screen is filled with the current display color.
452 *<FF>*:: <FF> = <Ctrl-L> = ASCII 12
453 +
454 Clear the screen, home the cursor. Note that the screen is filled with
455 the current display color.
457 *<FF>*::
458 <FF> = <Ctrl-L> = ASCII 12 +
459 Clear the screen, home the cursor. Note that the screen is filled with
460 the current display color.
462 *<SI>*'<bg><fg>':: <SI> = <Ctrl-O> = ASCII 15
463 +
464 Set the display colors to the specified background and foreground
465 colors, where <bg> and <fg> are the 2 hex digits representing 1 byte,
466 corresponding to the standard PC display attributes:
467 +
468 0 = black 8 = dark grey
469 1 = dark blue 9 = bright blue
470 2 = dark green a = bright green
471 3 = dark cyan b = bright cyan
472 4 = dark red c = bright red
473 5 = dark purple d = bright purple
474 6 = brown e = yellow
475 7 = light grey f = white
476 +
477 Picking a bright color (8-f) for the background results in the
478 corresponding dark color (0-7), with the foreground flashing.
479 +
480 Colors are not visible over the serial console.
482 *<CAN>*'filename<newline>':: <CAN> = <Ctrl-X> = ASCII 24
483 +
484 If a VGA display is present, enter graphics mode and display the graphic
485 included in the specified file. The file format is an ad hoc format
486 called LSS16; the included Perl program "ppmtolss16" can be used to
487 produce these images. This Perl program also includes the file format
488 specification.
489 +
490 The image is displayed in 640x480 16-color mode. Once in graphics mode,
491 the display attributes (set by <SI> code sequences) work slightly
492 differently: the background color is ignored, and the foreground colors
493 are the 16 colors specified in the image file. For that reason,
494 ppmtolss16 allows you to specify that certain colors should be assigned
495 to specific color indicies.
496 +
497 Color indicies 0 and 7, in particular, should be chosen with care: 0 is
498 the background color, and 7 is the color used for the text printed by
499 *Syslinux* itself.
501 *<EM>*:: <EM> = <Ctrl-Y> = ASCII 25 +
502 If we are currently in graphics mode, return to text mode.
504 *<DLE>*..*<ETB>*:: <Ctrl-P>..<Ctrl-W> = ASCII 16-23
505 +
506 These codes can be used to select which modes to print a certain part of
507 the message file in. Each of these control characters select a specific
508 set of modes (text screen, graphics screen, serial port) for which the
509 output is actually displayed:
510 +
511 Character Text Graph Serial
512 ------------------------------------------------------
513 <DLE> = <Ctrl-P> = ASCII 16 No No No
514 <DC1> = <Ctrl-Q> = ASCII 17 Yes No No
515 <DC2> = <Ctrl-R> = ASCII 18 No Yes No
516 <DC3> = <Ctrl-S> = ASCII 19 Yes Yes No
517 <DC4> = <Ctrl-T> = ASCII 20 No No Yes
518 <NAK> = <Ctrl-U> = ASCII 21 Yes No Yes
519 <SYN> = <Ctrl-V> = ASCII 22 No Yes Yes
520 <ETB> = <Ctrl-W> = ASCII 23 Yes Yes Yes
521 +
522 For example, the following will actually print out which mode the
523 console is in:
524 +
525 <DC1>Text mode<DC2>Graphics mode<DC4>Serial port<ETB>
527 *<SUB>*:: <SUB> = <Ctrl-Z> = ASCII 26
528 +
529 End of file (DOS convention).
531 *<BEL>*:: <BEL> = <Ctrl-G> = ASCII 7 +
532 Beep the speaker.
535 == BOOT LOADER IDS USED ==
536 The Linux boot protocol supports a "boot loader ID", a single byte where
537 the upper nybble specifies a boot loader family (3 = *Syslinux*) and the
538 lower nybble is version or, in the case of *Syslinux*, media:
540 0x31 (49) = SYSLINUX
541 0x32 (50) = PXELINUX
542 0x33 (51) = ISOLINUX
543 0x34 (52) = EXTLINUX
545 In recent versions of Linux, this ID is available as
546 /proc/sys/kernel/bootloader_type.
549 == NOVICE PROTECTION ==
550 *Syslinux* will attempt to detect booting on a machine with too little
551 memory, which means the Linux boot sequence cannot complete. If so, a
552 message is displayed and the boot sequence aborted. Holding down the
553 Ctrl key while booting disables this feature.
555 Any file that *Syslinux* uses can be marked hidden, system or readonly
556 if so is convenient; *Syslinux* ignores all file attributes. The
557 *SYSLINUX* installer automatically sets the readonly/hidden/system
558 attributes on LDLINUX.SYS.
561 == KNOWN BUGS ==
562 include::com-bug.txt[]
565 == BUG REPORTS ==
566 include::com-rpt.txt[]
569 == AUTHOR ==
570 This AsciiDoc derived document is a modified version of the original
571 *SYSLINUX* documentation by {author} <{author-email}>. The conversion
572 to an AsciiDoc was made by {editor1} <{editor1-email}>