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