Important: You are required to change your passwords used for Gentoo services and set an email address for your Wiki account if you haven't done so. See the full announcement and Wiki email policy change for more information.


From Gentoo Wiki
(Redirected from Syslinux Bootloader)
Jump to: navigation, search

External resources

Syslinux is a package that contains a family of bootloaders. The package includes SYSLINUX (FAT filesystem bootloader), EXTLINUX (ext2/3/4 and btrfs filesystem bootloader), PXELINUX (Network PXE bootloader) and ISOLINUX (ISO-9660 (CDROM) bootloader).


The installation of sys-boot/syslinux will provide the software on the system but not install (activate) the bootloader itself.

→ Information about USE flags
USE flag Default Recommended Description
custom-cflags No No Build with user-specified CFLAGS (unsupported)
root # emerge --ask syslinux


Assuming /dev/sda1 is the boot partition. If not: make adjustments!

To use EXTLINUX you need to make sure to both install the proper boot sector, and then to install the actual boot loader into the partition. Make sure not to omit steps.

The boot sector setups are not needed for the SYSLINUX, PXELINUX and ISOLINUX installations.

Boot sector setup

MBR (msdos) setup

These instructions are for MBR (msdos) partition layout. For GPT, read GPT setup.

First install the boot sector provided by syslinux. Take due care with this command; if count=1 is not given it will overwrite the entire disk rather than just the first 440 bytes:

root # dd bs=440 conv=notrunc count=1 if=/usr/share/syslinux/mbr.bin of=/dev/sda

Mark the boot partition as active. A * will appear in the "Boot" column:

root # fdisk /dev/sda
Command (m for help): a
Partition number (1-4): 1
Command (m for help): p
   Device Boot      Start         End      Blocks   Id  System
/dev/sda1   *        2048      133119       65536   83  Linux
/dev/sda2          133120     4327423     2097152   82  Linux swap / Solaris
/dev/sda3         4327424  1953525167   974598872   83  Linux
Command (m for help): w

GPT setup

These instructions are for the GPT partition layout. For MBR (msdos), read MBR (msdos) setup.

First install the boot sector provided by syslinux. Take due care with this command; if count=1 is not given it will overwrite the entire disk rather than just the first 440 bytes:

root # dd bs=440 conv=notrunc count=1 if=/usr/share/syslinux/gptmbr.bin of=/dev/sda

Next, run gdisk and enable legacy BIOS boot partition attributes on the partition where /boot/extlinux is stored.

Boot Loader Install


Use the extlinux command to install the necessary files in /boot/extlinux:

root # mkdir /boot/extlinux
root #
extlinux --install /boot/extlinux
root #
ln -snf . /boot/boot
The "boot -> ." symlink is not necessary per se, but for the sake of consistency, it's made so the example configurations are the same for users with /boot on same partition and those with separate partitions.

The syslinux package contains various modules to enable additional features. Starting with syslinux version 5, some modules depends on others, so it is a good idea to copy most basic modules regardless of the use case.

root # cd /usr/share/syslinux
root #
cp menu.c32 memdisk libcom32.c32 libutil.c32 /boot/extlinux


To install ISOLINUX, start off with a base directory in which all the files that need to reside on the CD or DVD are situated.

In that base directory, create a subdirectory called isolinux and copy the isolinux.bin file from the syslinux package into it.

root # mkdir isolinux
root #
cp /usr/share/syslinux/isolinux.bin isolinux/

Create the isolinux.cfg file according to the instructions mentioned below.

Next, create two more directories kernel and images in the base directory:

root # mkdir kernel images

Copy the memdisk binary into the kernel directory:

root # cp /usr/share/syslinux/memdisk kernel/

When the configuration has been made, the following mkisofs command can be used to create the final ISO image (substitute ${BASEDIR} with the actual base directory):

root # mkisofs -o output.iso -b isolinux/isolinux.bin -c isolinux/ -no-emul-boot -boot-load-size 4 -boot-info-table ${BASEDIR}

The file will be automatically created.


With PXELINUX is possible to netboot using images that are shared through a TFTP server. This article will assume there is a TFTP server installed, and its TFTP root directory is in /var/lib/tftpboot. With this setup, copy the PXELINUX loader to the TFTP boot dir and create a config dir.

root # cp /usr/share/syslinux/pxelinux.0 /var/lib/tftpboot/pxelinux.0
root #
mkdir /var/lib/tftpboot/pxelinux.cfg

The config dir can be used to store different configurations for the netbooted clients. When a client tries to boot, the MAC address or the IP address is used to determine the appropriate client config file. First it tries to look for the MAC address, followed by a try on the hexadecimal representation of the client IP. Next, a character is stripped from the end of this hexadecimal representation until no more characters are left, or until a config file is found. If none of the tries match, the default config file is used.

The hexadecimal representation of an IP can be found with the following command:

user $ gethostip -x

An example config file matching sequence occurs as follows:


For easy maintenance, create config files by hostname and symlink to the IP representation. If you want a default netboot, just delete or rename the symlink.


Use the syslinux command to install the SYSLINUX bootloader on the (FAT) file system:

root # syslinux --install /dev/sda1


The configuration file is named after the bootloader:

  • SYSLINUX: syslinux.cfg
  • EXTLINUX: extlinux.conf
  • ISOLINUX: isolinux.cfg

The configuration format however is the same.

Simple configuration

This will give you a simple "boot:" prompt, similar to the one in Gentoo's Minimal LiveCD:


DEFAULT gentoo
LABEL gentoo
      LINUX /boot/kernel-3.6.11-gentoo

Menu configuration

The following configuration provides a simple text menu example.

This is done via the vesamenu module, in some cases where vesa is not compatible, the simpler menu module will work.

Copy the VESA menu module into the boot filesystem:

root # cp /usr/share/syslinux/vesamenu.c32 /boot/extlinux/

UI vesamenu.c32
LABEL gentoo
      MENU LABEL Gentoo Linux
      LINUX /boot/kernel-3.6.11-gentoo
LABEL gentoo-old
      MENU LABEL Gentoo Linux (previous kernel)
      LINUX /boot/kernel-3.5.7-gentoo
Avoid using 'KERNEL' for selecting the kernel images, use LINUX instead. If you use KERNEL and the image ends with .0 then extlinux will misinterpret it and try to PXE it ending with a screen full of graphical artifacts and nothing else.

Passing Kernel Parameters

Unless the kernel parameters are hard-coded in the kernel image, these need to be passed on to the kernel through the boot loader. To do so, use the APPEND parameter, like this:

File/boot/extlinux/extlinux.confAdding kernel parameters

DEFAULT gentoo
LABEL gentoo
      LINUX /boot/kernel-3.6.11-gentoo
      APPEND root=/dev/sda1