step CLI
Lab Setup
The lessons run in a lab VM: a disposable Ubuntu 24.04 virtual machine. One setup file builds the same machine on macOS, Windows and Linux. The only thing you install on your own computer is Multipass, the tool that runs it.
Plan on about 15 minutes, most of it waiting for downloads.
What’s in the lab VM
Section titled “What’s in the lab VM”step-ca
OpenSSL
nginx
FreeRADIUS + eapol_test
certbot
OpenSSH server
curl and jq
The lessons are written against step CLI 0.31.0 and step-ca 0.30.2. The lab VM installs exactly these versions and checks their SHA-256 hashes first.
The other tools come from Ubuntu 24.04: OpenSSL 3.0.13, nginx 1.24.0, FreeRADIUS 3.2.5, eapol_test 2.10 and OpenSSH 9.6. certbot comes from the Snap Store, so you get the current release.
1. Install Multipass
Section titled “1. Install Multipass”You need macOS 14 Sonoma or later, on Apple silicon or Intel.
Download and run the installer from canonical.com/multipass/install. Or use Homebrew:
brew install --cask multipassYou need Windows 10 or 11 (Home, Pro or Enterprise), version 1809 or later. Turn on the Virtual Machine Platform Windows feature first.
- Download the installer from canonical.com/multipass/install.
- Set your network to Private. Windows stops Multipass from starting on a public network.
- Run the installer, and allow it administrator access.
Run the multipass commands below in PowerShell or Command Prompt.
Install the snap:
sudo snap install multipassCheck that it works:
multipass versionIt prints the Multipass version.
2. Download the setup file
Section titled “2. Download the setup file”Download cloud-init.yaml. Save it in the folder where you’ll open your terminal.
This cloud-init file tells a new Ubuntu machine what to install on first boot. It’s short. Read it before you run it, because it runs as root inside the VM. You’ll see that it checks each step download against a known SHA-256 hash, the same idea as the signature check in module 1.
3. Launch the lab VM
Section titled “3. Launch the lab VM”Run this from the folder that holds cloud-init.yaml:
multipass launch 24.04 --name pki-lab --cpus 2 --memory 2G --disk 10G --timeout 900 --cloud-init cloud-init.yaml| Option | Meaning |
|---|---|
24.04 |
The Ubuntu release. Every lesson was tested on it. |
--name pki-lab |
The name you use in every other multipass command. |
--cpus 2 --memory 2G --disk 10G |
Room for all the labs. Multipass’s defaults are smaller. |
--timeout 900 |
Wait up to 15 minutes. The first launch downloads Ubuntu and every package. |
--cloud-init cloud-init.yaml |
The setup file you downloaded. |
Multipass waits until setup finishes. If the launch times out, setup keeps going in the background. Wait for it to finish:
multipass exec pki-lab -- cloud-init status --wait4. Open a shell in the VM
Section titled “4. Open a shell in the VM”multipass shell pki-labYour prompt changes to ubuntu@pki-lab. Run every lesson command here, unless a lesson tells you otherwise.
5. Check it worked
Section titled “5. Check it worked”In the VM shell:
step versionSmallstep CLI/0.31.0 (linux/amd64)Release Date: 2026-09-25T19:53:51Zstep-ca versionSmallstep CA/0.30.2 (linux/amd64)Release Date: 2026-03-23T00:18:00ZOn an Apple silicon Mac, the platform is linux/arm64. That’s expected: the VM runs the ARM build of Ubuntu.
Your lab folder is ready too:
ls -d ~/pki-lab/home/ubuntu/pki-lab6. Take a snapshot
Section titled “6. Take a snapshot”A snapshot saves the VM as it is now. If a lab goes wrong, you can come back to this clean state in seconds.
Leave the VM shell with exit. Then, on your own computer, stop the VM:
multipass stop pki-labTake the snapshot. Multipass can only snapshot a stopped VM:
multipass snapshot pki-lab --name freshStart the VM again:
multipass start pki-labTo go back to the clean state later, stop the VM, then restore the snapshot:
multipass restore pki-lab.fresh --destructive--destructive discards everything since the snapshot. Without it, Multipass asks whether to save the current state first.
Everyday commands
Section titled “Everyday commands”Run these on your own computer, not in the VM:
| Task | Command |
|---|---|
| Open a shell | multipass shell pki-lab |
| Stop the VM | multipass stop pki-lab |
| Start it again | multipass start pki-lab |
| Copy a file out of the VM | multipass transfer pki-lab:pki-lab/issue/web.crt . |
| Delete it for good | multipass delete --purge pki-lab |
Each lesson’s step-ca runs in the foreground. After a restart, start it again from the VM shell, as in module 2.
Advanced: install on your own machine
Section titled “Advanced: install on your own machine”You can skip the VM and install the tools directly. The lesson commands are the same. Some lab steps change system services, and your output shows your own paths instead of /home/ubuntu.
Download and install the step CLI package:
wget https://github.com/smallstep/cli/releases/download/v0.31.0/step-cli_0.31.0-1_amd64.debsudo dpkg -i step-cli_0.31.0-1_amd64.debDownload and install the step-ca package:
wget https://github.com/smallstep/certificates/releases/download/v0.30.2/step-ca_0.30.2-1_amd64.debsudo dpkg -i step-ca_0.30.2-1_amd64.debOn ARM machines, swap amd64 for arm64 in both file names.
Install the remaining tools from your distribution:
sudo apt install -y openssl nginx freeradius eapoltest openssh-server curl jqInstall certbot from the Snap Store. Ubuntu’s apt package is an older 2.x release:
sudo snap install --classic certbotMake the lab folder:
mkdir -p ~/pki-labThe lab VM also makes three changes you’ll meet in the lessons on a host install:
- The
freeradiusservice starts on install. Module 5 stops it. - nginx’s default site holds port 80, which certbot needs in module 7.
- Module 8 needs the
/run/sshdfolder.
Each lesson shows the fix where it matters.
Install the tools with Homebrew. The step formula includes both step and step-ca:
brew install step openssl nginx certbotHomebrew installs the latest release, which may be newer than the versions above.
The EAP-TLS and SSH labs need a Linux server. Use the lab VM for those.
Install Ubuntu under WSL from an administrator PowerShell:
wsl --install -d UbuntuThen open Ubuntu and follow the Linux steps.
step keeps your CA in ~/.step. Run step path to see where. To start over on a host install, stop step-ca and delete ~/.step and ~/pki-lab.
Package names and versions change over time. Check each project’s official install docs if a command fails.