Upgrade an SSOGEN access gateway

An SSOGEN Gateway is upgraded on its own server, by running the installer of a newer Gateway archive. The Admin Console shows each instance’s version but does not push upgrades. The upgrade replaces the programs only: the bootstrap file, the instance’s identity, the secret files and the stored configuration are kept, so an enrolled gateway stays enrolled.

This page uses the fictional company Acme Corp, with a gateway on gw01.acme.example in the group eg_acme_hq. Run the commands as a user who may use sudo.

1. Before you start

Check	Why
Upgrade SSOGEN first.	A gateway that is newer than SSOGEN can show as stale on the Gateways screen, because SSOGEN refuses a status report it does not know. Access itself is not affected, but you lose the view you need during an upgrade. See Backup and upgrade.
Follow the order below.	Each part expects the parts before it to be at the new version.
Upgrade one instance of a group at a time.	The other instances keep serving, so people notice nothing.
Have the new archive and its `.sha256` file on the server.	The installer never downloads anything.

Order across your installation

A relay, if you run your own.
SSOGEN.
The Gateways, one instance at a time.
The Outbound Connectors.

2. What keeps running

During	What happens
`--check` and `--plan`	Nothing changes. Both only read.
`--apply`	The programs on disk are replaced in one step. The running service is not restarted; it keeps serving with the old program until you restart it.
The restart	That one instance stops serving for the time of the restart. The other instances of the group carry the traffic. A group with a single instance is unavailable for that time.
After the restart	The instance checks its stored, signed configuration, serves it, and fetches the newest revision from SSOGEN.

--apply never changes these: /etc/ssogen-edge/edge.yaml, the identity in /etc/ssogen-edge/pki, the files in /etc/ssogen-edge/secrets, and the state folder /var/lib/ssogen-edge. The ports you chose at install time, and any override you made with systemctl edit ssogen-edge, stay in force.

3. Upgrade one instance

Verify and unpack the new archive. Replace <release> with the file name without .tar.gz, for example ssogen-edge-<version>-<date>-linux-amd64.
```
sha256sum -c <release>.tar.gz.sha256
tar -xzf <release>.tar.gz
cd <release>
sha256sum --quiet -c MANIFEST.sha256 && echo manifest ok
```
The first command must answer OK and the last must print manifest ok. Stop if either fails.
Check and read the plan. Give no --mode: the installer reads the roles from the existing edge.yaml and keeps them.
```
sudo ./install-edge.sh --check
sudo ./install-edge.sh --plan
```
Drain the instance when the group has more than one instance behind a load balancer. Readiness goes false first, so the load balancer stops sending new work; work in flight has up to --drain-seconds (30 seconds unless you changed it) to finish; then the process exits.
```
sudo systemctl kill --signal=SIGUSR1 --kill-whom=main ssogen-edge
```
Install the new programs.
```
sudo ./install-edge.sh --apply
```
Before it replaces anything, the new program checks your existing edge.yaml. If it refuses the file, the upgrade stops there with the program’s message and nothing is changed. Correct what the message names and run the command again.
Restart the service.
```
sudo systemctl restart ssogen-edge
```
Confirm (section 4) before you go to the next instance.

4. Confirm the upgrade

On the server:

ssogen-edge-diagnostics --readiness && ssogen-edge-diagnostics --version

The first command must report ready; the second prints the version now installed. The service log carries the same identity on its start line:

sudo journalctl -u ssogen-edge --no-pager | grep 'SSOGEN Edge '

In the Admin Console, open Secure access, Gateways. The instance must show online with the new version, and its Config column must read “Running revision N” with no “was refused” line. The columns are explained in Install and enroll an SSOGEN Gateway.

Then open one application through the gateway as a normal user. Only then start the next instance.

5. If the instance is not ready after the restart

What you see	What it means	What to do
`--apply` stopped with a message about `edge.yaml`	The new program refuses the bootstrap file. Nothing was changed.	Correct the field the message names, then run `--apply` again.
Readiness stays false and the Config column says a revision was refused or kept aside	The new program does not accept the stored configuration. The instance does not stop; it serves nothing until SSOGEN delivers a configuration it accepts.	Publish a change for the group from the Admin Console, then check again. See Troubleshooting.
The service does not start	The log says why.	`sudo journalctl -u ssogen-edge --no-pager` and `systemctl status ssogen-edge`.

6. Going back

The configuration goes back by itself. A revision an instance cannot apply is never activated, and the instance stays on the last one it accepted. To return to earlier settings, publish them again from the Admin Console.

The programs. Going back to an older Gateway release is done with SSOGEN support. Contact SSOGEN support before you try it. An older program may refuse the configuration SSOGEN now publishes and stay on the last configuration it accepted.

What the installer keeps for that case: --apply saves the programs it replaced in /usr/lib/ssogen-edge/previous, one generation only. With support’s agreement, the previous programs are put back like this:

sudo systemctl stop ssogen-edge
sudo cp -p /usr/lib/ssogen-edge/previous/* /usr/lib/ssogen-edge/
sudo systemctl start ssogen-edge
ssogen-edge-diagnostics --version

Limits that always apply:

Never go back to a version below 0.8.2.
A version before 4.3.0 knows neither the relay nor the Outbound Connector tunnels of 4.3.0. Do not take a relay back. Take a connector or a Gateway back only together with its other end.
The port settings you chose at install time stay as they are.