OS Template Catalog#

The OS Template Catalog requires SynergyCP 5.4.0 or newer. See Upgrading if you are on an older release.

SynergyCP maintains a central, versioned library of OS reload templates — the Profiles, Boot Scripts, Preseeds and Shell Scripts that drive automated installs. Your installation pulls this catalog automatically using your license key, so new operating systems and install fixes arrive in your admin panel on their own, without waiting for a SynergyCP upgrade or building templates by hand.

This page explains what the catalog delivers, how and when it syncs, and what happens to templates you have customized yourself.

Before following Adding support for another OS, check whether the catalog already provides it. Most current Linux distributions are included and maintained for you.

What the catalog provides#

The catalog currently ships the following OS Reload Profiles, along with the Boot Scripts, Preseeds and Shell Scripts they depend on:

Profiles for end-of-life releases (CentOS 7, Debian 10, Debian 11) are still delivered but flagged deprecated — they remain available for reinstalls of existing customers, but SynergyCP no longer proposes template updates for them or provides support for them.

Windows Server installs are not delivered through the catalog. See Windows for Windows setup.

How syncing works#

Each template in the catalog carries a version number (for example 1.0.3). Your installation compares the catalog against its local copy and:

• Creates any Profile, Boot Script, Preseed or Shell Script it doesn’t have yet.
• Updates Profile settings (name, which Boot Script / Preseed / Shell Scripts are attached, deprecated flag) to match the catalog.
• Proposes — but does not apply — body changes to Boot Scripts, Preseeds and Shell Scripts that already exist locally. These appear as Suggested Template Changes for you to review (see below).

Catalog-provided items look like any other template in Admin > OS Reloads. They are linked to the catalog internally, so you can freely create your own Profiles alongside them.

When a sync runs#

Automatic syncing is controlled by the Catalog Auto Sync checkbox under Admin > Settings > Server. It is enabled by default. When disabled, no scheduled or event-driven syncs run; pxe:catalog:sync --force overrides the setting for a one-off sync.

Minimum version requirements#

Some templates rely on features introduced in a specific SynergyCP release. A Profile whose minimum version is newer than your installation is skipped, and a line like the following is written to Admin > System > Logs:

os_template_catalog: skipped os-almalinux10 — requires app version 5.3.0, running 5.2.5

Upgrading SynergyCP and letting the next sync run will bring the Profile in.

Your customizations are preserved#

The sync never silently overwrites the body of a Boot Script, Preseed or Shell Script that already exists on your installation. When the catalog has a newer body than your local copy, a Suggested Template Change is created instead, under Admin > System > Templates > Suggested Template Changes.

For each suggested change you can:

• Overwrite Current — replace your local template body with the catalog version.
• Keep Current — ignore this change and keep your customizations. The same change will not be proposed again; a future catalog version of the template will be.
• Manually Merge — edit the template yourself, combining your changes with the catalog’s.

“Overwrite Current” discards any edits you have made to that template. If you have customized a catalog-provided template, review the diff first or choose “Manually Merge”. Consider backing up the template body before overwriting.

Profile settings (attached scripts, name, deprecated flag) are updated automatically to match the catalog. If you need a different Boot Script, Preseed or Shell Script combination, create your own Profile rather than editing a catalog-provided one — your copy will not be touched by the sync.

Troubleshooting#

A newly announced OS isn’t showing up

1. Check Catalog Auto Sync is enabled under Settings > Server.
2. Check Admin > System > Logs for an os_template_catalog: skipped … entry — the Profile may require a newer SynergyCP version.
3. The catalog is cached for 24 hours. Run php artisan pxe:catalog:sync --no-cache on the application server to fetch a fresh copy immediately.

Sync fails or logs “no data available”

• Your license must be active. An invalid or expired license is rejected by the catalog server.
• The application server must be able to reach https://os-template-catalog.synergycp.com outbound over HTTPS.

A Suggested Template Change keeps appearing

Each distinct catalog version of a template is proposed once. If you chose “Keep Current” and a new suggestion appears, the catalog has since published a newer version of that template.

An install started failing after a sync

Syncs only change Profile settings automatically, never template bodies. If a Profile’s attached scripts changed, the previous combination can be restored by creating your own Profile with the attachments you want. If you applied a Suggested Template Change, restore the template body from the backup you made before overwriting, or contact SynergyCP support.

Test permutations#

An OS install template has to behave correctly regardless of how the server boots and how its disks are laid out. Each catalog template is tested against the combinations below — two firmware modes multiplied by three disk layouts, six permutations per template:

• Legacy BIOS / UEFI — firmware boot mode; changes the bootloader, partition table type and boot partition requirements.
• Single disk — one install disk.
• Multiple disks — install disk plus additional disks that must be left untouched (or wiped, depending on the profile).
• RAID 1 — software mirror across two disks, including the bootloader on both.

Because each permutation exercises a different code path in the preseed and boot script, a fix that lands for one combination is re-verified across the others before the template version is published.

If an install misbehaves in one of these configurations, or in a configuration not listed here, contact support with the profile name, firmware mode and disk layout so it can be reproduced.