For a basic explanation of the APPEND directive see Config#APPEND.
Take the following simple configuration:
DEFAULT mykernel APPEND root=/dev/sda2
Note that the APPEND line here is a global directive, as it is not part of any LABEL entry.
For Syslinux 4.xx and older, the above simple configuration works as (it used to be) expected.
Since version 5.00, the result for the above sample configuration is that the "root=/dev/sda2" argument is not parsed, which will lead to unexpected results, most probably with some kind of failure to boot the OS. In other words, the global APPEND is ignored by the DEFAULT directive.
For the above example, the configuration could be re-written as:
DEFAULT mykernel root=/dev/sda2
or even better as:
DEFAULT mylabel LABEL mylabel KERNEL mykernel APPEND root=/dev/sda2
which "moves" the global APPEND line into the new LABEL entry.
Generally speaking, it is recommended to have at least one LABEL entry.
The effect of the global APPEND on the resulting command depends on whether the particular LABEL entry includes its own specific APPEND.
# The following is a global directive: APPEND root=/dev/sda2 # default non-label command; global append ignored: DEFAULT mykernel # Specific append present; global append ignored: LABEL some_label KERNEL mykernel APPEND some_additional_options # No specific append; global append used: LABEL mylabel KERNEL mykernel # Specific append present; global append ignored: LABEL mylabel_alone KERNEL mykernel APPEND -
In the above example, the global APPEND is ignored by the DEFAULT command and by label entries that already have an APPEND directive, and it is effectively parsed when executing a label entry that has no APPEND line of its own.
Similarly, when using the DEFAULT directive with a label (as opposed to using it with a non-label command), the behavior is the same as with the corresponding label entry.
As pointed out in the #per-label section, the effect of the global APPEND depends on whether an APPEND line is used on a particular LABEL entry.
Since 5.00, the presence of an INITRD directive in a particular LABEL entry has no influence on whether a global APPEND is effectively used when executing such LABEL.
# The following is a global directive: APPEND vga=normal DEFAULT no_append_and_no_initrd # No specific append; global append used: LABEL no_append_and_no_initrd KERNEL mykernel # Specific append present; global append ignored: LABEL with_append_and_no_initrd KERNEL mykernel APPEND some_additional_options # Similar entries follow, but with an additional INITRD directive. # No specific append; global append used: LABEL no_append_and_with_initrd KERNEL mykernel INITRD myinitrd # Specific append present; global append ignored: LABEL with_append_and_with_initrd KERNEL mykernel INITRD myinitrd APPEND some_additional_options
Normally, the following directive:
would be considered equivalent to "APPEND initrd=myinitrd". But when using global APPEND, a separate INITRD directive has a different effect, as shown in the above examples.
Since 5.00, the global APPEND affects (some) LABEL entries only. Specifically, the global APPEND affects those LABEL entries with no particular APPEND line, as shown in the #per-label section.
When entering a label from the boot: prompt (or from a Syslinux boot menu), the resulting command is executed according to the aforementioned rules.
But what about non-label commands? Since 5.00, when typing in non-label commands, the global APPEND is ignored, just as it happens with the DEFAULT directive.
For versions prior to 5.00, the global APPEND was silently imposed on each and every command typed in, and there was no method to avoid it, sometimes producing unexpected results. This type of behavior was a reason to avoid using the global APPEND directive at all. With the changed behavior since version 5.00, the global APPEND directive is now flexible enough so as to be actually usable.
per-label and global
From the above examples, combining a specific APPEND line in a LABEL entry together with a global APPEND would seem not possible. One potential workaround would be:
# The following is a global directive: APPEND global_append DEFAULT mylabel # Specific append present; global append ignored: LABEL mylabel KERNEL mykernel APPEND myappend # No specific append; global append used: LABEL mylabel_2 KERNEL mykernel myappend
The effective result for mylabel is:
The effective result for mylabel_2 is:
mykernel myappend global_append
Note that with this last syntax, the latest arguments in the resulting command come from the global APPEND.
Although some scripts -- which attempt to retrieve the KERNEL line and the APPEND line separately for further utilization of their contents -- could be impacted by this syntax, such scripts would also need additional adaptations if a global APPEND were to be used, whether using older or newer versions of Syslinux.
The cmd.c32 module combines a basic command together with some additional parameters; thus providing an alternative to the global APPEND.
The following is one of many possible combinations.
# The following would be a global directive, # but it is commented out: # APPEND global_append DEFAULT mylabel # Specific append present; global append ignored: LABEL mylabel KERNEL mykernel APPEND myappend # Specific append present; global append ignored: # Same mykernel but with "global_append" options. # The original "myappend" options not included. LABEL mykernel_plus_global KERNEL mykernel APPEND global_append # Specific append present; global append ignored: LABEL mykernel_plus_global_plus_myappend KERNEL cmd.c32 APPEND mykernel_plus_global myappend
In the above example, all LABEL entries have their own APPEND line. When using 5.00 or newer, in fact the initial global "APPEND global_append" line is not being used by any entry (that's why it is already commented out in the example).
When executing the mykernel_plus_global_plus_myappend label, the effective result is the "mykernel global_append myappend" command.
See Cmd.c32 for more examples.