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