SSH Access

This page explains how shell access to the appliance is granted. SSH access is a vendor-support and file-transfer concern — not part of day-to-day operation. The terminal user interface (TUI) handles routine work directly on the console, and SSH exists only for the cases the TUI cannot cover.

Why SSH access exists

The Pulse appliance is designed so that 99% of operations are driven through the TUI. Operators install updates, manage TLS certificates, configure networking, and onboard SFTP keys without ever touching a shell. That keeps the system narrow and auditable.

There are two situations where shell access is still needed:

• Vendor support emergencies. When something goes wrong below the TUI — a kernel issue, a wedged service, a bug in the appliance image itself — a Pulse support engineer needs a shell on the appliance to investigate. SSH is the channel for that. The vendor signs a short-lived certificate for the support engineer's key; the operator does not have to provision anything in advance.
• The pulse-transfer SFTP principal. The keys the operator manages on the SFTP Access screen authorise an external party to drop files into the appliance's exchange directory. That party connects as pulse-transfer over the same SSH service, so SFTP delivery rides on top of the SSH stack described here.

In both cases the appliance trusts certificates signed by the appliance's SSH certificate authority (CA). There is no list of individual user keys to maintain on the appliance — trust is delegated to whoever holds the CA private key.

The two principals

Every signed certificate carries one or more principals. A principal is a label the SSH server uses to decide what kind of access the certificate grants. The appliance recognises exactly two:

pulse — operator role (SSH + TUI)

Logging in as pulse lands the user in the operator TUI. This is the same view the operator sees on the local console. From there they can manage networking, certificates, updates, and so on. The pulse user is unprivileged: they do not have a root shell, cannot edit system files directly, and cannot bypass the TUI to mutate appliance state. Anything they need to change goes through the menus, which call privileged wrappers under the hood.

Use -n pulse when signing a key for a support engineer who needs to operate the appliance the same way the on-site operator would.

pulse-transfer — SFTP only

The pulse-transfer principal authorises a chrooted SFTP session and nothing else: no interactive shell, no TCP forwarding, no X11, no tunnels. The holder of a pulse-transfer certificate can put files into uploads/ and get files from downloads/, and that is the entire surface available to them. This is the principal used by the keys the operator adds on the SFTP Access screen.

Use -n pulse-transfer when signing a key whose only job is to move files in and out of the exchange directory.

A single certificate can carry both principals at once when the same person legitimately needs both roles — for example, a support engineer who will also upload an update bundle during the same session.

How a vendor signs a customer key

The signing happens off the appliance, on a workstation that holds the SSH CA private key. The appliance never sees the CA private key; it only carries the corresponding public key as a trust anchor.

The end-to-end flow:

1. The operator (or whoever needs access) generates an SSH keypair on their workstation if they do not already have one. The public half lives at ~/.ssh/id_ed25519.pub.
2. The operator sends that .pub file to the vendor through whatever channel is convenient — email, ticket attachment, secure messaging. The private half never leaves the operator's machine.
3. The vendor signs the public key with the CA private key using ssh-keygen -s, choosing the principal that matches the access being granted.
4. The vendor returns the signed certificate file to the operator. By convention it is named id_ed25519-cert.pub (the same basename as the key, with -cert appended).
5. The operator drops the signed certificate next to their key — typically ~/.ssh/id_ed25519-cert.pub. The SSH client picks it up automatically the next time it connects.

The signing commands the vendor runs are:

Operator role (pulse principal)

ssh-keygen -s /path/to/ca_private_key -I "description" -n pulse -V +365d ~/.ssh/id_ed25519.pub

SFTP transfer role (pulse-transfer principal)

ssh-keygen -s /path/to/ca_private_key -I "description" -n pulse-transfer -V +365d ~/.ssh/id_ed25519.pub

Both principals in one certificate

ssh-keygen -s /path/to/ca_private_key -I "description" -n pulse,pulse-transfer -V +365d ~/.ssh/id_ed25519.pub

In every case the signed certificate is written to ~/.ssh/id_ed25519-cert.pub and picked up automatically by the SSH client.

The -I flag sets a free-text identity recorded inside the certificate — useful for audit trails. A short description like support-eng-jane-2026-05 or the ticket number that prompted the signing is the right level of detail.

Validity windows

The -V +365d flag in the examples above caps the certificate's validity at one year from signing. After that, the certificate expires and the SSH server refuses to accept it — even though the underlying key is unchanged.

This expiry is deliberate:

• It limits the blast radius of a key leak. A stolen certificate stops working on its own; nobody has to find and revoke it.
• It forces a periodic re-signing ritual, which is also the natural moment to ask "does this person still need access?".
• It matches the operational rhythm of a managed appliance: a year is long enough that re-signing is not a constant chore, short enough that long-departed engineers do not retain access indefinitely.

Shorter windows are appropriate for one-off support sessions — -V +1d or -V +1w for a single intervention, after which the certificate is dead. Use shorter validity when the access is for a specific task; reserve the one-year window for keys that will be in use repeatedly.

The certificate's expiry is independent of the SSH key itself. The key stays valid; only the signature on it expires.

What the operator does not get

A signed pulse certificate gives the user a shell on the appliance, but that shell is the same constrained environment the local operator works in:

• The pulse user is unprivileged. They do not have sudo for arbitrary commands. They cannot edit system configuration files directly, cannot restart system services from the shell, and cannot read or write the appliance's protected secrets.
• Configuration changes go through the TUI. The TUI itself calls a small set of audited privileged wrappers to mutate appliance state. There is no shortcut around it.
• A pulse-transfer certificate is even more restricted: no shell at all, just SFTP into the exchange directory.

In other words: SSH access is a way to reach the operator role from off-site, not a way to escalate beyond it. Anyone who needs to change appliance state still does so through the TUI — they just see it over SSH instead of on the local console.

Related screens

• SFTP Access — manage the customer-facing SFTP keys that authenticate as pulse-transfer.
• TUI Reference — the operator menu the pulse user lands in after SSH login.
• Installation — first-boot setup, including the SSH CA trust anchor that makes signed certificates work.