Install
Installing a Syslinux package is not the same as installing Syslinux as bootloader. This document is about how to install each of the Syslinux bootloaders so as to be able to use each of them to boot your system. This document is not about how to install some Syslinux-related package in your OS.
According to each (Linux) distribution, the Syslinux-related packages' names (and the amount of them) might vary. Each Syslinux-related file might be part of different packages, and the final location of the Syslinux-related files in the OS might vary too.
This document mentions several files that are part of the official Syslinux distribution archives published in kernel.org. The paths mentioned in this document are in reference to such official archives. The paths to the same files in your OS are not considered in this document.
The configuration file is not created/updated by the installation commands presented in this document. The configuration file might be modified either manually or by some auxiliary script/tool provided by a third party. In the official Syslinux distribution archives, there is no script (nor equivalent automatic method) to edit / modify / replace / update the configuration file(s). However, there are some command line options that allow changing the (next) boot behavior.
Contents
SYSLINUX
For BIOS systems, the SYSLINUX bootloader file is named "ldlinux.sys".
[4.00+] EXTLINUX has been merged into SYSLINUX, and both use "ldlinux.sys" as bootloader file.
[5.00+] In addition to the main bootloader file, SYSLINUX also needs at least a core module. The location of the core module file inside the official Syslinux distribution archives is "[bios/]com32/elflink/ldlinux/ldlinux.c32".
The SYSLINUX installers for BIOS systems will copy the bootloader file and patch the filesystem boot area (usually, the VBR). Since version 5.00, also the core module, "ldlinux.c32", is copied, together in the same directory, according to the installation command line options.
Note: The SYSLINUX bootloader is not installed to the MBR area (as other bootloaders do). See the mbr documentation about how to install the MBR/GPT boot code (if necessary), in addition to installing SYSLINUX.
Note: Some command line options are available in every alternative installer. Some command line options are (only) available in some installers but not in others.
Linux
There are several alternative commands available for installation of SYSLINUX as bootloader for BIOS systems.
Inside the official Syslinux distribution archives:
- [bios/]linux/syslinux
- Also known as "syslinux-nomtools", requires root permissions and the device's filesystem shall not be mounted. Supports FAT.
- [bios/]mtools/syslinux
- Depends on "mtools", requires unprivileged write permissions and the device's filesystem shall not be mounted. Supports FAT.
- [bios/]extlinux/extlinux
- Requires the filesystem (volume) to be mounted. Supports several filesystems.
The #options section in this document is valid for the Linux-based SYSLINUX installers since Syslinux 4.02, unless noted differently.
Syntax:
Note: The Device should be unmounted
before executing the syslinux command.
syslinux --version
syslinux [--help]
syslinux [options] <Device_Or_Image>
Note: For mounted fs installation:
extlinux --version
extlinux [--help]
extlinux [options] <target_directory>
Linux Examples:
syslinux --directory /boot/syslinux/ --install /dev/sdb1 |
Note the slash characters, "/", before and after the directory path.
syslinux --install /dev/fd0
Windows
The Windows-based installer located inside the official Syslinux distribution archives as "[bios/]win32/syslinux.exe" supports FAT and NTFS mounted filesystems.
In some 64-bit Windows environments (e.g. some WinPE x64), the normal "syslinux.exe" installer might fail. In such case, use "[bios/]win64/syslinux64.exe" instead.
The Windows-based SYSLINUX installers are also capable of installing an optional MBR boot code in addition to the normal installation of the bootloader. See #options.
The #options section in this document is valid for the Windows-based SYSLINUX installers since Syslinux 4.02, unless noted differently.
Syntax:
syslinux[64].exe --version
syslinux[64].exe [--help]
syslinux[64].exe [options] <drive>: [bootsecfile]
|
Windows Examples:
Floppy: (a: in this example)
syslinux.exe --install a:
HardDrive/FlashDrive/etc: (z: in this example)
syslinux.exe --mbr --active --directory /boot/syslinux/ --install z: |
- In the above example, syslinux.cfg would be expected to be in z:\boot\syslinux\syslinux.cfg.
- Note that the directory path in the command line is using slash "/", not backslash "\".
- Note the slash characters, "/", before and after the directory path.
- NOTE: Under NT/2K you may get a dialog box about not getting exclusive access and with Abort/Retry/Ignore buttons; selecting "Ignore" will make the command execute sucessfully.
DOS
The DOS-based installer located inside the official Syslinux distribution archives as "[bios/]dos/syslinux.com" supports FAT mounted filesystems.
The #options section in this document is valid for the DOS-based SYSLINUX installers since Syslinux 4.02, unless noted differently.
Syntax:
syslinux.com --version
syslinux.com [--help]
syslinux.com [options] <drive>: [bootsecfile]
|
DOS Examples:
syslinux.com --install a:
options
Note: The SYSLINUX bootloader is not installed to the MBR area (as other bootloaders do). See the mbr documentation about how to install the MBR/GPT boot code (if necessary), in addition to installing SYSLINUX.
Note: Some command line options are available in every alternative installer. Some command line options are (only) available in some installers but not in others.
Some command line options are available in some versions but not in others; i.e. there are old deprecated options, and new options added.
The following tables describe the available "long" options. For some of them, the "short" option is shown (too). The following options are available since version 4.02, unless noted differently. For the full list of options for each alternative installer (which might vary for each version), please execute the specific installer with the "--help" option.
Note that the options are case-sensitive.
Certain options require an additional argument (e.g. "--once="). In such cases, the option itself and its argument need to be separated, either by an equal sign ("=") or by a space character (e.g. "--sectors=32" or "--sectors 32").
| -h | --help | |
| -v | --version | |
| -i | --install | |
| Install over the current bootsector | ||
| -U | --update | |
| Update a previous installation of the bootloader code | ||
| -H | --heads=# | |
| Force number of heads | ||
| -S | --sectors=# | |
| Force the number of sectors per track | ||
| -z | --zip | |
| Force zipdrive geometry (-H 64 -S 32) | ||
| -s | --stupid | |
| Slow, safe, stupid mode.
Use simpler code that boots better. May work on some very buggy BIOSes on which SYSLINUX would otherwise fail. If you find a machine on which the "-s" option is required to make it boot reliably, please send as much info about your machine as you can, and include the failure mode. | ||
| -r | --raid | |
| Raid mode.
If Syslinux fails to boot, then tell the BIOS to boot the next device in the boot sequence (usually the next hard disk), instead of stopping with an error message. This is useful for RAID-1 booting. | ||
| --once=... | ||
| Execute a one-time command upon next boot. Usually the command is a known label. | ||
| --clear-once | ||
| Clear the boot-once command | ||
| --reset-adv | ||
| Reset auxiliary data vector | ||
| --menu-save=mylabel | ||
| Set the label to select as default on the next boot.
For this option to be applied, the configuration file needs to include the MENU SAVE directive too. | ||
Usage:
syslinux [options] <Device_Or_Image>
| ||
| -d | --directory <target_path> | |
| Subdirectory for installation target, based on the root of the target device.
The <target_path> directory should rather be created before executing the command. The <target_path> should rather be enclosed between slash characters. | ||
| -f | --force | |
| Force installing. Ignore precautions. In some cases, this option might not change the result. | ||
| --offset=# | ||
| Specify the byte offset of the filesystem image in the target "device".
The offset option is applicable only when the target device is a disk image file. | ||
Usage:
syslinux [options] <drive>: [bootsecfile]
| ||
| -d | --directory <target_path> | |
| Subdirectory for installation target, based on the root of the target device.
The <target_path> directory should rather be created before executing the command. The <target_path> should rather be enclosed between slash characters. | ||
| -f | --force | |
| Force installing. Ignore precautions. In some cases, this option might not change the result. | ||
| -m | --mbr | |
| Install a generic boot code to the MBR.
Note: The SYSLINUX bootloader is not installed to the MBR area, whether with or without this option. | ||
| -a | --active | |
| Mark the partition as "active" ("boot" flag). | ||
Usage:
extlinux [options] <target_directory>
| ||
| --device=device_name | ||
| [4.06+] Force use of a specific block device (experts only). | ||
other versions
Some command line options that were valid for prior versions have then changed in newer ones (or are deprecated). Newer versions might also add new options.
Linux old Syntax:
|
The -o option (if specified) is used with a disk image file and specifies the byte offset of the filesystem image in the file.
Note: Older versions used to use "-o" (deprecated) for "--offset". In versions where the long option, "--offset", is available, the use of the short option, "-o", should be avoided. If a byte offset value is required, use the long option, "--offset", when available.
NT/2K/XP old Syntax:
|
DOS old Syntax:
|
EXTLINUX
[4.00+] EXTLINUX has been merged into SYSLINUX, and both use "ldlinux.sys" as bootloader file. See the #SYSLINUX section of this document.
ISOLINUX
In BIOS systems, the ISOLINUX bootloader file is named "isolinux.bin". There is an alternative "isolinux-debug.bin" bootloader file for special purposes.
The location of the ISOLINUX bootloader file inside the official Syslinux distribution archives is "[bios/]core/isolinux.bin".
[5.00+] In addition to the main bootloader file, ISOLINUX also needs at least a core module. The location of the core module file inside the official Syslinux distribution archives is "[bios/]com32/elflink/ldlinux/ldlinux.c32".
The bootloader file is used by so-called "ISO building tools" (e.g. mkisofs/genisoimage/xorriso) as an "El Torito no-emulation" method for booting optical media.
There are no "installers" for ISOLINUX. Before building ISO images, usually the "isolinux.bin" bootloader file needs to be copied to a specific location, part of the future content of the ISO image. The "ISO building tool" will need to know this location as part of the parameters used during the procedures to build the ISO image. Since version 5.00, also the core module named "ldlinux.c32" needs to be copied to the same directory as "isolinux.bin".
Optionally, ISO images can be featured with isohybrid capabilities, so as to be able to boot storage media other than optical ones.
See ISOLINUX.
PXELINUX
The following bootloader files for BIOS network clients are included in the official Syslinux distribution archives:
- [bios/]core/pxelinux.0
- Supports TFTP network booting.
- [bios/]core/lpxelinux.0
- [6.03+] Supports TFTP/FTP/HTTP network booting.
- [bios/]gpxe/gpxelinux.0
- [3.70-6.03] A merge/mix of gpxe and pxelinux.0, supports several network protocols by means of network boot images (nbi).
[5.00+] In addition to the main bootloader file, PXELINUX also needs at least a core module. The location of the core module file inside the official Syslinux distribution archives is "[bios/]com32/elflink/ldlinux/ldlinux.c32".
The bootloader file shall be located in the relevant server, where the network client fetches it. Since version 5.00, also the core module named "ldlinux.c32" needs to be copied to the same directory as the bootloader file.
See PXELINUX.
For UEFI network booting, see the #UEFI section of this document.
UEFI
For UEFI systems, the bootloader files included in the official Syslinux distribution archives are originally named syslinux.efi:
- efi32/efi/syslinux.efi
- UEFI bootloader for EFI IA32 (x86) firmware.
- efi64/efi/syslinux.efi
- UEFI bootloader for EFI X64 (x86_64) firmware.
The UEFI bootloader files can be renamed, usually maintaining the ".efi" filename extension.
In UEFI systems, a GPT scheme usually replaces the traditional MBR Partition Table for storage media. The GPT standard is part of the UEFI specification, and it can also be used with BIOS firmware (Syslinux includes "gptmbr*.bin" files for the latter).
For storage media, UEFI bootloaders are expected to be found in a so-called EFI SYSTEM PARTITION.
The EFI SYSTEM PARTITION (see UEFI and EFI System partition) is frequently known as "$ESP". The most commonly supported filesystem format for $ESP is FAT32, although the UEFI specs allow for others too. Each firmware might recognize additional / different / several filesystems for $ESP (e.g. other FAT variants, UDF, HPF+, NTFS,...).
According to the UEFI specs, the default location and naming conventions for storage media are:
- EFI_SYSTEM_PARTITION/EFI/BOOT/BOOTIA32.EFI
- for EFI IA32 firmware.
- EFI_SYSTEM_PARTITION/EFI/BOOT/BOOTX64.EFI
- for EFI X64 firmware.
The UEFI specs allow for additional alternative locations and names for UEFI binaries; the aforementioned are just the default location and naming conventions according to the UEFI specs, depending on the relevant firmware/architecture type.
Some firmware might use a different default location and naming for its default UEFI executable(s).
Note: According to the UEFI specs, the firmware uses backslash ("\") instead of slash ("/") characters as path separator.
The syslinux.efi bootloader files need at least a corresponding core module.
Inside the official Syslinux distribution archives,
the core modules for respective UEFI architectures are located as:
- efi32/com32/elflink/ldlinux/ldlinux.e32
- for EFI IA32.
- efi64/com32/elflink/ldlinux/ldlinux.e64
- for EFI X64.
There are no "installers" for syslinux.efi. Copy the relevant syslinux.efi file to an appropriate location, and rename it if necessary or desired. Additionally, copy the necessary core module file (either "ldlinux.e32" or "ldlinux.e64", according to the architecture of the firmware) to the same directory.
For UEFI network boot, the "installation" (or rather, "setup") is
similar to the #PXELINUX section of this document, with some differences:
- The UEFI network bootloader file is "syslinux.efi", instead of "lpxelinux.0".
- The adequate "syslinux.efi" file depends on the architecture of the client's firmware, i.e. EFI IA32 or EFI X64.
- Instead of "[bios/]com32/elflink/ldlinux/ldlinux.c32", the core module is either "efi32/com32/elflink/ldlinux/ldlinux.e32" or "efi64/com32/elflink/ldlinux/ldlinux.e64", depending on the architecture of the client's firmware.
The UEFI bootloader file shall be located in the relevant server, where the UEFI network client fetches it. Together with the UEFI bootloader file, the relevant core module, named either "ldlinux.e32" or "ldlinux.e64" respectively, needs to be copied to the same directory as the bootloader file.
Multiple BIOS and UEFI bootloader files and their respective "ldlinux" core module can work together, selecting the necessary booting files depending on the architecture of the client's firmware.
See PXELINUX#UEFI and PXELINUX-Multi-Arch.
file list
This document mentions several files that are part of the official Syslinux distribution archives published in kernel.org. The paths mentioned in this document are in reference to such official archives. The paths to the same files in your OS are not considered in this document.
The locations of the relevant files as found in the official Syslinux distribution archives are here posted for convenience.
SYSLINUX (for BIOS) installers:
[bios/]linux/syslinux [bios/]mtools/syslinux [bios/]extlinux/extlinux [bios/]win32/syslinux.exe [bios/]win64/syslinux64.exe [bios/]dos/syslinux.com
ISOLINUX:
[bios/]core/isolinux.bin [bios/]com32/elflink/ldlinux/ldlinux.c32
Network booting (for BIOS):
[bios/]core/pxelinux.0 [bios/]core/lpxelinux.0 [bios/]gpxe/gpxelinux.0 [bios/]com32/elflink/ldlinux/ldlinux.c32
UEFI IA32:
efi32/efi/syslinux.efi efi32/com32/elflink/ldlinux/ldlinux.e32
UEFI X64:
efi64/efi/syslinux.efi efi64/com32/elflink/ldlinux/ldlinux.e64
See also
- Where the configuration file can/should be located
- Library modules used since version 5.00
- The PATH directive
- Bootloader configuration
- Network booting multiple firmware's architectures
