Difference between revisions of "Comboot/menu.c32"

From Syslinux Wiki
Jump to: navigation, search
m (Correct order of MENU RESOLUTION parameters.)
(Update to 6.04-pre1, with minor modifications. Wiki formatting.)
Line 6: Line 6:
 
Additional items that must be documented (in both doc/menu.txt and this page) since 4.0:
 
Additional items that must be documented (in both doc/menu.txt and this page) since 4.0:
 
* New MENU IMMEDIATE --- permit hotkeys to activate immediately without needing Enter.  
 
* New MENU IMMEDIATE --- permit hotkeys to activate immediately without needing Enter.  
* <font color=gray><font size=1><s>New MENU HELP statement to display fullscreen help text as a result of a menu selection. </s>''documented''</font size></font color>
+
* <font color="gray" size="1"><s>New MENU HELP statement to display fullscreen help text as a result of a menu selection.</s> ''documented''</font>
* <font color=gray><font size=1><s>New MENU HIDDENKEY command to provide a one-keystroke way to activate a boot option from a hidden menu intro screen. </s>''documented''</font size></font color>
+
* <font color="gray" size="1"><s>New MENU HIDDENKEY command to provide a one-keystroke way to activate a boot option from a hidden menu intro screen.</s> ''documented''</font>
* <font color=gray><font size=1><s>New MENU SAVE statement.</s>''documented''</font size></font color>
+
* <font color="gray" size="1"><s>New MENU SAVE statement.</s> ''documented''</font>
* <font color=gray><font size=1><s>New MENU CLEAR statement.</s>''documented''</font size></font color>
+
* <font color="gray" size="1"><s>New MENU CLEAR statement.</s> ''documented''</font>
* <font color=gray><font size=1><s>New MENU SHIFTKEY statement.</s>''documented''</font size></font color>
+
* <font color="gray" size="1"><s>New MENU SHIFTKEY statement.</s> ''documented''</font>
* <font color=gray><font size=1><s>New MENU RESOLUTION statement.</s>''documented''</font size></font color>
+
* <font color="gray" size="1"><s>New MENU RESOLUTION statement.</s> ''documented''</font>
  
  
 
(See also [[Syslinux 4 Changelog]] and  [[Config|How do I configure Syslinux]]&nbsp;)
 
(See also [[Syslinux 4 Changelog]] and  [[Config|How do I configure Syslinux]]&nbsp;)
  
<font size=1>( Note that since version 3.74, the <tt>default</tt> directive usage has changed. Use <tt>UI</tt> instead)
+
<font size="1">( Note that since version 3.74, the <tt>default</tt> directive usage has changed. Use <tt>UI</tt> instead)
( See [[News-3.74#UI mode|UI mode]] or [[Syslinux 3 Changelog#Changes in 3.74|Changes in 3.74]] )</font size>
+
( See [[News-3.74#UI mode|UI mode]] or [[Syslinux 3 Changelog#Changes in 3.74|Changes in 3.74]] )</font>
  
  
 
<small>Note: Some minor updated documentation can be seen at the [[Menu]] wiki page. </small><br />
 
<small>Note: Some minor updated documentation can be seen at the [[Menu]] wiki page. </small><br />
''The content of doc/menu.txt (release 3.72, with some updates):''
+
''The content of doc/menu.txt (<!--release -->6.04-pre1, with some updates):''
  
  
Line 28: Line 28:
  
  
=THE ADVANCED MENU SYSTEM=
+
== THE ADVANCED MENU SYSTEM ==
  
The advanced menu system, written by Murali Krishnan Ganapathy, is located in the <tt>cmenu/</tt> sub-directory.  It allows the user to create hierarchical sub-menus, dynamic options, check-boxes, and just about anything you want.  It requires the menu to be compiled from a simple C file, see [http://git.kernel.org/?p=boot/syslinux/syslinux.git;a=blob;f=menu/simple.c;h=92e8ab125f7c76f45e5f912cb742b9299e9110a0;hb=ed67201fcc004ccb0eb20e5489d71ed69cfb7428 menu/simple.c] and [http://git.kernel.org/?p=boot/syslinux/syslinux.git;a=blob;f=menu/complex.c;h=94627c4f79878ee996a83913c27958a3e24364c0;hb=ed67201fcc004ccb0eb20e5489d71ed69cfb7428 menu/complex.c] for examples.
+
The advanced menu system, written by Murali Krishnan Ganapathy, is  
<!-- The "h/hb" part of the URL should track the syslinux-3.72 tag in the repository -->
+
located in the <tt>com32/cmenu/</tt> sub-directory.  It allows the user to  
 +
create hierarchical sub-menus, dynamic options, check-boxes, and just  
 +
about anything.  It requires the menu to be compiled from a simple C  
 +
file (see  
 +
[https://repo.or.cz/syslinux.git/blob/HEAD:/com32/cmenu/simple.c com32/cmenu/simple.c] and  
 +
[https://repo.or.cz/syslinux.git/blob/HEAD:/com32/cmenu/complex.c com32/cmenu/complex.c]  
 +
for examples).
  
 +
The advanced menu system does not support serial console at this time.
  
The advanced menu system doesn't support serial console at this time.
+
See [https://repo.or.cz/syslinux.git/blob/HEAD:/com32/cmenu/README com32/cmenu/README]
 +
for more information.
  
See [http://git.kernel.org/?p=boot/syslinux/syslinux.git;a=blob;f=menu/README;h=d585d2fa792385fa051481deca026c6eb4577a13;hb=ed67201fcc004ccb0eb20e5489d71ed69cfb7428 menu/README] for more information.
+
== THE SIMPLE MENU SYSTEM ==
  
=THE SIMPLE MENU SYSTEM=
+
The simple menu system is based on a module located at
 +
<tt>com32/menu/vesamenu.c32</tt> (graphical) or <tt>com32/menu/menu.c32</tt> (text
 +
mode only).  It uses the same configuration file as the regular
 +
Syslinux command line, and displays all the <tt>LABEL</tt> statements.
  
The simple menu system is a single module located at <tt>com32/menu/vesamenu.c32</tt> (graphical) or <tt>com32/menu/menu.c32</tt> (text mode only).  It uses the same configuration file as the regular Syslinux command line, and displays all the <tt>LABEL</tt> statements.
+
To use the menu system, simply make sure <tt>[vesa]menu.c32</tt> is in the
 +
appropriate location for the boot medium (the same directory as the
 +
configuration file for SYSLINUX, EXTLINUX and ISOLINUX, and the same
 +
directory as pxelinux.0 for PXELINUX), and put the following options
 +
in the configuration file:
  
To use the menu system, simply make sure <tt>[vesa]menu.c32 </tt>is in the appropriate location for your boot medium (the same directory as the configuration file for SYSLINUX, EXTLINUX and ISOLINUX, and the same directory as pxelinux.0 for PXELINUX), and put the following options in your configuration file:
+
UI menu.c32
<pre>
+
 
DEFAULT menu.c32
+
 
PROMPT 0
+
There are a few menu additions to the configuration file, all starting
</pre>
+
with the keywords <tt>MENU</tt> or <tt>TEXT</tt>. As the rest of the Syslinux
 +
configuration file language, it is case-insensitive.
 +
 
 +
The remainder of this document is a reference of the directives that
 +
are relevant in the Simple [[Menu]] System.
  
There are a few menu additions to the configuration file, all starting with the keywords <tt>MENU</tt> or <tt>TEXT</tt>. As the rest of the Syslinux config file language, it is case insensitive:
 
  
 
'''MENU TITLE''' ''title''
 
'''MENU TITLE''' ''title''
  
::Give the menu a title.  The title is presented at the top of the menu.
+
: Give the menu a title.  The title is presented at the top of <!--
 +
-->  the menu.
 +
 
  
 
'''MENU HIDDEN'''
 
'''MENU HIDDEN'''
  
::Do not display the actual menu unless the user presses a key. All that is displayed is a timeout message.
+
: Do not display the actual menu unless the user presses a key. <!--
 +
-->  All that is displayed is a timeout message.
 +
 
  
 
'''MENU HIDDENKEY''' ''key[,key...] command...''
 
'''MENU HIDDENKEY''' ''key[,key...] command...''
  
::If they key used to interrupt MENU HIDDEN is "'key'", then execute the specified command instead of displaying the menu.
+
: If the key used to interrupt MENU HIDDEN is "''key''", then <!--
 +
-->  execute the specified command instead of displaying the menu.
  
::Currently, the following key names are recognized:
+
: Currently, the following key names are recognized:
  
:::<tt>Backspace, Tab, Enter, Esc, Space, F1..F12, Up, Down, Left, Right, PgUp, PgDn, Home, End, Insert, Delete</tt>
+
:: <tt>Backspace, Tab, Enter, Esc, Space, F1..F12, Up, Down, Left, <!--
 +
-->  Right, PgUp, PgDn, Home, End, Insert, Delete</tt>
 +
 
 +
: ... in addition to all single characters plus the syntax {{nowrap|" <code>''^X''</code> "}} <!--
 +
-->  for {{nowrap|" <tt>[Ctrl-X]</tt> "}}.  Note that single characters are treated as case <!--
 +
-->  sensitive, so "A" and "a" can bind different commands.  The <!--
 +
-->  same command can be bound to different keys by giving a <!--
 +
-->  comma-separated list of them:
 +
 
 +
menu hiddenkey A,a key_a_command
  
::... in addition to all single characters plus the syntax " ''^X'' " for " <tt>Ctrl-X</tt> ".  Note that single characters are treated as case sensitive, so "A" and "a" can bind different commands.  The same command can be bound to different keys by giving a comma-separated list of keys:
 
<pre>
 
menu hiddenkey A,a key_a_command
 
</pre>
 
  
 
'''MENU CLEAR'''
 
'''MENU CLEAR'''
  
::Clear the screen when exiting the menu, instead of leaving the menu displayed.  For vesamenu, this means the graphical background is still displayed without the menu itself for as long as the screen remains in graphics mode.
+
: Clear the screen when exiting the menu, instead of leaving the <!--
 +
-->  menu displayed.  For vesamenu, this means the graphical <!--
 +
-->  background is still displayed without the menu itself for as <!--
 +
-->  long as the screen remains in graphics mode.
 +
 
  
 
'''MENU SHIFTKEY'''
 
'''MENU SHIFTKEY'''
  
::Exit the menu system immediately unless either the <tt>Shift</tt> or <tt>Alt</tt> key is pressed, or <tt>Caps Lock</tt> or <tt>Scroll Lock</tt> is set.
+
: Exit the menu system immediately unless either the <tt>Shift</tt> or the <!--
 +
-->  <tt>Alt</tt> key is pressed, or <tt>Caps Lock</tt> or <tt>Scroll Lock</tt> is set.
 +
 
  
 
'''MENU SEPARATOR'''
 
'''MENU SEPARATOR'''
  
::Insert an empty line in the menu.
+
: Insert an empty line in the menu.
 +
 
  
 
'''MENU LABEL''' ''label''
 
'''MENU LABEL''' ''label''
  
::''(Only valid after a LABEL statement.)''
+
: ''(Only valid after a LABEL statement.)''
::Changes the label displayed for a specific entry.  This allows you to have a label that isn't suitable for the command line, for example:
+
: Change the label displayed for a specific menu entry.  Display <!--
 +
-->  a label that is not suitable for the command line. For example:
 
<pre>
 
<pre>
# Soft Cap Linux
+
# Soft Cap Linux
LABEL softcap
+
LABEL softcap
MENU LABEL Soft Cap ^Linux 9.6.36
+
  MENU LABEL Soft Cap ^Linux 9.6.36
KERNEL softcap-9.6.36.bzi
+
  KERNEL softcap-9.6.36.bzi
APPEND whatever
+
  APPEND whatever
 
+
 
# A very dense operating system
+
# A very dense operating system
LABEL brick
+
LABEL brick
MENU LABEL ^Windows CE/ME/NT
+
  MENU LABEL ^Windows CE/ME/NT
KERNEL chain.c32
+
  KERNEL chain.c32
APPEND hd0 2
+
  APPEND hd0 2
 
</pre>
 
</pre>
::The ^ symbol in a <tt>MENU LABEL</tt> statement defines a hotkey. The hotkey will be highlighted in the menu and will move the menu cursor immediately to that entry.
+
: The caret symbol (^) in a <tt>MENU LABEL</tt> statement defines a hotkey. <!--
 +
-->  Hotkeys are highlighted in the menu.  When a hotkey is pressed, <!--
 +
-->  the cursor will move to the corresponding menu entry.  If MENU <!--
 +
-->  IMMEDIATE is present, then when a hotkey is pressed the <!--
 +
-->  corresponding menu entry will be immediately launched.
  
::Reusing hotkeys is disallowed, subsequent entries will not be highlighted, and will not work.
+
: Reusing hotkeys has no effect on subsequent entries; they will <!--
 +
-->  not be highlighted, and the cursor will not move to them when <!--
 +
-->  the hotkey is pressed again.
  
::Keep in mind that the <tt>LABEL</tt>s, not <tt>MENU LABEL</tt>s, must be unique, or odd things will happen to the command-line.
+
: Keep in mind that the <tt>LABEL</tt>s, not <tt>MENU LABEL</tt>s, must be unique,  
 +
or odd things will happen to the command-line.
  
  
 
'''MENU INDENT''' ''count''
 
'''MENU INDENT''' ''count''
  
::''(Only valid after a LABEL statement.)''
+
: ''(Only valid after a LABEL statement.)''
::Will add "''count''" spaces in front of the displayed menu entry.
+
: Add "count" spaces in front of the displayed menu entry.
 +
 
  
 
'''MENU DISABLE'''
 
'''MENU DISABLE'''
  
::''(Only valid after a LABEL statement.)''
+
: ''(Only valid after a LABEL statement.)''
::Makes the entry unselectable.  This allows you to make a section in your menu with different options below it. for example:
+
: Make the entry unselectable.  This allows to display a <!--
 +
-->  section in the menu with different options below it. <!--
 +
-->  For example:
 +
 
 
<pre>
 
<pre>
# Entries for network boots
+
# Entries for network boots
LABEL -
+
LABEL -
MENU LABEL Network:
+
  MENU LABEL Network:
MENU DISABLE
+
  MENU DISABLE
 
+
# Soft Cap Linux
+
# Soft Cap Linux
LABEL softcap
+
LABEL softcap
MENU LABEL Soft Cap ^Linux 9.6.36
+
  MENU LABEL Soft Cap ^Linux 9.6.36
MENU INDENT 1
+
  MENU INDENT 1
KERNEL softcap-9.6.36.bzi
+
KERNEL softcap-9.6.36.bzi
APPEND whatever
+
APPEND whatever
 
+
# Dos 6.22
+
# Dos 6.22
LABEL dos
+
LABEL dos
MENU LABEL ^Dos 6.22
+
  MENU LABEL ^Dos 6.22
MENU INDENT 1
+
  MENU INDENT 1
KERNEL memdisk
+
KERNEL memdisk
APPEND initrd=dos622.imz
+
APPEND initrd=dos622.imz
 
+
# Separator
+
# Separator
MENU SEPARATOR
+
  MENU SEPARATOR
 
+
# Entries for local boots
+
# Entries for local boots
LABEL -
+
LABEL -
MENU LABEL Local:
+
  MENU LABEL Local:
MENU DISABLE
+
  MENU DISABLE
 
+
# Windows 2000
+
# Windows 2000
LABEL w2k
+
LABEL w2k
MENU LABEL ^Windows 2000
+
  MENU LABEL ^Windows 2000
MENU INDENT 1
+
  MENU INDENT 1
KERNEL chain.c32
+
KERNEL chain.c32
APPEND hd0 1
+
APPEND hd0 1
 
+
# Windows XP
+
# Windows XP
LABEL xp
+
LABEL xp
MENU LABEL Windows ^XP
+
  MENU LABEL Windows ^XP
MENU INDENT 1
+
  MENU INDENT 1
KERNEL chain.c32
+
KERNEL chain.c32
APPEND hd0 2
+
APPEND hd0 2
 
</pre>
 
</pre>
  
Line 162: Line 209:
 
'''MENU HIDE'''
 
'''MENU HIDE'''
  
::''(Only valid after a LABEL statement.)''
+
: ''(Only valid after a LABEL statement.)''
::Suppresses a particular LABEL entry from the menu.
+
: Suppresses a particular LABEL entry from the menu.
  
  
 
'''MENU DEFAULT'''
 
'''MENU DEFAULT'''
  
::''(Only valid after a LABEL statement.)''
+
: ''(Only valid after a LABEL statement.)''
::Indicates that this entry should be the default for the particular (sub)menu.  See also the DEFAULT directive.  If no default is specified, use the first one.
+
: The particular menu entry is considered the default for the <!--
 +
-->  particular (sub)menu.  If no default is specified, use the <!--
 +
-->  first one. See also the DEFAULT directive.
  
  
Line 177: Line 226:
 
'''ENDTEXT'''<br/>
 
'''ENDTEXT'''<br/>
  
::''(Only valid after a LABEL statement.)''
+
: ''(Only valid after a LABEL statement.)''
::Specifies a help text that should be displayed when a particular selection is highlighted.
+
: Specify a help text that should be displayed when a particular <!--
 +
-->  selection is highlighted.
  
  
 
'''MENU PASSWD''' ''passwd''
 
'''MENU PASSWD''' ''passwd''
  
::''(Only valid after a LABEL statement, or a MENU BEGIN statement.)''
+
: ''(Only valid after a LABEL statement, or a MENU BEGIN statement.)''
::Sets a password on this menu entry.  "''passwd''" can be either a cleartext password or a password encrypted with one of the following algorithms:
+
: Set a password on this menu entry.  "''passwd''" can be either a <!--
 +
-->  cleartext password or a password encrypted with one of the <!--
 +
-->  following algorithms:
  
:::<tt>MD5 (Signature: $1$)</tt>
+
{|
:::<tt>SHA-1 (Signature: $4$)</tt>
+
|
:::<tt>SHA-2-256 (Signature: $5$)</tt>
+
:&nbsp;
:::<tt>SHA-2-512 (Signature: $6$)</tt>
+
|
 +
<pre>
 +
MD5 (Signature: $1$)
 +
SHA-1 (Signature: $4$)
 +
SHA-2-256 (Signature: $5$)
 +
SHA-2-512 (Signature: $6$)
 +
</pre>
 +
|}
  
::Use the included Perl scripts "<tt>sha1pass</tt>" or "<tt>md5pass</tt>" to encrypt passwords.  MD5 passwords are compatible with most Unix password file utilities; SHA-1 passwords are probably unique to Syslinux; SHA-2 passwords are compatible with very recent Linux distributions.  Obviously, if you don't encrypt your passwords they will not be very secure at all.
+
: Use the included Perl scripts "<tt>sha1pass</tt>" or "<tt>md5pass</tt>" to <!--
 +
-->  encrypt passwords.  MD5 passwords are compatible with most <!--
 +
-->  Unix password file utilities; SHA-1 passwords are probably <!--
 +
-->  unique to Syslinux; SHA-2 passwords are compatible with very <!--
 +
-->  recent Linux distributions.  Obviously, if you don't encrypt <!--
 +
-->  your passwords they will not be very secure at all.
  
::If using passwords, make sure to use "NOESCAPE 1" and "PROMPT 0", and either set "ALLOWOPTIONS 0" or use a master password (see below).
+
: If using passwords, make sure to use {{nowrap|"<tt>NOESCAPE 1</tt>"}} and <!--
 +
-->  {{nowrap|"<tt>PROMPT 0</tt>"}}, and either set {{nowrap|"<tt>ALLOWOPTIONS 0</tt>"}} or use a master <!--
 +
-->  password (see below).
  
::If ''passwd'' is an empty string, this menu entry can only be unlocked with the master password.
+
: If ''passwd'' is an empty string, this menu entry can only be <!--
 +
-->  unlocked with the master password.
  
  
 
'''MENU MASTER PASSWD''' ''passwd''
 
'''MENU MASTER PASSWD''' ''passwd''
  
::Sets a master password.  This password can be used to boot any menu entry, and is required for the [Tab] and [Esc] keys to work.
+
: Set a master password.  This password can be used to boot any <!--
 +
-->  menu entry. If this directive is used, then the master password <!--
 +
-->  is also required for the [Tab] and [Esc] keys to work.
  
  
 
'''MENU RESOLUTION''' ''width height''
 
'''MENU RESOLUTION''' ''width height''
  
::Requests a specific screen resolution when in graphics mode.  The default is "640 480" corresponding to a resolution of 640x480 pixels, which all VGA-compatible monitors should be able to display.
+
: Request a specific screen resolution when in graphics mode. <!--
 +
--> The default is "640 480" corresponding to a resolution of <!--
 +
-->  640x480 pixels, which all VGA-compatible monitors should be <!--
 +
-->  able to display.
  
::If the selected resolution is unavailable, the text mode menu is displayed instead.
+
: If the requested resolution is unavailable, the text mode menu <!--
 +
-->  is displayed instead.
  
  
 
'''MENU BACKGROUND''' ''background''
 
'''MENU BACKGROUND''' ''background''
  
::For <tt>vesamenu.c32</tt>, sets the background image.  The ''background'' can either be a color (see <tt>MENU COLOR</tt>) or the name of an image file, which should be the size of the screen (normally 640x480 pixels, but see MENU RESOLUTION) and either in PNG, JPEG or LSS16 format.
+
: For <tt>vesamenu.c32</tt>, set the background image.  The ''background'' <!--
 +
-->  can either be a color (see <tt>MENU COLOR</tt>) or the name of an image <!--
 +
-->  file, which should be the size of the screen (normally 640x480 <!--
 +
-->  pixels, but see MENU RESOLUTION) and either in PNG, JPEG or <!--
 +
-->  LSS16 format.
 +
 
 +
: Note: When using an image file as background, its resolution <!--
 +
-->  should match the values used in MENU RESOLUTION.
  
  
Line 218: Line 298:
 
'''MENU END'''
 
'''MENU END'''
  
::Begin/end a submenu.  The entries between <tt>MENU BEGIN</tt> and <tt>MENU END</tt> form a submenu, which is marked with a > mark on the right hand of the screen.  Submenus inherit the properties of their parent menus, but can override them, and can thus have their own backgrounds, master passwords, titles, timeouts, messages and so forth.
+
: Begin/end a submenu.  The entries between <tt>MENU BEGIN</tt> and <tt>MENU <!--
 +
-->  END</tt> form a submenu, which is marked with a ">" mark on the right <!--
 +
-->  hand of the screen.  Submenus inherit the properties of their <!--
 +
-->  parent menus, but can override them, and can thus have their <!--
 +
-->  own backgrounds, master passwords, titles, timeouts, messages <!--
 +
-->  and so forth.
  
  
 
'''MENU GOTO''' ''tagname''
 
'''MENU GOTO''' ''tagname''
  
::''(Only valid after a LABEL statement.)''
+
: ''(Only valid after a LABEL statement.)''
::This label will transfer to the named submenu instead of booting anything.  To transfer to the top-level menu, specify "<tt>menu goto .top</tt>".
+
: Transfer to the named submenu instead of booting anything. <!--
 +
--> To transfer to the top-level menu, specify "<tt>menu goto .top</tt>".
  
  
 
'''MENU EXIT''' [''tagname'']
 
'''MENU EXIT''' [''tagname'']
  
::''(Only valid after a label statement inside <tt>MENU BEGIN ... MENU END</tt>)''
+
: ''(Only valid after a label statement inside {{nowrap|<tt>MENU BEGIN ... MENU END</tt>.)}}''
::Exit to the next higher menu, or, if tagname is specified, to the named menu.
+
: Exit to the next higher menu, or, if ''tagname'' is specified, to <!--
 +
-->  the named menu.
  
  
 
'''MENU QUIT'''
 
'''MENU QUIT'''
  
::''(Only valid after a LABEL statement.)''
+
: ''(Only valid after a LABEL statement.)''
::This label quits the menu system.
+
: Quit the menu system.
  
::'''WARNING''': if <tt>MENU MASTER PASSWD</tt> or <tt>ALLOWOPTIONS 0</tt> is set, this will still allow exiting to the CLI; however, a separate <tt>MENU PASSWD</tt> can of course be set for this label.
+
: '''WARNING''': Even if either <tt>MENU MASTER PASSWD</tt> or {{nowrap|"<tt>ALLOWOPTIONS 0</tt>"}} <!--
 +
-->  is set, MENU QUIT will still allow exiting to the CLI; however, <!--
 +
-->  a separate <tt>MENU PASSWD</tt> can of course be set for this <!--
 +
-->  label / menu entry.
  
  
 
'''MENU START'''
 
'''MENU START'''
  
::''(Only valid inside MENU BEGIN ... MENU END)''
+
: ''(Only valid inside {{nowrap|<tt>MENU BEGIN ... MENU END</tt>.)}}''
::Indicates that the menu system should start at the menu being defined instead of at the top-level menu.  See also the DEFAULT directive.
+
: Define the starting menu for the menu system, instead of <!--
 +
-->  starting at the top-level menu.  See also the DEFAULT directive.
  
  
 
'''DEFAULT''' ''label''
 
'''DEFAULT''' ''label''
  
::Set the global default.  If "''label''" points into a submenu, that menu becomes the <tt>start menu</tt>; in other words, this directive has the same effect as both MENU DEFAULT and MENU START.
+
: Set the global default.  If "''label''" points into a submenu, <!--
 +
-->  that menu becomes the start menu.  In other words, this <!--
 +
-->  directive has the same effect as both <tt>MENU DEFAULT</tt> and <tt>MENU <!--
 +
-->  START</tt>.
  
::For backwards compatibility with earlier versions of Syslinux, this behavior is ignored unless the configuration file also contains a UI directive.
+
: For backwards compatibility with earlier versions of Syslinux, <!--
 +
-->  this behavior is ignored unless the configuration file also <!--
 +
-->  contains a UI directive.
  
::Note: the CLI accepts options after the ''label'', or even a non-label.  The menu system does not support that.
+
: Note: the CLI accepts options after the ''label'', or even a <!--
 +
-->  non-label.  The menu system does not support that.
  
  
Line 259: Line 356:
 
'''MENU NOSAVE'''
 
'''MENU NOSAVE'''
  
::Remember the last selected entry and make that one the ''default'' for the next boot.  A password-protected menu entry is *not* saved.  This requires the ADV data storage mechanism, which is currently only implemented for EXTLINUX, although the other Syslinux derivatives will accept the command (and ignore it.)
+
: Remember the last selected entry and make that one the ''default'' <!--
 +
-->  for the next boot.  A password-protected menu entry is *not* <!--
 +
-->  saved.  This requires the ADV data storage mechanism, which is <!--
 +
-->  currently only implemented for SYSLINUX, although the other <!--
 +
-->  Syslinux derivatives will accept the command (and ignore it).
  
::NOTE: MENU SAVE stores the LABEL tag of the selected entry; this mechanism therefore relies on LABEL tags being unique.  On the other hand, it handles changes in the configuration file gracefully.
+
: NOTE: MENU SAVE stores the LABEL tag of the selected entry. <!--
 +
-->  This mechanism therefore relies on LABEL tags being unique. <!--
 +
--> On the other hand, it handles changes in the configuration <!--
 +
-->  file gracefully.
  
::NOTE: In software RAID-1 setups, MENU SAVE only stores the ''default'' label on the actual boot disk.  This may lead to inconsistent reads from the array, or unexpectedly change the default label after array resynchronization or disk failure.
+
: NOTE: In software RAID-1 setups, MENU SAVE only stores the <!--
 +
-->  ''default'' label on the actual boot disk.  This may lead to <!--
 +
-->  inconsistent reads from the array, or unexpectedly change the <!--
 +
-->  default label after array resynchronization or disk failure.
  
::The MENU SAVE information can be fully cleared with "extlinux --reset-adv <bootdir>".
+
: The MENU SAVE information can be fully cleared with <!--
 +
-->  {{nowrap|1="<code>extlinux --reset-adv <''bootdir''></code>".}}
  
::A MENU SAVE or MENU NOSAVE at the top of a (sub)menu affects all entries underneath that (sub)menu except those that in turn have MENU SAVE or MENU NOSAVE declared.  This can be used to only save certain entires when selected.
+
: A MENU SAVE or MENU NOSAVE at the top of a (sub)menu affects <!--
 +
-->  all entries underneath that (sub)menu except those that in <!--
 +
-->  turn have MENU SAVE or MENU NOSAVE declared.  This can be used <!--
 +
-->  to restrict which specific entries are allowed to be saved when <!--
 +
-->  executed.
  
  
Line 273: Line 385:
 
'''MENU INCLUDE''' ''filename'' [''tagname'']
 
'''MENU INCLUDE''' ''filename'' [''tagname'']
  
::Include the contents of the configuration file filename at this point.
+
: Include the contents of the "''filename''" configuration file at <!--
 +
-->  this point.
  
::In the case of MENU INCLUDE, the included data is only seen by the menu system; the core syslinux code does not parse this command, so any labels defined in it are unavailable.
+
: In the case of MENU INCLUDE, the included data is only seen by <!--
 +
-->  the menu system; the core Syslinux code does not parse this <!--
 +
-->  command, so any labels defined in it are unavailable.
  
::If a tagname is included, the whole file is considered to have been bracketed with a <tt>MENU BEGIN</tt> ''tagname'' ... <tt>MENU END</tt> pair, and will therefore show up as a submenu.
+
: If a tagname is included, the whole file is considered to have <!--
 +
-->  been bracketed with a {{nowrap|<tt>MENU BEGIN</tt> ''tagname'' ... <tt>MENU END</tt>}} pair, <!--
 +
-->  and will therefore show up as a submenu.
  
  
 
'''MENU AUTOBOOT''' ''message''
 
'''MENU AUTOBOOT''' ''message''
  
::Replaces the message "''Automatic boot in # second{,s}...''".  The symbol # is replaced with the number of seconds remaining. The syntax "{singular,[dual,]plural}" can be used to conjugate appropriately.
+
: Replace the message "''Automatic boot in # second{,s}...''".  The <!--
 +
-->  "#" symbol is replaced with the number of remaining seconds. <!--
 +
-->  The syntax "<code>{singular,[dual,]plural}</code>" can be used to conjugate <!--
 +
-->  appropriately.
  
  
 
'''MENU TABMSG''' ''message''
 
'''MENU TABMSG''' ''message''
  
::Replaces the message "''Press [Tab] to edit options''".
+
: Replace the message "''Press [Tab] to edit options''".
  
  
 
'''MENU NOTABMSG''' ''message''
 
'''MENU NOTABMSG''' ''message''
  
::Takes the place of the TABMSG message if option editing is disabled. Defaults to blank.
+
: Take the place of the TABMSG message when the [Tab] key is not <!--
 +
-->  allowed, i.e. if the possibility to edit the command is <!--
 +
-->  disabled. Defaults to blank.
  
  
 
'''MENU PASSPROMPT''' ''message''
 
'''MENU PASSPROMPT''' ''message''
  
::Replaces the message "''Password required''".
+
: Replace the message "''Password required''".
  
  
 
'''MENU COLOR''' ''element ansi foreground background shadow''
 
'''MENU COLOR''' ''element ansi foreground background shadow''
  
::Sets the color of element "''element''" to the specified color sequence:
+
: Set the color of element "''element''" to the specified color <!--
 +
-->  sequence:
 +
{|
 +
|
 
<pre>
 
<pre>
screen          Rest of the screen
+
screen          Rest of the screen
border          Border area
+
border          Border area
title          Title bar
+
title          Title bar
unsel          Unselected menu item
+
unsel          Unselected menu item
hotkey          Unselected hotkey
+
hotkey          Unselected hotkey
sel            Selection bar
+
sel            Selection bar
hotsel          Selected hotkey
+
hotsel          Selected hotkey
disabled Disabled menu item
+
disabled       Disabled menu item
scrollbar      Scroll bar
+
scrollbar      Scroll bar
tabmsg          Press [Tab] message
+
tabmsg          Press [Tab] message
cmdmark        Command line marker
+
cmdmark        Command line marker
cmdline        Command line
+
cmdline        Command line
pwdborder      Password box border
+
pwdborder      Password box border
pwdheader      Password box header
+
pwdheader      Password box header
pwdentry        Password box contents
+
pwdentry        Password box contents
timeout_msg    Timeout message
+
timeout_msg    Timeout message
timeout        Timeout counter
+
timeout        Timeout counter
help Help text
+
help           Help text
msgXX Message (F-key) file attribute XX
+
msgXX           Message (F-key) file attribute XX
 
</pre>
 
</pre>
::... where XX is two hexadecimal digits (the "plain text" is 07).
+
|}
 +
: ... where XX is two hexadecimal digits (the "plain text" is 07).
  
::"ansi" is a sequence of semicolon-separated ECMA-48 Set Graphics Rendition (<ESC>[m) sequences:
+
: "ansi" is a sequence of semicolon-separated {{nowrap|ECMA-48}} Set <!--
 +
-->  Graphics Rendition {{nowrap|1=<nowiki>(<code><ESC>[m</code>)</nowiki>}} sequences:
 +
{|
 +
|
 
<pre>
 
<pre>
0    reset all attributes to their defaults
+
0    reset all attributes to their defaults
1    set bold
+
1    set bold
4    set underscore (simulated with color on a color display)
+
4    set underscore (simulated with color on a color display)
5    set blink
+
5    set blink
7    set reverse video
+
7    set reverse video
22    set normal intensity
+
22    set normal intensity
24    underline off
+
24    underline off
25    blink off
+
25    blink off
27    reverse video off
+
27    reverse video off
30    set black foreground
+
30    set black foreground
31    set red foreground
+
31    set red foreground
32    set green foreground
+
32    set green foreground
33    set brown foreground
+
33    set brown foreground
34    set blue foreground
+
34    set blue foreground
35    set magenta foreground
+
35    set magenta foreground
36    set cyan foreground
+
36    set cyan foreground
37    set white foreground
+
37    set white foreground
38    set underscore on, set default foreground color
+
38    set underscore on, set default foreground color
39    set underscore off, set default foreground color
+
39    set underscore off, set default foreground color
40    set black background
+
40    set black background
41    set red background
+
41    set red background
42    set green background
+
42    set green background
43    set brown background
+
43    set brown background
44    set blue background
+
44    set blue background
45    set magenta background
+
45    set magenta background
46    set cyan background
+
46    set cyan background
47    set white background
+
47    set white background
49    set default background color
+
49    set default background color
 
</pre>
 
</pre>
::These are used (a) in text mode, and (b) on the serial console.
+
|}
 +
: These are used (a) in text mode, and (b) on the serial <!--
 +
-->  console.
  
::"''foreground''" and "''background''" are color codes in #AARRGGBB notation, where AA RR GG BB are hexadecimal digits for alpha (opacity), red, green and blue, respectively.  #00000000 represents fully transparent, and #ffffffff represents opaque white.
+
: "''foreground''" and "''background''" are color codes in #AARRGGBB <!--
 +
-->  notation, where AA RR GG BB are hexadecimal digits for alpha <!--
 +
-->  (opacity), red, green and blue, respectively.  #00000000 <!--
 +
-->  represents fully transparent, and #ffffffff represents opaque <!--
 +
-->  white.
  
::"''shadow''" controls the handling of the graphical console text shadow.  Permitted values are "<tt>none</tt>" (no shadowing), "<tt>std</tt>" or "<tt>standard</tt>" (standard shadowing - foreground pixels are raised), "<tt>all</tt>" (both background and foreground raised), and "<tt>rev</tt>" or "<tt>reverse</tt>" (background pixels are raised.)
+
: "''shadow''" controls the handling of the graphical console text <!--
 +
-->  shadow.  Permitted values are "<tt>none</tt>" (no shadowing), "<tt>std</tt>" or <!--
 +
-->  "<tt>standard</tt>" (standard shadowing - foreground pixels are <!--
 +
-->  raised), "<tt>all</tt>" (both background and foreground raised), and <!--
 +
-->  "<tt>rev</tt>" or "<tt>reverse</tt>" (background pixels are raised).
  
::If any field is set to "*" or omitted (at the end of the line) then that field is left unchanged.
+
: If any field is set to "*" or omitted (at the end of the line) <!--
 +
-->  then that field is left unchanged.
  
  
::The current defaults are:
+
: The current defaults are:
 +
{|
 +
|
 
<pre>
 
<pre>
menu color screen 37;40      #80ffffff #00000000 std
+
menu color screen 37;40      #80ffffff #00000000 std
menu color border 30;44      #40000000 #00000000 std
+
menu color border 30;44      #40000000 #00000000 std
menu color title 1;36;44    #c00090f0 #00000000 std
+
menu color title 1;36;44    #c00090f0 #00000000 std
menu color unsel 37;44      #90ffffff #00000000 std
+
menu color unsel 37;44      #90ffffff #00000000 std
menu color hotkey 1;37;44    #ffffffff #00000000 std
+
menu color hotkey 1;37;44    #ffffffff #00000000 std
menu color sel 7;37;40    #e0000000 #20ff8000 all
+
menu color sel 7;37;40    #e0000000 #20ff8000 all
menu color hotsel 1;7;37;40  #e0400000 #20ff8000 all
+
menu color hotsel 1;7;37;40  #e0400000 #20ff8000 all
menu color disabled 1;30;44    #60cccccc #00000000 std
+
menu color disabled 1;30;44    #60cccccc #00000000 std
menu color scrollbar 30;44      #40000000 #00000000 std
+
menu color scrollbar 30;44      #40000000 #00000000 std
menu color tabmsg 31;40      #90ffff00 #00000000 std
+
menu color tabmsg 31;40      #90ffff00 #00000000 std
menu color cmdmark 1;36;40    #c000ffff #00000000 std
+
menu color cmdmark 1;36;40    #c000ffff #00000000 std
menu color cmdline 37;40      #c0ffffff #00000000 std
+
menu color cmdline 37;40      #c0ffffff #00000000 std
menu color pwdborder 30;47      #80ffffff #20ffffff std
+
menu color pwdborder 30;47      #80ffffff #20ffffff std
menu color pwdheader 31;47      #80ff8080 #20ffffff std
+
menu color pwdheader 31;47      #80ff8080 #20ffffff std
menu color pwdentry 30;47      #80ffffff #20ffffff std
+
menu color pwdentry 30;47      #80ffffff #20ffffff std
menu color timeout_msg 37;40      #80ffffff #00000000 std
+
menu color timeout_msg 37;40      #80ffffff #00000000 std
menu color timeout 1;37;40    #c0ffffff #00000000 std
+
menu color timeout 1;37;40    #c0ffffff #00000000 std
menu color help 37;40      #c0ffffff #00000000 std
+
menu color help 37;40      #c0ffffff #00000000 std
menu color msg07 37;40      #90ffffff #00000000 std
+
menu color msg07 37;40      #90ffffff #00000000 std
 
</pre>
 
</pre>
 +
|}
  
  
 
'''MENU MSGCOLOR''' ''fg_filter bg_filter shadow''
 
'''MENU MSGCOLOR''' ''fg_filter bg_filter shadow''
  
::Sets <u>''all''</u> the msgXX colors to a color scheme derived from the fg_filter and bg_filter values.  Background color zero is always treated as transparent.  The default corresponds to:
+
: Set <u>''all''</u> the msgXX colors to a color scheme derived from the <!--
 +
-->  ''fg_filter'' and ''bg_filter'' values.  Background color zero is <!--
 +
-->  always treated as transparent.  The default corresponds to:
 +
{|
 +
|
 
<pre>
 
<pre>
menu msgcolor #90ffffff #80ffffff std
+
menu msgcolor #90ffffff #80ffffff std
 
</pre>
 
</pre>
::This directive should come before any directive that customizes individual msgXX colors.
+
|}
 +
: This directive should come before any directive that <!--
 +
-->  customizes individual msgXX colors.
  
  
Line 414: Line 563:
 
'''MENU VSHIFT''' 0<br/>
 
'''MENU VSHIFT''' 0<br/>
  
::These options control the layout of the menu on the screen.
+
: These options control the layout of the menu on the screen.
::The values above are the defaults.
+
: The values above are the defaults.
  
::A negative value is relative to the calculated length of the screen (25 for text mode, 28 for VESA graphics mode.)
+
: A negative value is relative to the calculated length of the <!--
 +
-->  screen (25 rows for text mode, 28 rows for VESA graphics mode).
  
  
Line 424: Line 574:
 
'''F12''' ''textfile'' [''background'']<br/>
 
'''F12''' ''textfile'' [''background'']<br/>
  
::Displays full-screen help (also available at the command line.) The same control code sequences as in the command line interface are supported, although some are ignored.
+
: Display full-screen help (also available at the command line). <!--
 +
-->  The same control code sequences as in the command line <!--
 +
-->  interface are supported, although some are ignored.
  
::Additionally, an optional second argument allows a different background image (see <tt>MENU BACKGROUND</tt> for supported formats) to be displayed.
+
: Additionally, an optional second argument allows a different <!--
 +
-->  background image to be displayed by vesamenu.c32 (see <tt>MENU <!--
 +
-->  BACKGROUND</tt> for supported formats).  The CLI and menu.c32 will <!--
 +
-->  ignore the second argument.
  
  
 
'''MENU HELP''' ''textfile'' [''background'']
 
'''MENU HELP''' ''textfile'' [''background'']
  
::Creates a menu entry which, when selected, displays full-screen help in the same way as the <tt>F-key</tt> help.
+
: Create a menu entry which, when selected, displays <!--
 +
-->  full-screen help in the same way as the <tt>F-key</tt> help.
  
  
  
The menu system honours the <tt>TIMEOUT</tt> command; if <tt>TIMEOUT</tt> is specified it will execute the ONTIMEOUT command if one exists, otherwise it will pick the default menu option.  WARNING: the TIMEOUT action will bypass password protection even if one is set for the specified or default entry!
+
The menu system honours the <tt>TIMEOUT</tt> command.  If <tt>TIMEOUT</tt> is specified,
 +
it will execute the ONTIMEOUT command if one exists, otherwise it will  
 +
pick the DEFAULT menu option.  WARNING: the TIMEOUT action will bypass  
 +
password protection even if one is set for the specified ONTIMEOUT
 +
and/or DEFAULT entry!
  
Normally, the user can press [Tab] to edit the menu entry, and [Esc] to return to the Syslinux command line.  However, if the configuration file specifies <tt>ALLOWOPTIONS 0</tt>, these keys will be disabled, and if <tt>MENU MASTER PASSWD</tt> is set, they require the master password.
+
Normally, users can press [Tab] to edit the menu entry, and [Esc]  
 +
to return to the Syslinux command line.  However, if the configuration  
 +
file specifies "<tt>ALLOWOPTIONS 0</tt>", these keys will be disabled, and if  
 +
<tt>MENU MASTER PASSWD</tt> is set, they require the master password.
  
The simple menu system supports serial console, using the normal <tt>SERIAL</tt> directive.  However, it can be quite slow over a slow serial link; you probably want to set your baudrate to 38400 or higher if possible.  It requires a Linux/VT220/ANSI-compatible terminal on the other end.
+
The simple menu system supports serial console, using the normal  
 +
<tt>SERIAL</tt> directive.  However, it can be quite slow over a slow serial  
 +
link; you probably want to set your baudrate to 38400 or higher if  
 +
possible.  It requires a Linux/VT220/ANSI-compatible terminal on the  
 +
other end.
  
=USING AN ALTERNATE CONFIGURATION FILE=
+
== USING AN ALTERNATE CONFIGURATION FILE ==
  
  
It is also possible to load a secondary configuration file, to get to another menu.  To do that, invoke <tt>menu.c32</tt> with the name of the secondary configuration file.
+
It is also possible to load a secondary configuration file, to get to  
 +
another menu.  To do that, invoke <tt>(vesa)menu.c32</tt> with the name of the  
 +
secondary configuration file.
 +
 
 
<pre>
 
<pre>
 
LABEL othermenu
 
LABEL othermenu
MENU LABEL Another Menu
+
MENU LABEL Another Menu
KERNEL menu.c32
+
KERNEL menu.c32
APPEND othermenu.conf
+
APPEND othermenu.conf
 
</pre>
 
</pre>
If you specify more than one file, they will all be read, in the order specified.  The dummy filename ~ (tilde) is replaced with the filename of the main configuration file.
+
If you specify more than one file, they will all be read, in the order  
 +
specified.  The dummy filename {{nowrap|"~" (tilde)}} is replaced with the filename  
 +
of the main configuration file.
 +
 
 +
{|
 +
|
 
<pre>
 
<pre>
 
# The file graphics.conf contains common color and layout commands for
 
# The file graphics.conf contains common color and layout commands for
 
# all menus.
 
# all menus.
 
LABEL othermenu
 
LABEL othermenu
MENU LABEL Another Menu
+
MENU LABEL Another Menu
KERNEL vesamenu.c32
+
KERNEL vesamenu.c32
APPEND graphics.conf othermenu.conf
+
APPEND graphics.conf othermenu.conf
 
+
 
# Return to the main menu
 
# Return to the main menu
 
LABEL mainmenu
 
LABEL mainmenu
MENU LABEL Return to Main Menu
+
MENU LABEL Return to Main Menu
KERNEL vesamenu.c32
+
KERNEL vesamenu.c32
APPEND graphics.conf ~
+
APPEND graphics.conf ~
 
</pre>
 
</pre>
 +
|}
 
See also the <tt>MENU INCLUDE</tt> directive above.
 
See also the <tt>MENU INCLUDE</tt> directive above.

Revision as of 19:15, 1 February 2019


Additional items that must be documented (in both doc/menu.txt and this page) since 4.0:

  • New MENU IMMEDIATE --- permit hotkeys to activate immediately without needing Enter.
  • New MENU HELP statement to display fullscreen help text as a result of a menu selection. documented
  • New MENU HIDDENKEY command to provide a one-keystroke way to activate a boot option from a hidden menu intro screen. documented
  • New MENU SAVE statement. documented
  • New MENU CLEAR statement. documented
  • New MENU SHIFTKEY statement. documented
  • New MENU RESOLUTION statement. documented


(See also Syslinux 4 Changelog and How do I configure Syslinux )

( Note that since version 3.74, the default directive usage has changed. Use UI instead) ( See UI mode or Changes in 3.74 )


Note: Some minor updated documentation can be seen at the Menu wiki page.
The content of doc/menu.txt (6.04-pre1, with some updates):


There are two menu systems included with Syslinux, the advanced menu system, and the simple menu system.


THE ADVANCED MENU SYSTEM

The advanced menu system, written by Murali Krishnan Ganapathy, is located in the com32/cmenu/ sub-directory. It allows the user to create hierarchical sub-menus, dynamic options, check-boxes, and just about anything. It requires the menu to be compiled from a simple C file (see com32/cmenu/simple.c and com32/cmenu/complex.c for examples).

The advanced menu system does not support serial console at this time.

See com32/cmenu/README for more information.

THE SIMPLE MENU SYSTEM

The simple menu system is based on a module located at com32/menu/vesamenu.c32 (graphical) or com32/menu/menu.c32 (text mode only). It uses the same configuration file as the regular Syslinux command line, and displays all the LABEL statements.

To use the menu system, simply make sure [vesa]menu.c32 is in the appropriate location for the boot medium (the same directory as the configuration file for SYSLINUX, EXTLINUX and ISOLINUX, and the same directory as pxelinux.0 for PXELINUX), and put the following options in the configuration file:

UI menu.c32


There are a few menu additions to the configuration file, all starting with the keywords MENU or TEXT. As the rest of the Syslinux configuration file language, it is case-insensitive.

The remainder of this document is a reference of the directives that are relevant in the Simple Menu System.


MENU TITLE title

Give the menu a title. The title is presented at the top of the menu.


MENU HIDDEN

Do not display the actual menu unless the user presses a key. All that is displayed is a timeout message.


MENU HIDDENKEY key[,key...] command...

If the key used to interrupt MENU HIDDEN is "key", then execute the specified command instead of displaying the menu.
Currently, the following key names are recognized:
Backspace, Tab, Enter, Esc, Space, F1..F12, Up, Down, Left, Right, PgUp, PgDn, Home, End, Insert, Delete
... in addition to all single characters plus the syntax " ^X " for " [Ctrl-X] ". Note that single characters are treated as case sensitive, so "A" and "a" can bind different commands. The same command can be bound to different keys by giving a comma-separated list of them:
menu hiddenkey A,a key_a_command


MENU CLEAR

Clear the screen when exiting the menu, instead of leaving the menu displayed. For vesamenu, this means the graphical background is still displayed without the menu itself for as long as the screen remains in graphics mode.


MENU SHIFTKEY

Exit the menu system immediately unless either the Shift or the Alt key is pressed, or Caps Lock or Scroll Lock is set.


MENU SEPARATOR

Insert an empty line in the menu.


MENU LABEL label

(Only valid after a LABEL statement.)
Change the label displayed for a specific menu entry. Display a label that is not suitable for the command line. For example:
 # Soft Cap Linux
 LABEL softcap
  MENU LABEL Soft Cap ^Linux 9.6.36
  KERNEL softcap-9.6.36.bzi
  APPEND whatever
  
 # A very dense operating system
 LABEL brick
  MENU LABEL ^Windows CE/ME/NT
  KERNEL chain.c32
  APPEND hd0 2
The caret symbol (^) in a MENU LABEL statement defines a hotkey. Hotkeys are highlighted in the menu. When a hotkey is pressed, the cursor will move to the corresponding menu entry. If MENU IMMEDIATE is present, then when a hotkey is pressed the corresponding menu entry will be immediately launched.
Reusing hotkeys has no effect on subsequent entries; they will not be highlighted, and the cursor will not move to them when the hotkey is pressed again.
Keep in mind that the LABELs, not MENU LABELs, must be unique,

or odd things will happen to the command-line.


MENU INDENT count

(Only valid after a LABEL statement.)
Add "count" spaces in front of the displayed menu entry.


MENU DISABLE

(Only valid after a LABEL statement.)
Make the entry unselectable. This allows to display a section in the menu with different options below it. For example:
# Entries for network boots
LABEL -
  MENU LABEL Network:
  MENU DISABLE
 
# Soft Cap Linux
LABEL softcap
  MENU LABEL Soft Cap ^Linux 9.6.36
  MENU INDENT 1
 KERNEL softcap-9.6.36.bzi
 APPEND whatever
 
# Dos 6.22
LABEL dos
  MENU LABEL ^Dos 6.22
  MENU INDENT 1
 KERNEL memdisk
 APPEND initrd=dos622.imz
 
# Separator
  MENU SEPARATOR
 
# Entries for local boots
LABEL -
  MENU LABEL Local:
  MENU DISABLE
 
# Windows 2000
LABEL w2k
  MENU LABEL ^Windows 2000
  MENU INDENT 1
 KERNEL chain.c32
 APPEND hd0 1
 
# Windows XP
LABEL xp
  MENU LABEL Windows ^XP
  MENU INDENT 1
 KERNEL chain.c32
 APPEND hd0 2


MENU HIDE

(Only valid after a LABEL statement.)
Suppresses a particular LABEL entry from the menu.


MENU DEFAULT

(Only valid after a LABEL statement.)
The particular menu entry is considered the default for the particular (sub)menu. If no default is specified, use the first one. See also the DEFAULT directive.


TEXT HELP
Help text ...
... which can span multiple lines
ENDTEXT

(Only valid after a LABEL statement.)
Specify a help text that should be displayed when a particular selection is highlighted.


MENU PASSWD passwd

(Only valid after a LABEL statement, or a MENU BEGIN statement.)
Set a password on this menu entry. "passwd" can be either a cleartext password or a password encrypted with one of the following algorithms:
 
MD5		(Signature: $1$)
SHA-1		(Signature: $4$)
SHA-2-256	(Signature: $5$)
SHA-2-512	(Signature: $6$)
Use the included Perl scripts "sha1pass" or "md5pass" to encrypt passwords. MD5 passwords are compatible with most Unix password file utilities; SHA-1 passwords are probably unique to Syslinux; SHA-2 passwords are compatible with very recent Linux distributions. Obviously, if you don't encrypt your passwords they will not be very secure at all.
If using passwords, make sure to use "NOESCAPE 1" and "PROMPT 0", and either set "ALLOWOPTIONS 0" or use a master password (see below).
If passwd is an empty string, this menu entry can only be unlocked with the master password.


MENU MASTER PASSWD passwd

Set a master password. This password can be used to boot any menu entry. If this directive is used, then the master password is also required for the [Tab] and [Esc] keys to work.


MENU RESOLUTION width height

Request a specific screen resolution when in graphics mode. The default is "640 480" corresponding to a resolution of 640x480 pixels, which all VGA-compatible monitors should be able to display.
If the requested resolution is unavailable, the text mode menu is displayed instead.


MENU BACKGROUND background

For vesamenu.c32, set the background image. The background can either be a color (see MENU COLOR) or the name of an image file, which should be the size of the screen (normally 640x480 pixels, but see MENU RESOLUTION) and either in PNG, JPEG or LSS16 format.
Note: When using an image file as background, its resolution should match the values used in MENU RESOLUTION.


MENU BEGIN [tagname]
MENU END

Begin/end a submenu. The entries between MENU BEGIN and MENU END form a submenu, which is marked with a ">" mark on the right hand of the screen. Submenus inherit the properties of their parent menus, but can override them, and can thus have their own backgrounds, master passwords, titles, timeouts, messages and so forth.


MENU GOTO tagname

(Only valid after a LABEL statement.)
Transfer to the named submenu instead of booting anything. To transfer to the top-level menu, specify "menu goto .top".


MENU EXIT [tagname]

(Only valid after a label statement inside MENU BEGIN ... MENU END.)
Exit to the next higher menu, or, if tagname is specified, to the named menu.


MENU QUIT

(Only valid after a LABEL statement.)
Quit the menu system.
WARNING: Even if either MENU MASTER PASSWD or "ALLOWOPTIONS 0" is set, MENU QUIT will still allow exiting to the CLI; however, a separate MENU PASSWD can of course be set for this label / menu entry.


MENU START

(Only valid inside MENU BEGIN ... MENU END.)
Define the starting menu for the menu system, instead of starting at the top-level menu. See also the DEFAULT directive.


DEFAULT label

Set the global default. If "label" points into a submenu, that menu becomes the start menu. In other words, this directive has the same effect as both MENU DEFAULT and MENU START.
For backwards compatibility with earlier versions of Syslinux, this behavior is ignored unless the configuration file also contains a UI directive.
Note: the CLI accepts options after the label, or even a non-label. The menu system does not support that.


MENU SAVE
MENU NOSAVE

Remember the last selected entry and make that one the default for the next boot. A password-protected menu entry is *not* saved. This requires the ADV data storage mechanism, which is currently only implemented for SYSLINUX, although the other Syslinux derivatives will accept the command (and ignore it).
NOTE: MENU SAVE stores the LABEL tag of the selected entry. This mechanism therefore relies on LABEL tags being unique. On the other hand, it handles changes in the configuration file gracefully.
NOTE: In software RAID-1 setups, MENU SAVE only stores the default label on the actual boot disk. This may lead to inconsistent reads from the array, or unexpectedly change the default label after array resynchronization or disk failure.
The MENU SAVE information can be fully cleared with "extlinux --reset-adv <bootdir>".
A MENU SAVE or MENU NOSAVE at the top of a (sub)menu affects all entries underneath that (sub)menu except those that in turn have MENU SAVE or MENU NOSAVE declared. This can be used to restrict which specific entries are allowed to be saved when executed.


INCLUDE filename [tagname]
MENU INCLUDE filename [tagname]

Include the contents of the "filename" configuration file at this point.
In the case of MENU INCLUDE, the included data is only seen by the menu system; the core Syslinux code does not parse this command, so any labels defined in it are unavailable.
If a tagname is included, the whole file is considered to have been bracketed with a MENU BEGIN tagname ... MENU END pair, and will therefore show up as a submenu.


MENU AUTOBOOT message

Replace the message "Automatic boot in # second{,s}...". The "#" symbol is replaced with the number of remaining seconds. The syntax "{singular,[dual,]plural}" can be used to conjugate appropriately.


MENU TABMSG message

Replace the message "Press [Tab] to edit options".


MENU NOTABMSG message

Take the place of the TABMSG message when the [Tab] key is not allowed, i.e. if the possibility to edit the command is disabled. Defaults to blank.


MENU PASSPROMPT message

Replace the message "Password required".


MENU COLOR element ansi foreground background shadow

Set the color of element "element" to the specified color sequence:
screen          Rest of the screen
border          Border area
title           Title bar
unsel           Unselected menu item
hotkey          Unselected hotkey
sel             Selection bar
hotsel          Selected hotkey
disabled        Disabled menu item
scrollbar       Scroll bar
tabmsg          Press [Tab] message
cmdmark         Command line marker
cmdline         Command line
pwdborder       Password box border
pwdheader       Password box header
pwdentry        Password box contents
timeout_msg     Timeout message
timeout         Timeout counter
help            Help text
msgXX           Message (F-key) file attribute XX
... where XX is two hexadecimal digits (the "plain text" is 07).
"ansi" is a sequence of semicolon-separated ECMA-48 Set Graphics Rendition (<code><ESC>[m</code>) sequences:
0     reset all attributes to their defaults
1     set bold
4     set underscore (simulated with color on a color display)
5     set blink
7     set reverse video
22    set normal intensity
24    underline off
25    blink off
27    reverse video off
30    set black foreground
31    set red foreground
32    set green foreground
33    set brown foreground
34    set blue foreground
35    set magenta foreground
36    set cyan foreground
37    set white foreground
38    set underscore on, set default foreground color
39    set underscore off, set default foreground color
40    set black background
41    set red background
42    set green background
43    set brown background
44    set blue background
45    set magenta background
46    set cyan background
47    set white background
49    set default background color
These are used (a) in text mode, and (b) on the serial console.
"foreground" and "background" are color codes in #AARRGGBB notation, where AA RR GG BB are hexadecimal digits for alpha (opacity), red, green and blue, respectively. #00000000 represents fully transparent, and #ffffffff represents opaque white.
"shadow" controls the handling of the graphical console text shadow. Permitted values are "none" (no shadowing), "std" or "standard" (standard shadowing - foreground pixels are raised), "all" (both background and foreground raised), and "rev" or "reverse" (background pixels are raised).
If any field is set to "*" or omitted (at the end of the line) then that field is left unchanged.


The current defaults are:
menu color screen	37;40      #80ffffff #00000000 std
menu color border	30;44      #40000000 #00000000 std
menu color title	1;36;44    #c00090f0 #00000000 std
menu color unsel	37;44      #90ffffff #00000000 std
menu color hotkey	1;37;44    #ffffffff #00000000 std
menu color sel		7;37;40    #e0000000 #20ff8000 all
menu color hotsel	1;7;37;40  #e0400000 #20ff8000 all
menu color disabled	1;30;44    #60cccccc #00000000 std
menu color scrollbar	30;44      #40000000 #00000000 std
menu color tabmsg	31;40      #90ffff00 #00000000 std
menu color cmdmark	1;36;40    #c000ffff #00000000 std
menu color cmdline	37;40      #c0ffffff #00000000 std
menu color pwdborder	30;47      #80ffffff #20ffffff std
menu color pwdheader	31;47      #80ff8080 #20ffffff std
menu color pwdentry	30;47      #80ffffff #20ffffff std
menu color timeout_msg	37;40      #80ffffff #00000000 std
menu color timeout	1;37;40    #c0ffffff #00000000 std
menu color help		37;40      #c0ffffff #00000000 std
menu color msg07	37;40      #90ffffff #00000000 std


MENU MSGCOLOR fg_filter bg_filter shadow

Set all the msgXX colors to a color scheme derived from the fg_filter and bg_filter values. Background color zero is always treated as transparent. The default corresponds to:
menu msgcolor #90ffffff #80ffffff std
This directive should come before any directive that customizes individual msgXX colors.


MENU WIDTH 80
MENU MARGIN 10
MENU PASSWORDMARGIN 3
MENU ROWS 12
MENU TABMSGROW 18
MENU CMDLINEROW 18
MENU ENDROW -1
MENU PASSWORDROW 11
MENU TIMEOUTROW 20
MENU HELPMSGROW 22
MENU HELPMSGENDROW -1
MENU HIDDENROW -2
MENU HSHIFT 0
MENU VSHIFT 0

These options control the layout of the menu on the screen.
The values above are the defaults.
A negative value is relative to the calculated length of the screen (25 rows for text mode, 28 rows for VESA graphics mode).


F1 textfile [background]
...
F12 textfile [background]

Display full-screen help (also available at the command line). The same control code sequences as in the command line interface are supported, although some are ignored.
Additionally, an optional second argument allows a different background image to be displayed by vesamenu.c32 (see MENU BACKGROUND for supported formats). The CLI and menu.c32 will ignore the second argument.


MENU HELP textfile [background]

Create a menu entry which, when selected, displays full-screen help in the same way as the F-key help.


The menu system honours the TIMEOUT command. If TIMEOUT is specified, it will execute the ONTIMEOUT command if one exists, otherwise it will pick the DEFAULT menu option. WARNING: the TIMEOUT action will bypass password protection even if one is set for the specified ONTIMEOUT and/or DEFAULT entry!

Normally, users can press [Tab] to edit the menu entry, and [Esc] to return to the Syslinux command line. However, if the configuration file specifies "ALLOWOPTIONS 0", these keys will be disabled, and if MENU MASTER PASSWD is set, they require the master password.

The simple menu system supports serial console, using the normal SERIAL directive. However, it can be quite slow over a slow serial link; you probably want to set your baudrate to 38400 or higher if possible. It requires a Linux/VT220/ANSI-compatible terminal on the other end.

USING AN ALTERNATE CONFIGURATION FILE

It is also possible to load a secondary configuration file, to get to another menu. To do that, invoke (vesa)menu.c32 with the name of the secondary configuration file.

LABEL othermenu
 MENU LABEL Another Menu
 KERNEL menu.c32
 APPEND othermenu.conf

If you specify more than one file, they will all be read, in the order specified. The dummy filename "~" (tilde) is replaced with the filename of the main configuration file.

# The file graphics.conf contains common color and layout commands for
# all menus.
LABEL othermenu
 MENU LABEL Another Menu
 KERNEL vesamenu.c32
 APPEND graphics.conf othermenu.conf
 
# Return to the main menu
LABEL mainmenu
 MENU LABEL Return to Main Menu
 KERNEL vesamenu.c32
 APPEND graphics.conf ~

See also the MENU INCLUDE directive above.