Directives/special keys

From Syslinux Wiki
Jump to: navigation, search

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:

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.

Retrieved from "https://wiki.syslinux.org/wiki/index.php?title=Directives/special_keys&oldid=4722"