Bootstrapping is how a server learns to trust your certificate authority. It is the step people most often get stuck on, so this page covers exactly what changes on the host.

Before you start

On the target host you need:

• sudo or root
• OpenSSH 7.2 or newer (for sshd_config.d drop-in support)
• Outbound HTTPS to your Shellius deployment — the host calls the API on every incoming SSH connection

In Shellius you need a Server record for the host, and the servers.onboard permission.

1. Generate the command

Open the server in the portal and choose Bootstrap. Shellius mints a one-time token valid for 30 minutes and gives you a command:

curl -fsSL "https://shellius.example.com/api/bootstrap/install.sh?token=…" | sudo bash

Windows targets get a PowerShell equivalent using install.ps1.

WARNING

The token is single-use and expires in 30 minutes. If you paste it into a ticket and run it an hour later it will fail with Invalid or expired bootstrap token. Generate a fresh one.

2. Run it on the host

The script is verbose and numbers its steps. It will:

Step	Change
0	Install jq and acl if missing
1	Write the CA public key to /etc/ssh/shellius_ca.pub
2	Write the host's agent token to /etc/shellius/agent-token
3	Create the just-in-time user runtime directories
4	Install check-principals to /usr/local/sbin/shellius-check-principals
5	Add a narrow sudoers drop-in so it can provision accounts
6	Write /etc/ssh/sshd_config.d/99-shellius.conf
7	Install the JIT reaper systemd units
8	Install the heartbeat timer
9	Install a logrotate rule for /var/log/shellius-jit.log
10	Validate the sshd config with sshd -t
11–12	Reload sshd and report in to the API

The sshd drop-in it writes is three directives:

TrustedUserCAKeys /etc/ssh/shellius_ca.pub
AuthorizedPrincipalsCommand /usr/local/sbin/shellius-check-principals validate %u %s
AuthorizedPrincipalsCommandUser nobody

AuthorizedPrincipalsCommandUser is nobody because OpenSSH refuses to run that command as a privileged user. The original sshd_config is backed up to /etc/ssh/sshd_config.shellius.bak first.

The script validates the configuration before reloading sshd, so a malformed config does not lock you out. Keep your existing session open until you have confirmed a new one works anyway.

3. Verify

On the host:

sudo sshd -t                                    # config is valid
systemctl status shellius-heartbeat.timer       # heartbeat is running
sudo /usr/local/sbin/shellius-check-principals --version

In the portal, the server should flip to reachable within a heartbeat interval. Then request access to it and connect — that is the real test, because it exercises check-principals against the API.

What it does not do

• It does not remove your existing authorized_keys. Your current access keeps working until you clear it out yourself, which is deliberate so bootstrapping cannot lock you out. Once certificate access works, remove the static keys — otherwise you still have the problem Shellius is there to solve.
• It does not open any inbound port. Traffic is outbound-only, from the host to the API.
• It does not install a long-running agent. check-principals runs per connection; the heartbeat is a systemd timer.

Re-running and upgrading

To update the agent components without touching CA trust or sshd:

curl -fsSL "https://shellius.example.com/api/bootstrap/install.sh?token=…" | sudo bash -s -- --upgrade

Undoing it

Shellius serves an uninstall script the same way, at /api/bootstrap/uninstall.sh?token=…. It removes the drop-in, the CA public key, the agent token, and the systemd units, and restores the sshd backup.

Make sure you have another way into the host before you run it.

When it does not work

Connection refused after bootstrapping. Check sudo sshd -t and journalctl -u ssh --since '5 min ago'. If check-principals cannot reach the API, it fails closed and no principals are returned.

Invalid or expired bootstrap token. The token was used or is older than 30 minutes. Generate a new one.

Host never reports reachable. Check the heartbeat timer and confirm the host can reach your API hostname over HTTPS, including through any egress proxy.

Certificate is rejected. Confirm the CA public key on the host matches the one shown under Administration → Certificate authority. If the CA was rotated after this host was bootstrapped, re-bootstrap it.