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 remainder 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 immediately launched.
 115
 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.
 119
 120         Keep in mind that the LABELs, not MENU LABELs, must be unique,
 121         or odd things will happen to the command-line.
 122
 123
 124 MENU INDENT count
 125
 126         (Only valid after a LABEL statement.)
 127         Add "count" spaces in front of the displayed menu entry.
 128
 129
 130 MENU DISABLE
 131
 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.
 135         For example:
 136
 137         # Entries for network boots
 138         LABEL -
 139                 MENU LABEL Network:
 140                 MENU DISABLE
 141
 142         # Soft Cap Linux
 143         LABEL softcap
 144                 MENU LABEL Soft Cap ^Linux 9.6.36
 145                 MENU INDENT 1
 146                 KERNEL softcap-9.6.36.bzi
 147                 APPEND whatever
 148
 149         # Dos 6.22
 150         LABEL dos
 151                 MENU LABEL ^Dos 6.22
 152                 MENU INDENT 1
 153                 KERNEL memdisk
 154                 APPEND initrd=dos622.imz
 155
 156         # Separator
 157         MENU SEPARATOR
 158
 159         # Entries for local boots
 160         LABEL -
 161                 MENU LABEL Local:
 162                 MENU DISABLE
 163
 164         # Windows 2000
 165         LABEL w2k
 166                 MENU LABEL ^Windows 2000
 167                 MENU INDENT 1
 168                 KERNEL chain.c32
 169                 APPEND hd0 1
 170
 171         # Windows XP
 172         LABEL xp
 173                 MENU LABEL Windows ^XP
 174                 MENU INDENT 1
 175                 KERNEL chain.c32
 176                 APPEND hd0 2
 177
 178 MENU HIDE
 179
 180         (Only valid after a LABEL statement.)
 181         Suppress a particular LABEL entry from the menu.
 182
 183
 184 MENU DEFAULT
 185
 186         (Only valid after a LABEL statement.)
 187
 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.
 191
 192
 193 TEXT HELP
 194 Help text ...
 195 ... which can span multiple lines
 196 ENDTEXT
 197
 198         (Only valid after a LABEL statement.)
 199
 200         Specify a help text that should be displayed when a particular
 201         selection is highlighted.
 202
 203
 204 MENU PASSWD passwd
 205
 206         (Only valid after a LABEL statement.)
 207
 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:
 211
 212         MD5             (Signature: $1$)
 213         SHA-1           (Signature: $4$)
 214         SHA-2-256       (Signature: $5$)
 215         SHA-2-512       (Signature: $6$)
 216
 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.
 223
 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).
 227
 228         If passwd is an empty string, this menu entry can only be
 229         unlocked with the master password.
 230
 231
 232 MENU MASTER PASSWD passwd
 233
 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.
 237
 238
 239 MENU RESOLUTION width height
 240
 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
 244         able to display.
 245
 246         If the requested resolution is unavailable, the text mode menu
 247         is displayed instead.
 248
 249
 250 MENU BACKGROUND background
 251
 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
 256         LSS16 format.
 257
 258         Note: When using an image file as background, its resolution
 259         should match the values used in MENU RESOLUTION.
 260
 261
 262 MENU BEGIN [tagname]
 263 MENU END
 264
 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
 270         and so forth.
 271
 272
 273 MENU GOTO tagname
 274
 275         (Only valid after a LABEL statement.)
 276
 277         Transfer to the named submenu instead of booting anything.
 278         To transfer to the top-level menu, specify "menu goto .top".
 279
 280
 281 MENU EXIT [tagname]
 282
 283         (Only valid after a LABEL statement inside MENU BEGIN ...
 284         MENU END)
 285
 286         Exit to the next higher menu, or, if tagname is specified, to
 287         the named menu.
 288
 289
 290 MENU QUIT
 291
 292         (Only valid after a LABEL statement.)
 293
 294         Quit the menu system.
 295
 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
 299         label / menu entry.
 300
 301
 302 MENU START
 303
 304         (Only valid inside MENU BEGIN ... MENU END)
 305
 306         Define the starting menu for the menu system, instead of
 307         starting at the top-level menu.  See also the DEFAULT directive.
 308
 309
 310 DEFAULT label
 311
 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
 315         START.
 316
 317         For backwards compatibility with earlier versions of Syslinux,
 318         this behavior is ignored unless the configuration file also
 319         contains a UI directive.
 320
 321         Note: the CLI accepts options after the label, or even a
 322         non-label.  The menu system does not support that.
 323
 324
 325 MENU SAVE
 326 MENU NOSAVE
 327
 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).
 333
 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
 337         file gracefully.
 338
 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.
 343
 344         The MENU SAVE information can be fully cleared with
 345         "extlinux --reset-adv <bootdir>".
 346
 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
 351         executed.
 352
 353
 354 INCLUDE filename [tagname]
 355 MENU INCLUDE filename [tagname]
 356
 357         Include the contents of the "filename" configuration file at
 358         this point.
 359
 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.
 363
 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.
 367
 368
 369 MENU AUTOBOOT message
 370
 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
 374         appropriately.
 375
 376
 377 MENU TABMSG message
 378
 379         Replace the message "Press [Tab] to edit options".
 380
 381
 382 MENU NOTABMSG message
 383
 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.
 387
 388
 389 MENU PASSPROMPT message
 390
 391         Replace the message "Password required".
 392
 393
 394 MENU COLOR element ansi foreground background shadow
 395
 396         Set the color of element "element" to the specified color
 397         sequence:
 398
 399         screen          Rest of the screen
 400         border          Border area
 401         title           Title bar
 402         unsel           Unselected menu item
 403         hotkey          Unselected hotkey
 404         sel             Selection bar
 405         hotsel          Selected hotkey
 406         disabled        Disabled menu item
 407         scrollbar       Scroll bar
 408         tabmsg          Press [Tab] message
 409         cmdmark         Command line marker
 410         cmdline         Command line
 411         pwdborder       Password box border
 412         pwdheader       Password box header
 413         pwdentry        Password box contents
 414         timeout_msg     Timeout message
 415         timeout         Timeout counter
 416         help            Help text
 417         msgXX           Message (F-key) file attribute XX
 418
 419         ... where XX is two hexadecimal digits (the "plain text" is 07).
 420
 421         "ansi" is a sequence of semicolon-separated ECMA-48 Set
 422         Graphics Rendition (<ESC>[m) sequences:
 423
 424         0     reset all attributes to their defaults
 425         1     set bold
 426         4     set underscore (simulated with color on a color display)
 427         5     set blink
 428         7     set reverse video
 429         22    set normal intensity
 430         24    underline off
 431         25    blink off
 432         27    reverse video off
 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
 452
 453         These are used (a) in text mode, and (b) on the serial
 454         console.
 455
 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
 460         white.
 461
 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).
 467
 468         If any field is set to "*" or omitted (at the end of the line)
 469         then that field is left unchanged.
 470
 471
 472         The current defaults are:
 473
 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
 493
 494
 495 MENU MSGCOLOR fg_filter bg_filter shadow
 496
 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:
 500
 501         menu msgcolor #90ffffff #80ffffff std
 502
 503         This directive should come before any directive that
 504         customizes individual msgXX colors.
 505
 506
 507 MENU WIDTH 80
 508 MENU MARGIN 10
 509 MENU PASSWORDMARGIN 3
 510 MENU ROWS 12
 511 MENU TABMSGROW 18
 512 MENU CMDLINEROW 18
 513 MENU ENDROW -1
 514 MENU PASSWORDROW 11
 515 MENU TIMEOUTROW 20
 516 MENU HELPMSGROW 22
 517 MENU HELPMSGENDROW -1
 518 MENU HIDDENROW -2
 519 MENU HSHIFT 0
 520 MENU VSHIFT 0
 521
 522         These options control the layout of the menu on the screen.
 523         The values above are the defaults.
 524
 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).
 527
 528
 529 F1 textfile [background]
 530 ...
 531 F12 textfile [background]
 532
 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.
 536
 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.
 541
 542
 543 MENU HELP textfile [background]
 544
 545         Create a menu entry which, when selected, displays
 546         full-screen help in the same way as the F-key help.
 547
 548
 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!
 554
 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.
 559
 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
 564 other end.
 565
 566
 567         +++ USING AN ALTERNATE CONFIGURATION FILE +++
 568
 569
 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.
 573
 574 LABEL othermenu
 575         MENU LABEL Another Menu
 576         KERNEL menu.c32
 577         APPEND othermenu.conf
 578
 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.
 582
 583 # The file graphics.conf contains common color and layout commands for
 584 # all menus.
 585 LABEL othermenu
 586         MENU LABEL Another Menu
 587         KERNEL vesamenu.c32
 588         APPEND graphics.conf othermenu.conf
 589
 590 # Return to the main menu
 591 LABEL mainmenu
 592         MENU LABEL Return to Main Menu
 593         KERNEL vesamenu.c32
 594         APPEND graphics.conf ~
 595
 596 See also the MENU INCLUDE directive above.