From Syslinux Wiki
Revision as of 04:50, 2 August 2019 by Ady (talk | contribs) (Wiki formatting. Minor rewording. Add new sections.)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Please note, this page might be outdated, incomplete or possibly use incorrect terminology.


When users encounter issues, there are a number of steps that can be taken to collect information. Steps here should contain no compiling.

First Steps

Check over Hardware Compatibility, Common Problems and the latest NEWS file to see if your issue might be known/resolved/have a workaround.

Even if your issue is not explicitly mentioned there, testing with the latest (pre-)release is probably one of the first troubleshooting steps.


Follow first steps first :). Then...

When booting (virtual) optical media with ISOLINUX, you might get stuck with a message similar to:

ISOLINUX <version> <date> isolinux: Disk error xx, drive yy

or perhaps with some Copyright banner line, or with "Boot failed: press a key to retry...", or...

When the ISOLINUX boot prompt cannot be reached, we need more information in order to find out what's wrong, whether it is a problem in the ISOLINUX bootloader or in the specific BIOS.

In some cases, replacing the original "isolinux.bin" file with its corresponding "isolinux-debug.bin" file (from the same version/build/package) and rebuilding the ISO image with the latter might provide additional information.

Note however, that "isolinux-debug.bin" is not compatible with isohybrid; it can only be (potentially) helpful when booting (virtual) optical media.

Usually the suggested procedure is to:

  1. make a backup of the original "isolinux.bin" file;
  2. copy "isolinux-debug.bin" in place of (aka renamed as) the original "isolinux.bin" that was used for the original ISO image;
  3. build the ISO image;
  4. test the new ISO image using the same previously-failing (virtual) system.

Considering that the "isolinux-debug.bin" file is only aimed at gathering information about the particular problematic system/BIOS and its interaction with the ISOLINUX bootloader, the new ISO image doesn't really need anything but the ISOLINUX-related files (located in their relevant directories within the ISO image). In this context, files such as kernel(s), initrd(s) and any other files that are not directly related to the bootloader, are not required for debugging with "isolinux-debug.bin". The resulting minimal debugging ISO image could thus be less than 1 MB in size.

The new ISO image (built with "isolinux-debug.bin", renamed as "isolinux.bin" in place of the original) might provide additional information regarding the specific failing system. Please contact The Syslinux Project and provide all the details in order to try to improve ISOLINUX and/or to try to find a workaround for the failing system.

Boot sector diagnose

Follow first steps first :). Then...


There are two basic inline methods:

  • use a hardware device called a "tap", that will replicate the packets to 1 or 2 ports or;
  • use something like Linux bridging to put a machine with 2+ NICs inline.

Using a "tap" generally involves just plugging-in the monitored ports between the target device and its uplink and the monitor ports to a capture machine.


brctl addbr br0
brctl addif br0 eth1
brctl addif br0 eth2

Now, connecting eth1 to the target device and connecting eth2 to its uplink will result in being able to capture on any of these three and see all the packets the target sees.


Using a port mirror in an intelligent switch is the most effective way of capturing the traffic to/from a PXE client. Cisco Catalyst switches running IOS use "port monitor" and/or "monitor session". Cisco Catalyst switches running CatOS (CatalystOS) use "span" (short for "Switch Port ANalyzer"). Some HP switches use "traffic mirroring" and "traffic monitoring".

  • Cisco IOS example:
monitor session 1 source interface GigabitEthernet0/2
monitor session 1 destination interface GigabitEthernet0/1
  • HP ProVision ASIC example (last line stops the monitor):
mirror 4 port 1
interface 2
monitor all both mirror 4
no monitor all both mirror 4

Once a mirror of the PXE client's port is configured, the capture interface on the machine doing the capture should be as silent as possible to prevent unwanted packets from being captured.


For a PXE client that can successfully use DHCP to identify the characteristics it should use (including the server and filename to boot), capturing traffic from the machine running the tftpd is pretty effective. Most tftpds will move to another port for the actual data transmission but the PXE client's IP should be in all of the applicable traffic. Filtering to just packets with that IP will likely suffice.

Using wireshark with a capture filter of 'host' (assuming is the PXE client) will generally capture all relevant packets and no irrelevant packets.

  • An example tcpdump command:
`tcpdump -i eth0 -s 0 -w dump.cap 'host'`
  • Other sample filters include:
<host-specifier> or ( (udp port 67 or udp port 68) and (udp[36:4] = 0x<MAC-0-3>) and (udp[40:2] = 0x<MAC-4-5>) )
"host specifier" could be an IP address as above, or a MAC address like 'ether host 12:34:56:78:9a:bc'.
"MAC-0-3" is the first-through-fourth byte of the MAC and "MAC-4-5" is the fifth and sixth. In the example:
  ether host 12:34:56:78:9a:bc or ( (udp port 67 or udp port 68) and (udp[36:4] = 0x12345678) and (udp[40:2] = 0x9abc) )'


If a PXE client has difficulty retrieving pxelinux.0, or PXELINUX has difficulty retrieving a file on the same or another server, a simple test is to attempt to retrieve the same file from a full-blown client. Sometimes testing from a client on another subnet is sufficient to see the issue, but sometimes it is necessary to test from the same subnet as the PXE client, or the same IP as the PXE client (with the PXE client off), in case there are any ACLs on devices between the PXE client and the TFTP system, or ACLs on the TFTP system.


One aid to determining how a given UEFI machine is structured is a dump of the device handles, the GUID to text aliases and search specifically on a certain alias.

 guid > fs0:\efi-guid.txt
 dh > fs0:\efi-dh.txt
 dh -p Net > fs0:\efi-dh-net.txt
 dh -p SimpleNetwork >> fs0:\efi-dh-net.txt

Depending on the system, "Net" or "SimpleNetwork" may be the alias for the EFI_SIMPLE_NETWORK_PROTOCOL GUID.

See also