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 thestep 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.