README.menu

   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 LABEL label
  50
  51         (Only valid after a LABEL statement.)
  52         Changes the label displayed for a specific entry.  This allows
  53         you to have a label that isn't suitable for the command line,
  54         for example:
  55
  56         # Soft Cap Linux
  57         LABEL softcap
  58                 MENU LABEL Soft Cap ^Linux 9.6.36
  59                 KERNEL softcap-9.6.36.bzi
  60                 APPEND whatever
  61
  62         # A very dense operating system
  63         LABEL brick
  64                 MENU LABEL ^Windows CE/ME/NT
  65                 KERNEL chain.c32
  66                 APPEND hd0 2
  67
  68         The ^ symbol in a MENU LABEL statement defines a hotkey.
  69         The hotkey will be highlighted in the menu and will move the
  70         menu cursor immediately to that entry.
  71
  72         Reusing hotkeys is disallowed, subsequent entries will not be
  73         highlighted, and will not work.
  74
  75         Keep in mind that the LABELs, not MENU LABELs, must be unique,
  76         or odd things will happen to the command-line.
  77
  78
  79 MENU HIDE
  80
  81         (Only valid after a LABEL statement.)
  82         Suppresses a particular LABEL entry from the menu.
  83
  84
  85 MENU DEFAULT
  86
  87         (Only valid after a LABEL statement.)
  88         Indicates that this entry should be the default.  If no
  89         default is specified, use the first one.
  90
  91
  92 TEXT HELP
  93 Help text ...
  94 ... which can span multiple lines
  95 ENDTEXT
  96
  97         (Only valid after a LABEL statement.)
  98         Specifies a help text that should be displayed when a particular
  99         selection is highlighted.
 100
 101
 102 MENU PASSWD passwd
 103
 104         (Only valid after a LABEL statement.)
 105
 106         Sets a password on this menu entry.  "passwd" can be either a
 107         cleartext password, a SHA-1 encrypted password (starting with
 108         $4$), or and MD5 encrypted password (starting with $1$).
 109
 110         Use the included Perl scripts "sha1pass" or "md5pass" to
 111         encrypt passwords.  MD5 passwords are compatible with most
 112         Unix password file utilities; SHA-1 passwords are probably
 113         unique to SYSLINUX.  Obviously, if you don't encrypt your
 114         passwords they will not be very secure at all.
 115
 116         If you are using passwords, you want to make sure you also use
 117         the settings "NOESCAPE 1", "PROMPT 0", and either set
 118         "ALLOWOPTIONS 0" or use a master password (see below.)
 119
 120         If passwd is an empty string, this menu entry can only be
 121         unlocked with the master password.
 122
 123
 124 MENU MASTER PASSWD passwd
 125
 126         Sets a master password.  This password can be used to boot any
 127         menu entry, and is required for the [Tab] and [Esc] keys to
 128         work.
 129
 130
 131 MENU BACKGROUND background
 132
 133         For vesamenu.c32, sets the background image.  The background
 134         can either be a color (see MENU COLOR) or the name of an image
 135         file, which should be 640x480 pixels and either in PNG or JPEG
 136         format.
 137
 138
 139 INCLUDE filename
 140 MENU INCLUDE filename
 141
 142         Include the contents of the configuration file filename at
 143         this point.
 144
 145         In the case of MENU INCLUDE, the included data is only seen by
 146         the menu system; the core syslinux code does not parse this
 147         command, so any labels defined in it are unavailable.
 148
 149
 150 MENU AUTOBOOT message
 151
 152         Replaces the message "Automatic boot in # second{,s}...".  The
 153         symbol # is replaced with the number of seconds remaining.
 154         The syntax "{singular,[dual,]plural}" can be used to conjugate
 155         appropriately.
 156
 157
 158 MENU TABMSG message
 159
 160         Replaces the message "Press [Tab] to edit options".
 161
 162
 163 MENU NOTABMSG message
 164
 165         Takes the place of the TABMSG message if option editing is
 166         disabled.  Defaults to blank.
 167
 168
 169 MENU PASSPROMPT message
 170
 171         Replaces the message "Password required".
 172
 173
 174 MENU COLOR element ansi foreground background shadow
 175
 176         Sets the color of element "element" to the specified color
 177         sequence:
 178
 179         screen          Rest of the screen
 180         border          Border area
 181         title           Title bar
 182         unsel           Unselected menu item
 183         hotkey          Unselected hotkey
 184         sel             Selection bar
 185         hotsel          Selected hotkey
 186         scrollbar       Scroll bar
 187         tabmsg          Press [Tab] message
 188         cmdmark         Command line marker
 189         cmdline         Command line
 190         pwdborder       Password box border
 191         pwdheader       Password box header
 192         pwdentry        Password box contents
 193         timeout_msg     Timeout message
 194         timeout         Timeout counter
 195         help            Help text
 196         msgXX           Message (F-key) file attribute XX
 197
 198         ... where XX is two hexadecimal digits (the "plain text" is 07).
 199
 200         "ansi" is a sequence of semicolon-separated ECMA-48 Set
 201         Graphics Rendition (<ESC>[m) sequences:
 202
 203         0     reset all attributes to their defaults
 204         1     set bold
 205         4     set underscore (simulated with color on a color display)
 206         5     set blink
 207         7     set reverse video
 208         22    set normal intensity
 209         24    underline off
 210         25    blink off
 211         27    reverse video off
 212         30    set black foreground
 213         31    set red foreground
 214         32    set green foreground
 215         33    set brown foreground
 216         34    set blue foreground
 217         35    set magenta foreground
 218         36    set cyan foreground
 219         37    set white foreground
 220         38    set underscore on, set default foreground color
 221         39    set underscore off, set default foreground color
 222         40    set black background
 223         41    set red background
 224         42    set green background
 225         43    set brown background
 226         44    set blue background
 227         45    set magenta background
 228         46    set cyan background
 229         47    set white background
 230         49    set default background color
 231
 232         These are used (a) in text mode, and (b) on the serial
 233         console.
 234
 235         "foreground" and "background" are color codes in #AARRGGBB
 236         notation, where AA RR GG BB are hexadecimal digits for alpha
 237         (opacity), red, green and blue, respectively.  #00000000
 238         represents fully transparent, and #ffffffff represents opaque
 239         white.
 240
 241         "shadow" controls the handling of the graphical console text
 242         shadow.  Permitted values are "none" (no shadowing), "std" or
 243         "standard" (standard shadowing - foreground pixels are
 244         raised), "all" (both background and foreground raised), and
 245         "rev" or "reverse" (background pixels are raised.)
 246
 247         If any field is set to "*" or omitted (at the end of the line)
 248         then that field is left unchanged.
 249
 250
 251         The current defaults are:
 252
 253         menu color screen       37;40      #80ffffff #00000000 std
 254         menu color border       30;44      #40000000 #00000000 std
 255         menu color title        1;36;44    #c00090f0 #00000000 std
 256         menu color unsel        37;44      #90ffffff #00000000 std
 257         menu color hotkey       1;37;44    #ffffffff #00000000 std
 258         menu color sel          7;37;40    #e0000000 #20ff8000 all
 259         menu color hotsel       1;7;37;40  #e0400000 #20ff8000 all
 260         menu color scrollbar    30;44      #40000000 #00000000 std
 261         menu color tabmsg       31;40      #90ffff00 #00000000 std
 262         menu color cmdmark      1;36;40    #c000ffff #00000000 std
 263         menu color cmdline      37;40      #c0ffffff #00000000 std
 264         menu color pwdborder    30;47      #80ffffff #20ffffff std
 265         menu color pwdheader    31;47      #80ff8080 #20ffffff std
 266         menu color pwdentry     30;47      #80ffffff #20ffffff std
 267         menu color timeout_msg  37;40      #80ffffff #00000000 std
 268         menu color timeout      1;37;40    #c0ffffff #00000000 std
 269         menu color help         37;40      #c0ffffff #00000000 std
 270         menu color msg07        37;40      #90ffffff #00000000 std
 271
 272
 273 MENU MSGCOLOR fg_filter bg_filter shadow
 274
 275         Sets *all* the msgXX colors to a color scheme derived from the
 276         fg_filter and bg_filter values.  Background color zero is
 277         always treated as transparent.  The default corresponds to:
 278
 279         menu msgcolor #90ffffff #80ffffff std
 280
 281         This directive should come before any directive that
 282         customizes individual msgXX colors.
 283
 284
 285 MENU WIDTH 80
 286 MENU MARGIN 10
 287 MENU PASSWORDMARGIN 3
 288 MENU ROWS 12
 289 MENU TABMSGROW 18
 290 MENU CMDLINEROW 18
 291 MENU ENDROW -1
 292 MENU PASSWORDROW 11
 293 MENU TIMEOUTROW 20
 294 MENU HELPMSGROW 22
 295 MENU HELPMSGENDROW -1
 296 MENU HIDDENROW -2
 297 MENU HSHIFT 0
 298 MENU VSHIFT 0
 299
 300         These options control the layout of the menu on the screen.
 301         The values above are the defaults.
 302
 303         A negative value is relative to the calculated length of the
 304         screen (25 for text mode, 28 for VESA graphics mode.)
 305
 306
 307 F1 textfile background
 308 ...
 309 F12 textfile background
 310
 311         Displays full-screen help (also available at the command line.)
 312         The same control code sequences as in the command line
 313         interface are supported, although some are ignored.
 314
 315         Additionally, a second argument allows a different background
 316         image (see MENU BACKGROUND for supported formats) to be displayed.
 317
 318
 319 The menu system honours the TIMEOUT command; if TIMEOUT is specified
 320 it will execute the ONTIMEOUT command if one exists, otherwise it will
 321 pick the default menu option.
 322
 323 Normally, the user can press [Tab] to edit the menu entry, and [Esc]
 324 to return to the SYSLINUX command line.  However, if the configuration
 325 file specifies ALLOWOPTIONS 0, these keys will be disabled, and if
 326 MENU MASTER PASSWD is set, they require the master password.
 327
 328 The simple menu system supports serial console, using the normal
 329 SERIAL directive.  However, it can be quite slow over a slow serial
 330 link; you probably want to set your baudrate to 38400 or higher if
 331 possible.  It requires a Linux/VT220/ANSI-compatible terminal on the
 332 other end.
 333
 334
 335         +++ USING AN ALTERNATE CONFIGURATION FILE +++
 336
 337
 338 It is also possible to load a secondary configuration file, to get to
 339 another menu.  To do that, invoke menu.c32 with the name of the
 340 secondary configuration file.
 341
 342 LABEL othermenu
 343         MENU LABEL Another Menu
 344         KERNEL menu.c32
 345         APPEND othermenu.conf
 346
 347 If you specify more than one file, they will all be read, in the order
 348 specified.  The dummy filename ~ (tilde) is replaced with the filename
 349 of the main configuration file.
 350
 351 # The file graphics.conf contains common color and layout commands for
 352 # all menus.
 353 LABEL othermenu
 354         MENU LABEL Another Menu
 355         KERNEL vesamenu.c32
 356         APPEND graphics.conf othermenu.conf
 357
 358 # Return to the main menu
 359 LABEL mainmenu
 360         MENU LABEL Return to Main Menu
 361         KERNEL vesamenu.c32
 362         APPEND graphics.conf ~
 363
 364 See also the MENU INCLUDE directive above.