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         NOTE: In software RAID-1 setups MENU SAVE only stores the
 313         default label on the actual boot disk.  This may lead to
 314         inconsistent reads from the array, or unexpectedly change the
 315         default label after array resynchronization or disk failure.
 316
 317         The MENU SAVE information can be fully cleared with
 318         "extlinux --reset-adv <bootdir>".
 319
 320         A MENU SAVE or MENU NOSAVE at the top of a (sub)menu affects
 321         all entries underneath that (sub)menu except those that in
 322         turn have MENU SAVE or MENU NOSAVE declared.  This can be used
 323         to only save certain entires when selected.
 324
 325
 326 INCLUDE filename [tagname]
 327 MENU INCLUDE filename [tagname]
 328
 329         Include the contents of the configuration file filename at
 330         this point.
 331
 332         In the case of MENU INCLUDE, the included data is only seen by
 333         the menu system; the core syslinux code does not parse this
 334         command, so any labels defined in it are unavailable.
 335
 336         If a tagname is included, the whole file is considered to have
 337         been bracketed with a MENU BEGIN tagname ... MENU END pair,
 338         and will therefore show up as a submenu.
 339
 340
 341 MENU AUTOBOOT message
 342
 343         Replaces the message "Automatic boot in # second{,s}...".  The
 344         symbol # is replaced with the number of seconds remaining.
 345         The syntax "{singular,[dual,]plural}" can be used to conjugate
 346         appropriately.
 347
 348
 349 MENU TABMSG message
 350
 351         Replaces the message "Press [Tab] to edit options".
 352
 353
 354 MENU NOTABMSG message
 355
 356         Takes the place of the TABMSG message if option editing is
 357         disabled.  Defaults to blank.
 358
 359
 360 MENU PASSPROMPT message
 361
 362         Replaces the message "Password required".
 363
 364
 365 MENU COLOR element ansi foreground background shadow
 366
 367         Sets the color of element "element" to the specified color
 368         sequence:
 369
 370         screen          Rest of the screen
 371         border          Border area
 372         title           Title bar
 373         unsel           Unselected menu item
 374         hotkey          Unselected hotkey
 375         sel             Selection bar
 376         hotsel          Selected hotkey
 377         disabled        Disabled menu item
 378         scrollbar       Scroll bar
 379         tabmsg          Press [Tab] message
 380         cmdmark         Command line marker
 381         cmdline         Command line
 382         pwdborder       Password box border
 383         pwdheader       Password box header
 384         pwdentry        Password box contents
 385         timeout_msg     Timeout message
 386         timeout         Timeout counter
 387         help            Help text
 388         msgXX           Message (F-key) file attribute XX
 389
 390         ... where XX is two hexadecimal digits (the "plain text" is 07).
 391
 392         "ansi" is a sequence of semicolon-separated ECMA-48 Set
 393         Graphics Rendition (<ESC>[m) sequences:
 394
 395         0     reset all attributes to their defaults
 396         1     set bold
 397         4     set underscore (simulated with color on a color display)
 398         5     set blink
 399         7     set reverse video
 400         22    set normal intensity
 401         24    underline off
 402         25    blink off
 403         27    reverse video off
 404         30    set black foreground
 405         31    set red foreground
 406         32    set green foreground
 407         33    set brown foreground
 408         34    set blue foreground
 409         35    set magenta foreground
 410         36    set cyan foreground
 411         37    set white foreground
 412         38    set underscore on, set default foreground color
 413         39    set underscore off, set default foreground color
 414         40    set black background
 415         41    set red background
 416         42    set green background
 417         43    set brown background
 418         44    set blue background
 419         45    set magenta background
 420         46    set cyan background
 421         47    set white background
 422         49    set default background color
 423
 424         These are used (a) in text mode, and (b) on the serial
 425         console.
 426
 427         "foreground" and "background" are color codes in #AARRGGBB
 428         notation, where AA RR GG BB are hexadecimal digits for alpha
 429         (opacity), red, green and blue, respectively.  #00000000
 430         represents fully transparent, and #ffffffff represents opaque
 431         white.
 432
 433         "shadow" controls the handling of the graphical console text
 434         shadow.  Permitted values are "none" (no shadowing), "std" or
 435         "standard" (standard shadowing - foreground pixels are
 436         raised), "all" (both background and foreground raised), and
 437         "rev" or "reverse" (background pixels are raised.)
 438
 439         If any field is set to "*" or omitted (at the end of the line)
 440         then that field is left unchanged.
 441
 442
 443         The current defaults are:
 444
 445         menu color screen       37;40      #80ffffff #00000000 std
 446         menu color border       30;44      #40000000 #00000000 std
 447         menu color title        1;36;44    #c00090f0 #00000000 std
 448         menu color unsel        37;44      #90ffffff #00000000 std
 449         menu color hotkey       1;37;44    #ffffffff #00000000 std
 450         menu color sel          7;37;40    #e0000000 #20ff8000 all
 451         menu color hotsel       1;7;37;40  #e0400000 #20ff8000 all
 452         menu color disabled     1;30;44    #60cccccc #00000000 std
 453         menu color scrollbar    30;44      #40000000 #00000000 std
 454         menu color tabmsg       31;40      #90ffff00 #00000000 std
 455         menu color cmdmark      1;36;40    #c000ffff #00000000 std
 456         menu color cmdline      37;40      #c0ffffff #00000000 std
 457         menu color pwdborder    30;47      #80ffffff #20ffffff std
 458         menu color pwdheader    31;47      #80ff8080 #20ffffff std
 459         menu color pwdentry     30;47      #80ffffff #20ffffff std
 460         menu color timeout_msg  37;40      #80ffffff #00000000 std
 461         menu color timeout      1;37;40    #c0ffffff #00000000 std
 462         menu color help         37;40      #c0ffffff #00000000 std
 463         menu color msg07        37;40      #90ffffff #00000000 std
 464
 465
 466 MENU MSGCOLOR fg_filter bg_filter shadow
 467
 468         Sets *all* the msgXX colors to a color scheme derived from the
 469         fg_filter and bg_filter values.  Background color zero is
 470         always treated as transparent.  The default corresponds to:
 471
 472         menu msgcolor #90ffffff #80ffffff std
 473
 474         This directive should come before any directive that
 475         customizes individual msgXX colors.
 476
 477
 478 MENU WIDTH 80
 479 MENU MARGIN 10
 480 MENU PASSWORDMARGIN 3
 481 MENU ROWS 12
 482 MENU TABMSGROW 18
 483 MENU CMDLINEROW 18
 484 MENU ENDROW -1
 485 MENU PASSWORDROW 11
 486 MENU TIMEOUTROW 20
 487 MENU HELPMSGROW 22
 488 MENU HELPMSGENDROW -1
 489 MENU HIDDENROW -2
 490 MENU HSHIFT 0
 491 MENU VSHIFT 0
 492
 493         These options control the layout of the menu on the screen.
 494         The values above are the defaults.
 495
 496         A negative value is relative to the calculated length of the
 497         screen (25 for text mode, 28 for VESA graphics mode.)
 498
 499
 500 F1 textfile [background]
 501 ...
 502 F12 textfile [background]
 503
 504         Displays full-screen help (also available at the command line.)
 505         The same control code sequences as in the command line
 506         interface are supported, although some are ignored.
 507
 508         Additionally, a optional second argument allows a different
 509         background image (see MENU BACKGROUND for supported formats)
 510         to be displayed.
 511
 512
 513 MENU HELP textfile [background]
 514
 515         Creates a menu entry which, when selected, displays
 516         full-screen help in the same way as the F-key help.
 517
 518
 519 The menu system honours the TIMEOUT command; if TIMEOUT is specified
 520 it will execute the ONTIMEOUT command if one exists, otherwise it will
 521 pick the default menu option.  WARNING: the timeout action will bypass
 522 password protection even if one is set for the specified or default
 523 entry!
 524
 525 Normally, the user can press [Tab] to edit the menu entry, and [Esc]
 526 to return to the Syslinux command line.  However, if the configuration
 527 file specifies ALLOWOPTIONS 0, these keys will be disabled, and if
 528 MENU MASTER PASSWD is set, they require the master password.
 529
 530 The simple menu system supports serial console, using the normal
 531 SERIAL directive.  However, it can be quite slow over a slow serial
 532 link; you probably want to set your baudrate to 38400 or higher if
 533 possible.  It requires a Linux/VT220/ANSI-compatible terminal on the
 534 other end.
 535
 536
 537         +++ USING AN ALTERNATE CONFIGURATION FILE +++
 538
 539
 540 It is also possible to load a secondary configuration file, to get to
 541 another menu.  To do that, invoke menu.c32 with the name of the
 542 secondary configuration file.
 543
 544 LABEL othermenu
 545         MENU LABEL Another Menu
 546         KERNEL menu.c32
 547         APPEND othermenu.conf
 548
 549 If you specify more than one file, they will all be read, in the order
 550 specified.  The dummy filename ~ (tilde) is replaced with the filename
 551 of the main configuration file.
 552
 553 # The file graphics.conf contains common color and layout commands for
 554 # all menus.
 555 LABEL othermenu
 556         MENU LABEL Another Menu
 557         KERNEL vesamenu.c32
 558         APPEND graphics.conf othermenu.conf
 559
 560 # Return to the main menu
 561 LABEL mainmenu
 562         MENU LABEL Return to Main Menu
 563         KERNEL vesamenu.c32
 564         APPEND graphics.conf ~
 565
 566 See also the MENU INCLUDE directive above.