Convert a Syslinux Configuration into a Testable grub.cfg

Migrating an old PXE or ISO boot setup off Syslinux? grub-syslinux2cfg turns its configuration into GRUB text you can review before touching anything live. This guide uses grub-syslinux2cfg from GRUB 2.12-1ubuntu7.3, supplied by Ubuntu's grub-common package. Allow about 15 minutes for a small configuration and a careful review.

You need a readable Syslinux, ISOLINUX or PXELINUX configuration and a writable working directory. The conversion itself normally needs no elevated privileges. Do not write directly to /boot/grub/grub.cfg: generating text is reversible, but replacing a boot configuration can leave a machine unbootable.

1. Confirm the installed converter

Check which executable will run and record its version:

$ command -v grub-syslinux2cfg
/usr/bin/grub-syslinux2cfg
$ grub-syslinux2cfg --version
grub-syslinux2cfg (GRUB) 2.12-1ubuntu7.3

The version matters because this guide describes the installed command. The manpage calls the program a transformer from a Syslinux configuration into a GRUB one. It does not install GRUB, copy kernels, or validate that a resulting entry can boot.

2. Inspect the input and choose its format

Start by identifying the actual file. The converter assumes the parent directory of the input file is the Syslinux current directory unless you provide --cwd. Keep the input unchanged while testing:

$ ls -l /srv/boot/syslinux/syslinux.cfg
$ sed -n '1,160p' /srv/boot/syslinux/syslinux.cfg

Use one format switch when the file's origin is known: --syslinux, --isolinux, or --pxelinux. If the file is an ordinary Syslinux configuration, the explicit form is easiest to review:

$ grub-syslinux2cfg --syslinux /srv/boot/syslinux/syslinux.cfg

The output goes to standard output by default. If the input is for an ISO image, use --isolinux; for a PXELINUX setup, use --pxelinux. These switches describe how the source should be interpreted. They do not convert a disk image or fetch files from a network.

3. Generate a review copy

Write the result to a new file in a working directory. This command changes only the destination named after --output:

$ mkdir -p "$HOME/grub-conversion-review"
$ grub-syslinux2cfg \
    --syslinux \
    --output="$HOME/grub-conversion-review/grub.cfg" \
    /srv/boot/syslinux/syslinux.cfg
$ sed -n '1,200p' "$HOME/grub-conversion-review/grub.cfg"

A simple source containing a LABEL linux entry produces GRUB text resembling this:

set timeout=5
default='linux'
menuentry 'Linux test' --id 'linux' {
 if test x$grub_platform = xpc; then linux_suffix=16; else linux_suffix= ; fi
  linux$linux_suffix '/'/'/vmlinuz' initrd=/initrd.img quiet
  initrd$linux_suffix '/'/'/initrd.img'
}

The exact result depends on the source directives. Treat it as generated configuration, not as proof that the referenced kernel and initrd exist at the paths GRUB will use.

Checkpoint: confirm that the file is non-empty and contains the entries you expected:

$ test -s "$HOME/grub-conversion-review/grub.cfg" && echo 'generated grub.cfg is non-empty'
generated grub.cfg is non-empty
$ grep -n '^menuentry ' "$HOME/grub-conversion-review/grub.cfg"
3:menuentry 'Linux test' --id 'linux' {

4. Map source paths to runtime paths when needed

Conversion often happens while a mounted disk, extracted ISO tree or staging directory is visible somewhere other than its eventual root. Use --root for the source disk root and --cwd for the source configuration directory. Use --target-root and --target-cwd for the paths those locations will have at runtime.

$ grub-syslinux2cfg \
    --syslinux \
    --cwd=/srv/boot/syslinux \
    --root=/srv \
    --target-root=/mnt \
    --target-cwd=/boot/syslinux \
    --output="$HOME/grub-conversion-review/grub.cfg" \
    /srv/boot/syslinux/syslinux.cfg

The defaults are / for both roots. The current directory defaults to the input file's parent, and the target current directory follows the same default unless overridden. A common trap is setting only --root: that describes where the converter finds source files, not necessarily how GRUB will address them later.

5. Review before any privileged change

Read every generated menuentry. Compare kernel, initrd, append or command-line arguments, labels, and default selection with the source configuration. Test that referenced files exist in the intended runtime tree:

$ test -r /mnt/vmlinuz && echo 'kernel is readable'
$ test -r /mnt/initrd.img && echo 'initrd is readable'
$ grep -nE '^(menuentry|[[:space:]]+linux|[[:space:]]+initrd)' \
    "$HOME/grub-conversion-review/grub.cfg"

These checks inspect files; they do not boot them. If an entry points somewhere unexpected, correct the source or the root mappings and generate a fresh review copy. Do not patch the generated file and assume a later conversion will preserve that edit.

Only after an administrator has separately confirmed the target layout and recovery route should a generated configuration be copied into a boot directory. That installation step is outside this converter and may require root. Keep the old configuration until the new one has been tested; recovery is then a matter of restoring the known-good file through your normal boot-repair procedure.

6. Handle failures without losing the source

If the command cannot open the input, check the path and permissions:

$ test -r /srv/boot/syslinux/syslinux.cfg && echo readable
$ ls -l /srv/boot/syslinux/syslinux.cfg

If output was redirected to a file and the command failed, treat that file as untrusted and generate again to a new name. Shell redirection can create or truncate the destination before the program reports an error. The input configuration is not modified by the converter.

Use --verbose when a conversion needs more diagnostic information. Use --help or --usage to check the option spelling on another installed GRUB release. Do not infer format-specific behaviour from a filename alone: select the matching format option when the deployment context is clear.

Done means