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