These are the instructions for setting up a host by hand. We also have an installation script, which is the preferred setup method.
Now let's set up your host. You'll run the entire Host Configuration setup as the
$ curl -L -o step https://files.smallstep.com/step-linux-0.15.3 $ install -m 0755 -t /usr/bin step
This step will install modules and services.
Install on Ubuntu & Debian (DEB package)
$ curl -LO https://files.smallstep.com/step-ssh_0.19.1-1_amd64.deb $ dpkg -i step-ssh_0.19.1-1_amd64.deb
Comment out the broken
common-session, which causes a delay at login (this is a known Ubuntu/Debian bug):
sed -e '/pam_systemd.so/s/^/#/g' -i /etc/pam.d/common-session
Install on CentOS or Amazon Linux 2 (RPM package)
$ curl -LO "https://files.smallstep.com/step-ssh-0.19.1-1.x86_64.rpm" $ yum -y install step-ssh-0.19.1-1.x86_64.rpm
step ca bootstrap --team="[your smallstep team ID]"
Remember the enrollment token you got when you signed up? You'll need it now. If you downloaded it, the file is called
_👇 This leading space will (usually) keep the token out of your shell's history.
$ export enrollment_token="[your enrollment token]" $ export hostname="[your hostname]"
hostname is your host's canonical hostname or IP. This will be the name clients use to SSH to this host.
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
Note: When a host has multiple hostnames, your users will only be able to
sshto the canonical
$hostname, as shown by the
step ssh hostscommand.
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
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 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-ssh activate "$hostname"
step-ssh activate command will leverage a short-lived identity certificate to authenticate itself to the host inventory.
This command will leverage the host identity certificate to authenticate itself to the host inventory.
step-ssh-ctl register --hostname "$hostname"
For access control in multi-user environments, host tags can be assigned via the
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.
If the host you're registering is a bastion, add the
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.
If the host you're registering is behind a bastion, add the
step-ssh-ctl register --hostname "$hostname" --bastion "[bastion hostname]"
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
You should see your host listed under the "Hosts" tab.