Using SSH Keys on OS Reloads#

Every OS reload started from SynergyCP 5.5 onwards asks how root should be able to log in once the install finishes. The Root SSH Login Mode selector in the reload confirmation dialog replaces the old fixed behaviour of always generating a root password, and it is where a user’s stored SSH public keys are put to use.

Requires SynergyCP 5.5 or newer and an OS template that reads the new {$login_type} and {$ssh_keys} variables. All of SynergyCP’s stock Linux templates do; see Template support for the details and for what to change in templates of your own.

The Root SSH Login Mode#

When a user clicks Reload Operating System on a server, chooses a profile and continues, the Are you sure? dialog opens with a Root SSH Login Mode drop-down. It has four options:

The dialog changes with the selection:

• In the two password modes, the Root Password field is shown, pre-filled with a generated 12-character alphanumeric password. It can be edited or regenerated with Generate Password. As before, this password is not saved anywhere by SynergyCP, so it must be copied before confirming.
• In the two SSH Public Key modes, an SSH Public Keys section is shown. See Choosing keys below.
• In No SSH root login mode, neither appears. Instead a warning explains that no credentials will be issued and root SSH login will not be configured. This mode is intended only for images that set their own root credentials and are accessed via the KVM console.

The mode and the keys are recorded on the install itself, so they survive a queued install and are visible to whichever template runs. Choosing a key-only mode on a template that does not support keys leaves the server without a usable root login; see Template support.

Choosing keys#

In the With SSH Public Key and With password and SSH Public Key modes, the dialog offers two ways to supply keys, which can be combined:

• Select stored SSH public keys. A multi-select lists the keys stored on the account, each shown as its name and fingerprint. Any number can be selected. If the user has no stored keys, the list is replaced by the note No stored SSH Public Keys available. You can paste public keys below.
• Or paste additional SSH public keys (one per line). A text box accepts extra public keys for this install only. Each line must be a complete, valid public key in the same format accepted on the SSH Public Keys page. Pasted keys are not added to the account; use this for a colleague’s key or a one-off key you do not want to store.

Selected and pasted keys are merged, de-duplicated and written to the install when the dialog is confirmed. Pasting a key that is also selected does no harm. A pasted line that is not a valid public key is rejected with Each pasted key must be a valid SSH public key. and the install is not created.

The keys are copied into the install at that moment. Deleting a key from the account afterwards does not alter an install that already has it, and adding keys to the account later does not retroactively add them to a server; reload the server again, or edit /root/.ssh/authorized_keys on it directly.

Reloads started by an administrator#

Administrators see the same Root SSH Login Mode selector when they reload a server from the admin panel, and the same password and key sections. The difference is where the stored keys come from:

• If a client is assigned to the server, the multi-select lists that client’s stored keys. This lets support staff rebuild a customer’s server with the customer’s own keys without ever handling a password. The dialog shows each key’s name and fingerprint.
• If no client is assigned, the dialog says No SSH Public Keys were found because no user is assigned to this server. You can paste a public key below. The administrator can still choose a key mode and paste keys.

Administrators have no key store of their own. An administrator who regularly needs their own key on servers pastes it into the dialog each time.

Reloads created for a server through an integration or the API follow the same rules; see Via the API.

What is configured on the server#

With the stock Linux templates, the install ends with the following state, according to the mode chosen:

A locked root password cannot be used anywhere, including at the KVM console. In With SSH Public Key mode this is harmless, because OpenSSH authenticates the key and never consults the password hash. In No SSH root login mode it means the stock templates leave no root login at all, which is why that mode is reserved for images that set their own credentials.

Keys are installed for root only. Templates that create additional accounts, or operators who want the keys on a different user, can adapt the template as described below.

Template support#

The mode and the keys are passed to templates as two Smarty variables, documented in full in the Preseed Script Template Variables reference:

• {$login_type} — one of with_password, with_ssh_key, with_password_and_ssh_key or no_root_ssh.
• {$ssh_keys} — an array of OpenSSH public key lines, empty unless the mode includes keys.

{$password} is empty in the two modes that have no password, so a template that writes it into the root account unconditionally would leave the root password empty or invalid. The stock templates guard against this.

Stock templates#

The following templates delivered by the OS Template Catalog read both variables and behave as described in the table above:

• AlmaLinux 8, 9 and 10
• CentOS 7 and CentOS Stream 10
• Rocky Linux 9 and 10
• Debian (all versions, via the multi-version preseed)
• Ubuntu (all Subiquity-based releases)

The templates test whether the variables exist before using them, so the same template versions also run unchanged on SynergyCP 5.4 and older, where they fall back to the classic password-only behaviour. Make sure your installation has synced the catalog since upgrading to 5.5 so that these versions are in place; the Preseeds list under OS Reloads shows each template’s catalog version.

The following do not read the variables, and should be reloaded in With password mode only:

• Windows. Windows installs use the Administrator password and RDP; SSH keys are ignored.
• Proxmox 9 Automated. The automated installer answer file sets a root password only. Choosing a key mode would install Proxmox with no usable root password.
• Any custom preseed or kickstart of your own until it is updated as described next.

Adding support to your own templates#

If you maintain your own preseed or kickstart templates, add handling for the two variables. The pattern used by the stock templates is:

1. Decide the PermitRootLogin value from {$login_type}: no for no_root_ssh, prohibit-password for with_ssh_key, and yes otherwise.
2. Only write {$password} into the root account when the mode is with_password or with_password_and_ssh_key; otherwise lock the account (rootpw --lock in kickstart, passwd/root-password-crypted password * in the Debian installer, or leave the shadow entry untouched in Subiquity).
3. Loop over {$ssh_keys} and append each line to /root/.ssh/authorized_keys, creating the directory with mode 0700 and the file with mode 0600.
4. Apply the PermitRootLogin value to /etc/ssh/sshd_config. On EL9 and EL10, sshd_config.d/*.conf is read first and the first value wins, so write a 00- prefixed drop-in there instead of only editing the main file.

Worked examples for the Debian installer, kickstart and Subiquity are in the {$ssh_keys} entry of the variables reference. Wrap each use in {if isset($login_type)} / {if isset($ssh_keys)} if the template must also run on installations older than 5.5.

Both variables are available in preseed, kickstart and autoinstall templates only. They are not available in boot scripts.

Via the API#

An OS reload is created with POST server/{id}/install. Three fields were added in 5.5, alongside the existing password:

curl -sS "https://api.example.com/server/42/install" --data-urlencode "key=$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pxe_profile_id": 7,
    "login_type": "with_password_and_ssh_key",
    "ssh_key_ids": [12, 15],
    "ssh_keys_raw": "ssh-ed25519 AAAA... [email protected]",
    "password": "generated-root-password"
  }'

To offer a user’s stored keys in your own ordering flow, read them with GET server/{id}/ssh-key. It returns the assigned client’s keys as keys (id, name, fingerprint and public key) and a boolean client_assigned. The endpoint is available to administrators with the OS reload write permission and to the assigned client itself.

Automated provisioning through the WHMCS modules continues to pass a password and installs in With password mode.

Troubleshooting#

• The Root SSH Login Mode selector is missing. The installation is older than 5.5, or the browser is holding a cached copy of the old portal. Check the version on the admin dashboard and hard-refresh the page.
• The stored keys list is empty. The user has not stored any keys yet, or, on an admin reload, no client is assigned to the server. Keys can still be pasted into the text box.
• “One or more selected SSH keys do not belong to the server’s client.” The install was submitted with ssh_key_ids of another user’s keys, which only happens with API calls. Use the IDs from GET server/{id}/ssh-key.
• Key login is refused after the install. Confirm the server was installed with a template that supports keys (see Stock templates), and that the catalog has been synced since the 5.5 upgrade. On the server, check that the key is present in /root/.ssh/authorized_keys and that sshd -T | grep permitrootlogin reports prohibit-password or yes. If the file is empty, the template ran without the variables; reload with an updated template.
• Password login is refused in “With SSH Public Key” mode. This is by design. Reload in With password and SSH Public Key mode if both are needed.
• No credentials were shown. The reload was started in No SSH root login mode. The image is expected to provide its own credentials, reachable over the KVM console. Reload in another mode if that was not intended.