smallstep_full_white

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:

sudo su

Step 2. Install step CLI tool

$ curl -L -o step https://dl.smallstep.com/s3/cli/docs-ssh-host-step-by-step/step_latest_linux_amd64
$ install -m 0755 -t /usr/bin step

Step 3. Install the step-ssh utilities

This step will install modules and services.

  • Install on Ubuntu & Debian (DEB package)

    $ curl -LO https://dl.smallstep.com/s3/ssh/docs-ssh-host-step-by-step/step-ssh_latest_amd64.deb
$ dpkg -i step-ssh_latest_amd64.deb

  • Install on CentOS or Amazon Linux 2 (RPM package)

    $ curl -LO "https://dl.smallstep.com/s3/ssh/docs-ssh-host-step-by-step/step-ssh_latest_x86_64.rpm"
$ yum -y install step-ssh_latest_x86_64.rpm

Step 4. Configure step to connect to your CA

step ca bootstrap --team="[your smallstep team ID]"

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.

$  export enrollment_token="[your enrollment token]"
$ export hostname="[your hostname]"

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:

step ssh certificate $hostname /etc/ssh/ssh_host_ecdsa_key.pub \
    --host --sign --provisioner "Service Account" --token $enrollment_token

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:

step ssh certificate $hostname /etc/ssh/ssh_host_ecdsa_key.pub \
    --host --sign --provisioner "Service Account" --token $enrollment_token \
    --principal $hostname --principal 10.0.0.42

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

step ssh config --host --set Certificate=ssh_host_ecdsa_key-cert.pub \
                         --set Key=ssh_host_ecdsa_key

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

step-ssh activate "$hostname"

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.

step-ssh-ctl register --hostname "$hostname"

Registering a host with host tags

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

step-ssh-ctl register --tag <key=value> --tag <role=web> --hostname "$hostname"

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:

step-ssh-ctl register --hostname "$hostname" --is-bastion

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-ssh-ctl register --hostname "$hostname" --bastion "[bastion hostname]"

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.