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