Difference between revisions of "Syslinux"

From ArchWiki
Jump to: navigation, search
(Using memtest: the pacakge is memtest86+)
m (Keyboard layout: Fix path)
 
(218 intermediate revisions by 71 users not shown)
Line 3: Line 3:
 
[[fr:Syslinux]]
 
[[fr:Syslinux]]
 
[[it:Syslinux]]
 
[[it:Syslinux]]
 +
[[ja:Syslinux]]
 +
[[ru:Syslinux]]
 
[[tr:Syslinux]]
 
[[tr:Syslinux]]
 
[[zh-CN:Syslinux]]
 
[[zh-CN:Syslinux]]
{{Article summary start}}
+
{{Related articles start}}
{{Article summary text|Describes installing and configuring Syslinux, a collection of bootloaders.}}
+
{{Related|Arch boot process}}
{{Article summary heading|Overview}}
+
{{Related|Boot loaders}}
{{Article summary text|{{Boot process overview}}}}
+
{{Related articles end}}
{{Article summary end}}
+
  
{{Merge|Network_Installation_Guide#Pxelinux|No mention of PXE capability in this article}}
+
[[Wikipedia:SYSLINUX|Syslinux]] is a collection of boot loaders capable of booting from hard drives, CDs, and over the network via PXE. It supports the [[Wikipedia:File Allocation Table|FAT]], [[Wikipedia:ext2|ext2]], [[ext3]], [[ext4]], and [[Btrfs]] [[file systems]].
  
[[Wikipedia:SYSLINUX|Syslinux]] is a collection of boot loaders capable of booting from hard drives, CDs, and over the network via PXE. It supports the [[Wikipedia:File Allocation Table|FAT]], [[Wikipedia:ext2|ext2]], [[Ext3|ext3]], [[Ext4|ext4]], and [[Btrfs]] file systems.
+
{{Note|Syslinux cannot access files from partitions other than its own. For an alternative bootloader with the multifs feature see [[GRUB]].}}
  
{{Note|Since Syslinux 4, Extlinux and Syslinux are the same thing.}}
+
== BIOS Systems ==
{{Note|Syslinux UEFI support is present in version 6.00-preXX and is currently of alpha quality. See [[UEFI_Bootloaders#SYSLINUX]] for more info.}}
+
  
== Syslinux Boot Process ==
+
=== Boot process overview ===
# '''Load MBR'''. At boot, the computer loads the [[MBR]] ({{ic|/usr/lib/syslinux/mbr.bin}}).
+
# '''Search active partition'''. The MBR looks for the partition that is marked as active (boot flag).
+
# '''Execute volume boot record'''. Once found, the volume boot record (VBR) will be executed. In the case of ext2/3/4 and FAT12/16/32, the starting sector of {{ic|ldlinux.sys}} is hard-coded into the VBR.
+
# '''Execute ldlinux.sys'''. The VBR will execute ({{ic|ldlinux.sys}}). Therefore, if the location of {{ic|ldlinux.sys}} changes, Syslinux will no longer boot. (In the case of Btrfs, the above method will not work since files move around resulting in the sector location of {{ic|ldlinux.sys}} changing. Therefore, the entire Syslinux code needs to be stored outside the filesystem. The code is stored in the sectors following the VBR.)
+
# '''Search configuration file'''. Once Syslinux is fully loaded, it looks for a configuration file, either {{ic|extlinux.conf}} or {{ic|syslinux.cfg}}.
+
# '''Load configuration'''. If one is found, the configuration file is loaded. If no configuration file is found, you will be given a Syslinux prompt.
+
  
== Installation ==
+
# '''Stage 1 : Part 1''' - '''Load MBR''' - At boot, the BIOS loads the 440 byte [[MBR]] boot code at the start of the disk ({{ic|/usr/lib/syslinux/bios/mbr.bin}} or {{ic|/usr/lib/syslinux/bios/gptmbr.bin}}).
 +
# '''Stage 1 : Part 2''' - '''Search active partition'''. The '''Stage 1 MBR boot code''' looks for the partition that is marked as active (boot flag in MBR disks). Let us assume this is the {{ic|/boot}} partition for example.
 +
# '''Stage 2 : Part 1''' - '''Execute volume boot record''' - The '''Stage 1 MBR boot code''' executes the Volume Boot Record (VBR) of the {{ic|/boot}} partition. In the case of Syslinux, the VBR boot code is the starting sector of {{ic|/boot/syslinux/ldlinux.sys}} which is created by the {{ic|extlinux --install}} command. Note {{ic|ldlinux.sys}} is not same as {{ic|ldlinux.c32}}.
 +
# '''Stage 2 : Part 2''' - '''Execute {{ic|/boot/syslinux/ldlinux.sys}}''' - The VBR will load the rest of {{ic|/boot/syslinux/ldlinux.sys}}. The sector location of {{ic|/boot/syslinux/ldlinux.sys}} should not change, otherwise syslinux will not boot. {{Note|In the case of [[Btrfs]], the above method will not work since files move around resulting in changing of the sector location of {{ic|ldlinux.sys}}. Therefore, in BTRFS the entire {{ic|ldlinux.sys}} code is embedded in the space following the VBR and is not installed at {{ic|/boot/syslinux/ldlinux.sys}} unlike the case of other filesystems.}}
 +
# '''Stage 3''' - '''Load {{ic|/boot/syslinux/ldlinux.c32}}''' - The {{ic|/boot/syslinux/ldlinux.sys}} will load the {{ic|/boot/syslinux/ldlinux.c32}} (core module) that contains the rest of the '''core''' part of syslinux that could not be fit into {{ic|ldlinux.sys}} (due to file-size constraints). The {{ic|ldlinux.c32}} file should be present in every Syslinux installation and should match the version of {{ic|ldlinux.sys}} installed in the partition. Otherwise Syslinux will fail to boot. See http://bugzilla.syslinux.org/show_bug.cgi?id=7 for more info.
 +
# '''Stage 4''' - '''Search and Load configuration file''' - Once Syslinux is fully loaded, it looks for {{ic|/boot/syslinux/syslinux.cfg}} (or {{ic|/boot/syslinux/extlinux.conf}} in some cases) and loads it if it is found. If no configuration file is found, you will be dropped to a Syslinux {{ic|boot:}} prompt. This step and the rest of '''non-core''' parts of Syslinux ({{ic|/boot/syslinux/*.c32}} modules, excluding {{ic|lib*.c32}} and {{ic|ldlinux.c32}}) require {{ic|/boot/syslinux/lib*.c32}} (library) modules to be present (http://www.syslinux.org/wiki/index.php/Common_Problems#ELF). The {{ic|lib*.c32}} library modules and non-core {{ic|*.c32}} modules should match the version of {{ic|ldlinux.sys}} installed in the partition.
  
[[Pacman|Install]] {{Pkg|syslinux}} from the [[official repositories]].
+
=== Installation on BIOS ===
  
=== Automatic Install ===
+
[[Install]] the {{Pkg|syslinux}} package.
The {{ic|syslinux-install_update}} script will install Syslinux, copy/symlink {{ic|*.c32}} modules to {{ic|/boot/syslinux}}, set the boot flag and install the boot code in the MBR. It can handle [[Master Boot Record|MBR]] and [[GUID Partition Table|GPT]] disks along with software RAID.
+
 
 +
{{Note|
 +
* {{Pkg|gptfdisk}} is required for [[wikipedia:GUID_Partition_Table|GPT]] support using the automated script.
 +
* If your boot partition is FAT, you will also need {{Pkg|mtools}}.
 +
}}
 +
 
 +
Installing the package is not the same as installing the bootloader. After installing the relevant package(s), the bootloader code itself needs to be installed (to the adequate area, usually the VBR) so to be able to boot the system; the following sections provide alternative instructions depending on the characteristics of your particular system.
 +
 
 +
==== Automatic Install ====
 +
 
 +
{{Note|The {{ic|syslinux-install_update}} script is Arch specific, and is not provided/supported by Syslinux upstream. Please direct any bug reports specific to the script to the Arch Bug Tracker and not upstream.
 +
}}
 +
 
 +
* After executing the {{ic|syslinux-install_update}} script, do not forget to edit {{ic|/boot/syslinux/syslinux.cfg}} by following [[#Configuration]] and [[#Kernel parameters]].
 +
 
 +
{{Warning|The {{ic|syslinux-install_update}} script sets a default root partition that possibly will not match your particular system. It is important to point Syslinux to the correct root partition by editing {{ic|/boot/syslinux/syslinux.cfg}}, or the OS will fail to boot. See [[#Kernel parameters]].}}
 +
 
 +
The {{ic|syslinux-install_update}} script will install Syslinux, copy {{ic|*.c32}} modules to {{ic|/boot/syslinux}}, set the boot flag and install the boot code in the MBR. It can handle [[MBR]] and [[GPT]] disks along with software RAID:
 
   
 
   
:1. If you use a separate boot partition make sure that it is mounted. Check with {{ic|lsblk}}; if you don't see a {{ic|/boot}} mountpoint, mount it before you go any further.
+
If you use a separate boot partition make sure that it is mounted. Check with {{ic|lsblk}}; if you do not see a {{ic|/boot}} mountpoint, mount it before you go any further.
  
:2. Run {{ic|syslinux-install_update}} with flags: {{ic|-i}} (install the files), {{ic|-a}} (mark the partition ''active'' with the ''boot'' flag), {{ic|-m}} (install the ''MBR'' boot code):
+
* Run {{ic|syslinux-install_update}} with flags: {{ic|-i}} (install the files), {{ic|-a}} (mark the partition ''active'' with the ''boot'' flag), {{ic|-m}} (install the ''MBR'' boot code): {{bc|# syslinux-install_update -i -a -m}} If this command fails with ''Syslinux BIOS install failed'', the problem is likely that the {{ic|extlinux}} binary could not find the partition containing {{ic|/boot}}:
# syslinux-install_update -i -a -m
+
  
:3. Edit {{ic|/boot/syslinux/syslinux.cfg}}.
+
{{hc|# extlinux --install /boot/syslinux/|
 +
extlinux: cannot find device for path /boot/syslinux
 +
extlinux: cannot open device (null)
 +
}}  
  
{{Note|For this to work with [[GUID Partition Table|GPT]], the {{pkg|gptfdisk}} package is needed as the backend for setting the boot flag.}}
+
This can happen for example when upgrading from [[LILO]] which, while booting a current custom kernel, turned a kernel command line parameter of say {{ic|1=root=/dev/sda1}} into its numeric equivalent {{ic|1=root=801}}, as evidenced by {{ic|/proc/cmdline}} and the output of the {{ic|mount}} command. Remedy the situation by either continuing with the manual install described below while specifying {{ic|1=--device=/dev/sda1}} to {{ic|extlinux}}, or simply by first rebooting into a stock Arch Linux kernel; its use of an initramfs avoids the problem.
  
=== Manual Install ===
+
{{Note|
{{Note| If you are unsure of which partition table you are using (MBR or GPT), you are likely using the MBR partition table. Most of the time GPT will create a special MBR-style partition (type {{ic|0xEE}}) using the whole disk which will be displayed with the following command:
+
* When you reboot your system now, you will have a Syslinux prompt. To automatically boot your system or get a boot menu, you still need to create a configuration file.
# fdisk -l /dev/sda
+
* If you are on another root directory (e.g. from an install disk) install SYSLINUX by directing to the chroot:
 +
# syslinux-install_update -i -a -m -c /mnt/
 +
}}
 +
 
 +
* Now is the time to edit {{ic|/boot/syslinux/syslinux.cfg}} by following [[#Configuration]] and [[#Kernel parameters]].
 +
 
 +
==== Manual install ====
  
or alternatively:
+
{{Note|
  # sgdisk -p /dev/sda
+
* If you are unsure of which partition table you are using (MBR or GPT), you can check using the following command
 +
  # blkid -s PTTYPE -o value /dev/sda
 +
gpt
  
will show "GPT: not present" if it is not a GPT disk.
+
* If you are trying to rescue an installed system with a live CD, be sure to [[chroot]] into it before executing these commands. If you do not chroot first, you must prepend all file paths (not {{ic|/dev/}} paths) with the mount point.
 
}}
 
}}
  
{{Note| If you are trying to rescue an installed system with a live CD, be sure to [[Change_Root|chroot]] into it before executing these commands. If you do not chroot first, you must prepend all file paths (not {{ic|/dev/}} paths) with the mount point.}}
+
Your boot partition, on which you plan to install Syslinux, must contain a FAT, ext2, ext3, ext4, or Btrfs file system. You should install it on a mounted directory—not a {{ic|/dev/sdXY}} device. You do not have to install it on the root directory of a file system, e.g., with device {{ic|/dev/sda1}} mounted on {{ic|/boot}}. You can install Syslinux in the {{ic|syslinux}} directory:
  
Your boot partition, on which you plan to install Syslinux, must contain a FAT, ext2, ext3, ext4, or Btrfs file system. You should install it on a mounted directory, not a {{ic|/dev/sdXY}} device. You do not have to install it on the root directory of a file system, e.g., with device {{ic|/dev/sda1}} mounted on {{ic|/boot}} you can install Syslinux in the {{ic|syslinux}} directory:
 
 
  # mkdir /boot/syslinux
 
  # mkdir /boot/syslinux
  # extlinux --install /boot/syslinux  
+
# cp -r /usr/lib/syslinux/bios/*.c32 /boot/syslinux/                          ## copy ALL the *.c32 files from /usr/lib/syslinux/bios/, DO NOT SYMLINK
 +
  # extlinux --install /boot/syslinux/
  
==== MBR Partition Table ====
+
After this, proceed to install the Syslinux boot code ({{ic|mbr.bin}} or {{ic|gptmbr.bin}}) to the Master Boot Record 440-byte boot code region (not to be confused with MBR aka msdos partition table) of the disk, as described in the next sections, respectively.
{{Box||See the main article: [[Master Boot Record]]|#E5E5FF|#FCFCFC}}
+
  
Next you need to mark your boot partition active in your partition table. Applications capable of doing this include {{ic|fdisk}}, {{ic|cfdisk}}, {{ic|sfdisk}}, {{ic|parted/gparted}}. It should look like this:
+
{{Note|For a partitionless install, there is no need to install the Syslinux boot code to the MBR. See [https://unix.stackexchange.com/questions/103501/boot-partiotionless-disk-with-syslinux].}}
 +
 
 +
===== MBR partition table =====
 +
 
 +
See the main article: [[Master Boot Record]].
 +
 
 +
Next you need to mark your boot partition as "active" in your partition table. Applications capable of doing this include {{ic|fdisk}}, {{ic|cfdisk}}, {{ic|sfdisk}}, {{ic|parted/gparted}} ("boot" flag). It should look like this:
 
{{hc|# fdisk -l /dev/sda|
 
{{hc|# fdisk -l /dev/sda|
 
[...]
 
[...]
Line 70: Line 101:
  
 
Install the MBR:
 
Install the MBR:
  # dd bs=440 count=1 conv=notrunc if=/usr/lib/syslinux/mbr.bin of=/dev/sda
+
  # dd bs=440 count=1 if=/usr/lib/syslinux/bios/mbr.bin of=/dev/sda
  
An alternate MBR which Syslinux provides is: {{ic|altmbr.bin}}. This MBR does ''not'' scan for bootable partitions; instead, the last byte of the MBR is set to a value indicating which partition to boot from. Here is an example of how {{ic|altmbr.bin}} can be copied into position:
+
An alternative MBR which Syslinux provides is: {{ic|altmbr.bin}}. This MBR does ''not'' scan for bootable partitions; instead, the last byte of the MBR is set to a value indicating which partition to boot from. Here is an example of how {{ic|altmbr.bin}} can be copied into position:
  # printf '\x5' | cat /usr/lib/syslinux/altmbr.bin - | dd bs=440 count=1 iflag=fullblock conv=notrunc of=/dev/sda
+
  # printf '\x5' | cat /usr/lib/syslinux/bios/altmbr.bin - | dd bs=440 count=1 iflag=fullblock of=/dev/sda
  
In this case, a single byte of value 5 is appended to the contents of {{ic|altmbr.bin}} and the resulting 440 bytes are written to the MBR on device {{ic|sda}}. Syslinux was installed on the first logical partition ({{ic|/dev/sda5}}) of the disk.
+
In this case, a single byte of value 5 (hexadecimal) is appended to the contents of {{ic|altmbr.bin}} and the resulting 440 bytes are written to the MBR on device {{ic|sda}}. Syslinux was installed on the first logical partition ({{ic|/dev/sda5}}) of the disk.
  
==== GUID Partition Table aka GPT ====
+
===== GUID partition table =====
{{Box||See the main article: [[GUID Partition Table]]|#E5E5FF|#FCFCFC}}
+
  
Bit 2 of the attributes for the {{ic|/boot}} partition needs to be set.
+
See the main article: [[GUID Partition Table]].
 +
 
 +
Bit 2 of the attributes ("legacy_boot" attribute) needs to be set for the {{ic|/boot}} partition:.
 
  # sgdisk /dev/sda --attributes=1:set:2
 
  # sgdisk /dev/sda --attributes=1:set:2
  
 
This would toggle the attribute ''legacy BIOS bootable'' on partition 1. To check:
 
This would toggle the attribute ''legacy BIOS bootable'' on partition 1. To check:
# sgdisk /dev/sda --attributes=1:show
+
{{hc|<nowiki># sgdisk /dev/sda --attributes=1:show</nowiki>|
 
  1:2:1 (legacy BIOS bootable)
 
  1:2:1 (legacy BIOS bootable)
 +
}}
  
 
Install the MBR:
 
Install the MBR:
  # dd bs=440 conv=notrunc count=1 if=/usr/lib/syslinux/gptmbr.bin of=/dev/sda
+
  # dd bs=440 conv=notrunc count=1 if=/usr/lib/syslinux/bios/gptmbr.bin of=/dev/sda
  
==== Rebooting ====
+
If this does not work you can also try:
When you reboot your system now, you will have a Syslinux prompt. To automatically boot your system or get a boot menu, you still need to create a configuration file.
+
# syslinux-install_update -i -m
 +
 
 +
== UEFI Systems ==
 +
 
 +
{{Note|
 +
*{{ic|$esp}} is the mountpoint of the [[ESP]] (EFI System Partition) in the below commands.
 +
 
 +
* {{ic|efi64}} denotes x86_64 UEFI systems, for IA32 (32-bit) EFI replace {{ic|efi64}} with {{ic|efi32}} in the below commands.
 +
 
 +
* For Syslinux, the kernel and initramfs files need to be in the ESP, as Syslinux does not (currently) have the ability to access files outside its own partition (i.e. outside ESP in this case). For this reason, it is recommended to mount ESP at {{ic|/boot}}.
 +
 
 +
* The automatic install script {{ic|/usr/bin/syslinux-install_update}} does not support UEFI install.
 +
 
 +
* The configuration syntax of {{ic|syslinux.cfg}} for UEFI is same as that of BIOS.
 +
}}
 +
 
 +
=== Limitations of UEFI Syslinux ===
 +
 
 +
* UEFI Syslinux application {{ic|syslinux.efi}} cannot be signed by {{ic|sbsign}} (from sbsigntool) for UEFI Secure Boot. Bug report - http://bugzilla.syslinux.org/show_bug.cgi?id=8
 +
 
 +
* Using TAB to edit kernel parameters in UEFI Syslinux menu might lead to garbaged display (text on top of one-another). Bug report - http://bugzilla.syslinux.org/show_bug.cgi?id=9
 +
 
 +
* UEFI Syslinux does not support chainloading other EFI applications like {{ic|UEFI Shell}} or {{ic|Windows Boot Manager}}. Enhancement request - http://bugzilla.syslinux.org/show_bug.cgi?id=17
 +
 
 +
* In some cases, UEFI Syslinux might not boot in some Virtual Machines like QEMU/OVMF or VirtualBox or some VMware products/versions and in some UEFI emulation environments like DUET. A Syslinux contributor has confirmed no such issues present on VMware Workstation 10.0.2 and Syslinux-6.02 or later. Bug reports - http://bugzilla.syslinux.org/show_bug.cgi?id=21 and http://bugzilla.syslinux.org/show_bug.cgi?id=23
 +
 
 +
* Memdisk is not available for UEFI. Enhancement request - http://bugzilla.syslinux.org/show_bug.cgi?id=30
 +
 
 +
=== Installation on UEFI ===
 +
 
 +
* Install the {{Pkg|syslinux}} and {{Pkg|efibootmgr}} packages from the [[official repositories]].  Then setup Syslinux in the EFI System Partition (ESP) as follows:
 +
 
 +
* Copy Syslinux files to ESP (replace {{ic|$esp}} by the mount point of the ESP, usually {{ic|/boot}}):
 +
 
 +
# mkdir -p $esp/EFI/syslinux
 +
# cp -r /usr/lib/syslinux/efi64/* $esp/EFI/syslinux/
 +
 
 +
* Setup boot entry for Syslinux using [[Unified Extensible Firmware Interface#efibootmgr|efibootmgr]]:
 +
 
 +
# efibootmgr -c -d /dev/sdX -p Y -l /EFI/syslinux/syslinux.efi -L "Syslinux"
 +
 
 +
where {{ic|/dev/sdXY}} is the partition containing the bootloader.
 +
 
 +
* Create or edit {{ic|$esp/EFI/syslinux/syslinux.cfg}} by following [[#Configuration]].
 +
 
 +
{{Note|The config file for UEFI is {{ic|$esp/EFI/syslinux/syslinux.cfg}}, not {{ic|/boot/syslinux/syslinux.cfg}}. Files in {{ic|/boot/syslinux/}} are BIOS specific and not related to UEFI Syslinux.}}
  
 
== Configuration ==
 
== Configuration ==
The Syslinux configuration file, {{ic|syslinux.cfg}}, should be created in the same directory where you installed Syslinux. In our case, {{ic|/boot/syslinux/}}.
+
 
 +
The Syslinux configuration file, {{ic|syslinux.cfg}}, should be created in the same directory where you installed Syslinux. In our case, {{ic|/boot/syslinux/}} for BIOS systems and {{ic|$esp/EFI/syslinux/}} for UEFI systems.
  
 
The bootloader will look for either {{ic|syslinux.cfg}} (preferred) or {{ic|extlinux.conf}}
 
The bootloader will look for either {{ic|syslinux.cfg}} (preferred) or {{ic|extlinux.conf}}
Line 100: Line 179:
 
{{Tip|
 
{{Tip|
 
* Instead of {{ic|LINUX}}, the keyword {{ic|KERNEL}} can also be used. {{ic|KERNEL}} tries to detect the type of the file, while {{ic|LINUX}} always expects a Linux kernel.  
 
* Instead of {{ic|LINUX}}, the keyword {{ic|KERNEL}} can also be used. {{ic|KERNEL}} tries to detect the type of the file, while {{ic|LINUX}} always expects a Linux kernel.  
* {{ic|TIMEOUT}} value is in units of '''1/10''' of a second.
+
* {{ic|TIMEOUT}} value is in units of '''0.1 seconds'''.
 
}}
 
}}
  
 
=== Examples ===
 
=== Examples ===
==== Basic Config ====
 
This is a simple configuration file that will show a {{ic|boot:}} prompt and automatically boot after 5 seconds.
 
  
{{Note|The partition in question needs to be whatever you have as {{ic|/}} (root), not {{ic|/boot}}.}}
+
{{Note|
 +
* Any configuration file found in the examples needs to be edited to set the proper kernel parameters. See section [[#Kernel parameters]].
 +
* Please, pay close attention to the paths. The examples may not be suitable for your installation, especially when using UEFI.
 +
}}
 +
 
 +
==== Boot prompt ====
 +
This is a simple configuration file that will show a {{ic|boot:}} prompt and automatically boot after 5 seconds. If you want to boot directly without seeing a prompt, set {{ic|PROMPT}} to {{ic|0}}.
  
 
Configuration:
 
Configuration:
Line 117: Line 200:
 
  LABEL arch
 
  LABEL arch
 
         LINUX ../vmlinuz-linux
 
         LINUX ../vmlinuz-linux
         APPEND root=/dev/sda2 ro
+
         APPEND root=/dev/sda2 rw
 
         INITRD ../initramfs-linux.img
 
         INITRD ../initramfs-linux.img
 
   
 
   
 
  LABEL archfallback
 
  LABEL archfallback
 
         LINUX ../vmlinuz-linux
 
         LINUX ../vmlinuz-linux
         APPEND root=/dev/sda2 ro
+
         APPEND root=/dev/sda2 rw
 
         INITRD ../initramfs-linux-fallback.img</nowiki>
 
         INITRD ../initramfs-linux-fallback.img</nowiki>
 
}}
 
}}
  
If you want to boot directly without seeing a prompt, set {{ic|PROMPT}} to {{ic|0}}.
+
==== Text boot menu ====
 
+
If you want to use [[UUID]] for persistent device naming instead of device names, change the {{ic|APPEND}} line to your equivalent {{ic|UUID}} of the root partition:
+
APPEND root='''UUID='''978e3e81-8048-4ae1-8a06-aa727458e8ff ro
+
 
+
If you use encryption [[LUKS]] change the {{ic|APPEND}} line to use your encrypted volume:
+
APPEND root=/dev/mapper/<group>-<name> cryptdevice=/dev/sda2:<name> ro
+
 
+
If you are using software [[Wikipedia:RAID|RAID]] using [http://neil.brown.name/blog/mdadm mdadm], change the {{ic|APPEND}} line to accommodate your RAID arrays. As an example the following accommodates three RAID 1 array's and sets the appropriate one as root:
+
APPEND root=/dev/md1 ro md=0,/dev/sda2,/dev/sdb2 md=1,/dev/sda3,/dev/sdb3 md=2,/dev/sda4,/dev/sdb4
+
  
==== Text Boot menu ====
+
Syslinux also allows you to use a boot menu. To use it, copy the {{ic|menu}} module to your Syslinux directory:
Syslinux also allows you to use a boot menu. To use it, copy the {{ic|menu}} COM32 module to your Syslinux directory:
+
  # cp /usr/lib/syslinux/bios/menu.c32 /boot/syslinux/
  # cp /usr/lib/syslinux/menu.c32 /boot/syslinux/
+
  
If {{ic|/boot}} is in the same partition as {{ic|/usr}}, a symlink will also work:
+
Copying additional {{ic|lib*.c32}} library modules might be needed too.
# ln -s /usr/lib/syslinux/menu.c32 /boot/syslinux/
+
  
 
Configuration:
 
Configuration:
Line 156: Line 228:
 
         MENU LABEL Arch Linux
 
         MENU LABEL Arch Linux
 
         LINUX ../vmlinuz-linux
 
         LINUX ../vmlinuz-linux
         APPEND root=/dev/sda2 ro
+
         APPEND root=/dev/sda2 rw
 
         INITRD ../initramfs-linux.img
 
         INITRD ../initramfs-linux.img
 
   
 
   
Line 162: Line 234:
 
         MENU LABEL Arch Linux Fallback
 
         MENU LABEL Arch Linux Fallback
 
         LINUX ../vmlinuz-linux
 
         LINUX ../vmlinuz-linux
         APPEND root=/dev/sda2 ro
+
         APPEND root=/dev/sda2 rw
 
         INITRD ../initramfs-linux-fallback.img</nowiki>
 
         INITRD ../initramfs-linux-fallback.img</nowiki>
 
}}
 
}}
  
For more details about the menu system, see [http://git.kernel.org/?p=boot/syslinux/syslinux.git;a=blob;f=doc/menu.txt the Syslinux documentation].
+
For more details about the menu system, see [http://www.syslinux.org/wiki/index.php/Menu the Syslinux wiki].
 +
 
 +
==== Graphical boot menu ====
  
==== Graphical Boot menu ====
 
 
Syslinux also allows you to use a graphical boot menu. To use it, copy the {{ic|vesamenu}} COM32 module to your Syslinux folder:
 
Syslinux also allows you to use a graphical boot menu. To use it, copy the {{ic|vesamenu}} COM32 module to your Syslinux folder:
  # cp /usr/lib/syslinux/vesamenu.c32 /boot/syslinux/
+
  # cp /usr/lib/syslinux/bios/vesamenu.c32 /boot/syslinux/
 +
 
 +
Copying additional {{ic|lib*.c32}} library modules might be needed too.
  
If {{ic|/boot}} is the same partition as {{ic|/}}, a symlink will also work:
+
{{Note| If you are using [[UEFI]] make sure to copy from {{ic|/usr/lib/syslinux/efi64/}} ({{ic|efi32}} for i686 systems), otherwise you will be presented with a black screen. In that case, boot from a live medium and use [[chroot]] to make the appropriate changes.}}
# ln -s /usr/lib/syslinux/vesamenu.c32 /boot/syslinux/
+
  
[https://projects.archlinux.org/archiso.git/tree/configs/releng/syslinux This config] uses the same menu design as the Arch Install CD. The background file can be found there too.
+
This configuration uses the same menu design as the Arch Install CD, its config can be found at [https://projects.archlinux.org/archiso.git/tree/configs/releng/syslinux projects.archlinux.org]. The [https://projects.archlinux.org/archiso.git/plain/configs/releng/syslinux/splash.png Arch Linux background image] can be downloaded from there, too. Copy the image to {{ic|/boot/syslinux/splash.png}}.
  
 
Configuration:
 
Configuration:
Line 212: Line 286:
 
         MENU LABEL Arch Linux
 
         MENU LABEL Arch Linux
 
         LINUX ../vmlinuz-linux
 
         LINUX ../vmlinuz-linux
         APPEND root=/dev/sda2 ro
+
         APPEND root=/dev/sda2 rw
 
         INITRD ../initramfs-linux.img
 
         INITRD ../initramfs-linux.img
 
   
 
   
Line 219: Line 293:
 
         MENU LABEL Arch Linux Fallback
 
         MENU LABEL Arch Linux Fallback
 
         LINUX ../vmlinuz-linux
 
         LINUX ../vmlinuz-linux
         APPEND root=/dev/sda2 ro
+
         APPEND root=/dev/sda2 rw
 
         INITRD ../initramfs-linux-fallback.img</nowiki>
 
         INITRD ../initramfs-linux-fallback.img</nowiki>
 
}}
 
}}
Line 225: Line 299:
 
Since Syslinux 3.84, {{ic|vesamenu.c32}} supports the {{ic|MENU RESOLUTION $WIDTH $HEIGHT}} directive.
 
Since Syslinux 3.84, {{ic|vesamenu.c32}} supports the {{ic|MENU RESOLUTION $WIDTH $HEIGHT}} directive.
 
To use it, insert {{ic|MENU RESOLUTION 1440 900}} into your config for a 1440x900 resolution.
 
To use it, insert {{ic|MENU RESOLUTION 1440 900}} into your config for a 1440x900 resolution.
The background picture has to have exactly the right resolution, however, as Syslinux will otherwise refuse to load the menu.
+
However, the background picture has to have exactly the right resolution, as Syslinux will otherwise refuse to load the menu.
  
=== Auto Boot ===
+
To center the menu and adjust resolution, use {{ic|MENU RESOLUTION}}, {{ic|MENU HSHIFT $N}} and {{ic|MENU VSHIFT $N}} where {{ic|$N}} is a positive number. The default values are both {{ic|0}} which is the upper-left hand corner of your monitor. Conversely, a negative number starts from the opposite end of the screen (e.g. {{ic|VHSHIFT -4}} would be 4 rows from the bottom of the screen).
If you don't want to see the Syslinux menu at all, comment out all {{ic|UI}} commands and make sure there is a {{ic|DEFAULT}} set in your {{ic|syslinux.cfg}}.
+
 
 +
To move the menu to the center, add or edit these values:
 +
 
 +
{{hc|/boot/syslinux/syslinux.cfg|<nowiki>
 +
MENU RESOLUTION 800 600 # or whatever your screen resolution is
 +
MENU WIDTH 78          # width of the menu also required to bring the menu box to size
 +
MENU VSHIFT 10          # moves menu down
 +
MENU HSHIFT 10          # moves menu right
 +
</nowiki>
 +
}}
 +
 
 +
VESA standards are commonly a maximum of 25 rows and 80 columns, so going higher than those values might move the menu off the screen, potentially requiring editing from a rescue CD.
 +
 
 +
=== Kernel parameters ===
 +
 
 +
The [[kernel parameters]] are set using the {{ic|APPEND}} line in {{ic|syslinux.cfg}}. It is recommended to make the following changes for the fallback entry as well.
 +
 
 +
'''In the simplest case''', the partition name in the {{ic|root}} parameter needs to be replaced. Change {{ic|/dev/sda2}} to point to the correct root partition.
 +
 
 +
APPEND root=/dev/sda2
 +
 
 +
'''If you want to use [[UUID]]''' for [[persistent block device naming]] change the {{ic|APPEND}} line as follows, substituting {{ic|1234}} with the {{ic|UUID}} of your root partition:
 +
 
 +
APPEND root=UUID=''1234'' rw
 +
 
 +
'''If you use encryption''' [[LUKS]] change the {{ic|APPEND}} line to use your encrypted volume:
 +
 
 +
APPEND root=/dev/mapper/''group''-''name'' cryptdevice=/dev/sda2:''name'' rw
 +
 
 +
'''If you are using software''' [[Wikipedia:RAID|RAID]] using [http://neil.brown.name/blog/mdadm mdadm], change the {{ic|APPEND}} line to accommodate your RAID arrays. As an example the following accommodates three RAID 1 arrays and sets the appropriate one as root:
 +
 
 +
APPEND root=/dev/md1 rw md=0,/dev/sda2,/dev/sdb2 md=1,/dev/sda3,/dev/sdb3 md=2,/dev/sda4,/dev/sdb4
 +
 
 +
If booting from a software raid partition fails using the kernel device node method above an alternative, a more reliable, way is to use partition labels:
 +
 
 +
APPEND root=LABEL=THEROOTPARTITIONLABEL rw
 +
 
 +
'''If booting a [[btrfs]] subvolume''', amend the {{ic|APPEND}} line with {{ic|rootflags<nowiki>=</nowiki>subvol<nowiki>=</nowiki><root subvolume>}}. For example, where {{ic|/dev/sda2}} has been mounted as a btrfs subvolume called 'ROOT' (e.g. {{ic|mount -o noatime,subvol<nowiki>=</nowiki>ROOT /dev/sda2 /mnt}}), then the {{ic|APPEND}} line would need to be modified as follows:
 +
APPEND root=/dev/sda2 rw rootflags=subvol=ROOT
 +
 
 +
A failure to do so will otherwise result in the following error message: {{ic|ERROR: Root device mounted successfully, but /sbin/init does not exist.}}
 +
 
 +
=== Auto boot ===
 +
 
 +
If you do not want to see the Syslinux menu at all, use the [[#Boot prompt]], and set {{ic|PROMPT}} to {{ic|0}} and comment out any {{ic|UI}} menu entries. Setting the {{ic|TIMEOUT}} variable to {{ic|0}} might also be a good idea. Make sure there is a {{ic|DEFAULT}} set in your {{ic|syslinux.cfg}}.
 +
 
 +
=== Security ===
 +
 
 +
Syslinux has two levels of bootloader security: a menu master password, and a per-menu-item password. In {{ic|syslinux.cfg}}, use
 +
{{bc|
 +
MENU MASTER PASSWD passwd
 +
}}
 +
to set a master bootloader password, and
 +
{{bc|
 +
MENU PASSWD passwd
 +
}}
 +
within a {{ic|LABEL}} block to password-protect individual boot items.
 +
 
 +
The passwd can be either a cleartext password or hashed: [http://www.syslinux.org/wiki/index.php/Comboot/menu.c32 see official documentation].
  
 
=== Chainloading ===
 
=== Chainloading ===
If you want to chainload other operating systems (such as Windows) or boot loaders, copy (or symlink) the {{ic|chain.c32}} module to the Syslinux directory (for details, see the instructions in the previous section). Then create a section in the configuration file:
+
 
 +
{{Note|Syslinux BIOS cannot directly chainload files from other partitions; however, {{ic|chain.c32}} can boot a partition boot sector (VBR).}}
 +
 +
If you want to chainload other operating systems (such as Windows) or boot loaders, copy the {{ic|chain.c32}} module to the Syslinux directory (additional {{ic|lib*.c32}} library modules might be needed too; for details, see the instructions in the previous section). Then create a section in the configuration file:
 
{{hc|/boot/syslinux/syslinux.cfg|
 
{{hc|/boot/syslinux/syslinux.cfg|
 
...
 
...
Line 242: Line 377:
  
 
{{ic|hd0 3}} is the third partition on the first BIOS drive - drives are counted from zero, but partitions are counted from one.  
 
{{ic|hd0 3}} is the third partition on the first BIOS drive - drives are counted from zero, but partitions are counted from one.  
 +
 +
{{note|For Windows, this skips the system's own boot manager ({{ic|bootmgr}}), which is required for a few important updates ([http://support.microsoft.com/kb/2883200 eg.]) to complete. In such cases it may be advisable to temporarily set the MBR boot flag to the Windows partition (eg. with [[GParted]]), let the update finish installing, and then reset the flag to the Syslinux partition (eg. with Windows's own [http://www.online-tech-tips.com/computer-tips/set-active-partition-vista-xp DiskPart]).}}
  
 
If you are unsure about which drive your BIOS thinks is "first", you can instead use the MBR identifier, or if you are using GPT, the filesystem labels. To use the MBR identifier, run the command
 
If you are unsure about which drive your BIOS thinks is "first", you can instead use the MBR identifier, or if you are using GPT, the filesystem labels. To use the MBR identifier, run the command
Line 278: Line 415:
 
...</nowiki>
 
...</nowiki>
 
}}
 
}}
 
+
Alternatively, it is also possible to load [[GRUB]] as a linux kernel by prepending {{ic|lnxboot.img}} to {{ic|core.img}}. The file {{ic|lnxboot.img}} is part of {{ic|core/grub}} and can be found in {{ic|/usr/lib/grub/i386-pc}}.
 +
{{hc|/boot/syslinux/syslinux.cfg|<nowiki>
 +
...
 +
LABEL grub2lnx
 +
        MENU LABEL Grub2 (lnxboot)
 +
        LINUX ../grub/i386-pc/lnxboot.img
 +
        INITRD ../grub/i386-pc/core.img
 +
...</nowiki>
 +
}}
 
This may be required for booting from ISO images.
 
This may be required for booting from ISO images.
  
 
=== Chainloading other Linux systems ===
 
=== Chainloading other Linux systems ===
Chainloading another bootloader such as Windows' is pretty obvious, as there is a definite bootloader to chain to.  But with Syslinux, it is only able to load files residing on the same partition as the configuration file.  Thus, if you have another version of Linux on a separate partition, without a shared {{ic|/boot}}, it becomes necessary to employ Extlinux. Essentially, Extlinux can be installed on the partition superblock and be called as a separate bootloader from the MBR installed by Syslinux. Extlinux is part of the Syslinux project and is included with the {{Pkg|syslinux}} package.
+
{{Accuracy|Among other inaccuracies... 1_ There is no obligation to install yet another boot loader if you already have one related to the other partition/OS (e.g. GRUB2 installed in the MBR or in the VBR of the partition being chainloaded to). 2_ Syslinux (in any of its derivatives) is never "installed to the MBR", so mentioning the MBR in this section without any explanation of what it is being meant or how to do it in practical terms is just adding confusion. 3_ Typos and misspelling. 4_No need to explain (yet again) how to install some (other) bootloader to some (other) partition / OS; just how to chainload from Syslinux to that other partition / bootloader / OS.}}
 +
Chainloading another bootloader such as Windows' is pretty obvious, as there is a definite bootloader to chain to.  But with Syslinux, it is only able to load files residing on the same partition as the configuration file.  Thus, if you have another version of Linux on a separate partition, without a shared {{ic|/boot}}, it becomes ''necessary'' to employ EXTLINUX rather than the other OS's default bootloader (eg. GRUB2). Essentially, EXTLINUX can be installed on the partition superblock/[[wikipedia:Volume_boot_record|VBR]] and be called as a ''separate bootloader'' right from the MBR installed by Syslinux. EXTLINUX is part of The Syslinux Project and is included with the {{Pkg|syslinux}} package.
  
The following instructions assume you have Syslinux installed already. These instructions will also assume that the typical Arch Linux configuration path of {{ic|/boot/syslinux}} is being used and the chainloaded {{ic|/}} is on {{ic|/dev/sda3}}.   
+
The following instructions assume you have Syslinux installed already. These instructions will also assume that the typical Arch Linux configuration path of {{ic|/boot/syslinux}} is being used and the chainloaded system's {{ic|/}} is on {{ic|/dev/sda3}}.   
  
From a booted Linux (likely the partition that Syslinux is set up to boot), mount the other root partition to your desired mount point. In this example this will be {{ic|/mnt}}. Also, if a separate {{ic|/boot}} partition is used on the second operating system, that will also need to be mounted.  The example assumes this is {{ic|/dev/sda2}}.
+
From a booted Linux (likely the partition that Syslinux is set up to boot), mount the other system's root partition to your desired mount point. In this example this will be {{ic|/mnt}}. Also, if a separate {{ic|/boot}} partition is used on the second operating system, that will also need to be mounted.  The example assumes this is {{ic|/dev/sda2}}.
 
  # mount /dev/sda3 /mnt
 
  # mount /dev/sda3 /mnt
 
  # mount /dev/sda2 /mnt/boot (only necessary for separate /boot)
 
  # mount /dev/sda2 /mnt/boot (only necessary for separate /boot)
Install Extlinux and copy necessary {{ic|*.c32}} files
+
Install EXTLINUX to the partition VBR, and copy necessary {{ic|*.c32}} files
  # extlinux -i /mnt/boot/syslinux
+
  # extlinux -i /mnt/boot/syslinux/ (first create the directory if necessary)
  # cp /usr/lib/syslinux/{chain,menu}.c32 /mnt/boot/syslinux
+
  # cp /usr/lib/syslinux/bios/*.c32 /mnt/boot/syslinux
  
Create {{ic|/mnt/boot/syslinux/syslinux.cfg}}. Below is an example:
+
Create {{ic|/mnt/boot/syslinux/syslinux.cfg}}. You can use the other Linux's bootloader menu file for reference. Below is an example:
 
{{hc|/boot/syslinux/syslinux.cfg '''on /dev/sda3'''|<nowiki>
 
{{hc|/boot/syslinux/syslinux.cfg '''on /dev/sda3'''|<nowiki>
 
timeout 10
 
timeout 10
  
 
ui menu.c32
 
ui menu.c32
 
  
 
label Other Linux
 
label Other Linux
 
     linux /boot/vmlinuz-linux
 
     linux /boot/vmlinuz-linux
 
     initrd /boot/initramfs-linux.img
 
     initrd /boot/initramfs-linux.img
     append root=/dev/sda3 ro quiet
+
     append root=/dev/sda3 rw quiet
 
+
  
 
label MAIN
 
label MAIN
Line 312: Line 456:
  
 
taken from [[User:Djgera|Djgera's user wiki page]].
 
taken from [[User:Djgera|Djgera's user wiki page]].
 +
 +
Note that the other Linux entry in {{ic|<other-OS>/boot/syslinux/syslinux.cfg}} will need to be edited each time you update this OS's kernel. Since we are booting the kernel directly and not chainloading the other-OS's default bootloader.
  
 
=== Using memtest ===
 
=== Using memtest ===
 +
 
Install {{Pkg|memtest86+}} from the [[official repositories]].
 
Install {{Pkg|memtest86+}} from the [[official repositories]].
  
Line 324: Line 471:
 
...
 
...
 
}}
 
}}
 +
''
 +
{{Note|If you are using PXELINUX, change the name from ''memtest.bin'' to ''memtest'' since PXELINUX treats the file with .bin extension as a boot sector and loads only 2KB of it.}}
  
 
=== HDT ===
 
=== HDT ===
[http://hdt-project.org/ HDT (Hardware Detection Tool)] displays hardware information. Like before, the {{ic|.c32}} file has to be copied or symlinked from {{ic|/boot/syslinux/}}.
+
 
For PCI info, either copy or symlink {{ic|/usr/share/hwdata/pci.ids}} to {{ic|/boot/syslinux/pci.ids}} and add the following to your configuration file:
+
[http://hdt-project.org/ HDT (Hardware Detection Tool)] displays hardware information. Like before, the {{ic|.c32}} file has to be copied from {{ic|/boot/syslinux/}}. Additional {{ic|lib*.c32}} library modules might be needed too.
 +
For PCI info, copy {{ic|/usr/share/hwdata/pci.ids}} to {{ic|/boot/syslinux/pci.ids}} and add the following to your configuration file:
 
{{hc|/boot/syslinux/syslinux.cfg|
 
{{hc|/boot/syslinux/syslinux.cfg|
 
  LABEL hdt
 
  LABEL hdt
Line 335: Line 485:
  
 
=== Reboot and power off ===
 
=== Reboot and power off ===
 +
 +
{{Note|As of Syslinux 6.03, {{ic|poweroff.c32}} only works with APM and not with ACPI. For a possible solution, see [http://www.syslinux.org/archives/2012-March/017661.html this thread] .}}
 +
 
Use the following sections to reboot or power off your machine:
 
Use the following sections to reboot or power off your machine:
 
{{hc|/boot/syslinux/syslinux.cfg|
 
{{hc|/boot/syslinux/syslinux.cfg|
Line 343: Line 496:
 
  LABEL poweroff
 
  LABEL poweroff
 
         MENU LABEL Power Off
 
         MENU LABEL Power Off
         COMBOOT poweroff.com
+
         COM32 poweroff.c32
 
}}
 
}}
  
=== Clear Menu ===
+
=== Clear menu ===
 +
 
 
To clear the screen when exiting the menu, add the following line:
 
To clear the screen when exiting the menu, add the following line:
 
{{hc|/boot/syslinux/syslinux.cfg|
 
{{hc|/boot/syslinux/syslinux.cfg|
Line 352: Line 506:
 
}}
 
}}
  
=== Keyboard remapping ===
+
=== Keyboard layout ===
If you often have to edit your boot parameters, you might want to remap your keyboard layout. This allows you to enter "=", "/" and other characters easily on a non-US keyboard.
+
  
First you have to create a compatible keymap (for example a German one):
+
If you often have to edit your boot command with diverse parameters in the Syslinux boot prompt, then you might want to remap your keyboard layout. This allows you to enter "=", "/" and other characters easily on a non-US keyboard.
# cp /usr/share/kbd/keymaps/i386/qwerty/us.map.gz ./
+
# cp /usr/share/kbd/keymaps/i386/qwertz/de.map.gz ./
+
# gunzip {de,us}.map.gz
+
# mv de.{,k}map
+
# mv us.{,k}map
+
# keytab-lilo de > de.ktl
+
  
Copy {{ic|de.ktl}} as root to {{ic|/boot/syslinux/}} and set ownership to root:
+
{{note|keytab-lilo is a perl script invoking the "loadkeys" program.}}
  # chown root:root /boot/syslinux/de.ktl
+
 
 +
To create a compatible keymap (e.g. a german one) run:
 +
  # keytab-lilo /usr/share/kbd/keymaps/i386/qwerty/us.kmap.gz /usr/share/kbd/keymaps/i386/qwertz/de.kmap.gz > /boot/syslinux/de.ktl
 +
 
 +
Now edit {{ic|syslinux.cfg}} and add:
  
Now edit {{ic|syslinux.conf}} and add:
 
 
{{hc|/boot/syslinux/syslinux.cfg|
 
{{hc|/boot/syslinux/syslinux.cfg|
KBDMAP de.ktl
+
KBDMAP de.ktl
 
}}
 
}}
 +
 +
See the [http://www.syslinux.org/wiki/index.php/Directives/kbdmap Syslinux wiki] for more details.
  
 
=== Hiding the menu ===
 
=== Hiding the menu ===
 +
 
Use the option:
 
Use the option:
 
{{hc|/boot/syslinux/syslinux.cfg|
 
{{hc|/boot/syslinux/syslinux.cfg|
Line 377: Line 530:
 
}}
 
}}
 
to hide the menu while displaying only the timeout. Press any key to bring up the menu.
 
to hide the menu while displaying only the timeout. Press any key to bring up the menu.
 +
 +
=== Pxelinux ===
 +
 +
{{Note|For UEFI, Syslinux uses the same binary for disk booting and network booting.  Loading files from TFTP or other network protocols will require network booting Syslinux.  }}
 +
 +
[[Syslinux|PXELINUX]] is provided by the {{Pkg|syslinux}} package.
 +
 +
For BIOS clients, copy the {{ic|<nowiki>{l,}pxelinux.0</nowiki>}} bootloader to the boot directory of the client. For version 5.00 and newer, also copy {{ic|ldlinux.c32}} from the same package:
 +
 +
# cp /usr/lib/syslinux/bios/pxelinux.0 "$root/boot"
 +
# cp /usr/lib/syslinux/bios/ldlinux.c32 "$root/boot"
 +
# mkdir "$root/boot/pxelinux.cfg"
 +
 +
We also created the {{ic|pxelinux.cfg}} directory, which is where PXELINUX searches for configuration files by default. Because we do not want to discriminate between different host MACs, we then create the {{ic|default}} configuration.
 +
 +
{{hc|# vim "$root/boot/pxelinux.cfg/default"|<nowiki>
 +
default linux
 +
 +
label linux
 +
kernel vmlinuz-linux
 +
append initrd=initramfs-linux.img quiet ip=:::::eth0:dhcp nfsroot=10.0.0.1:/arch
 +
</nowiki>}}
 +
 +
Or if you are using NBD, use the following append line:
 +
 +
{{bc|<nowiki>append ro initrd=initramfs-linux.img ip=:::::eth0:dhcp nbd_host=10.0.0.1 nbd_name=arch root=/dev/nbd0</nowiki>}}
 +
 +
{{Note|You will need to change {{ic|nbd_host}} and/or {{ic|nfsroot}}, respectively, to match your network configuration (the address of the NFS/NBD server)}}
 +
 +
PXELINUX uses the same configuration syntax as SYSLINUX; refer to the upstream documentation for more information.
 +
 +
The kernel and initramfs will be transferred via TFTP, so the paths to those are going to be relative to the TFTP root. Otherwise, the root filesystem is going to be the NFS mount itself, so those are relative to the root of the NFS server.
 +
 +
To actually load PXELINUX, replace {{ic|filename "/grub/i386-pc/core.0";}} in {{ic|/etc/dhcpd.conf}} with {{ic|filename "/pxelinux.0"}} (or with {{ic|filename "/lpxelinux.0"}}).
 +
 +
=== Booting ISO9660 image files with memdisk ===
 +
 +
Syslinux supports booting from ISO images directly using the [http://www.syslinux.org/wiki/index.php/MEMDISK memdisk] module, see [[Multiboot USB drive#Using Syslinux and memdisk]] for examples.
 +
 +
=== Serial console ===
 +
 +
{{Merge|Working with the serial console|General page about topic not specific to Syslinux, already provides examples for GRUB.}}
 +
 +
To enable Serial Console add the {{ic|SERIAL port [baudrate]}} to the top of {{ic|syslinux.cfg}} file. "port" is a number (0 for {{ic|/dev/ttyS0}}), if "baudrate" is omitted, the baud rate default is 9600 bps. The serial parameters are hardcoded to 8 bits, no parity and 1 stop bit.[http://www.syslinux.org/wiki/index.php/SYSLINUX#SERIAL_port_.5Bbaudrate_.5Bflowcontrol.5D.5D]
 +
 +
{{hc|syslinux.cfg|
 +
SERIAL 0 115200
 +
}}
 +
 +
Enable Serial Console in the kernel at boot by adding {{ic|1=console=tty0 console=ttyS0,115200n8}} to the {{ic|APPEND}} option.[http://www.mjmwired.net/kernel/Documentation/kernel-parameters.txt#681]
 +
 +
{{hc|syslinux.cfg|2=
 +
APPEND root=UUID=126ca36d-c853-4f3a-9f46-cdd49d034ce4 rw console=tty0 console=ttyS0,115200n8
 +
}}
 +
 +
How to do this with GRUB: [[Working with the serial console#GRUB2 and systemd]]
  
 
== Troubleshooting ==
 
== Troubleshooting ==
 +
 
=== Using the Syslinux prompt===
 
=== Using the Syslinux prompt===
 +
 
You can type in the {{ic|LABEL}} name of the entry that you want to boot (as per your {{ic|syslinux.cfg}}). If you used the example configurations, just type:
 
You can type in the {{ic|LABEL}} name of the entry that you want to boot (as per your {{ic|syslinux.cfg}}). If you used the example configurations, just type:
 
  boot: arch
 
  boot: arch
  
 
If you get an error that the configuration file could not be loaded, you can pass your needed boot parameters, e.g.:
 
If you get an error that the configuration file could not be loaded, you can pass your needed boot parameters, e.g.:
  boot: ../vmlinuz-linux root=/dev/sda2 ro initrd=../initramfs-linux.img
+
  boot: ../vmlinuz-linux root=/dev/sda2 rw initrd=../initramfs-linux.img
  
If you do not have access to {{ic|boot:}} in [[Ramdisk|ramfs]], and therefore temporarily unable to boot kernel again,
+
If you do not have access to {{ic|boot:}} in [[Ramdisk|ramfs]], and therefore temporarily unable to boot the kernel again,
 
:1. Create a temporary directory, in order to mount your root partition (if it does not exist already):
 
:1. Create a temporary directory, in order to mount your root partition (if it does not exist already):
 
   # mkdir -p /new_root
 
   # mkdir -p /new_root
 
:2. Mount {{ic|/}} under {{ic|/new_root}} (in case {{ic|/boot/}} is on the same partition, otherwise you will need to mount them both):
 
:2. Mount {{ic|/}} under {{ic|/new_root}} (in case {{ic|/boot/}} is on the same partition, otherwise you will need to mount them both):
{{Note|If {{ic|/boot}} is on its own ext2 partition then busybox cannot mount it.}}
+
{{Note|Busybox cannot mount {{ic|/boot}} if it is on its own ext2 partition.}}
 
   # mount /dev/sd[a-z][1-9] /new_root
 
   # mount /dev/sd[a-z][1-9] /new_root
  
 
:3. Use {{ic|vim}} and edit {{ic|syslinux.cfg}} again to suit your needs and save file.
 
:3. Use {{ic|vim}} and edit {{ic|syslinux.cfg}} again to suit your needs and save file.
 
:4. Reboot.
 
:4. Reboot.
 +
 +
=== Fsck fails on root partition ===
 +
 +
In the case of a badly corrupted root partition (in which the journal is damaged), in the ramfs emergency shell, mount the root file system:
 +
 +
# mount /dev/''root partition'' /new_root
 +
And grab the tune2fs binary from the root partition (it is not included in Syslinux):
 +
# cp /new_root/sbin/tune2fs /sbin/
 +
 +
Follow the instructions at [[Fsck#ext2fs_:_no_external_journal|ext2fs: no external journal]] to create a new journal for the root partition.
  
 
=== No Default or UI found on some computers ===
 
=== No Default or UI found on some computers ===
 +
 
Certain motherboard manufacturers have less compatibility for booting from USB devices than others. While an ext4 formatted USB drive may boot on a more recent computer, some computers may hang if the boot partition containing the ''kernel'' and ''initrd'' are not on a FAT16 partition. To prevent an older machine from loading {{ic|ldlinux}} and failing to read {{ic|syslinux.cfg}}, use {{ic|cfdisk}} to create a FAT16 partition (<=2GB) and format using {{Pkg|dosfstools}}:
 
Certain motherboard manufacturers have less compatibility for booting from USB devices than others. While an ext4 formatted USB drive may boot on a more recent computer, some computers may hang if the boot partition containing the ''kernel'' and ''initrd'' are not on a FAT16 partition. To prevent an older machine from loading {{ic|ldlinux}} and failing to read {{ic|syslinux.cfg}}, use {{ic|cfdisk}} to create a FAT16 partition (<=2GB) and format using {{Pkg|dosfstools}}:
 
  # mkfs.msdos -F 16 /dev/sda1
 
  # mkfs.msdos -F 16 /dev/sda1
Line 402: Line 624:
 
then install and configure Syslinux.
 
then install and configure Syslinux.
  
=== Missing Operating System ===
+
=== Missing operating system ===
If you get this message, check if the partition that contains {{ic|/boot}} has the boot flag enabled. If the flag is enabled, then perhaps this partition starts at sector 1 rather than sector 63 or 2048.  Check this with {{ic|fdisk -l}}.  If it starts at sector 1, you can move the partition(s) with {{ic|gparted}} from a rescue disk. Or, if you have a separate boot partition, you can back up {{ic|/boot}} with  
+
 
 +
* Check that you have installed {{ic|gptmbr.bin}} for GPT and {{ic|mbr.bin}} for msdos partition table. A "Missing operating system" message comes from {{ic|mbr.bin}} while {{ic|gptmbr.bin}} would show a "Missing OS" message.
 +
 
 +
* Check whether the partition that contains {{ic|/boot}} has the "boot" flag enabled.
 +
 
 +
* Check whether the first partition at the boot device starts at sector 1 rather than sector 63 or 2048.  Check this with {{ic|fdisk -l}}.  If it starts at sector 1, you can move the partition(s) with {{ic|gparted}} from a rescue disk. Or, if you have a separate boot partition, you can back up {{ic|/boot}} with  
 
  # cp -a /boot /boot.bak
 
  # cp -a /boot /boot.bak
 
and then boot up with the Arch install disk. Next, use {{ic|cfdisk}} to delete the {{ic|/boot}} partition, and recreate it.  This time it should begin at the proper sector, '''63'''. Now mount your partitions and {{ic|chroot}} into your mounted system, as described in the beginners guide. Restore {{ic|/boot}} with the command
 
and then boot up with the Arch install disk. Next, use {{ic|cfdisk}} to delete the {{ic|/boot}} partition, and recreate it.  This time it should begin at the proper sector, '''63'''. Now mount your partitions and {{ic|chroot}} into your mounted system, as described in the beginners guide. Restore {{ic|/boot}} with the command
Line 410: Line 637:
 
  # syslinux-install_update -iam
 
  # syslinux-install_update -iam
 
and reboot.
 
and reboot.
 +
 +
You will also get this error if you are trying to boot from a md [[RAID]] 1 array and created the array with a too new version of the metadata that Syslinux does not understand. As of August 2013 by default mdadm will create an array with version 1.2 metadata, but Syslinux does not understand metadata newer than 1.0. If this is the case you will need to recreate your [[RAID]] array using the {{ic|1=--metadata=1.0}} flag to mdadm.
  
 
=== Windows boots up, ignoring Syslinux ===
 
=== Windows boots up, ignoring Syslinux ===
 +
 
'''Solution:''' Make sure the partition that contains {{ic|/boot}} has the boot flag enabled. Also, make sure the boot flag is not enabled on the Windows partition. See the installation section above.
 
'''Solution:''' Make sure the partition that contains {{ic|/boot}} has the boot flag enabled. Also, make sure the boot flag is not enabled on the Windows partition. See the installation section above.
  
Line 417: Line 647:
  
 
=== Menu entries do nothing ===
 
=== Menu entries do nothing ===
You select a menu entry and it does nothing, it just ''"refreshes"'' the menu. This usually means that you have an error in your {{ic|syslinux.cfg}} file. Hit {{Keypress|Tab}} to edit your boot parameters. Alternatively, press {{Keypress|Esc}} and type in the {{ic|LABEL}} of your boot entry (e.g. ''arch'').
+
 
 +
You select a menu entry and it does nothing, it just ''"refreshes"'' the menu. This usually means that you have an error in your {{ic|syslinux.cfg}} file. Hit {{ic|Tab}} to edit your boot parameters. Alternatively, press {{ic|Esc}} and type in the {{ic|LABEL}} of your boot entry (e.g. ''arch''). Another cause could be that you do not have a kernel installed. Find a way to access your file system (through live CD, etc) and make sure that {{ic|/mount/vmlinuz-linux}} exists and does not have a size of 0. If this is the case, [[Kernel_Panics#Option_2:_Reinstall_kernel|reinstall your kernel]].
  
 
=== Cannot remove ldlinux.sys ===
 
=== Cannot remove ldlinux.sys ===
Line 426: Line 657:
  
 
=== White block in upper left corner when using vesamenu ===
 
=== White block in upper left corner when using vesamenu ===
 +
 
Problem:
 
Problem:
 
''As of linux-3.0, the modesetting driver tries to keep the current contents of the screen after changing the resolution (at least it does so with my Intel, when having Syslinux in text mode). It seems that this goes wrong when combined with the vesamenu module in Syslinux (the white block is actually an attempt to keep the Syslinux menu, but the driver fails to capture the picture from vesa graphics mode).''
 
''As of linux-3.0, the modesetting driver tries to keep the current contents of the screen after changing the resolution (at least it does so with my Intel, when having Syslinux in text mode). It seems that this goes wrong when combined with the vesamenu module in Syslinux (the white block is actually an attempt to keep the Syslinux menu, but the driver fails to capture the picture from vesa graphics mode).''
  
 
If you have a custom resolution and a {{ic|vesamenu}} with early modesetting, try to append the following in {{ic|syslinux.cfg}} to remove the white block and continue in graphics mode:
 
If you have a custom resolution and a {{ic|vesamenu}} with early modesetting, try to append the following in {{ic|syslinux.cfg}} to remove the white block and continue in graphics mode:
  APPEND root=/dev/sda6 ro 5 '''vga=current''' quiet splash
+
  APPEND root=/dev/sda6 rw 5 '''vga=current''' quiet splash
 +
 
 +
=== Chainloading Windows does not work, when it is installed on another drive ===
 +
 
 +
If Windows is installed on a different drive than Arch and you have trouble chainloading it, try the following configuration:
 +
 
 +
LABEL Windows
 +
        MENU LABEL Windows
 +
        COM32 chain.c32
 +
        APPEND mbr:0xdfc1ba9e swap
 +
 
 +
Replace the mbr code with the one your Windows drive has (details [[#Chainloading|above]]), and append {{ic|swap}} to the options.
 +
 
 +
=== Read bootloader log ===
 +
 
 +
In some cases (e.g. bootloader unable to boot kernel) it is highly desirable to get more information from the boot process. ''Syslinux'' prints error messages to screen but the boot menu quickly overwrites the text. To avoid losing the log information, disable {{ic|UI menu}} in {{ic|syslinux.cfg}} and use the default "command-line" prompt. It means:
 +
 
 +
* avoid the UI directive
 +
* avoid ONTIMEOUT
 +
* avoid ONERROR
 +
* avoid MENU CLEAR
 +
* use a higher TIMEOUT
 +
* use PROMPT 1
 +
* use DEFAULT <problematic_label>
 +
 
 +
To get more detailed debug log, recompile the {{Pkg|syslinux}} package with additional CFLAGS:
 +
 
 +
-DDEBUG_STDIO=1 -DCORE_DEBUG=1
 +
 
 +
=== Btrfs compression ===
 +
 
 +
Booting from btrfs with compression is not supported.[http://www.syslinux.org/wiki/index.php/Syslinux_4_Changelog#Changes_in_4.02]
 +
This error will show:
 +
btrfs: found compressed data, cannot continue!
 +
invalid or corrupt kernel image.
 +
[[GRUB]] supports btrfs with compression.
  
 
== See also ==
 
== See also ==
* [http://www.syslinux.org Official Website]
+
 
 +
* [http://www.syslinux.org Official website]
 
* [http://www.josephn.net/scrapbook/pxelinux_stuff PXELinux configuration]
 
* [http://www.josephn.net/scrapbook/pxelinux_stuff PXELinux configuration]
 +
* [http://blog.jak.me/2013/01/03/creating-a-multiboot-usb-stick-using-syslinux/ Multiboot USB using Syslinux]{{Dead link|2015|05|15}}

Latest revision as of 01:03, 23 April 2016

Syslinux is a collection of boot loaders capable of booting from hard drives, CDs, and over the network via PXE. It supports the FAT, ext2, ext3, ext4, and Btrfs file systems.

Note: Syslinux cannot access files from partitions other than its own. For an alternative bootloader with the multifs feature see GRUB.

BIOS Systems

Boot process overview

  1. Stage 1 : Part 1 - Load MBR - At boot, the BIOS loads the 440 byte MBR boot code at the start of the disk (/usr/lib/syslinux/bios/mbr.bin or /usr/lib/syslinux/bios/gptmbr.bin).
  2. Stage 1 : Part 2 - Search active partition. The Stage 1 MBR boot code looks for the partition that is marked as active (boot flag in MBR disks). Let us assume this is the /boot partition for example.
  3. Stage 2 : Part 1 - Execute volume boot record - The Stage 1 MBR boot code executes the Volume Boot Record (VBR) of the /boot partition. In the case of Syslinux, the VBR boot code is the starting sector of /boot/syslinux/ldlinux.sys which is created by the extlinux --install command. Note ldlinux.sys is not same as ldlinux.c32.
  4. Stage 2 : Part 2 - Execute /boot/syslinux/ldlinux.sys - The VBR will load the rest of /boot/syslinux/ldlinux.sys. The sector location of /boot/syslinux/ldlinux.sys should not change, otherwise syslinux will not boot.
    Note: In the case of Btrfs, the above method will not work since files move around resulting in changing of the sector location of ldlinux.sys. Therefore, in BTRFS the entire ldlinux.sys code is embedded in the space following the VBR and is not installed at /boot/syslinux/ldlinux.sys unlike the case of other filesystems.
  5. Stage 3 - Load /boot/syslinux/ldlinux.c32 - The /boot/syslinux/ldlinux.sys will load the /boot/syslinux/ldlinux.c32 (core module) that contains the rest of the core part of syslinux that could not be fit into ldlinux.sys (due to file-size constraints). The ldlinux.c32 file should be present in every Syslinux installation and should match the version of ldlinux.sys installed in the partition. Otherwise Syslinux will fail to boot. See http://bugzilla.syslinux.org/show_bug.cgi?id=7 for more info.
  6. Stage 4 - Search and Load configuration file - Once Syslinux is fully loaded, it looks for /boot/syslinux/syslinux.cfg (or /boot/syslinux/extlinux.conf in some cases) and loads it if it is found. If no configuration file is found, you will be dropped to a Syslinux boot: prompt. This step and the rest of non-core parts of Syslinux (/boot/syslinux/*.c32 modules, excluding lib*.c32 and ldlinux.c32) require /boot/syslinux/lib*.c32 (library) modules to be present (http://www.syslinux.org/wiki/index.php/Common_Problems#ELF). The lib*.c32 library modules and non-core *.c32 modules should match the version of ldlinux.sys installed in the partition.

Installation on BIOS

Install the syslinux package.

Note:
  • gptfdisk is required for GPT support using the automated script.
  • If your boot partition is FAT, you will also need mtools.

Installing the package is not the same as installing the bootloader. After installing the relevant package(s), the bootloader code itself needs to be installed (to the adequate area, usually the VBR) so to be able to boot the system; the following sections provide alternative instructions depending on the characteristics of your particular system.

Automatic Install

Note: The syslinux-install_update script is Arch specific, and is not provided/supported by Syslinux upstream. Please direct any bug reports specific to the script to the Arch Bug Tracker and not upstream.
Warning: The syslinux-install_update script sets a default root partition that possibly will not match your particular system. It is important to point Syslinux to the correct root partition by editing /boot/syslinux/syslinux.cfg, or the OS will fail to boot. See #Kernel parameters.

The syslinux-install_update script will install Syslinux, copy *.c32 modules to /boot/syslinux, set the boot flag and install the boot code in the MBR. It can handle MBR and GPT disks along with software RAID:

If you use a separate boot partition make sure that it is mounted. Check with lsblk; if you do not see a /boot mountpoint, mount it before you go any further.

  • Run syslinux-install_update with flags: -i (install the files), -a (mark the partition active with the boot flag), -m (install the MBR boot code):
    # syslinux-install_update -i -a -m
    If this command fails with Syslinux BIOS install failed, the problem is likely that the extlinux binary could not find the partition containing /boot:
# extlinux --install /boot/syslinux/
extlinux: cannot find device for path /boot/syslinux
extlinux: cannot open device (null)

This can happen for example when upgrading from LILO which, while booting a current custom kernel, turned a kernel command line parameter of say root=/dev/sda1 into its numeric equivalent root=801, as evidenced by /proc/cmdline and the output of the mount command. Remedy the situation by either continuing with the manual install described below while specifying --device=/dev/sda1 to extlinux, or simply by first rebooting into a stock Arch Linux kernel; its use of an initramfs avoids the problem.

Note:
  • When you reboot your system now, you will have a Syslinux prompt. To automatically boot your system or get a boot menu, you still need to create a configuration file.
  • If you are on another root directory (e.g. from an install disk) install SYSLINUX by directing to the chroot:
# syslinux-install_update -i -a -m -c /mnt/

Manual install

Note:
  • If you are unsure of which partition table you are using (MBR or GPT), you can check using the following command
# blkid -s PTTYPE -o value /dev/sda
gpt
  • If you are trying to rescue an installed system with a live CD, be sure to chroot into it before executing these commands. If you do not chroot first, you must prepend all file paths (not /dev/ paths) with the mount point.

Your boot partition, on which you plan to install Syslinux, must contain a FAT, ext2, ext3, ext4, or Btrfs file system. You should install it on a mounted directory—not a /dev/sdXY device. You do not have to install it on the root directory of a file system, e.g., with device /dev/sda1 mounted on /boot. You can install Syslinux in the syslinux directory:

# mkdir /boot/syslinux
# cp -r /usr/lib/syslinux/bios/*.c32 /boot/syslinux/                           ## copy ALL the *.c32 files from /usr/lib/syslinux/bios/, DO NOT SYMLINK
# extlinux --install /boot/syslinux/

After this, proceed to install the Syslinux boot code (mbr.bin or gptmbr.bin) to the Master Boot Record 440-byte boot code region (not to be confused with MBR aka msdos partition table) of the disk, as described in the next sections, respectively.

Note: For a partitionless install, there is no need to install the Syslinux boot code to the MBR. See [1].
MBR partition table

See the main article: Master Boot Record.

Next you need to mark your boot partition as "active" in your partition table. Applications capable of doing this include fdisk, cfdisk, sfdisk, parted/gparted ("boot" flag). It should look like this:

# fdisk -l /dev/sda
[...]
  Device Boot      Start         End      Blocks   Id  System
/dev/sda1   *        2048      104447       51200   83  Linux
/dev/sda2          104448   625142447   312519000   83  Linux

Install the MBR:

# dd bs=440 count=1 if=/usr/lib/syslinux/bios/mbr.bin of=/dev/sda

An alternative MBR which Syslinux provides is: altmbr.bin. This MBR does not scan for bootable partitions; instead, the last byte of the MBR is set to a value indicating which partition to boot from. Here is an example of how altmbr.bin can be copied into position:

# printf '\x5' | cat /usr/lib/syslinux/bios/altmbr.bin - | dd bs=440 count=1 iflag=fullblock of=/dev/sda

In this case, a single byte of value 5 (hexadecimal) is appended to the contents of altmbr.bin and the resulting 440 bytes are written to the MBR on device sda. Syslinux was installed on the first logical partition (/dev/sda5) of the disk.

GUID partition table

See the main article: GUID Partition Table.

Bit 2 of the attributes ("legacy_boot" attribute) needs to be set for the /boot partition:.

# sgdisk /dev/sda --attributes=1:set:2

This would toggle the attribute legacy BIOS bootable on partition 1. To check:

# sgdisk /dev/sda --attributes=1:show
 1:2:1 (legacy BIOS bootable)

Install the MBR:

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

If this does not work you can also try:

# syslinux-install_update -i -m

UEFI Systems

Note:
  • $esp is the mountpoint of the ESP (EFI System Partition) in the below commands.
  • efi64 denotes x86_64 UEFI systems, for IA32 (32-bit) EFI replace efi64 with efi32 in the below commands.
  • For Syslinux, the kernel and initramfs files need to be in the ESP, as Syslinux does not (currently) have the ability to access files outside its own partition (i.e. outside ESP in this case). For this reason, it is recommended to mount ESP at /boot.
  • The automatic install script /usr/bin/syslinux-install_update does not support UEFI install.
  • The configuration syntax of syslinux.cfg for UEFI is same as that of BIOS.

Limitations of UEFI Syslinux

Installation on UEFI

  • Copy Syslinux files to ESP (replace $esp by the mount point of the ESP, usually /boot):
# mkdir -p $esp/EFI/syslinux
# cp -r /usr/lib/syslinux/efi64/* $esp/EFI/syslinux/
# efibootmgr -c -d /dev/sdX -p Y -l /EFI/syslinux/syslinux.efi -L "Syslinux"

where /dev/sdXY is the partition containing the bootloader.

  • Create or edit $esp/EFI/syslinux/syslinux.cfg by following #Configuration.
Note: The config file for UEFI is $esp/EFI/syslinux/syslinux.cfg, not /boot/syslinux/syslinux.cfg. Files in /boot/syslinux/ are BIOS specific and not related to UEFI Syslinux.

Configuration

The Syslinux configuration file, syslinux.cfg, should be created in the same directory where you installed Syslinux. In our case, /boot/syslinux/ for BIOS systems and $esp/EFI/syslinux/ for UEFI systems.

The bootloader will look for either syslinux.cfg (preferred) or extlinux.conf

Tip:
  • Instead of LINUX, the keyword KERNEL can also be used. KERNEL tries to detect the type of the file, while LINUX always expects a Linux kernel.
  • TIMEOUT value is in units of 0.1 seconds.

Examples

Note:
  • Any configuration file found in the examples needs to be edited to set the proper kernel parameters. See section #Kernel parameters.
  • Please, pay close attention to the paths. The examples may not be suitable for your installation, especially when using UEFI.

Boot prompt

This is a simple configuration file that will show a boot: prompt and automatically boot after 5 seconds. If you want to boot directly without seeing a prompt, set PROMPT to 0.

Configuration:

/boot/syslinux/syslinux.cfg
 PROMPT 1
 TIMEOUT 50
 DEFAULT arch
 
 LABEL arch
         LINUX ../vmlinuz-linux
         APPEND root=/dev/sda2 rw
         INITRD ../initramfs-linux.img
 
 LABEL archfallback
         LINUX ../vmlinuz-linux
         APPEND root=/dev/sda2 rw
         INITRD ../initramfs-linux-fallback.img

Text boot menu

Syslinux also allows you to use a boot menu. To use it, copy the menu module to your Syslinux directory:

# cp /usr/lib/syslinux/bios/menu.c32 /boot/syslinux/

Copying additional lib*.c32 library modules might be needed too.

Configuration:

/boot/syslinux/syslinux.cfg
 UI menu.c32
 PROMPT 0
 
 MENU TITLE Boot Menu
 TIMEOUT 50
 DEFAULT arch
 
 LABEL arch
         MENU LABEL Arch Linux
         LINUX ../vmlinuz-linux
         APPEND root=/dev/sda2 rw
         INITRD ../initramfs-linux.img
 
 LABEL archfallback
         MENU LABEL Arch Linux Fallback
         LINUX ../vmlinuz-linux
         APPEND root=/dev/sda2 rw
         INITRD ../initramfs-linux-fallback.img

For more details about the menu system, see the Syslinux wiki.

Graphical boot menu

Syslinux also allows you to use a graphical boot menu. To use it, copy the vesamenu COM32 module to your Syslinux folder:

# cp /usr/lib/syslinux/bios/vesamenu.c32 /boot/syslinux/

Copying additional lib*.c32 library modules might be needed too.

Note: If you are using UEFI make sure to copy from /usr/lib/syslinux/efi64/ (efi32 for i686 systems), otherwise you will be presented with a black screen. In that case, boot from a live medium and use chroot to make the appropriate changes.

This configuration uses the same menu design as the Arch Install CD, its config can be found at projects.archlinux.org. The Arch Linux background image can be downloaded from there, too. Copy the image to /boot/syslinux/splash.png.

Configuration:

/boot/syslinux/syslinux.cfg
 UI vesamenu.c32
 DEFAULT arch
 PROMPT 0
 MENU TITLE Boot Menu
 MENU BACKGROUND splash.png
 TIMEOUT 50
 
 MENU WIDTH 78
 MENU MARGIN 4
 MENU ROWS 5
 MENU VSHIFT 10
 MENU TIMEOUTROW 13
 MENU TABMSGROW 11
 MENU CMDLINEROW 11
 MENU HELPMSGROW 16
 MENU HELPMSGENDROW 29
 
 # Refer to http://www.syslinux.org/wiki/index.php/Comboot/menu.c32
 
 MENU COLOR border       30;44   #40ffffff #a0000000 std
 MENU COLOR title        1;36;44 #9033ccff #a0000000 std
 MENU COLOR sel          7;37;40 #e0ffffff #20ffffff all
 MENU COLOR unsel        37;44   #50ffffff #a0000000 std
 MENU COLOR help         37;40   #c0ffffff #a0000000 std
 MENU COLOR timeout_msg  37;40   #80ffffff #00000000 std
 MENU COLOR timeout      1;37;40 #c0ffffff #00000000 std
 MENU COLOR msg07        37;40   #90ffffff #a0000000 std
 MENU COLOR tabmsg       31;40   #30ffffff #00000000 std
 
 
 LABEL arch
         MENU LABEL Arch Linux
         LINUX ../vmlinuz-linux
         APPEND root=/dev/sda2 rw
         INITRD ../initramfs-linux.img
 
 
 LABEL archfallback
         MENU LABEL Arch Linux Fallback
         LINUX ../vmlinuz-linux
         APPEND root=/dev/sda2 rw
         INITRD ../initramfs-linux-fallback.img

Since Syslinux 3.84, vesamenu.c32 supports the MENU RESOLUTION $WIDTH $HEIGHT directive. To use it, insert MENU RESOLUTION 1440 900 into your config for a 1440x900 resolution. However, the background picture has to have exactly the right resolution, as Syslinux will otherwise refuse to load the menu.

To center the menu and adjust resolution, use MENU RESOLUTION, MENU HSHIFT $N and MENU VSHIFT $N where $N is a positive number. The default values are both 0 which is the upper-left hand corner of your monitor. Conversely, a negative number starts from the opposite end of the screen (e.g. VHSHIFT -4 would be 4 rows from the bottom of the screen).

To move the menu to the center, add or edit these values:

/boot/syslinux/syslinux.cfg
MENU RESOLUTION 800 600 # or whatever your screen resolution is
MENU WIDTH 78           # width of the menu also required to bring the menu box to size
MENU VSHIFT 10          # moves menu down
MENU HSHIFT 10          # moves menu right

VESA standards are commonly a maximum of 25 rows and 80 columns, so going higher than those values might move the menu off the screen, potentially requiring editing from a rescue CD.

Kernel parameters

The kernel parameters are set using the APPEND line in syslinux.cfg. It is recommended to make the following changes for the fallback entry as well.

In the simplest case, the partition name in the root parameter needs to be replaced. Change /dev/sda2 to point to the correct root partition.

APPEND root=/dev/sda2

If you want to use UUID for persistent block device naming change the APPEND line as follows, substituting 1234 with the UUID of your root partition:

APPEND root=UUID=1234 rw

If you use encryption LUKS change the APPEND line to use your encrypted volume:

APPEND root=/dev/mapper/group-name cryptdevice=/dev/sda2:name rw

If you are using software RAID using mdadm, change the APPEND line to accommodate your RAID arrays. As an example the following accommodates three RAID 1 arrays and sets the appropriate one as root:

APPEND root=/dev/md1 rw md=0,/dev/sda2,/dev/sdb2 md=1,/dev/sda3,/dev/sdb3 md=2,/dev/sda4,/dev/sdb4

If booting from a software raid partition fails using the kernel device node method above an alternative, a more reliable, way is to use partition labels:

APPEND root=LABEL=THEROOTPARTITIONLABEL rw

If booting a btrfs subvolume, amend the APPEND line with rootflags=subvol=<root subvolume>. For example, where /dev/sda2 has been mounted as a btrfs subvolume called 'ROOT' (e.g. mount -o noatime,subvol=ROOT /dev/sda2 /mnt), then the APPEND line would need to be modified as follows:

APPEND root=/dev/sda2 rw rootflags=subvol=ROOT

A failure to do so will otherwise result in the following error message: ERROR: Root device mounted successfully, but /sbin/init does not exist.

Auto boot

If you do not want to see the Syslinux menu at all, use the #Boot prompt, and set PROMPT to 0 and comment out any UI menu entries. Setting the TIMEOUT variable to 0 might also be a good idea. Make sure there is a DEFAULT set in your syslinux.cfg.

Security

Syslinux has two levels of bootloader security: a menu master password, and a per-menu-item password. In syslinux.cfg, use

MENU MASTER PASSWD passwd 

to set a master bootloader password, and

MENU PASSWD passwd 

within a LABEL block to password-protect individual boot items.

The passwd can be either a cleartext password or hashed: see official documentation.

Chainloading

Note: Syslinux BIOS cannot directly chainload files from other partitions; however, chain.c32 can boot a partition boot sector (VBR).

If you want to chainload other operating systems (such as Windows) or boot loaders, copy the chain.c32 module to the Syslinux directory (additional lib*.c32 library modules might be needed too; for details, see the instructions in the previous section). Then create a section in the configuration file:

/boot/syslinux/syslinux.cfg
...
 LABEL windows
         MENU LABEL Windows
         COM32 chain.c32
         APPEND hd0 3
...

hd0 3 is the third partition on the first BIOS drive - drives are counted from zero, but partitions are counted from one.

Note: For Windows, this skips the system's own boot manager (bootmgr), which is required for a few important updates (eg.) to complete. In such cases it may be advisable to temporarily set the MBR boot flag to the Windows partition (eg. with GParted), let the update finish installing, and then reset the flag to the Syslinux partition (eg. with Windows's own DiskPart).

If you are unsure about which drive your BIOS thinks is "first", you can instead use the MBR identifier, or if you are using GPT, the filesystem labels. To use the MBR identifier, run the command

# fdisk -l /dev/sdb
 Disk /dev/sdb: 128.0 GB, 128035676160 bytes 
 255 heads, 63 sectors/track, 15566 cylinders, total 250069680 sectors
 Units = sectors of 1 * 512 = 512 bytes
 Sector size (logical/physical): 512 bytes / 512 bytes
 I/O size (minimum/optimal): 512 bytes / 512 bytes
 Disk identifier: 0xf00f1fd3
  
 Device Boot      Start         End      Blocks   Id  System
 /dev/sdb1            2048     4196351     2097152    7  HPFS/NTFS/exFAT
 /dev/sdb2         4196352   250066943   122935296    7  HPFS/NTFS/exFAT

replacing /dev/sdb with the drive you wish to chainload. Using the hexadecimal number under Disk identifier: 0xf00f1fd3 in this case, the syntax in syslinux.cfg is

/boot/syslinux/syslinux.cfg
...
 LABEL windows
         MENU LABEL Windows
         COM32 chain.c32
         APPEND mbr:0xf00f1fd3
...

For more details about chainloading, see the Syslinux wiki.

If you have GRUB installed on the same partition, you can chainload it by using:

/boot/syslinux/syslinux.cfg
...
 LABEL grub2
        MENU LABEL Grub2
        COM32 chain.c32
        append file=../grub/boot.img
...

Alternatively, it is also possible to load GRUB as a linux kernel by prepending lnxboot.img to core.img. The file lnxboot.img is part of core/grub and can be found in /usr/lib/grub/i386-pc.

/boot/syslinux/syslinux.cfg
...
 LABEL grub2lnx
        MENU LABEL Grub2 (lnxboot)
        LINUX ../grub/i386-pc/lnxboot.img
        INITRD ../grub/i386-pc/core.img
...

This may be required for booting from ISO images.

Chainloading other Linux systems

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: Among other inaccuracies... 1_ There is no obligation to install yet another boot loader if you already have one related to the other partition/OS (e.g. GRUB2 installed in the MBR or in the VBR of the partition being chainloaded to). 2_ Syslinux (in any of its derivatives) is never "installed to the MBR", so mentioning the MBR in this section without any explanation of what it is being meant or how to do it in practical terms is just adding confusion. 3_ Typos and misspelling. 4_No need to explain (yet again) how to install some (other) bootloader to some (other) partition / OS; just how to chainload from Syslinux to that other partition / bootloader / OS. (Discuss in Talk:Syslinux#)

Chainloading another bootloader such as Windows' is pretty obvious, as there is a definite bootloader to chain to. But with Syslinux, it is only able to load files residing on the same partition as the configuration file. Thus, if you have another version of Linux on a separate partition, without a shared /boot, it becomes necessary to employ EXTLINUX rather than the other OS's default bootloader (eg. GRUB2). Essentially, EXTLINUX can be installed on the partition superblock/VBR and be called as a separate bootloader right from the MBR installed by Syslinux. EXTLINUX is part of The Syslinux Project and is included with the syslinux package.

The following instructions assume you have Syslinux installed already. These instructions will also assume that the typical Arch Linux configuration path of /boot/syslinux is being used and the chainloaded system's / is on /dev/sda3.

From a booted Linux (likely the partition that Syslinux is set up to boot), mount the other system's root partition to your desired mount point. In this example this will be /mnt. Also, if a separate /boot partition is used on the second operating system, that will also need to be mounted. The example assumes this is /dev/sda2.

# mount /dev/sda3 /mnt
# mount /dev/sda2 /mnt/boot (only necessary for separate /boot)

Install EXTLINUX to the partition VBR, and copy necessary *.c32 files

# extlinux -i /mnt/boot/syslinux/ (first create the directory if necessary)
# cp /usr/lib/syslinux/bios/*.c32 /mnt/boot/syslinux

Create /mnt/boot/syslinux/syslinux.cfg. You can use the other Linux's bootloader menu file for reference. Below is an example:

/boot/syslinux/syslinux.cfg on /dev/sda3
timeout 10

ui menu.c32

label Other Linux
    linux /boot/vmlinuz-linux
    initrd /boot/initramfs-linux.img
    append root=/dev/sda3 rw quiet

label MAIN
    com32 chain.c32
    append hd0 0

taken from Djgera's user wiki page.

Note that the other Linux entry in <other-OS>/boot/syslinux/syslinux.cfg will need to be edited each time you update this OS's kernel. Since we are booting the kernel directly and not chainloading the other-OS's default bootloader.

Using memtest

Install memtest86+ from the official repositories.

Use this LABEL section to launch memtest:

/boot/syslinux/syslinux.cfg
...
 LABEL memtest
         MENU LABEL Memtest86+
         LINUX ../memtest86+/memtest.bin
...

Note: If you are using PXELINUX, change the name from memtest.bin to memtest since PXELINUX treats the file with .bin extension as a boot sector and loads only 2KB of it.

HDT

HDT (Hardware Detection Tool) displays hardware information. Like before, the .c32 file has to be copied from /boot/syslinux/. Additional lib*.c32 library modules might be needed too. For PCI info, copy /usr/share/hwdata/pci.ids to /boot/syslinux/pci.ids and add the following to your configuration file:

/boot/syslinux/syslinux.cfg
 LABEL hdt
         MENU LABEL Hardware Info
         COM32 hdt.c32

Reboot and power off

Note: As of Syslinux 6.03, poweroff.c32 only works with APM and not with ACPI. For a possible solution, see this thread .

Use the following sections to reboot or power off your machine:

/boot/syslinux/syslinux.cfg
 LABEL reboot
         MENU LABEL Reboot
         COM32 reboot.c32
 
 LABEL poweroff
         MENU LABEL Power Off
         COM32 poweroff.c32

Clear menu

To clear the screen when exiting the menu, add the following line:

/boot/syslinux/syslinux.cfg
 MENU CLEAR

Keyboard layout

If you often have to edit your boot command with diverse parameters in the Syslinux boot prompt, then you might want to remap your keyboard layout. This allows you to enter "=", "/" and other characters easily on a non-US keyboard.

Note: keytab-lilo is a perl script invoking the "loadkeys" program.

To create a compatible keymap (e.g. a german one) run:

# keytab-lilo /usr/share/kbd/keymaps/i386/qwerty/us.kmap.gz /usr/share/kbd/keymaps/i386/qwertz/de.kmap.gz > /boot/syslinux/de.ktl

Now edit syslinux.cfg and add:

/boot/syslinux/syslinux.cfg
KBDMAP de.ktl

See the Syslinux wiki for more details.

Hiding the menu

Use the option:

/boot/syslinux/syslinux.cfg
 MENU HIDDEN

to hide the menu while displaying only the timeout. Press any key to bring up the menu.

Pxelinux

Note: For UEFI, Syslinux uses the same binary for disk booting and network booting. Loading files from TFTP or other network protocols will require network booting Syslinux.

PXELINUX is provided by the syslinux package.

For BIOS clients, copy the {l,}pxelinux.0 bootloader to the boot directory of the client. For version 5.00 and newer, also copy ldlinux.c32 from the same package:

# cp /usr/lib/syslinux/bios/pxelinux.0 "$root/boot"
# cp /usr/lib/syslinux/bios/ldlinux.c32 "$root/boot"
# mkdir "$root/boot/pxelinux.cfg"

We also created the pxelinux.cfg directory, which is where PXELINUX searches for configuration files by default. Because we do not want to discriminate between different host MACs, we then create the default configuration.

# vim "$root/boot/pxelinux.cfg/default"
default linux

label linux
kernel vmlinuz-linux
append initrd=initramfs-linux.img quiet ip=:::::eth0:dhcp nfsroot=10.0.0.1:/arch

Or if you are using NBD, use the following append line:

append ro initrd=initramfs-linux.img ip=:::::eth0:dhcp nbd_host=10.0.0.1 nbd_name=arch root=/dev/nbd0
Note: You will need to change nbd_host and/or nfsroot, respectively, to match your network configuration (the address of the NFS/NBD server)

PXELINUX uses the same configuration syntax as SYSLINUX; refer to the upstream documentation for more information.

The kernel and initramfs will be transferred via TFTP, so the paths to those are going to be relative to the TFTP root. Otherwise, the root filesystem is going to be the NFS mount itself, so those are relative to the root of the NFS server.

To actually load PXELINUX, replace filename "/grub/i386-pc/core.0"; in /etc/dhcpd.conf with filename "/pxelinux.0" (or with filename "/lpxelinux.0").

Booting ISO9660 image files with memdisk

Syslinux supports booting from ISO images directly using the memdisk module, see Multiboot USB drive#Using Syslinux and memdisk for examples.

Serial console

Merge-arrows-2.pngThis article or section is a candidate for merging with Working with the serial console.Merge-arrows-2.png

Notes: General page about topic not specific to Syslinux, already provides examples for GRUB. (Discuss in Talk:Syslinux#)

To enable Serial Console add the SERIAL port [baudrate] to the top of syslinux.cfg file. "port" is a number (0 for /dev/ttyS0), if "baudrate" is omitted, the baud rate default is 9600 bps. The serial parameters are hardcoded to 8 bits, no parity and 1 stop bit.[2]

syslinux.cfg
SERIAL 0 115200

Enable Serial Console in the kernel at boot by adding console=tty0 console=ttyS0,115200n8 to the APPEND option.[3]

syslinux.cfg
APPEND root=UUID=126ca36d-c853-4f3a-9f46-cdd49d034ce4 rw console=tty0 console=ttyS0,115200n8

How to do this with GRUB: Working with the serial console#GRUB2 and systemd

Troubleshooting

Using the Syslinux prompt

You can type in the LABEL name of the entry that you want to boot (as per your syslinux.cfg). If you used the example configurations, just type:

boot: arch

If you get an error that the configuration file could not be loaded, you can pass your needed boot parameters, e.g.:

boot: ../vmlinuz-linux root=/dev/sda2 rw initrd=../initramfs-linux.img

If you do not have access to boot: in ramfs, and therefore temporarily unable to boot the kernel again,

1. Create a temporary directory, in order to mount your root partition (if it does not exist already):
 # mkdir -p /new_root
2. Mount / under /new_root (in case /boot/ is on the same partition, otherwise you will need to mount them both):
Note: Busybox cannot mount /boot if it is on its own ext2 partition.
 # mount /dev/sd[a-z][1-9] /new_root
3. Use vim and edit syslinux.cfg again to suit your needs and save file.
4. Reboot.

Fsck fails on root partition

In the case of a badly corrupted root partition (in which the journal is damaged), in the ramfs emergency shell, mount the root file system:

# mount /dev/root partition /new_root

And grab the tune2fs binary from the root partition (it is not included in Syslinux):

# cp /new_root/sbin/tune2fs /sbin/

Follow the instructions at ext2fs: no external journal to create a new journal for the root partition.

No Default or UI found on some computers

Certain motherboard manufacturers have less compatibility for booting from USB devices than others. While an ext4 formatted USB drive may boot on a more recent computer, some computers may hang if the boot partition containing the kernel and initrd are not on a FAT16 partition. To prevent an older machine from loading ldlinux and failing to read syslinux.cfg, use cfdisk to create a FAT16 partition (<=2GB) and format using dosfstools:

# mkfs.msdos -F 16 /dev/sda1

then install and configure Syslinux.

Missing operating system

  • Check that you have installed gptmbr.bin for GPT and mbr.bin for msdos partition table. A "Missing operating system" message comes from mbr.bin while gptmbr.bin would show a "Missing OS" message.
  • Check whether the partition that contains /boot has the "boot" flag enabled.
  • Check whether the first partition at the boot device starts at sector 1 rather than sector 63 or 2048. Check this with fdisk -l. If it starts at sector 1, you can move the partition(s) with gparted from a rescue disk. Or, if you have a separate boot partition, you can back up /boot with
# cp -a /boot /boot.bak

and then boot up with the Arch install disk. Next, use cfdisk to delete the /boot partition, and recreate it. This time it should begin at the proper sector, 63. Now mount your partitions and chroot into your mounted system, as described in the beginners guide. Restore /boot with the command

# cp -a /boot.bak/* /boot

Check if /etc/fstab is correct, run:

# syslinux-install_update -iam

and reboot.

You will also get this error if you are trying to boot from a md RAID 1 array and created the array with a too new version of the metadata that Syslinux does not understand. As of August 2013 by default mdadm will create an array with version 1.2 metadata, but Syslinux does not understand metadata newer than 1.0. If this is the case you will need to recreate your RAID array using the --metadata=1.0 flag to mdadm.

Windows boots up, ignoring Syslinux

Solution: Make sure the partition that contains /boot has the boot flag enabled. Also, make sure the boot flag is not enabled on the Windows partition. See the installation section above.

The MBR that comes with Syslinux looks for the first active partition that has the boot flag set. The Windows partition was likely found first and had the boot flag set. If you wanted, you could use the MBR that Windows or MS-DOS fdisk provides.

Menu entries do nothing

You select a menu entry and it does nothing, it just "refreshes" the menu. This usually means that you have an error in your syslinux.cfg file. Hit Tab to edit your boot parameters. Alternatively, press Esc and type in the LABEL of your boot entry (e.g. arch). Another cause could be that you do not have a kernel installed. Find a way to access your file system (through live CD, etc) and make sure that /mount/vmlinuz-linux exists and does not have a size of 0. If this is the case, reinstall your kernel.

Cannot remove ldlinux.sys

The ldlinux.sys file has the immutable attribute set, which prevents it from being deleted or overwritten. This is because the sector location of the file must not change or else Syslinux has to be reinstalled. To remove it, run:

# chattr -i /boot/syslinux/ldlinux.sys
# rm /boot/syslinux/ldlinux.sys

White block in upper left corner when using vesamenu

Problem: As of linux-3.0, the modesetting driver tries to keep the current contents of the screen after changing the resolution (at least it does so with my Intel, when having Syslinux in text mode). It seems that this goes wrong when combined with the vesamenu module in Syslinux (the white block is actually an attempt to keep the Syslinux menu, but the driver fails to capture the picture from vesa graphics mode).

If you have a custom resolution and a vesamenu with early modesetting, try to append the following in syslinux.cfg to remove the white block and continue in graphics mode:

APPEND root=/dev/sda6 rw 5 vga=current quiet splash

Chainloading Windows does not work, when it is installed on another drive

If Windows is installed on a different drive than Arch and you have trouble chainloading it, try the following configuration:

LABEL Windows
       MENU LABEL Windows
       COM32 chain.c32
       APPEND mbr:0xdfc1ba9e swap

Replace the mbr code with the one your Windows drive has (details above), and append swap to the options.

Read bootloader log

In some cases (e.g. bootloader unable to boot kernel) it is highly desirable to get more information from the boot process. Syslinux prints error messages to screen but the boot menu quickly overwrites the text. To avoid losing the log information, disable UI menu in syslinux.cfg and use the default "command-line" prompt. It means:

  • avoid the UI directive
  • avoid ONTIMEOUT
  • avoid ONERROR
  • avoid MENU CLEAR
  • use a higher TIMEOUT
  • use PROMPT 1
  • use DEFAULT <problematic_label>

To get more detailed debug log, recompile the syslinux package with additional CFLAGS:

-DDEBUG_STDIO=1 -DCORE_DEBUG=1

Btrfs compression

Booting from btrfs with compression is not supported.[4] This error will show:

btrfs: found compressed data, cannot continue!
invalid or corrupt kernel image.

GRUB supports btrfs with compression.

See also