1 There are two menu systems included with Syslinux, the advanced menu
2 system, and the simple menu system.
5 +++ THE ADVANCED MENU SYSTEM +++
7 The advanced menu system, written by Murali Krishnan Ganapathy, is
8 located in the com32/cmenu/ sub-directory. It allows the user to
9 create hierarchical sub-menus, dynamic options, check-boxes, and just
10 about anything. It requires the menu to be compiled from a simple C
11 file (see com32/cmenu/simple.c and com32/cmenu/complex.c for examples).
13 The advanced menu system does not support serial console at this time.
15 See com32/cmenu/README for more information.
18 +++ THE SIMPLE MENU SYSTEM +++
20 The simple menu system is based on a module located at
21 com32/menu/vesamenu.c32 (graphical) or com32/menu/menu.c32 (text
22 mode only). It uses the same configuration file as the regular
23 Syslinux command line, and displays all the LABEL statements.
25 To use the menu system, simply make sure [vesa]menu.c32 is in the
26 appropriate location for the boot medium (the same directory as the
27 configuration file for SYSLINUX, EXTLINUX and ISOLINUX, and the same
28 directory as pxelinux.0 for PXELINUX), and put the following options
29 in the configuration file:
34 There are a few menu additions to the configuration file, all starting
35 with the keywords MENU or TEXT. As the rest of the Syslinux
36 configuration file language, it is case-insensitive.
38 The remainder of this document is a reference of the directives that
39 are relevant in the Simple Menu System.
44 Give the menu a title. The title is presented at the top of
50 Do not display the actual menu unless the user presses a key.
51 All that is displayed is a timeout message.
54 MENU HIDDENKEY key[,key...] command...
56 If the key used to interrupt MENU HIDDEN is <key>, then
57 execute the specified command instead of displaying the menu.
59 Currently, the following key names are recognized:
61 Backspace, Tab, Enter, Esc, Space, F1..F12, Up, Down, Left,
62 Right, PgUp, PgDn, Home, End, Insert, Delete
64 ... in addition to all single characters plus the syntax ^X
65 for Ctrl-X. Note that single characters are treated as case
66 sensitive, so "A" and "a" can bind different commands. The
67 same command can be bound to different keys by giving a
68 comma-separated list of them:
70 menu hiddenkey A,a key_a_command
75 Clear the screen when exiting the menu, instead of leaving the
76 menu displayed. For vesamenu, this means the graphical
77 background is still displayed without the menu itself for as
78 long as the screen remains in graphics mode.
83 Exit the menu system immediately unless either the Shift or the
84 Alt key is pressed, or Caps Lock or Scroll Lock is set.
89 Insert an empty line in the menu.
94 (Only valid after a LABEL statement.)
95 Change the label displayed for a specific menu entry. Display
96 a label that is not suitable for the command line. For example:
100 MENU LABEL Soft Cap ^Linux 9.6.36
101 KERNEL softcap-9.6.36.bzi
104 # A very dense operating system
106 MENU LABEL ^Windows CE/ME/NT
110 The caret symbol (^) in a MENU LABEL statement defines a hotkey.
111 Hotkeys are highlighted in the menu. When a hotkey is pressed,
112 the cursor will move to the corresponding menu entry. If MENU
113 IMMEDIATE is present, then when a hotkey is pressed the
114 corresponding menu entry will be immediately launched.
116 Reusing hotkeys has no effect on subsequent entries; they will
117 not be highlighted, and the cursor will not move to them when
118 the hotkey is pressed again.
120 Keep in mind that the LABELs, not MENU LABELs, must be unique,
121 or odd things will happen to the command-line.
126 (Only valid after a LABEL statement.)
127 Add "count" spaces in front of the displayed menu entry.
132 (Only valid after a LABEL statement.)
133 Make the entry unselectable. This allows to display a
134 section in the menu with different options below it.
137 # Entries for network boots
144 MENU LABEL Soft Cap ^Linux 9.6.36
146 KERNEL softcap-9.6.36.bzi
154 APPEND initrd=dos622.imz
159 # Entries for local boots
166 MENU LABEL ^Windows 2000
173 MENU LABEL Windows ^XP
180 (Only valid after a LABEL statement.)
181 Suppress a particular LABEL entry from the menu.
186 (Only valid after a LABEL statement.)
188 The particular menu entry is considered the default for the
189 particular (sub)menu. If no default is specified, use the
190 first one. See also the DEFAULT directive.
195 ... which can span multiple lines
198 (Only valid after a LABEL statement.)
200 Specify a help text that should be displayed when a particular
201 selection is highlighted.
206 (Only valid after a LABEL statement.)
208 Set a password on this menu entry. "passwd" can be either a
209 cleartext password or a password encrypted with one of the
210 following algorithms:
213 SHA-1 (Signature: $4$)
214 SHA-2-256 (Signature: $5$)
215 SHA-2-512 (Signature: $6$)
217 Use the included Perl scripts "sha1pass" or "md5pass" to
218 encrypt passwords. MD5 passwords are compatible with most
219 Unix password file utilities; SHA-1 passwords are probably
220 unique to Syslinux; SHA-2 passwords are compatible with very
221 recent Linux distributions. Obviously, if you don't encrypt
222 your passwords they will not be very secure at all.
224 If using passwords, make sure to use "NOESCAPE 1" and
225 "PROMPT 0", and either set "ALLOWOPTIONS 0" or use a master
226 password (see below).
228 If passwd is an empty string, this menu entry can only be
229 unlocked with the master password.
232 MENU MASTER PASSWD passwd
234 Set a master password. This password can be used to boot any
235 menu entry. If this directive is used, then the master password
236 is also required for the [Tab] and [Esc] keys to work.
239 MENU RESOLUTION width height
241 Request a specific screen resolution when in graphics mode.
242 The default is "640 480" corresponding to a resolution of
243 640x480 pixels, which all VGA-compatible monitors should be
246 If the requested resolution is unavailable, the text mode menu
247 is displayed instead.
250 MENU BACKGROUND background
252 For vesamenu.c32, set the background image. The background
253 can either be a color (see MENU COLOR) or the name of an image
254 file, which should be the size of the screen (normally 640x480
255 pixels, but see MENU RESOLUTION) and either in PNG, JPEG or
258 Note: When using an image file as background, its resolution
259 should match the values used in MENU RESOLUTION.
265 Begin/end a submenu. The entries between MENU BEGIN and MENU
266 END form a submenu, which is marked with a ">" mark on the right
267 hand of the screen. Submenus inherit the properties of their
268 parent menus, but can override them, and can thus have their
269 own backgrounds, master passwords, titles, timeouts, messages
275 (Only valid after a LABEL statement.)
277 Transfer to the named submenu instead of booting anything.
278 To transfer to the top-level menu, specify "menu goto .top".
283 (Only valid after a LABEL statement inside MENU BEGIN ...
286 Exit to the next higher menu, or, if tagname is specified, to
292 (Only valid after a LABEL statement.)
294 Quit the menu system.
296 WARNING: Even if either MENU MASTER PASSWD or "ALLOWOPTIONS 0"
297 is set, MENU QUIT will still allow exiting to the CLI; however,
298 a separate MENU PASSWD can of course be set for this
304 (Only valid inside MENU BEGIN ... MENU END)
306 Define the starting menu for the menu system, instead of
307 starting at the top-level menu. See also the DEFAULT directive.
312 Set the global default. If "label" points into a submenu,
313 that menu becomes the start menu. In other words, this
314 directive has the same effect as both MENU DEFAULT and MENU
317 For backwards compatibility with earlier versions of Syslinux,
318 this behavior is ignored unless the configuration file also
319 contains a UI directive.
321 Note: the CLI accepts options after the label, or even a
322 non-label. The menu system does not support that.
328 Remember the last selected entry and make that one the default
329 for the next boot. A password-protected menu entry is *not*
330 saved. This requires the ADV data storage mechanism, which is
331 currently only implemented for SYSLINUX, although the other
332 Syslinux derivatives will accept the command (and ignore it).
334 NOTE: MENU SAVE stores the LABEL tag of the selected entry.
335 This mechanism therefore relies on LABEL tags being unique.
336 On the other hand, it handles changes in the configuration
339 NOTE: In software RAID-1 setups, MENU SAVE only stores the
340 default label on the actual boot disk. This may lead to
341 inconsistent reads from the array, or unexpectedly change the
342 default label after array resynchronization or disk failure.
344 The MENU SAVE information can be fully cleared with
345 "extlinux --reset-adv <bootdir>".
347 A MENU SAVE or MENU NOSAVE at the top of a (sub)menu affects
348 all entries underneath that (sub)menu except those that in
349 turn have MENU SAVE or MENU NOSAVE declared. This can be used
350 to restrict which specific entries are allowed to be saved when
354 INCLUDE filename [tagname]
355 MENU INCLUDE filename [tagname]
357 Include the contents of the "filename" configuration file at
360 In the case of MENU INCLUDE, the included data is only seen by
361 the menu system; the core Syslinux code does not parse this
362 command, so any labels defined in it are unavailable.
364 If a tagname is included, the whole file is considered to have
365 been bracketed with a "MENU BEGIN tagname ... MENU END" pair,
366 and will therefore show up as a submenu.
369 MENU AUTOBOOT message
371 Replace the message "Automatic boot in # second{,s}...". The
372 "#" symbol is replaced with the number of remaining seconds.
373 The syntax "{singular,[dual,]plural}" can be used to conjugate
379 Replace the message "Press [Tab] to edit options".
382 MENU NOTABMSG message
384 Take the place of the TABMSG message when the [Tab] key is not
385 allowed, i.e. if the possibility to edit the command is
386 disabled. Defaults to blank.
389 MENU PASSPROMPT message
391 Replace the message "Password required".
394 MENU COLOR element ansi foreground background shadow
396 Set the color of element "element" to the specified color
399 screen Rest of the screen
402 unsel Unselected menu item
403 hotkey Unselected hotkey
405 hotsel Selected hotkey
406 disabled Disabled menu item
408 tabmsg Press [Tab] message
409 cmdmark Command line marker
411 pwdborder Password box border
412 pwdheader Password box header
413 pwdentry Password box contents
414 timeout_msg Timeout message
415 timeout Timeout counter
417 msgXX Message (F-key) file attribute XX
419 ... where XX is two hexadecimal digits (the "plain text" is 07).
421 "ansi" is a sequence of semicolon-separated ECMA-48 Set
422 Graphics Rendition (<ESC>[m) sequences:
424 0 reset all attributes to their defaults
426 4 set underscore (simulated with color on a color display)
429 22 set normal intensity
433 30 set black foreground
434 31 set red foreground
435 32 set green foreground
436 33 set brown foreground
437 34 set blue foreground
438 35 set magenta foreground
439 36 set cyan foreground
440 37 set white foreground
441 38 set underscore on, set default foreground color
442 39 set underscore off, set default foreground color
443 40 set black background
444 41 set red background
445 42 set green background
446 43 set brown background
447 44 set blue background
448 45 set magenta background
449 46 set cyan background
450 47 set white background
451 49 set default background color
453 These are used (a) in text mode, and (b) on the serial
456 "foreground" and "background" are color codes in #AARRGGBB
457 notation, where AA RR GG BB are hexadecimal digits for alpha
458 (opacity), red, green and blue, respectively. #00000000
459 represents fully transparent, and #ffffffff represents opaque
462 "shadow" controls the handling of the graphical console text
463 shadow. Permitted values are "none" (no shadowing), "std" or
464 "standard" (standard shadowing - foreground pixels are
465 raised), "all" (both background and foreground raised), and
466 "rev" or "reverse" (background pixels are raised).
468 If any field is set to "*" or omitted (at the end of the line)
469 then that field is left unchanged.
472 The current defaults are:
474 menu color screen 37;40 #80ffffff #00000000 std
475 menu color border 30;44 #40000000 #00000000 std
476 menu color title 1;36;44 #c00090f0 #00000000 std
477 menu color unsel 37;44 #90ffffff #00000000 std
478 menu color hotkey 1;37;44 #ffffffff #00000000 std
479 menu color sel 7;37;40 #e0000000 #20ff8000 all
480 menu color hotsel 1;7;37;40 #e0400000 #20ff8000 all
481 menu color disabled 1;30;44 #60cccccc #00000000 std
482 menu color scrollbar 30;44 #40000000 #00000000 std
483 menu color tabmsg 31;40 #90ffff00 #00000000 std
484 menu color cmdmark 1;36;40 #c000ffff #00000000 std
485 menu color cmdline 37;40 #c0ffffff #00000000 std
486 menu color pwdborder 30;47 #80ffffff #20ffffff std
487 menu color pwdheader 31;47 #80ff8080 #20ffffff std
488 menu color pwdentry 30;47 #80ffffff #20ffffff std
489 menu color timeout_msg 37;40 #80ffffff #00000000 std
490 menu color timeout 1;37;40 #c0ffffff #00000000 std
491 menu color help 37;40 #c0ffffff #00000000 std
492 menu color msg07 37;40 #90ffffff #00000000 std
495 MENU MSGCOLOR fg_filter bg_filter shadow
497 Set *all* the msgXX colors to a color scheme derived from the
498 fg_filter and bg_filter values. Background color zero is
499 always treated as transparent. The default corresponds to:
501 menu msgcolor #90ffffff #80ffffff std
503 This directive should come before any directive that
504 customizes individual msgXX colors.
509 MENU PASSWORDMARGIN 3
517 MENU HELPMSGENDROW -1
522 These options control the layout of the menu on the screen.
523 The values above are the defaults.
525 A negative value is relative to the calculated length of the
526 screen (25 rows for text mode, 28 rows for VESA graphics mode).
529 F1 textfile [background]
531 F12 textfile [background]
533 Display full-screen help (also available at the command line).
534 The same control code sequences as in the command line
535 interface are supported, although some are ignored.
537 Additionally, an optional second argument allows a different
538 background image to be displayed by vesamenu.c32 (see MENU
539 BACKGROUND for supported formats). The CLI and menu.c32 will
540 ignore the second argument.
543 MENU HELP textfile [background]
545 Create a menu entry which, when selected, displays
546 full-screen help in the same way as the F-key help.
549 The menu system honours the TIMEOUT command. If TIMEOUT is specified,
550 it will execute the ONTIMEOUT command if one exists, otherwise it will
551 pick the DEFAULT menu option. WARNING: the TIMEOUT action will bypass
552 password protection even if one is set for the specified ONTIMEOUT
553 and/or DEFAULT entry!
555 Normally, users can press [Tab] to edit the menu entry, and [Esc]
556 to return to the Syslinux command line. However, if the configuration
557 file specifies "ALLOWOPTIONS 0", these keys will be disabled, and if
558 MENU MASTER PASSWD is set, they require the master password.
560 The simple menu system supports serial console, using the normal
561 SERIAL directive. However, it can be quite slow over a slow serial
562 link; you probably want to set your baudrate to 38400 or higher if
563 possible. It requires a Linux/VT220/ANSI-compatible terminal on the
567 +++ USING AN ALTERNATE CONFIGURATION FILE +++
570 It is also possible to load a secondary configuration file, to get to
571 another menu. To do that, invoke (vesa)menu.c32 with the name of the
572 secondary configuration file.
575 MENU LABEL Another Menu
577 APPEND othermenu.conf
579 If you specify more than one file, they will all be read, in the order
580 specified. The dummy filename ~ (tilde) is replaced with the filename
581 of the main configuration file.
583 # The file graphics.conf contains common color and layout commands for
586 MENU LABEL Another Menu
588 APPEND graphics.conf othermenu.conf
590 # Return to the main menu
592 MENU LABEL Return to Main Menu
594 APPEND graphics.conf ~
596 See also the MENU INCLUDE directive above.