Upgrading to SynergyCP 5.0

Upgrading to SynergyCP 5.0 #

The upgrade from legacy SynergyCP to SynergyCP 5.0 has some major steps involved, due to our transition from gPXE to iPXE.

The major steps are:

  • Take a backup
  • Upgrade your DHCP servers
  • Upgrade your file servers
  • Update the file server package on your file servers
  • Update the app
  • Migrate your OS templates

Take a backup #

Please be sure to back up your SynergyCP installation. This is something that is expected you are doing anyway.

Additionally, if SynergyCP and its various ecosystem (DHCP, file server) components are running on virtual machines, snapshotting in advance of the upgrade process is recommended.

Please ensure that you have both your database backup and your configuration backup.
WARNING: Without the secret key, the information in your SynergyCP database will be unrecoverable, so it is important that the configuration backup be saved in a safe and secure place.

Upgrade your DHCP servers #

To upgrade your DHCP servers, run the following on each DHCP server:

wget https://install.synergycp.com/bm/pxe-dhcp-server.sh -O - | bash

This should reinstall your DHCP server to the latest DHCP server release in-place, without changing your API key or any other settings about your DHCP server.

Please confirm that the API key displayed to you matches what is set in the SynergyCP app for this particular DHCP server.
Please note that all DHCP servers must be upgraded. SynergyCP 5.0 and newer cannot work with mixed older versions of DHCP servers.

Upgrade your file servers #

If you reinstall your file server to upgrade it, AND you have Windows profiles set up in your SynergyCP install, please remember to sync files from your file server master to file server children, otherwise your Windows installs will stall after boot with a message like “The path is not found.”

To upgrade your file servers, run the following on each file server:

wget https://install.synergycp.com/bm/pxe-file-server.sh -O - | bash

This should reinstall your file server to the latest file server release in-place, without changing your API key or any other settings about your file server.

Please confirm that the API key displayed to you matches what is set in the SynergyCP app for this particular file server.
Please note that all file servers must be upgraded. SynergyCP 5.0 and newer cannot work with mixed older versions of file servers.

Update the file server package on your file servers #

Please follow the instructions at Updating the file server’s OS files to the latest version to update your file server’s files.

You can either update all of your file server’s file OS files individually, or update your file master and then sync to children.

Once complete via your preferred method, confirm that every file server has the following file:

damian@api:~$ ls -l /scp/pxe/file/srv/tftp/ipxe.efi
-rw-r--r-- 1 damian damian 1088000 Feb 26 13:42 /scp/pxe/file/srv/tftp/ipxe.efi
damian@api:~$

This is a new file present as of Synergy 5.0, and confirms that you have successfully updated your file server’s file package.

Update the app #

Upgrading the main SynergyCP app itself is the usual process to do so, and described here.

Migrate your OS templates #

Due to the change from gPXE to iPXE as the bootloader in use, and the variability of modified operating system templates, you’ll need to either manually adjust your OS template’s boot scripts to match iPXE format, or use our new OS templates that can be found in the app with billing IDs ending in -neo.

Only the boot scripts need to be changed. Preseeds, shell scripts, etc generally do not need to be modified, because those are executed by the OS installer of respective distributions, and no format change has taken place with our switch to iPXE.

If you want to modify your existing OS templates, details below:

Adapting gPXE boot scripts to iPXE #

Unfortunately, older versions of SynergyCP hard-coded a gPXE header into boot scripts. While this may have saved a few seconds of time, this means that the mix between boot script content and the hard-coded header in the app results in a situation where automated adaptation of boot scripts is not possible.

iPXE’s documentation can be found here: https://ipxe.org/docs. We won’t replicate their documentation here, however the general idea to move boot scripts from gPXE to iPXE is:

  • Add #!ipxe at the top as a header
  • A kernel and initrd on separate lines
    • the kernel line points at the kernel, contains an initrd pointer, and anything that was in an append line for gPXE goes on this line.
    • the initrd line points at the initrd, and that’s generally all that is on the initrd line.
      • there can be multiple initrd lines if required for the kernel
  • boot at the end

For comparison, here is a Debian 11 boot script in the legacy gPXE format:

kernel debian/buster/amd64/linux
append auto=true interface=auto DEBIAN_FRONTEND=text locale=en_US console-keymaps-at/keymap=us keymap=us netcfg/dhcp_timeout=60 netcfg/choose_interface=auto netcfg/disable_dhcp=true netcfg/get_ipaddress={$ip} netcfg/get_netmask={$netmask} netcfg/get_nameservers=8.8.8.8 netcfg/get_gateway={$gateway} netcfg/confirm_static=true url={$preseed_url|replace:'https://':'http://'} priority=critical vga=788 initrd=debian/buster/amd64/initrd.gz --
IPAPPEND 2

Here is the same boot script in the modern iPXE format:

#!ipxe
kernel {$share.http}/debian/buster/amd64/linux initrd=initrd.gz auto=true interface=auto DEBIAN_FRONTEND=text locale=en_US console-keymaps-at/keymap=us keymap=us netcfg/dhcp_timeout=60 netcfg/choose_interface=auto netcfg/disable_dhcp=true netcfg/get_ipaddress={$ip} netcfg/get_netmask={$netmask} netcfg/get_nameservers=8.8.8.8 netcfg/get_gateway={$gateway} netcfg/confirm_static=true url={$preseed_url|replace:'https://':'http://'} priority=critical
initrd {$share.http}/debian/buster/amd64/initrd.gz
boot

Complete #

At this point, you should be able to execute a server OS reload from the SynergyCP app as normal, and everything will work as it did before you upgraded from your legacy SynergyCP version.

If you encounter any issues, please don’t hesitate to contact us and we’ll be happy to assist!