Enroll a Smallstep SSH Host Manually

These are the instructions for setting up a host by hand. We also have an installation script, which is the preferred setup method.

Step 1. Run all steps as root

Now let's set up your host. You'll run the entire Host Configuration setup as the root user:

Step 2. Install step CLI tool

Step 3. Install the step-ssh utilities

This step will install modules and services.

Step 4. Configure step to connect to your CA

Step 5. Get an SSH host certificate

Remember the enrollment token you got when you signed up? You'll need it now. If you downloaded it, the file is called enrollment_token.

_👇 This leading space will (usually) keep the token out of your shell's history.

The hostname is your host's canonical hostname or IP. This will be the name clients use to SSH to this host.

For hosts with a single hostname

Run the following to issue a certificate for your host:

If a host has multiple hostnames...

Note: When a host has multiple hostnames, your users will only be able to ssh to the canonical $hostname, as shown by the step ssh hosts command.

If you need multiple hostnames in your host certificate (e.g., public and private hostnames, or a hostname and an IP address), you can pass each of them to step ssh certificate via the --principal flag:

When multiple hostnames are needed, the canonical $hostname must be passed twice: Once to establish the certificate's Key ID, and again explicitly as its first Principal.

Step 6. Configure SSHD to use certificate authentication

This command will add a few lines of configuration to the end of your /etc/ssh/sshd_config to enable certificate authentication. These lines are annotated with a comment that says # autogenerated by step @ <timestamp> so you can identify them later if you need to modify or revert these changes.

Step 7. Activate PAM/NSS Modules & HUP SSHD

The step-ssh activate command will leverage a short-lived identity certificate to authenticate itself to the host inventory.

Step 8. Register the host and add tags(s)

This command will leverage the host identity certificate to authenticate itself to the host inventory.

Registering a host with host tags

For access control in multi-user environments, host tags can be assigned via the --tag flag.

It is possible to rerun step-ssh-ctl register multiple times, to rename the host, replace its tags, or change the bastion settings. Note: This command replaces all existing tags and bastion settings for a host.

Registering a bastion host (jump boxes)

If the host you're registering is a bastion, add the --is-bastion flag:

Note: Your bastion host will need the nc command installed. Our bastion host support uses nc (along with the ProxyCommand directive) because it's widely compatible with older SSHD servers.

Registering a host behind a bastion

If the host you're registering is behind a bastion, add the --bastion flag:

Step 9. Test your installation

Before you sign out of your sudo session, test your installation by logging in and running sudo in a separate session.

This step is especially important if you have made any non-standard changes to your PAM or NSS stacks.

Now sign in at https://smallstep.com/app/[Team ID]

You should see your host listed under the "Hosts" tab.