"Fossies" - the Fresh Open Source Software Archive

Member "syslinux-6.03/doc/menu.txt" (6 Oct 2014, 16858 Bytes) of package /linux/misc/syslinux-6.03.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

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