Server install details

What the install command needs and changes on a server. Use this page when a server won't join, or to check what Fob did to sshd. To add a server, see Add a server.

Requirements

• Linux, run as root. For Through Fob, x86_64 or arm64.
• OpenSSH 6.8 or later, with a configuration that already passes sshd -t.
• curl 7.55 or later.
• Outbound HTTPS to your organization's URL, such as https://acme.fobauth.com, and to https://app.fob.so for the fob-agent download.
• To record direct sessions: script from util-linux 2.35 or later. Without it, direct sessions are listed but not recorded.

The install command

The console shows the full command with a token filled in:

curl -fsSL https://acme.fobauth.com/access/v1/agent.sh | sudo sh -s -- --token fob_jt_... --tunnel

Option	What it does
--token	Required. The one-time join token from the console. It puts the server in the server groups you chose.
--name	The name people connect to, such as web-01.prod. Lowercase letters, digits, dots and hyphens. Defaults to the server's full hostname.
--tunnel	Also installs fob-agent, so people connect through Fob. Leave it out for direct servers.

To pass options to every curl call the script makes, such as a proxy, set FOB_CURL_OPTS. If you use --connect-to, add an entry for both hosts above.

What the script changes

• It gives the server's Ed25519 host key a certificate from your host CA, so fob can verify the server. The certificate lasts 30 days and renews automatically.
• It configures sshd to trust your user CA, accept the logins given on this server, refuse revoked certificates, and record sessions.
• It installs /usr/local/sbin/fob-access-refresh and runs it every hour, with a systemd timer or cron. The refresh fetches access changes, revoked certificates and new CAs.
• It reloads sshd.

The settings go in /etc/ssh/sshd_config.d/10-fob-access.conf. If sshd_config doesn't include that folder, they go in sshd_config between # BEGIN FOB ACCESS and # END FOB ACCESS.

Existing logins keep working. The script doesn't change sshd's forwarding settings, and an AuthorizedPrincipalsFile you already use still works.

Before changing anything, the script copies your configuration to /etc/ssh/fob_sshd_backup. If sshd -t rejects the result, it puts the old files back.

Fix a failed install

What you see	What to do
sshd already has <setting> set	The script needs TrustedUserCAKeys, AuthorizedPrincipalsCommand, RevokedKeys and ForceCommand. Remove the one named from your sshd configuration, then run the command again.
sshd's configuration doesn't pass sshd -t	Fix the existing configuration first. Run sshd -t to see the error.
couldn't join	The token has expired or been used, or another server is already joined with that name. Create a new command in the console.
sshd couldn't be reloaded	The server joined, but sshd isn't using Fob's settings yet. Restart sshd, then run sudo /usr/local/sbin/fob-access-refresh.
Exit status 3, nothing runs fob-access-refresh every hour	The server joined, but cron isn't running. Start cron, or run /usr/local/sbin/fob-access-refresh every hour yourself.

Warning

A server that never runs the hourly refresh doesn't pick up access changes, revoked certificates or new CAs, and its host certificate expires after 30 days.

Apply changes straight away

Servers pick up access changes, revoked certificates and CA rotations at their hourly refresh. To apply them now, run:

sudo /usr/local/sbin/fob-access-refresh

fob-agent

With --tunnel, the script installs fob-agent as a systemd service called fob-agent, running as its own unprivileged user. The agent only connects out, so sshd can listen on 127.0.0.1 alone.

The agent connects to sshd on 127.0.0.1:22. If sshd listens somewhere else, add FOB_SSH=address:port to /etc/fob-agent/env and restart the service.

On a system without systemd, the script starts the agent in the background, logging to /var/log/fob-agent.log. It won't start again after a reboot until you add it to your init system.

Join a server again

To join a server again, for example after its Fob files were removed, create a new command in the console and run it on the same server, as root. The server keeps its name and record, and is added to the server groups you chose for the new command.

If the server's disk was replaced, remove it on Access > Servers first, then join it again.

Remove a server

Removing a server on Access > Servers disconnects its agent.

Warning

The server still accepts Fob certificates for direct SSH until you delete Fob's sshd settings (the file or block above) and reload sshd.

Set up a server by hand

Without the install script, you can make sshd trust your user CA directly. Set up a server on Access > Settings shows these commands with the server group filled in:

curl -fsSL https://acme.fobauth.com/access/v1/ssh/ca | sudo tee /etc/ssh/fob_user_ca.pub
sudo tee -a /etc/ssh/sshd_config <<'EOF'
TrustedUserCAKeys /etc/ssh/fob_user_ca.pub
AuthorizedPrincipalsCommand /bin/echo fob:<server group id>:%u
AuthorizedPrincipalsCommandUser nobody
EOF
sudo systemctl reload sshd

The server then accepts the logins given on that server group. The Unix users must already exist.

Warning

A server set up by hand isn't listed under Servers, gets no host certificate, doesn't record sessions and doesn't refuse revoked certificates. It also keeps the old CA after a rotation until you download the file again. Use the install command unless you can't run it.