Directives/special keys
Introduction and disambiguation
This document is about combining certain directives, together with special keys, affecting the way Syslinux behaves, specially during the initial boot time.
This document is not about:
- keyboard layout (language);
- usage of keys in the command line interface nor in boot menus.
The directives mentioned here are not sorted alphabetically, but rather in an attempt to help the reader understand their relations and differences. Each section in this page adds information or alternatives to a prior one. This document does not include every single detail about the directives mentioned here. Additional information about each individual directive is provided in the configuration wiki page and/or in the Menu wiki page.
Behavior
The following directives affect the way Syslinux behaves depending on the status (on/off) of certain keys.
Basic case
Using the following basic configuration, Syslinux will automatically launch mylabel:
DEFAULT mylabel LABEL mylabel KERNEL mykernel
Escape keys
To avoid the automatic launch of the DEFAULT command, press any one of the [Shift] or [Alt] keys, or set [Caps Lock] or [Scroll lock], during boot time.
Under certain conditions (such as specific hardware or BIOS versions), some of the alternative "escape" keys might not trigger the desired behavior. In such case, the other alternative "escape" keys should be used (instead of assuming that the feature does not work at all). For example, if [Shift] does not work, try [Alt].
Note: The goal of certain directives (some of them are mentioned in this document) is to change the behavior of Syslinux according to the status (on/off) of the "escape" keys during boot time. If a particular firmware (BIOS / UEFI) version is not capable of identifying (reading, sensing) the status of any of these "escape" keys during boot time, then at least part of the expected behavior of such directives will fail. The same consideration could be valid for a serial console. Please consider these potential situations when including such directives in a configuration file.
Note: If not even one of the alternative "escape" keys works as expected, please report it to the Syslinux Mailing List, including specific hardware and firmware details.
PROMPT
Alternatively, adding "PROMPT 1" will avoid the automatic launch of the DEFAULT command, without having to press any special keys. The following configuration will force Syslinux to display a "boot:" prompt, instead of automatically launching the DEFAULT command:
DEFAULT mylabel PROMPT 1 LABEL mylabel KERNEL mykernel
NOESCAPE
On the other hand,
to force the automatic launch of the DEFAULT command we would need to:
1_ not use PROMPT 1; and
2_ ignore the aforementioned "escape" keys' status
(i.e. whether any of the [Shift] or [Alt] keys is pressed,
or whether either [Caps Lock] or [Scroll lock] is set).
To accomplish the second condition, use NOESCAPE 1:
DEFAULT mylabel PROMPT 0 NOESCAPE 1 LABEL mylabel KERNEL mykernel
The "NOESCAPE 1" statement also disables the effects of the [Esc] key.
UI
UI overrides the PROMPT directive and takes precedence over the DEFAULT directive. Therefore, if UI is used, the PROMPT directive is ignored and the UI command - not the DEFAULT command - is automatically launched:
UI menu.c32 DEFAULT mylabel # Even if present, the PROMPT directive is ignored when UI is used. LABEL mylabel KERNEL mykernel |
UI and escape keys
Although the PROMPT directive is ignored when UI is used, the NOESCAPE directive is still considered.
If all the following conditions apply:
1_ UI is present; and,
2_ NOESCAPE 1 is not present; and
3_ any of the "escape" keys is used during boot time;
then the precise behavior might vary depending on the version of Syslinux. Under these conditions, with some versions the "boot:" prompt will be displayed, whereas with other versions the boot menu will be displayed in accordance to the UI directive. In either case, the DEFAULT command is not automatically launched, which is the main goal for using these "escape" keys.
MENU SHIFTKEY
While the typical goal of using the UI directive is to automatically display a user-friendly boot menu with several choices - instead of automatically booting the DEFAULT label - the opposite situation is also possible. Frequently, a user might want to normally launch the DEFAULT label, whereas only rarely the other choices in the boot menu are selected.
The MENU SHIFTKEY directive, when used together with UI, allows for the DEFAULT label to be launched directly without having to show first the boot menu. Under this configuration, the boot menu is displayed only when using the "escape" keys during boot time.
MENU HIDDEN
Similarly to MENU SHIFTKEY, the MENU HIDDEN directive also hides the initial boot menu, which can then be displayed when pressing some key. For MENU SHIFTKEY to show the boot menu, the aforementioned "escape" keys are used. For MENU HIDDEN to show the boot menu, pressing any key displays the menu.
Usually a TIMEOUT directive is also used in conjunction with MENU HIDDEN.
MENU HIDDENKEY
The MENU HIDDENKEY directive modifies the behavior of specific keys (or a combination of keys): instead of showing the boot menu when pressing a key - as it happens with MENU HIDDEN alone - a specific command can be directly triggered.
The MENU HIDDENKEY directive requires the MENU HIDDEN directive to be also present.
Using the caret symbol (^) in front of a key in a MENU HIDDENKEY statement means that the combination of [Ctrl] with such key would trigger the relevant command.
In the following example,
- pressing [a] (lowercase) or [A] (uppercase) would automatically execute "mylabel_a";
- pressing [b] (lowercase) or [Ctrl-B] (uppercase) or [Ctrl-b] (lowercase) would automatically execute "mylabel_b";
- note that pressing [B] (uppercase) alone (without [Ctrl]) would trigger no specific action other than the menu.
UI menu.c32 TIMEOUT 40 MENU HIDDEN MENU HIDDENKEY a,A mylabel_a MENU HIDDENKEY b,^B,^b mylabel_b LABEL mydefault KERNEL mykernel LABEL mylabel_a KERNEL mykernel_a LABEL mylabel_b KERNEL mykernel_b |
MENU LABEL hotkeys
The caret symbol (^) in a MENU LABEL statement defines a hotkey. While displaying the boot menu, hotkeys are highlighted and pressing a hotkey will move the selection to the corresponding menu item.
MENU IMMEDIATE
Allow hotkeys to activate immediately without needing to press [Enter].
Others
The following directives are not necessarily related to how Syslinux behaves, but rather to what the user is (dis)allowed. In other words, the following directives (dis)allow the user (to be able) to perform certain actions.
F1..F12
Load the respective DISPLAY file.
When using the serial console, press [Ctrl-F][digit] to get to the help screens, e.g. [Ctrl-F][2] to get to the F2 screen. For F10-F12, hit [Ctrl-F][A], [Ctrl-F][B], [Ctrl-F][C]. For compatibility with earlier versions, F10 can also be entered as [Ctrl-F][0].
NOCOMPLETE
Using "NOCOMPLETE 1", the [Tab] key does not display labels at the "boot:" prompt.
ALLOWOPTIONS
Please contact the Syslinux mailing list regarding this directive.
MENU PASSWD
Set a password on a particular menu entry.
MENU MASTER PASSWD
Set a master password. This password can be used to boot any menu entry (in comparison to MENU PASSWD). If this directive is used, then the master password is required for the [Tab] and [Esc] keys to work.
Novice protection
Syslinux will attempt to detect booting on a machine with too-little memory, which means the Linux boot sequence cannot be completed. If so, a message is displayed and the boot sequence is aborted. Holding down the [Ctrl] key while booting, disables this feature.