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