Adding upstream version 3.62+dfsg.
[syslinux-debian/hramrach.git] / doc / menu.txt
blobaa161bcace606e68649708b388bfbc65348b2311
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 menu/ subdirectly.  It allows the user to create
9 hierarchial submenus, dynamic options, checkboxes, and just about
10 anything you want.  It requires that the menu is compiled from a
11 simple C file, see menu/simple.c and menu/complex.c for examples.
13 The advanced menu system doesn't support serial console at this time.
15 See menu/README for more information.
18 +++ THE SIMPLE MENU SYSTEM +++
20 The simple menu system is a single module located at
21 com32/modules/vesamenu.c32 (graphical) or com32/modules/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 your 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 your configuration file:
31 DEFAULT menu.c32
32 PROMPT 0
35 There are a few menu additions to the command line, all starting with
36 the keywords MENU or TEXT; like the rest of the SYSLINUX config file
37 language, it is case insensitive:
39 MENU TITLE title
41         Give the menu a title.  The title is presented at the top of
42         the menu.
44 MENU HIDDEN
46         Do not display the actual menu unless the user presses a key.
47         All that is displayed is a timeout message.
49 MENU SEPARATOR
51         Insert an empty line in the menu.
53 MENU LABEL label
55         (Only valid after a LABEL statement.)
56         Changes the label displayed for a specific entry.  This allows
57         you to have a label that isn't suitable for the command line,
58         for example:
60         # Soft Cap Linux
61         LABEL softcap
62                 MENU LABEL Soft Cap ^Linux 9.6.36
63                 KERNEL softcap-9.6.36.bzi
64                 APPEND whatever
66         # A very dense operating system
67         LABEL brick
68                 MENU LABEL ^Windows CE/ME/NT
69                 KERNEL chain.c32
70                 APPEND hd0 2
72         The ^ symbol in a MENU LABEL statement defines a hotkey.
73         The hotkey will be highlighted in the menu and will move the
74         menu cursor immediately to that entry.
76         Reusing hotkeys is disallowed, subsequent entries will not be
77         highlighted, and will not work.
79         Keep in mind that the LABELs, not MENU LABELs, must be unique,
80         or odd things will happen to the command-line.
83 MENU INDENT count
85         (Only valid after a LABEL statement.)
86         Will add "count" spaces in front of the displayed menu entry.
88 MENU DISABLE
90         (Only valid after a LABEL statement.)
91         Makes the entry unselectable.  This allows you to make a
92         section in your menu with different options below it.
93         for example:
95         # Entries for network boots
96         LABEL -
97                 MENU LABEL Network:
98                 MENU DISABLE
100         # Soft Cap Linux
101         LABEL softcap
102                 MENU LABEL Soft Cap ^Linux 9.6.36
103                 MENU INDENT 1
104                 KERNEL softcap-9.6.36.bzi
105                 APPEND whatever
107         # Dos 6.22
108         LABEL dos
109                 MENU LABEL ^Dos 6.22
110                 MENU INDENT 1
111                 KERNEL memdisk
112                 APPEND initrd=dos622.imz
114         # Separator
115         MENU SEPARATOR
117         # Entries for local boots
118         LABEL -
119                 MENU LABEL Local:
120                 MENU DISABLE
122         # Windows 2000
123         LABEL w2k
124                 MENU LABEL ^Windows 2000
125                 MENU INDENT 1
126                 KERNEL chain.c32
127                 APPEND hd0 1
129         # Windows XP
130         LABEL xp
131                 MENU LABEL Windows ^XP
132                 MENU INDENT 1
133                 KERNEL chain.c32
134                 APPEND hd0 2
136 MENU HIDE
138         (Only valid after a LABEL statement.)
139         Suppresses a particular LABEL entry from the menu.
142 MENU DEFAULT
144         (Only valid after a LABEL statement.)
145         Indicates that this entry should be the default.  If no
146         default is specified, use the first one.
149 TEXT HELP
150 Help text ...
151 ... which can span multiple lines
152 ENDTEXT
154         (Only valid after a LABEL statement.)
156         Specifies a help text that should be displayed when a particular
157         selection is highlighted.
160 MENU PASSWD passwd
162         (Only valid after a LABEL statement.)
164         Sets a password on this menu entry.  "passwd" can be either a
165         cleartext password, a SHA-1 encrypted password (starting with
166         $4$), or and MD5 encrypted password (starting with $1$).
168         Use the included Perl scripts "sha1pass" or "md5pass" to
169         encrypt passwords.  MD5 passwords are compatible with most
170         Unix password file utilities; SHA-1 passwords are probably
171         unique to SYSLINUX.  Obviously, if you don't encrypt your
172         passwords they will not be very secure at all.
174         If you are using passwords, you want to make sure you also use
175         the settings "NOESCAPE 1", "PROMPT 0", and either set
176         "ALLOWOPTIONS 0" or use a master password (see below.)
178         If passwd is an empty string, this menu entry can only be
179         unlocked with the master password.
182 MENU MASTER PASSWD passwd
184         Sets a master password.  This password can be used to boot any
185         menu entry, and is required for the [Tab] and [Esc] keys to
186         work.
189 MENU BACKGROUND background
191         For vesamenu.c32, sets the background image.  The background
192         can either be a color (see MENU COLOR) or the name of an image
193         file, which should be 640x480 pixels and either in PNG or JPEG
194         format.
197 MENU BEGIN [tagname]
198 MENU END
200         Begin/end a submenu.  The entries between MENU BEGIN and MENU
201         END form a submenu, which is marked with a > mark on the right
202         hand of the screen.  Submenus inherit the properties of their
203         parent menus, but can override them, and can thus have their
204         own backgrounds, master passwords, titles, timeouts, messages
205         and so forth.
208 MENU GOTO tagname
210         (Only valid after a LABEL statement.)
212         This label will transfer to the named submenu instead of
213         booting anything.  To transfer to the top-level menu, specify
214         "menu goto .top".
217 MENU EXIT [tagname]
219         (Only valid after a label statement inside MENU BEGIN ...
220         MENU END)
222         Exit to the next higher menu, or, if tagname is specified, to
223         the named menu.
226 MENU QUIT
228         (Only valid after a LABEL statement.)
230         This label quits the menu system.
232         WARNING: if MENU MASTER PASSWD or ALLOWOPTIONS 0 is set, this
233         will still allow exiting to the CLI; however, a separate MENU
234         PASSWD can of course be set for this label.
237 MENU START
239         (Only valid inside MENU BEGIN ... MENU END)
241         Indicates that the menu system should start at the menu being
242         defined instead of at the top-level menu.
245 INCLUDE filename [tagname]
246 MENU INCLUDE filename [tagname]
248         Include the contents of the configuration file filename at
249         this point.
251         In the case of MENU INCLUDE, the included data is only seen by
252         the menu system; the core syslinux code does not parse this
253         command, so any labels defined in it are unavailable.
255         If a tagname is included, the whole file is considered to have
256         been bracketed with a MENU BEGIN tagname ... MENU END pair,
257         and will therefore show up as a submenu.
260 MENU AUTOBOOT message
262         Replaces the message "Automatic boot in # second{,s}...".  The
263         symbol # is replaced with the number of seconds remaining.
264         The syntax "{singular,[dual,]plural}" can be used to conjugate
265         appropriately.
268 MENU TABMSG message
270         Replaces the message "Press [Tab] to edit options".
273 MENU NOTABMSG message
275         Takes the place of the TABMSG message if option editing is
276         disabled.  Defaults to blank.
279 MENU PASSPROMPT message
281         Replaces the message "Password required".
284 MENU COLOR element ansi foreground background shadow
286         Sets the color of element "element" to the specified color
287         sequence:
289         screen          Rest of the screen
290         border          Border area
291         title           Title bar
292         unsel           Unselected menu item
293         hotkey          Unselected hotkey
294         sel             Selection bar
295         hotsel          Selected hotkey
296         disabled        Disabled menu item
297         scrollbar       Scroll bar
298         tabmsg          Press [Tab] message
299         cmdmark         Command line marker
300         cmdline         Command line
301         pwdborder       Password box border
302         pwdheader       Password box header
303         pwdentry        Password box contents
304         timeout_msg     Timeout message
305         timeout         Timeout counter
306         help            Help text
307         msgXX           Message (F-key) file attribute XX
309         ... where XX is two hexadecimal digits (the "plain text" is 07).
311         "ansi" is a sequence of semicolon-separated ECMA-48 Set
312         Graphics Rendition (<ESC>[m) sequences:
314         0     reset all attributes to their defaults
315         1     set bold
316         4     set underscore (simulated with color on a color display)
317         5     set blink
318         7     set reverse video
319         22    set normal intensity
320         24    underline off
321         25    blink off
322         27    reverse video off
323         30    set black foreground
324         31    set red foreground
325         32    set green foreground
326         33    set brown foreground
327         34    set blue foreground
328         35    set magenta foreground
329         36    set cyan foreground
330         37    set white foreground
331         38    set underscore on, set default foreground color
332         39    set underscore off, set default foreground color
333         40    set black background
334         41    set red background
335         42    set green background
336         43    set brown background
337         44    set blue background
338         45    set magenta background
339         46    set cyan background
340         47    set white background
341         49    set default background color
343         These are used (a) in text mode, and (b) on the serial
344         console.
346         "foreground" and "background" are color codes in #AARRGGBB
347         notation, where AA RR GG BB are hexadecimal digits for alpha
348         (opacity), red, green and blue, respectively.  #00000000
349         represents fully transparent, and #ffffffff represents opaque
350         white.
352         "shadow" controls the handling of the graphical console text
353         shadow.  Permitted values are "none" (no shadowing), "std" or
354         "standard" (standard shadowing - foreground pixels are
355         raised), "all" (both background and foreground raised), and
356         "rev" or "reverse" (background pixels are raised.)
358         If any field is set to "*" or omitted (at the end of the line)
359         then that field is left unchanged.
362         The current defaults are:
364         menu color screen       37;40      #80ffffff #00000000 std
365         menu color border       30;44      #40000000 #00000000 std
366         menu color title        1;36;44    #c00090f0 #00000000 std
367         menu color unsel        37;44      #90ffffff #00000000 std
368         menu color hotkey       1;37;44    #ffffffff #00000000 std
369         menu color sel          7;37;40    #e0000000 #20ff8000 all
370         menu color hotsel       1;7;37;40  #e0400000 #20ff8000 all
371         menu color disabled     1;30;44    #60cccccc #00000000 std
372         menu color scrollbar    30;44      #40000000 #00000000 std
373         menu color tabmsg       31;40      #90ffff00 #00000000 std
374         menu color cmdmark      1;36;40    #c000ffff #00000000 std
375         menu color cmdline      37;40      #c0ffffff #00000000 std
376         menu color pwdborder    30;47      #80ffffff #20ffffff std
377         menu color pwdheader    31;47      #80ff8080 #20ffffff std
378         menu color pwdentry     30;47      #80ffffff #20ffffff std
379         menu color timeout_msg  37;40      #80ffffff #00000000 std
380         menu color timeout      1;37;40    #c0ffffff #00000000 std
381         menu color help         37;40      #c0ffffff #00000000 std
382         menu color msg07        37;40      #90ffffff #00000000 std
385 MENU MSGCOLOR fg_filter bg_filter shadow
387         Sets *all* the msgXX colors to a color scheme derived from the
388         fg_filter and bg_filter values.  Background color zero is
389         always treated as transparent.  The default corresponds to:
391         menu msgcolor #90ffffff #80ffffff std
393         This directive should come before any directive that
394         customizes individual msgXX colors.
397 MENU WIDTH 80
398 MENU MARGIN 10
399 MENU PASSWORDMARGIN 3
400 MENU ROWS 12
401 MENU TABMSGROW 18
402 MENU CMDLINEROW 18
403 MENU ENDROW -1
404 MENU PASSWORDROW 11
405 MENU TIMEOUTROW 20
406 MENU HELPMSGROW 22
407 MENU HELPMSGENDROW -1
408 MENU HIDDENROW -2
409 MENU HSHIFT 0
410 MENU VSHIFT 0
412         These options control the layout of the menu on the screen.
413         The values above are the defaults.
415         A negative value is relative to the calculated length of the
416         screen (25 for text mode, 28 for VESA graphics mode.)
419 F1 textfile background
421 F12 textfile background
423         Displays full-screen help (also available at the command line.)
424         The same control code sequences as in the command line
425         interface are supported, although some are ignored.
427         Additionally, a second argument allows a different background
428         image (see MENU BACKGROUND for supported formats) to be displayed.
431 The menu system honours the TIMEOUT command; if TIMEOUT is specified
432 it will execute the ONTIMEOUT command if one exists, otherwise it will
433 pick the default menu option.
435 Normally, the user can press [Tab] to edit the menu entry, and [Esc]
436 to return to the SYSLINUX command line.  However, if the configuration
437 file specifies ALLOWOPTIONS 0, these keys will be disabled, and if
438 MENU MASTER PASSWD is set, they require the master password.
440 The simple menu system supports serial console, using the normal
441 SERIAL directive.  However, it can be quite slow over a slow serial
442 link; you probably want to set your baudrate to 38400 or higher if
443 possible.  It requires a Linux/VT220/ANSI-compatible terminal on the
444 other end.
447         +++ USING AN ALTERNATE CONFIGURATION FILE +++
450 It is also possible to load a secondary configuration file, to get to
451 another menu.  To do that, invoke menu.c32 with the name of the
452 secondary configuration file.
454 LABEL othermenu
455         MENU LABEL Another Menu
456         KERNEL menu.c32
457         APPEND othermenu.conf
459 If you specify more than one file, they will all be read, in the order
460 specified.  The dummy filename ~ (tilde) is replaced with the filename
461 of the main configuration file.
463 # The file graphics.conf contains common color and layout commands for
464 # all menus.
465 LABEL othermenu
466         MENU LABEL Another Menu
467         KERNEL vesamenu.c32
468         APPEND graphics.conf othermenu.conf
470 # Return to the main menu
471 LABEL mainmenu
472         MENU LABEL Return to Main Menu
473         KERNEL vesamenu.c32
474         APPEND graphics.conf ~
476 See also the MENU INCLUDE directive above.