Setting Up a Console Server#

A Console Server is a standalone Debian machine you provision once per location. It runs the disposable containers that broker KVM sessions. Follow these steps to stand one up and enable Containerized Consoles on your servers.

1. Provision a Console Server#

Provision a server or VM with a fresh install of Debian 13 that can reach the BMC network for the location it will serve. Do not reuse an existing server, as the installer sets up Docker and binds ports 80 and 443.

We do not recommend installing the Console Server on your SynergyCP master server. It sets up its own Docker stack, which can interfere with the Docker Swarm that runs the main SynergyCP application. Always use a separate, dedicated machine or VM.

The machine needs:

  • A public, fully qualified hostname (for example console.example.com) with a public DNS A record pointing at the machine. This is required so the Console Server can obtain a Let’s Encrypt SSL certificate and so customers can reach the console over HTTPS.
  • Network access to the BMC/IPMI IPs of the servers at that location.

Before going further, confirm the Console Server host can actually reach the BMC network — for example, ping and curl a known BMC IP and verify you get a response:

ping -c 3 <bmc-ip>
curl -k -I https://<bmc-ip>

If the host node itself cannot reach the BMCs, neither can the containers it runs, and consoles will fail to connect.

2. Install the Console Server software#

Run the following command on the new server as root:

curl -fsSL https://distribution.synergycp.com/scripts/console-server-installer.sh | bash

The installer sets up Docker, Node.js, and a systemd service (scp-console-server), then generates an API key. Copy the API key shown at the end of the installation — you’ll need it in the next step.

You can re-check the service at any time with:

systemctl status scp-console-server

3. Open the required firewall ports#

The Console Server needs the following reachable:

  • Ports 80 and 443 — open to the public internet. Port 80 is used only for the Let’s Encrypt certificate challenge and a redirect to HTTPS; port 443 carries the actual console sessions.
  • Port 3000 — the management API. This only needs to be reachable from your SynergyCP master.

Without a working public DNS record and ports 80/443 open, the Console Server cannot obtain its SSL certificate and consoles will stay in a “warming up” state.

4. Register the Console Server in SynergyCP#

In SynergyCP, go to Network → Deploy Console Servers and create a new Console Server with the following fields:

  • Name — a friendly name for this Console Server (for example, US-East Console).
  • Hostname — the fully qualified domain name of the Console Server (for example, console.example.com). Enter the hostname only: no http:// prefix, no port, no path, and not an IP address.
  • API Port — the management API port. Leave this as 3000 unless you changed it during installation.
  • API Key — the API key printed at the end of the installation.

Click Save.

5. Assign the Console Server to IP Groups#

When editing the Console Server, set the IP Groups field to the IP group(s) for the location this Console Server serves. SynergyCP uses this to decide which Console Server to use for a given server: when a user launches a console, SynergyCP finds the server’s IP Group and routes the session to a healthy Console Server assigned to that group.

Make sure every location where you want Containerized Consoles has at least one healthy Console Server assigned to its IP Group.

6. Verify SSL and health#

SynergyCP automatically pushes the SSL configuration (your installation’s SSL contact email plus the Console Server hostname) to each Console Server, which then obtains and renews its Let’s Encrypt certificate on its own. No manual certificate management is required.

Check the Health column on the Console Servers page:

  • OK — the Console Server is reachable and ready.
  • Warning — reachable, but reporting a non-fatal issue.
  • Error — SynergyCP cannot reach the Console Server. Re-check the hostname, API port, API key, and that the service is running.
  • Unknown — health has not been checked yet. Use the refresh control to run a check.

Once the SSL certificate has been issued, the Console Server is ready to serve sessions.

7. Enable Containerized Consoles on servers#

Containerized Consoles are enabled per server by setting the server’s Launch KVM Action. Select one or more servers, choose Assign Launch KVM Action, and set the action to Containerized Console. Then choose:

  • Console Image — the container image to run for the session (for example, synergycp/bm-console-container-legacy).
  • Console Tag — the image version/tag to use.

Save the assignment. Those servers will now use a Containerized Console when a console is launched.

For help choosing between the images we provide, see Console images.

The list of available console images comes from a catalog that is cached for performance. If a newly published image or tag isn’t listed yet, use the Refresh console image catalog control on the Console Servers page to pull the latest list.

Backward Containerized Consoles Using a Containerized Console Forward