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