com32: export the filename of a com32 module to the module itself
[profile/ivi/syslinux.git] / doc / menu.txt
1 There are two menu systems included with Syslinux, the advanced menu
2 system, and the simple menu system.
3
4
5 +++ THE ADVANCED MENU SYSTEM +++
6
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.
12
13 The advanced menu system doesn't support serial console at this time.
14
15 See menu/README for more information.
16
17
18 +++ THE SIMPLE MENU SYSTEM +++
19
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.
24
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:
30
31 UI menu.c32
32
33
34 There are a few menu additions to the configuration file, all starting
35 with the keywords MENU or TEXT; like the rest of the Syslinux config
36 file language, it is case insensitive:
37
38
39 MENU TITLE title
40
41         Give the menu a title.  The title is presented at the top of
42         the menu.
43
44
45 MENU HIDDEN
46
47         Do not display the actual menu unless the user presses a key.
48         All that is displayed is a timeout message.
49
50
51 MENU CLEAR
52
53         Clear the screen when exiting the menu, instead of leaving the
54         menu displayed.  For vesamenu, this means the graphical
55         background is still displayed without the menu itself for as
56         long as the screen remains in graphics mode.
57
58
59 MENU SHIFTKEY
60
61         Exit the menu system immediately unless either the Shift or Alt
62         key is pressed, or Caps Lock or Scroll Lock is set.
63
64
65 MENU SEPARATOR
66
67         Insert an empty line in the menu.
68
69
70 MENU LABEL label
71
72         (Only valid after a LABEL statement.)
73         Changes the label displayed for a specific entry.  This allows
74         you to have a label that isn't suitable for the command line,
75         for example:
76
77         # Soft Cap Linux
78         LABEL softcap
79                 MENU LABEL Soft Cap ^Linux 9.6.36
80                 KERNEL softcap-9.6.36.bzi
81                 APPEND whatever
82
83         # A very dense operating system
84         LABEL brick
85                 MENU LABEL ^Windows CE/ME/NT
86                 KERNEL chain.c32
87                 APPEND hd0 2
88
89         The ^ symbol in a MENU LABEL statement defines a hotkey.
90         The hotkey will be highlighted in the menu and will move the
91         menu cursor immediately to that entry.
92
93         Reusing hotkeys is disallowed, subsequent entries will not be
94         highlighted, and will not work.
95
96         Keep in mind that the LABELs, not MENU LABELs, must be unique,
97         or odd things will happen to the command-line.
98
99
100 MENU INDENT count
101
102         (Only valid after a LABEL statement.)
103         Will add "count" spaces in front of the displayed menu entry.
104
105
106 MENU DISABLE
107
108         (Only valid after a LABEL statement.)
109         Makes the entry unselectable.  This allows you to make a
110         section in your menu with different options below it.
111         for example:
112
113         # Entries for network boots
114         LABEL -
115                 MENU LABEL Network:
116                 MENU DISABLE
117
118         # Soft Cap Linux
119         LABEL softcap
120                 MENU LABEL Soft Cap ^Linux 9.6.36
121                 MENU INDENT 1
122                 KERNEL softcap-9.6.36.bzi
123                 APPEND whatever
124
125         # Dos 6.22
126         LABEL dos
127                 MENU LABEL ^Dos 6.22
128                 MENU INDENT 1
129                 KERNEL memdisk
130                 APPEND initrd=dos622.imz
131
132         # Separator
133         MENU SEPARATOR
134
135         # Entries for local boots
136         LABEL -
137                 MENU LABEL Local:
138                 MENU DISABLE
139
140         # Windows 2000
141         LABEL w2k
142                 MENU LABEL ^Windows 2000
143                 MENU INDENT 1
144                 KERNEL chain.c32
145                 APPEND hd0 1
146
147         # Windows XP
148         LABEL xp
149                 MENU LABEL Windows ^XP
150                 MENU INDENT 1
151                 KERNEL chain.c32
152                 APPEND hd0 2
153
154 MENU HIDE
155
156         (Only valid after a LABEL statement.)
157         Suppresses a particular LABEL entry from the menu.
158
159
160 MENU DEFAULT
161
162         (Only valid after a LABEL statement.)
163
164         Indicates that this entry should be the default for this
165         particular submenu.  See also the DEFAULT directive below.
166
167
168 TEXT HELP
169 Help text ...
170 ... which can span multiple lines
171 ENDTEXT
172
173         (Only valid after a LABEL statement.)
174
175         Specifies a help text that should be displayed when a particular
176         selection is highlighted.
177
178
179 MENU PASSWD passwd
180
181         (Only valid after a LABEL statement.)
182
183         Sets a password on this menu entry.  "passwd" can be either a
184         cleartext password or a password encrypted with one of the
185         following algorithms:
186
187         MD5             (Signature: $1$)
188         SHA-1           (Signature: $4$)
189         SHA-2-256       (Signature: $5$)
190         SHA-2-512       (Signature: $6$)
191
192         Use the included Perl scripts "sha1pass" or "md5pass" to
193         encrypt passwords.  MD5 passwords are compatible with most
194         Unix password file utilities; SHA-1 passwords are probably
195         unique to Syslinux; SHA-2 passwords are compatible with very
196         recent Linux distributions.  Obviously, if you don't encrypt
197         your passwords they will not be very secure at all.
198
199         If you are using passwords, you want to make sure you also use
200         the settings "NOESCAPE 1", "PROMPT 0", and either set
201         "ALLOWOPTIONS 0" or use a master password (see below.)
202
203         If passwd is an empty string, this menu entry can only be
204         unlocked with the master password.
205
206
207 MENU MASTER PASSWD passwd
208
209         Sets a master password.  This password can be used to boot any
210         menu entry, and is required for the [Tab] and [Esc] keys to
211         work.
212
213
214 MENU RESOLUTION height width
215
216         Requests a specific screen resolution when in graphics mode.
217         The default is "640 480" corresponding to a resolution of
218         640x480 pixels, which all VGA-compatible monitors should be
219         able to display.
220
221         If the selected resolution is unavailable, the text mode menu
222         is displayed instead.
223
224
225 MENU BACKGROUND background
226
227         For vesamenu.c32, sets the background image.  The background
228         can either be a color (see MENU COLOR) or the name of an image
229         file, which should be the size of the screen (normally 640x480
230         pixels, but see MENU RESOLUTION) and either in PNG, JPEG or
231         LSS16 format.
232
233
234 MENU BEGIN [tagname]
235 MENU END
236
237         Begin/end a submenu.  The entries between MENU BEGIN and MENU
238         END form a submenu, which is marked with a > mark on the right
239         hand of the screen.  Submenus inherit the properties of their
240         parent menus, but can override them, and can thus have their
241         own backgrounds, master passwords, titles, timeouts, messages
242         and so forth.
243
244
245 MENU GOTO tagname
246
247         (Only valid after a LABEL statement.)
248
249         This label will transfer to the named submenu instead of
250         booting anything.  To transfer to the top-level menu, specify
251         "menu goto .top".
252
253
254 MENU EXIT [tagname]
255
256         (Only valid after a label statement inside MENU BEGIN ...
257         MENU END)
258
259         Exit to the next higher menu, or, if tagname is specified, to
260         the named menu.
261
262
263 MENU QUIT
264
265         (Only valid after a LABEL statement.)
266
267         This label quits the menu system.
268
269         WARNING: if MENU MASTER PASSWD or ALLOWOPTIONS 0 is set, this
270         will still allow exiting to the CLI; however, a separate MENU
271         PASSWD can of course be set for this label.
272
273
274 MENU START
275
276         (Only valid inside MENU BEGIN ... MENU END)
277
278         Indicates that the menu system should start at the menu being
279         defined instead of at the top-level menu.  See also the
280         DEFAULT directive below.
281
282
283 DEFAULT label
284
285         Set the global default.  If "label" points into a submenu,
286         that menu becomes the start menu; in other words, this
287         directive has the same effect as both MENU DEFAULT and MENU
288         START.
289
290         For backwards compatibility with earlier versions of Syslinux,
291         this directive is ignored unless the configuration file also
292         contains a UI directive.
293
294         Note: the CLI accepts options after the label, or even a
295         non-label.  The menu system does not support that.
296
297
298 MENU SAVE
299 MENU NOSAVE
300
301         Remember the last entry selected and make that the default for
302         the next boot.  A password-protected menu entry is *not*
303         saved.  This requires the ADV data storage mechanism, which is
304         currently only implemented for EXTLINUX, although the other
305         Syslinux derivatives will accept the command (and ignore it.)
306
307         NOTE: MENU SAVE stores the LABEL tag of the selected entry;
308         this mechanism therefore relies on LABEL tags being unique.
309         On the other hand, it handles changes in the configuration
310         file gracefully.
311
312         The MENU SAVE information can be cleared with
313         "extlinux --reset-adv <bootdir>".
314
315         A MENU SAVE or MENU NOSAVE at the top of a (sub)menu affects
316         all entries underneath that (sub)menu except those that in
317         turn have MENU SAVE or MENU NOSAVE declared.  This can be used
318         to only save certain entires when selected.
319
320
321 INCLUDE filename [tagname]
322 MENU INCLUDE filename [tagname]
323
324         Include the contents of the configuration file filename at
325         this point.
326
327         In the case of MENU INCLUDE, the included data is only seen by
328         the menu system; the core syslinux code does not parse this
329         command, so any labels defined in it are unavailable.
330
331         If a tagname is included, the whole file is considered to have
332         been bracketed with a MENU BEGIN tagname ... MENU END pair,
333         and will therefore show up as a submenu.
334
335
336 MENU AUTOBOOT message
337
338         Replaces the message "Automatic boot in # second{,s}...".  The
339         symbol # is replaced with the number of seconds remaining.
340         The syntax "{singular,[dual,]plural}" can be used to conjugate
341         appropriately.
342
343
344 MENU TABMSG message
345
346         Replaces the message "Press [Tab] to edit options".
347
348
349 MENU NOTABMSG message
350
351         Takes the place of the TABMSG message if option editing is
352         disabled.  Defaults to blank.
353
354
355 MENU PASSPROMPT message
356
357         Replaces the message "Password required".
358
359
360 MENU COLOR element ansi foreground background shadow
361
362         Sets the color of element "element" to the specified color
363         sequence:
364
365         screen          Rest of the screen
366         border          Border area
367         title           Title bar
368         unsel           Unselected menu item
369         hotkey          Unselected hotkey
370         sel             Selection bar
371         hotsel          Selected hotkey
372         disabled        Disabled menu item
373         scrollbar       Scroll bar
374         tabmsg          Press [Tab] message
375         cmdmark         Command line marker
376         cmdline         Command line
377         pwdborder       Password box border
378         pwdheader       Password box header
379         pwdentry        Password box contents
380         timeout_msg     Timeout message
381         timeout         Timeout counter
382         help            Help text
383         msgXX           Message (F-key) file attribute XX
384
385         ... where XX is two hexadecimal digits (the "plain text" is 07).
386
387         "ansi" is a sequence of semicolon-separated ECMA-48 Set
388         Graphics Rendition (<ESC>[m) sequences:
389
390         0     reset all attributes to their defaults
391         1     set bold
392         4     set underscore (simulated with color on a color display)
393         5     set blink
394         7     set reverse video
395         22    set normal intensity
396         24    underline off
397         25    blink off
398         27    reverse video off
399         30    set black foreground
400         31    set red foreground
401         32    set green foreground
402         33    set brown foreground
403         34    set blue foreground
404         35    set magenta foreground
405         36    set cyan foreground
406         37    set white foreground
407         38    set underscore on, set default foreground color
408         39    set underscore off, set default foreground color
409         40    set black background
410         41    set red background
411         42    set green background
412         43    set brown background
413         44    set blue background
414         45    set magenta background
415         46    set cyan background
416         47    set white background
417         49    set default background color
418
419         These are used (a) in text mode, and (b) on the serial
420         console.
421
422         "foreground" and "background" are color codes in #AARRGGBB
423         notation, where AA RR GG BB are hexadecimal digits for alpha
424         (opacity), red, green and blue, respectively.  #00000000
425         represents fully transparent, and #ffffffff represents opaque
426         white.
427
428         "shadow" controls the handling of the graphical console text
429         shadow.  Permitted values are "none" (no shadowing), "std" or
430         "standard" (standard shadowing - foreground pixels are
431         raised), "all" (both background and foreground raised), and
432         "rev" or "reverse" (background pixels are raised.)
433
434         If any field is set to "*" or omitted (at the end of the line)
435         then that field is left unchanged.
436
437
438         The current defaults are:
439
440         menu color screen       37;40      #80ffffff #00000000 std
441         menu color border       30;44      #40000000 #00000000 std
442         menu color title        1;36;44    #c00090f0 #00000000 std
443         menu color unsel        37;44      #90ffffff #00000000 std
444         menu color hotkey       1;37;44    #ffffffff #00000000 std
445         menu color sel          7;37;40    #e0000000 #20ff8000 all
446         menu color hotsel       1;7;37;40  #e0400000 #20ff8000 all
447         menu color disabled     1;30;44    #60cccccc #00000000 std
448         menu color scrollbar    30;44      #40000000 #00000000 std
449         menu color tabmsg       31;40      #90ffff00 #00000000 std
450         menu color cmdmark      1;36;40    #c000ffff #00000000 std
451         menu color cmdline      37;40      #c0ffffff #00000000 std
452         menu color pwdborder    30;47      #80ffffff #20ffffff std
453         menu color pwdheader    31;47      #80ff8080 #20ffffff std
454         menu color pwdentry     30;47      #80ffffff #20ffffff std
455         menu color timeout_msg  37;40      #80ffffff #00000000 std
456         menu color timeout      1;37;40    #c0ffffff #00000000 std
457         menu color help         37;40      #c0ffffff #00000000 std
458         menu color msg07        37;40      #90ffffff #00000000 std
459
460
461 MENU MSGCOLOR fg_filter bg_filter shadow
462
463         Sets *all* the msgXX colors to a color scheme derived from the
464         fg_filter and bg_filter values.  Background color zero is
465         always treated as transparent.  The default corresponds to:
466
467         menu msgcolor #90ffffff #80ffffff std
468
469         This directive should come before any directive that
470         customizes individual msgXX colors.
471
472
473 MENU WIDTH 80
474 MENU MARGIN 10
475 MENU PASSWORDMARGIN 3
476 MENU ROWS 12
477 MENU TABMSGROW 18
478 MENU CMDLINEROW 18
479 MENU ENDROW -1
480 MENU PASSWORDROW 11
481 MENU TIMEOUTROW 20
482 MENU HELPMSGROW 22
483 MENU HELPMSGENDROW -1
484 MENU HIDDENROW -2
485 MENU HSHIFT 0
486 MENU VSHIFT 0
487
488         These options control the layout of the menu on the screen.
489         The values above are the defaults.
490
491         A negative value is relative to the calculated length of the
492         screen (25 for text mode, 28 for VESA graphics mode.)
493
494
495 F1 textfile background
496 ...
497 F12 textfile background
498
499         Displays full-screen help (also available at the command line.)
500         The same control code sequences as in the command line
501         interface are supported, although some are ignored.
502
503         Additionally, a second argument allows a different background
504         image (see MENU BACKGROUND for supported formats) to be displayed.
505
506
507 The menu system honours the TIMEOUT command; if TIMEOUT is specified
508 it will execute the ONTIMEOUT command if one exists, otherwise it will
509 pick the default menu option.  WARNING: the timeout action will bypass
510 password protection even if one is set for the specified or default
511 entry!
512
513 Normally, the user can press [Tab] to edit the menu entry, and [Esc]
514 to return to the Syslinux command line.  However, if the configuration
515 file specifies ALLOWOPTIONS 0, these keys will be disabled, and if
516 MENU MASTER PASSWD is set, they require the master password.
517
518 The simple menu system supports serial console, using the normal
519 SERIAL directive.  However, it can be quite slow over a slow serial
520 link; you probably want to set your baudrate to 38400 or higher if
521 possible.  It requires a Linux/VT220/ANSI-compatible terminal on the
522 other end.
523
524
525         +++ USING AN ALTERNATE CONFIGURATION FILE +++
526
527
528 It is also possible to load a secondary configuration file, to get to
529 another menu.  To do that, invoke menu.c32 with the name of the
530 secondary configuration file.
531
532 LABEL othermenu
533         MENU LABEL Another Menu
534         KERNEL menu.c32
535         APPEND othermenu.conf
536
537 If you specify more than one file, they will all be read, in the order
538 specified.  The dummy filename ~ (tilde) is replaced with the filename
539 of the main configuration file.
540
541 # The file graphics.conf contains common color and layout commands for
542 # all menus.
543 LABEL othermenu
544         MENU LABEL Another Menu
545         KERNEL vesamenu.c32
546         APPEND graphics.conf othermenu.conf
547
548 # Return to the main menu
549 LABEL mainmenu
550         MENU LABEL Return to Main Menu
551         KERNEL vesamenu.c32
552         APPEND graphics.conf ~
553
554 See also the MENU INCLUDE directive above.