doc/menu.doc

   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 QUIT
 218
 219         (Only valid after a LABEL statement.)
 220
 221         This label quits the menu system.
 222
 223         WARNING: if MENU MASTER PASSWD or ALLOWOPTIONS 0 is set, this
 224         will still allow exiting to the CLI; however, a separate MENU
 225         PASSWD can of course be set for this label.
 226
 227
 228 INCLUDE filename [tagname]
 229 MENU INCLUDE filename [tagname]
 230
 231         Include the contents of the configuration file filename at
 232         this point.
 233
 234         In the case of MENU INCLUDE, the included data is only seen by
 235         the menu system; the core syslinux code does not parse this
 236         command, so any labels defined in it are unavailable.
 237
 238         If a tagname is included, the whole file is considered to have
 239         been bracketed with a MENU BEGIN tagname ... MENU END pair,
 240         and will therefore show up as a submenu.
 241
 242
 243 MENU AUTOBOOT message
 244
 245         Replaces the message "Automatic boot in # second{,s}...".  The
 246         symbol # is replaced with the number of seconds remaining.
 247         The syntax "{singular,[dual,]plural}" can be used to conjugate
 248         appropriately.
 249
 250
 251 MENU TABMSG message
 252
 253         Replaces the message "Press [Tab] to edit options".
 254
 255
 256 MENU NOTABMSG message
 257
 258         Takes the place of the TABMSG message if option editing is
 259         disabled.  Defaults to blank.
 260
 261
 262 MENU PASSPROMPT message
 263
 264         Replaces the message "Password required".
 265
 266
 267 MENU COLOR element ansi foreground background shadow
 268
 269         Sets the color of element "element" to the specified color
 270         sequence:
 271
 272         screen          Rest of the screen
 273         border          Border area
 274         title           Title bar
 275         unsel           Unselected menu item
 276         hotkey          Unselected hotkey
 277         sel             Selection bar
 278         hotsel          Selected hotkey
 279         disabled        Disabled menu item
 280         scrollbar       Scroll bar
 281         tabmsg          Press [Tab] message
 282         cmdmark         Command line marker
 283         cmdline         Command line
 284         pwdborder       Password box border
 285         pwdheader       Password box header
 286         pwdentry        Password box contents
 287         timeout_msg     Timeout message
 288         timeout         Timeout counter
 289         help            Help text
 290         msgXX           Message (F-key) file attribute XX
 291
 292         ... where XX is two hexadecimal digits (the "plain text" is 07).
 293
 294         "ansi" is a sequence of semicolon-separated ECMA-48 Set
 295         Graphics Rendition (<ESC>[m) sequences:
 296
 297         0     reset all attributes to their defaults
 298         1     set bold
 299         4     set underscore (simulated with color on a color display)
 300         5     set blink
 301         7     set reverse video
 302         22    set normal intensity
 303         24    underline off
 304         25    blink off
 305         27    reverse video off
 306         30    set black foreground
 307         31    set red foreground
 308         32    set green foreground
 309         33    set brown foreground
 310         34    set blue foreground
 311         35    set magenta foreground
 312         36    set cyan foreground
 313         37    set white foreground
 314         38    set underscore on, set default foreground color
 315         39    set underscore off, set default foreground color
 316         40    set black background
 317         41    set red background
 318         42    set green background
 319         43    set brown background
 320         44    set blue background
 321         45    set magenta background
 322         46    set cyan background
 323         47    set white background
 324         49    set default background color
 325
 326         These are used (a) in text mode, and (b) on the serial
 327         console.
 328
 329         "foreground" and "background" are color codes in #AARRGGBB
 330         notation, where AA RR GG BB are hexadecimal digits for alpha
 331         (opacity), red, green and blue, respectively.  #00000000
 332         represents fully transparent, and #ffffffff represents opaque
 333         white.
 334
 335         "shadow" controls the handling of the graphical console text
 336         shadow.  Permitted values are "none" (no shadowing), "std" or
 337         "standard" (standard shadowing - foreground pixels are
 338         raised), "all" (both background and foreground raised), and
 339         "rev" or "reverse" (background pixels are raised.)
 340
 341         If any field is set to "*" or omitted (at the end of the line)
 342         then that field is left unchanged.
 343
 344
 345         The current defaults are:
 346
 347         menu color screen       37;40      #80ffffff #00000000 std
 348         menu color border       30;44      #40000000 #00000000 std
 349         menu color title        1;36;44    #c00090f0 #00000000 std
 350         menu color unsel        37;44      #90ffffff #00000000 std
 351         menu color hotkey       1;37;44    #ffffffff #00000000 std
 352         menu color sel          7;37;40    #e0000000 #20ff8000 all
 353         menu color hotsel       1;7;37;40  #e0400000 #20ff8000 all
 354         menu color disabled     1;30;44    #60cccccc #00000000 std
 355         menu color scrollbar    30;44      #40000000 #00000000 std
 356         menu color tabmsg       31;40      #90ffff00 #00000000 std
 357         menu color cmdmark      1;36;40    #c000ffff #00000000 std
 358         menu color cmdline      37;40      #c0ffffff #00000000 std
 359         menu color pwdborder    30;47      #80ffffff #20ffffff std
 360         menu color pwdheader    31;47      #80ff8080 #20ffffff std
 361         menu color pwdentry     30;47      #80ffffff #20ffffff std
 362         menu color timeout_msg  37;40      #80ffffff #00000000 std
 363         menu color timeout      1;37;40    #c0ffffff #00000000 std
 364         menu color help         37;40      #c0ffffff #00000000 std
 365         menu color msg07        37;40      #90ffffff #00000000 std
 366
 367
 368 MENU MSGCOLOR fg_filter bg_filter shadow
 369
 370         Sets *all* the msgXX colors to a color scheme derived from the
 371         fg_filter and bg_filter values.  Background color zero is
 372         always treated as transparent.  The default corresponds to:
 373
 374         menu msgcolor #90ffffff #80ffffff std
 375
 376         This directive should come before any directive that
 377         customizes individual msgXX colors.
 378
 379
 380 MENU WIDTH 80
 381 MENU MARGIN 10
 382 MENU PASSWORDMARGIN 3
 383 MENU ROWS 12
 384 MENU TABMSGROW 18
 385 MENU CMDLINEROW 18
 386 MENU ENDROW -1
 387 MENU PASSWORDROW 11
 388 MENU TIMEOUTROW 20
 389 MENU HELPMSGROW 22
 390 MENU HELPMSGENDROW -1
 391 MENU HIDDENROW -2
 392 MENU HSHIFT 0
 393 MENU VSHIFT 0
 394
 395         These options control the layout of the menu on the screen.
 396         The values above are the defaults.
 397
 398         A negative value is relative to the calculated length of the
 399         screen (25 for text mode, 28 for VESA graphics mode.)
 400
 401
 402 F1 textfile background
 403 ...
 404 F12 textfile background
 405
 406         Displays full-screen help (also available at the command line.)
 407         The same control code sequences as in the command line
 408         interface are supported, although some are ignored.
 409
 410         Additionally, a second argument allows a different background
 411         image (see MENU BACKGROUND for supported formats) to be displayed.
 412
 413
 414 The menu system honours the TIMEOUT command; if TIMEOUT is specified
 415 it will execute the ONTIMEOUT command if one exists, otherwise it will
 416 pick the default menu option.
 417
 418 Normally, the user can press [Tab] to edit the menu entry, and [Esc]
 419 to return to the SYSLINUX command line.  However, if the configuration
 420 file specifies ALLOWOPTIONS 0, these keys will be disabled, and if
 421 MENU MASTER PASSWD is set, they require the master password.
 422
 423 The simple menu system supports serial console, using the normal
 424 SERIAL directive.  However, it can be quite slow over a slow serial
 425 link; you probably want to set your baudrate to 38400 or higher if
 426 possible.  It requires a Linux/VT220/ANSI-compatible terminal on the
 427 other end.
 428
 429
 430         +++ USING AN ALTERNATE CONFIGURATION FILE +++
 431
 432
 433 It is also possible to load a secondary configuration file, to get to
 434 another menu.  To do that, invoke menu.c32 with the name of the
 435 secondary configuration file.
 436
 437 LABEL othermenu
 438         MENU LABEL Another Menu
 439         KERNEL menu.c32
 440         APPEND othermenu.conf
 441
 442 If you specify more than one file, they will all be read, in the order
 443 specified.  The dummy filename ~ (tilde) is replaced with the filename
 444 of the main configuration file.
 445
 446 # The file graphics.conf contains common color and layout commands for
 447 # all menus.
 448 LABEL othermenu
 449         MENU LABEL Another Menu
 450         KERNEL vesamenu.c32
 451         APPEND graphics.conf othermenu.conf
 452
 453 # Return to the main menu
 454 LABEL mainmenu
 455         MENU LABEL Return to Main Menu
 456         KERNEL vesamenu.c32
 457         APPEND graphics.conf ~
 458
 459 See also the MENU INCLUDE directive above.