What’s New in 2.0 and Upgrading from 1.x

---

Applies to SSHepherd 2.0

New features

• Tunnel definitions. Administrators can save SSH, RDP, Generic and Agent-to-Agent tunnels on the new Tunnels page and assign them to users or groups. Users open them by name in the Control App or with shepctl --tunnelid <tunnel id> tunnel. See Tunnel Definitions.
• Agent-to-Agent (A2A) tunnels. A permanent link from one or more source agents to a service on a destination agent, with optional commands that run when the link connects or disconnects. The new Agent-to-Agent page shows the status of each link. See Agent-to-Agent (A2A) Tunnels.
• Agent isolation. Each agent has an Availability setting: Normal, Isolated with Admin Access, or Fully Isolated. Isolation takes effect immediately and ends running sessions. See Agent Isolation.
• Custom roles. Create your own roles from 34 permissions, in the console. See Managing Roles.
• API key types. The Keys page creates four types of key: Agent Registration, SCIM Integration, Full Isolation and Admin Isolation. shepctl can create, list and delete keys. See API Keys.
• Settings in the console. Mail, reauthentication, email validation and logging settings are now on Settings → General. You no longer edit the C3 StatefulSet. See Configuring C3 Settings.
• System Status page. Shows the C3 server’s pods and the cluster certificate.
• Richer session details. Each session shows the client’s host name, IP address and MAC address, and the data sent in each direction.
• Agent commands. shepagent info, shepagent version and shepagent list-tunnel show an agent’s registration, version and tunnels on the host itself.
• New shepctl commands and options. add-license, list-license, create-apikey, list-apikey, remove-apikey, list-tunnel and version, and the options --tunnelid, --relaytunnel, --bindip and --sessionfile. See the CLI Reference.
• Installer changes. The C3 installer shows the license agreement (EULA), checks memory and disk space, and creates the first administrator account. Each C3 server gets its own Kubernetes namespace. The C3 images are pinned to exact versions, so the server never updates itself.

Changed names

SSHepherd 1.x	SSHepherd 2.0
Hosts (in the console)	Agents
Other App (tunnel type)	Generic
Whitelist	Allowed Ports (Agents → Settings)

Removed or replaced

Removed in 2.0	Use instead
Automatic upgrades from the :latest image	Planned upgrades.
shepagent --port <port> add-whitelist and remove-whitelist	Allowed Ports on the agent’s Settings tab.
Editing "whitelist" in agent.conf by hand	Allowed Ports in the console.
shepagent --groups "A, B"	--group A --group B (repeat for each group).
Editing or patching the python-flask StatefulSet to change settings	Settings → General in the console.
sendgrid-patch.yaml and mail-server-patch.yaml	Mail fields on Settings → General.
shepctl --srcrdpport	--port (--srcrdpport still works but is deprecated).
shepagent --token	--apikey (--token still works but is deprecated).

Upgrading from 1.x to 2.0

The 2.0 server bundle includes upgrade_to_2.0.py and README-upgrade-2.0. The script upgrades an existing single-tenant SSHepherd 1.8 installation in place. It runs on a Linux host with Python 3.8 or later and kubectl (or MicroK8s).

Before you start

• Schedule a maintenance window when no sessions are being recorded. The upgrade replaces the C3 and recording pods, which can interrupt live sessions and recordings.
• Back up the MongoDB database and the recordings. The script doesn’t back them up.
• Know your Kubernetes context and the namespace of your C3 server.
• Have the container registry name and credentials FullArmor gave you.

MicroK8s: move to the Traefik ingress

The 2.0 MicroK8s installer needs MicroK8s 1.35 or later, where the ingress add-on uses Traefik instead of NGINX. To move an existing MicroK8s server:

1. Update MicroK8s to 1.35 or later, for example:

sudo snap refresh microk8s --channel=1.36/stable

2. Copy the 2.0 server bundle to a host that can reach your cluster, and unpack it: tar -xf shepserver-microk8s-install-<build>.tar

3. cd to the folder that tar created

4. From the unpacked 2.0 bundle, run:

sudo ./upgrade-ingress-to-traefik.sh

The script migrates every SSHepherd server on the cluster. Web, recording and console traffic stop briefly while the ingress controllers are swapped, so run it in a maintenance window. Azure AKS keeps using NGINX ingress.

Upgrade the C3 server

1. If you didn’t already unpack the 2.0 server bundle in the previous section, copy the 2.0 server bundle to a host that can reach your cluster, and unpack it: tar -xf shepserver-microk8s-install-<build>.tar Then cd to the folder that tar created. For Azure AKS, use shepserver-azure-install-<build>.tar, which unpacks to shepserver-azure-install-<version>.
2. Apply the 2.0 role and policy file to your namespace: microk8s kubectl -n <your namespace> apply -f rbac.yamlOn AKS, use kubectl instead of microk8s kubectl. Without this step, saving Settings → General fails.
3. Run a dry run. It checks the cluster, permissions and images and changes nothing: sudo ./upgrade_to_2.0.py --context <your context> --namespace <your namespace> --registry <your registry> --dry-run
4. Fix anything the dry run reports.
5. Run the upgrade: sudo ./upgrade_to_2.0.py --context <your context> --namespace <your namespace> --registry <your registry> --confirm-idle-recording-windowThe script saves a snapshot of the C3 configuration in a private backup folder (by default ./sshepherd-upgrade-backups) before it changes anything. It then upgrades the recording service and the C3 server and waits until the server is ready.
6. Sign in to the Administrator Console, check that you can open a tunnel, and play back one new recorded session.

If the upgrade fails, follow RECOVERY.txt in the backup folder the script printed. It contains rollback steps for the C3 server and the recording service. Restore the database and recordings from your own backups if needed.

Upgrade agents and clients

After the C3 server is upgraded:

1. Install the 2.0 Agent over the 1.x Agent on each host (MSI, .deb or .rpm). The host keeps its host ID.
2. Restart the Agent service on each host.
3. Install the 2.0 Control App and shepctl on each user’s computer.
4. Replace any scripts that use add-whitelist, remove-whitelist, --groups or --srcrdpport.
5. Move any allowed ports that were set by hand in agent.conf into Allowed Ports in the console.