Adding support for another OS#
Before building a template by hand, check the OS Template Catalog. SynergyCP maintains and automatically delivers install templates for most current Linux distributions and rescue tools, so the OS you need may already be available in Admin > OS Reloads > Profiles.
This page covers operating systems that are not in the catalog — niche distributions, custom images, or unusual configurations. If a mainstream distribution or release is missing from the catalog, contact support and request it: adding it to the catalog delivers it to every SynergyCP installation, and it is tested and maintained by SynergyCP going forward.
Windows Server#
Windows Server is added through the ISO Manager rather than by building templates — see Adding Windows Server Support. Non-server versions of Windows are not currently supported due to restrictions by Microsoft. Windows Server evaluation ISOs may work but are not tested, and we do not provide support for getting them to work.
Linux and other operating systems#
An OS reload is made up of four pieces, all managed under Admin > OS Reloads:
| Piece | What it does |
|---|---|
| Kernel + initrd on the file server | The installer the server network-boots into. |
| Boot Script | An iPXE script that tells the server which kernel and initrd to load and with which kernel parameters. |
| Preseed | The unattended-install answer file (Debian preseed, kickstart, autoinstall, …) that drives the installer. |
| Profile | Ties the above together, along with Shell Scripts that run during and after the install. |
Boot Scripts, Preseeds and Shell Scripts are all rendered through the Smarty template engine before being served to the server.
Never put a
{immediately followed by a non-space character in a Boot Script, Preseed or Shell Script — Smarty will treat it as a tag and the whole template fails to render, which usually shows up as the installer dropping to an interactive prompt. See Smarty templates and curly braces.
1. Upload the kernel and initrd#
Find the netboot archive for the distribution you are adding (for example, search for "Netboot Ubuntu 22.04"). Inside it there is a folder containing the kernel — usually named linux or vmlinuz — and the initrd — usually initrd.gz or initrd.img. Some distributions instead publish these alongside their ISO images.
Copy just those two files to /scp/pxe/file/srv/http/<your path>/ on the file server you will be testing from.
Choose a path outside the directories SynergyCP provides (for example
/scp/pxe/file/srv/http/custom/<os>/). The file server updates its OS files automatically and will overwrite anything placed inside SynergyCP-managed directories.
2. Create the Boot Script#
Go to Admin > OS Reloads > Boot Scripts. Open the Boot Script closest to your OS (same distribution family, same installer), copy its body into a new Boot Script, and replace the kernel and initrd paths with the ones you uploaded. Every Boot Script starts with #!ipxe.
The kernel parameters in the Boot Script are what point the installer at its answer file and network settings, so you may need to add or change parameters to get the OS booting correctly. The variables available (server IP, gateway, preseed URL, and so on) are listed in Boot Script Template Variables.
3. Create the Preseed#
Go to Admin > OS Reloads > Preseeds. Pick the Preseed for the closest existing OS — the format depends on the installer family:
- Debian / Ubuntu (debian-installer): Debian preseed
- Ubuntu 20.04+ (Subiquity): cloud-init autoinstall
- Red Hat family (Alma, Rocky, CentOS, Fedora): kickstart
Copy it into a new Preseed and adjust package names, repository URLs, and anything version-specific. The variables available (root password, SSH keys, network configuration, partitioning) are listed in Preseed Template Variables.
4. Create the Profile#
Go to Admin > OS Reloads > Profiles. Open the Profile closest to your OS and create a new Profile with the same settings, then select your new Boot Script and Preseed.
Keep the existing Shell Scripts attached — in particular the script that reports installation completion back to SynergyCP, without which the reload will never leave the “installing” state. See Using OS Reload Shell Scripts for what each attached script does and how to add your own.
5. Test#
Provision a server with the new Profile. A template that installs cleanly on one server can still fail on another, so test across the same boot mode and disk layout permutations the catalog templates are validated against — Legacy BIOS and UEFI, single disk, multiple disks, and RAID 1 — for every configuration you intend to offer.
If the install stalls, Troubleshooting Failing OS Reloads explains what each progress percentage means and where to look.
6. Roll out to all file servers#
Once the Profile is confirmed working, copy the kernel and initrd to the master file server (if you tested on a different one), then open the master file server under Admin > OS Reloads > Deploy File Servers and use Sync Files to Children to push them to every child file server.