From b1271c8a38aeba81f74ac1e1f02d61a6a009f014 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 21 May 2026 09:11:49 -0700 Subject: [PATCH 01/10] docs(agent): consolidate install into single agent page (EFF-313) --- platform/smallstep-agent.mdx | 93 ++++++++++++++++++++++-------------- 1 file changed, 57 insertions(+), 36 deletions(-) diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index 7d8d47ae..ee79b685 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -1,24 +1,23 @@ --- -updated_at: February 03, 2026 -title: Deploy the Agent -html_title: Deploy the Smallstep Agent -description: Distribute and configure Smallstep Agent on Linux, macOS, and Windows. For organizations without MDM or using script-based deployment. +updated_at: May 21, 2026 +title: Install the Smallstep Agent +html_title: Install the Smallstep Agent on macOS, Windows, and Linux +description: Install, configure, and deploy the Smallstep Agent on macOS, Windows, and Linux endpoints. Includes manual install, MDM integration, system requirements, and network endpoints. --- -The Smallstep Agent brings automated certificate management, device identity, and configuration management features to your endpoints. +The Smallstep Agent brings automated certificate management, device identity, and configuration management features to your endpoints across macOS, Windows, and Linux. + +The agent runs as a background service on all platforms and includes an optional desktop UI for transparency and troubleshooting on macOS, Windows, and Linux. # Introduction -This guide covers **manual installation** of the Smallstep Agent on: +This guide covers installation of the Smallstep Agent on: * [Linux](#linux-installation) * [macOS](#macos-installation) * [Windows](#windows-installation) -Use this guide if you -want to install the agent -via a software management tool separate from your MDM (eg Ansible, Munki), -or if your MDM only supports limited software management workflows. +Use this guide if you are deploying the agent manually, via a software management tool separate from your MDM (e.g. Ansible, Munki), or if your MDM only supports limited software management workflows. Using an MDM? See: @@ -27,29 +26,64 @@ Using an MDM? See: - [Connect Workspace ONE to Smallstep](../tutorials/connect-workspace-one-to-smallstep.mdx) (Windows) -# Network access +# System requirements -The agent will connect to the following Smallstep hosts: -- Your CA: `.ca.smallstep.com` and subdomains -- Agent API: `control.infra.smallstep.com` -- Smallstep API: `gateway.smallstep.com` -- TPM Attestation CA: `att.smallstep.com` +## Windows -# Linux installation +- Windows 10 or later (Windows Home editions are _not_ supported) +- Trusted Platform Module (TPM 2.0) +- Architectures: `amd64`, `arm64` + +## macOS + +- macOS 13 (Ventura) or later +- Secure Enclave +- The agent must be installed for a single user (multi-user deployments are not yet supported) -## System requirements +## Linux - Supported operating systems: - Enterprise Linux (RHEL, CentOS Stream, Rocky Linux, Alma Linux, etc) - Ubuntu (Current Stable and LTS) - Debian (Current Releases) - Fedora (Current Releases) +- `systemd`-based service manager - A TPM 2.0 module is required. Smallstep depends on TPMs to create a high-assurance device inventory. -- We support `amd64` and `arm64` architectures -- The following directories are used by default: - - runtime state in `/run/step-agent` - - configuration in `/etc/step-agent` - - certificates in `/var/lib/step-agent` and in your configured locations +- `p11-kit`, `tpm-tss2` +- Architectures: `amd64`, `arm64` + +# Runtime requirements + +All platforms require an internet connection for normal operation. + +## Windows + +- *Administrator privileges* — the Smallstep Agent requires privilege escalation to be able to communicate to the TPM. + +## macOS + +- *Location permission* — to enable management of Wi-Fi networks, the Smallstep Agent needs location permission. +- *Keychain access* — the Smallstep Agent uses the macOS keychain to store both keys and certificates it manages. +- *Network Extension entitlement* — the Smallstep Agent requests the *Network Extension* entitlement so that it can manage VPN connections. + +## Linux + +- *TPM read/write permission* — the Smallstep Agent communicates to the TPM from user-space using `tpm-tss2`, and the running user must have read/write permissions to the TPM resource manager (typically `/dev/tpmrm0`). + +# Connectivity requirements + +The agent connects to the following Smallstep hosts: + +- Your CA: `.ca.smallstep.com` and subdomains +- Agent API: `control.infra.smallstep.com` +- Smallstep API: `gateway.smallstep.com` +- TPM Attestation CA: `att.smallstep.com` + +# Downloads + +Browse and download every released artifact (`.deb`, `.rpm`, `.pkg`, `.msi`, `.pkg.tar.zst`) — with SHA-256 and signature-verification commands — at [releases.smallstep.com](https://releases.smallstep.com). + +# Linux installation ## Quick install @@ -329,12 +363,6 @@ To uninstall the Smallstep Agent from a Linux system: # macOS installation -## System requirements - -- macOS 10.15 (Catalina) or later -- The agent must be installed for a single user (multi-user deployments are not yet supported) -- Installation location: `/Applications/SmallstepAgent.app` - ## Manual install 1. Download the latest package from [packages.smallstep.com](https://packages.smallstep.com/stable/darwin/step-agent_latest.pkg) @@ -389,13 +417,6 @@ To uninstall the Smallstep Agent from a macOS system: # Windows installation -## System requirements - -- Windows 10 (Anniversary Edition) or later -- Windows Home is not supported -- A TPM 2.0 module is required -- We support `amd64` and `arm64` architectures - ## Install via Winget Install the agent via [Winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/): From 48e3c6a59bbbabf3de477c6be08d623183678d9a Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 21 May 2026 09:11:56 -0700 Subject: [PATCH 02/10] docs(agent): remove standalone smallstep-app page (EFF-313) --- platform/smallstep-app.mdx | 99 -------------------------------------- 1 file changed, 99 deletions(-) delete mode 100644 platform/smallstep-app.mdx diff --git a/platform/smallstep-app.mdx b/platform/smallstep-app.mdx deleted file mode 100644 index 2690c893..00000000 --- a/platform/smallstep-app.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -updated_at: February 03, 2026 -title: The Smallstep Agent -html_title: Smallstep Agent User Documentation Guide -description: Complete guide to the Smallstep Agent for enterprise security workflows. Manage certificates, devices, and identity from a unified interface. ---- -Smallstep ensures that access to financial data, code repositories, PII, and other sensitive resources is only possible from trusted devices. - -The Smallstep Agent offers a uniform experience for device identity across macOS, Windows, and Linux, and is foundational to Smallstep's high-assurance device attestation workflow, automating the enrollment and delivery of client certificates, and configuring the components that depend on them. - -The agent runs as a background service on all platforms. On macOS and Windows, the agent includes an optional desktop app that provides visibility into the agent's status and aids in troubleshooting. - -The Smallstep Agent operates differently for Linux. For Linux specific instructions, see [Smallstep Agent for Linux](./smallstep-agent.mdx). - -## Download - - -On macOS and Windows, the Smallstep Agent includes an optional desktop app UI for transparency and troubleshooting. -The agent runs as a background service on all platforms. - - -Install packages are available from the [Smallstep package repository](https://releases.smallstep.com): - -- https://packages.smallstep.com/stable/darwin/step-agent_latest.pkg -- https://packages.smallstep.com/stable/windows/step-agent_amd64_latest.msi -- https://packages.smallstep.com/stable/windows/step-agent_arm64_latest.msi -- https://packages.smallstep.com/stable/linux/step-agent_amd64_latest.deb -- https://packages.smallstep.com/stable/linux/step-agent_arm64_latest.deb -- https://packages.smallstep.com/stable/linux/step-agent_x86_64_latest.rpm -- https://packages.smallstep.com/stable/linux/step-agent_aarch64_latest.rpm -- https://packages.smallstep.com/stable/linux/step-agent_amd64_latest.pkg.tar.zst -- https://packages.smallstep.com/stable/linux/step-agent_arm64_latest.pkg.tar.zst - -For Linux installation instructions, see [Deploy the Agent](./smallstep-agent.mdx#linux-installation). - -## System requirements - -### Windows - -- Windows 10 or later (Windows Home editions are _not supported_.) -- Trusted Platform Module (TPM 2.0) - -### Linux - -- Debian 12+, Ubuntu 22.04+, Fedora 38+ -- `systemd`-based service manager -- Trusted Platform Module (TPM 2.0) -- p11-kit -- tpm-tss2 - -### macOS - -- macOS 13 (Ventura) or later -- Secure Enclave - -## Runtime requirements - -All platforms require an internet connection for normal operation. - -### Windows - -- *Administrator privileges* - the Smallstep Agent requires privilege escalation to be able to communicate to the TPM - -### macOS - -- *Location permission* - to enable management of Wi-Fi networks, the Smallstep Agent needs location permission -- *Keychain access* - the Smallstep Agent uses the macOS keychain to store both keys and certificates it manages -- *Network Extension entitlement* - the Smallstep Agent requests the *Network Extension* entitlement so that it can manage VPN connections - -### Linux - -- *TPM read/write permission* - the Smallstep Agent communicates to the TPM from user-space using `tpm-tss2`, and the running user must have read/write permissions to the TPM resource manager (typically `/dev/tpmrm0`) - -## Connectivity requirements - -The Smallstep Agent connects to the following Smallstep hosts: -- Your CA: `.ca.smallstep.com` and subdomains -- Agent API: `control.infra.smallstep.com` -- Smallstep API: `gateway.smallstep.com` -- TPM Attestation CA: `att.smallstep.com` - -## File access - -On all platforms, the Smallstep Agent creates and manages a directory on the filesystem in a well-known location for management of keys and certificates. However, it does not access any other file on a device except the one it creates. - -- On macOS: `$HOME/Library/Application Support/Smallstep` -- On Windows: `%LOCALAPPDATA%/Smallstep` -- On Linux: `$XDG_RUNTIME_DIR/step-agent` and `$XDG_CONFIG_HOME/step-agent` - -## Telemetry - -The Smallstep Agent collects and reports some data from the host device as part of its normal operation. These are: - -- Device Identifiers from TPM-enabled platforms -- Device/Computer Name -- Device/Computer Hostname -- Chipset Architecture -- Operating System Version -- WAN IP Address From d278f3aab644fc62c5cadf1401a8aad35fc602cf Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 21 May 2026 09:12:23 -0700 Subject: [PATCH 03/10] docs: repoint inbound links from smallstep-app to smallstep-agent (EFF-313) --- platform/enrollment-guide.mdx | 4 ++-- platform/troubleshooting-agent.mdx | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/platform/enrollment-guide.mdx b/platform/enrollment-guide.mdx index 1b75d3cc..72fc3eff 100644 --- a/platform/enrollment-guide.mdx +++ b/platform/enrollment-guide.mdx @@ -31,7 +31,7 @@ into your Smallstep inventory: You can [manually invite users to join your Smallstep team](https://smallstep.com/app/?next=/users/invite), and they will be able to self-enroll devices -using the [Smallstep Desktop App](./smallstep-app.mdx) +using the [Smallstep Agent](./smallstep-agent.mdx) or the [Smallstep Agent](./smallstep-agent.mdx). By default, administrators @@ -48,7 +48,7 @@ With IdP self-enrollment enabled, when you connect Smallstep to your identity provider, your users will be able to self-enroll via single sign-on, -using the [Smallstep Desktop App](./smallstep-app.mdx) +using the [Smallstep Agent](./smallstep-agent.mdx) or the [Smallstep Agent](./smallstep-agent.mdx). By default, administrators diff --git a/platform/troubleshooting-agent.mdx b/platform/troubleshooting-agent.mdx index 6c1eee72..ce735424 100644 --- a/platform/troubleshooting-agent.mdx +++ b/platform/troubleshooting-agent.mdx @@ -127,9 +127,9 @@ This section covers issues with individual devices, the Smallstep Agent, and end ### Prerequisites Before troubleshooting endpoint issues, verify the device meets requirements: -- Review [System Requirements](./smallstep-app.mdx#system-requirements) -- Check [Runtime Requirements](./smallstep-app.mdx#runtime-requirements) -- Verify [Connectivity Requirements](./smallstep-app.mdx#connectivity-requirements) +- Review [System Requirements](./smallstep-agent.mdx#system-requirements) +- Check [Runtime Requirements](./smallstep-agent.mdx#runtime-requirements) +- Verify [Connectivity Requirements](./smallstep-agent.mdx#connectivity-requirements) ### Using the doctor command @@ -417,7 +417,7 @@ This outputs check results in JSON format: **Solutions:** 1. Verify internet connectivity: `ping 8.8.8.8` 2. Test DNS resolution: `nslookup gateway.smallstep.com` -3. Review [Connectivity Requirements](./smallstep-app.mdx#connectivity-requirements) +3. Review [Connectivity Requirements](./smallstep-agent.mdx#connectivity-requirements) 4. Check corporate firewall and proxy settings 5. Ensure all required Smallstep hosts are allowlisted From c38b9aa1d1c2d21a69860126ceddaf26c7267a51 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 21 May 2026 09:12:43 -0700 Subject: [PATCH 04/10] docs(nav): remove smallstep-app entry, rename agent entry (EFF-313) --- manifest.json | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/manifest.json b/manifest.json index f6eb9919..83c0fcd5 100644 --- a/manifest.json +++ b/manifest.json @@ -78,11 +78,7 @@ "title": "Configure Devices for Smallstep", "routes": [ { - "title": "Install the Smallstep App", - "path": "/platform/smallstep-app.mdx" - }, - { - "title": "Deploy the Agent", + "title": "Install the Smallstep Agent", "path": "/platform/smallstep-agent.mdx" }, { From d28b53d1d993ce54371c4fab269416af889bab61 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 21 May 2026 09:20:43 -0700 Subject: [PATCH 05/10] docs(enrollment): collapse duplicate agent links from sed cleanup (EFF-313) --- platform/enrollment-guide.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/platform/enrollment-guide.mdx b/platform/enrollment-guide.mdx index 72fc3eff..a671f932 100644 --- a/platform/enrollment-guide.mdx +++ b/platform/enrollment-guide.mdx @@ -31,8 +31,7 @@ into your Smallstep inventory: You can [manually invite users to join your Smallstep team](https://smallstep.com/app/?next=/users/invite), and they will be able to self-enroll devices -using the [Smallstep Agent](./smallstep-agent.mdx) -or the [Smallstep Agent](./smallstep-agent.mdx). +using the [Smallstep Agent](./smallstep-agent.mdx). By default, administrators must approve a new device @@ -48,8 +47,7 @@ With IdP self-enrollment enabled, when you connect Smallstep to your identity provider, your users will be able to self-enroll via single sign-on, -using the [Smallstep Agent](./smallstep-agent.mdx) -or the [Smallstep Agent](./smallstep-agent.mdx). +using the [Smallstep Agent](./smallstep-agent.mdx). By default, administrators must approve newly enrolled devices From 3a4b0af0cc3579203e426b85260382ecb989cfda Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 21 May 2026 09:20:47 -0700 Subject: [PATCH 06/10] docs(agent): fix macOS Uninstall step numbering (1,3,4 -> 1,2,3) --- platform/smallstep-agent.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index ee79b685..99702b01 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -401,13 +401,13 @@ To uninstall the Smallstep Agent from a macOS system: Replace `` with your Team ID from the Smallstep UI (found in [Settings → Team](https://smallstep.com/app/?next=/settings/team)). -3. Remove the application directory: +2. Remove the application directory: ```bash rm -rf /Applications/SmallstepAgent.app ``` -4. Remove the package receipt: +3. Remove the package receipt: ```bash if pkgutil --packages | grep -q com.smallstep.Agent; then From 4f2d041d0b4f1c8cb3594f06546a56238c77c0de Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 21 May 2026 11:24:18 -0700 Subject: [PATCH 07/10] docs(agent): drop redundant inline anchors on consolidated headings The MDX renderer auto-slugs each `# heading` to the same kebab-case id already targeted by inbound links. The explicit `` tags were producing a parallel id with a trailing dash (e.g. `id="system-requirements-"`) and visible whitespace in the rendered heading text. Removing them yields a single clean `id="system-requirements"` on the heading itself, and inbound links from troubleshooting-agent.mdx continue to resolve. EFF-313 --- platform/smallstep-agent.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index 99702b01..77ad8a2f 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -26,7 +26,7 @@ Using an MDM? See: - [Connect Workspace ONE to Smallstep](../tutorials/connect-workspace-one-to-smallstep.mdx) (Windows) -# System requirements +# System requirements ## Windows @@ -52,7 +52,7 @@ Using an MDM? See: - `p11-kit`, `tpm-tss2` - Architectures: `amd64`, `arm64` -# Runtime requirements +# Runtime requirements All platforms require an internet connection for normal operation. @@ -70,7 +70,7 @@ All platforms require an internet connection for normal operation. - *TPM read/write permission* — the Smallstep Agent communicates to the TPM from user-space using `tpm-tss2`, and the running user must have read/write permissions to the TPM resource manager (typically `/dev/tpmrm0`). -# Connectivity requirements +# Connectivity requirements The agent connects to the following Smallstep hosts: From 8bc88484dcf9ff84e2ffcc3cb58580fa52e698d6 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 21 May 2026 11:25:15 -0700 Subject: [PATCH 08/10] docs(agent): drop "Use this guide if..." framing on Introduction The conditional phrasing was left over from when this page only covered manual install. Now the page is the canonical install guide regardless of distribution method; the MDM Alert that follows already handles the "but I'm on an MDM" case. EFF-313 --- platform/smallstep-agent.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index 77ad8a2f..8b913cc5 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -17,8 +17,6 @@ This guide covers installation of the Smallstep Agent on: * [macOS](#macos-installation) * [Windows](#windows-installation) -Use this guide if you are deploying the agent manually, via a software management tool separate from your MDM (e.g. Ansible, Munki), or if your MDM only supports limited software management workflows. - Using an MDM? See: - [Connect Jamf Pro to Smallstep](../tutorials/connect-jamf-pro-to-smallstep.mdx) (macOS) From c3f366286739917582f3af0ff6cf8ce13b93532c Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 21 May 2026 11:28:53 -0700 Subject: [PATCH 09/10] docs(agent): restore unversioned _latest download URLs in Downloads section These stable, unversioned URLs were on the old smallstep-app page and got dropped in the initial consolidation. The releases.smallstep.com SPA only shows versioned artifacts, so the _latest aliases aren't surfaced anywhere else and are useful for embedding in scripts and docs. EFF-313 --- platform/smallstep-agent.mdx | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index 8b913cc5..a7e5fc05 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -56,12 +56,12 @@ All platforms require an internet connection for normal operation. ## Windows -- *Administrator privileges* — the Smallstep Agent requires privilege escalation to be able to communicate to the TPM. +- *Administrator privileges* — the Smallstep Agent requires privilege escalation to be able to communicate with the TPM. ## macOS -- *Location permission* — to enable management of Wi-Fi networks, the Smallstep Agent needs location permission. -- *Keychain access* — the Smallstep Agent uses the macOS keychain to store both keys and certificates it manages. +- *Location permission* — only required if the agent will manage Wi-Fi network configurations. +- *Keychain access* — the agent uses the macOS keychain to store both keys and certificates it manages. - *Network Extension entitlement* — the Smallstep Agent requests the *Network Extension* entitlement so that it can manage VPN connections. ## Linux @@ -79,7 +79,27 @@ The agent connects to the following Smallstep hosts: # Downloads -Browse and download every released artifact (`.deb`, `.rpm`, `.pkg`, `.msi`, `.pkg.tar.zst`) — with SHA-256 and signature-verification commands — at [releases.smallstep.com](https://releases.smallstep.com). +Stable, unversioned URLs that always point at the latest release on the `stable` channel: + +**macOS** + +- [step-agent_latest.pkg](https://packages.smallstep.com/stable/darwin/step-agent_latest.pkg) + +**Windows** + +- [step-agent_amd64_latest.msi](https://packages.smallstep.com/stable/windows/step-agent_amd64_latest.msi) +- [step-agent_arm64_latest.msi](https://packages.smallstep.com/stable/windows/step-agent_arm64_latest.msi) + +**Linux** + +- [step-agent_amd64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent_amd64_latest.deb) +- [step-agent_arm64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent_arm64_latest.deb) +- [step-agent_x86_64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent_x86_64_latest.rpm) +- [step-agent_aarch64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent_aarch64_latest.rpm) +- [step-agent_amd64_latest.pkg.tar.zst](https://packages.smallstep.com/stable/linux/step-agent_amd64_latest.pkg.tar.zst) +- [step-agent_arm64_latest.pkg.tar.zst](https://packages.smallstep.com/stable/linux/step-agent_arm64_latest.pkg.tar.zst) + +For versioned artifacts — with SHA-256 and signature-verification commands — see [releases.smallstep.com](https://releases.smallstep.com). # Linux installation From 43b4cae86d41fadc79f333680b8c81dcd151e69b Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 21 May 2026 11:38:13 -0700 Subject: [PATCH 10/10] docs(agent): point at troubleshooting guide; move PKCS#11 diagnostics over - Add a 'Running into trouble?' pointer to the troubleshooting guide just below the MDM callout in the Introduction. - Move the PKCS#11 troubleshooting subsection (logs + `pkcs11-tool` slot enumeration + p11-kit reference) from the install page into the existing 'PKCS#11 not working' section of troubleshooting-agent.mdx, where the rest of the PKCS#11 diagnostics already live. Replace the install-page subsection with a one-line link. EFF-313 --- platform/smallstep-agent.mdx | 30 ++++++++++++++---------------- platform/troubleshooting-agent.mdx | 14 ++++++++++++++ 2 files changed, 28 insertions(+), 16 deletions(-) diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index a7e5fc05..6fd24745 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -7,7 +7,7 @@ description: Install, configure, and deploy the Smallstep Agent on macOS, Window The Smallstep Agent brings automated certificate management, device identity, and configuration management features to your endpoints across macOS, Windows, and Linux. -The agent runs as a background service on all platforms and includes an optional desktop UI for transparency and troubleshooting on macOS, Windows, and Linux. +The agent runs as a background service on all platforms. Smallstep also has an optional desktop UI for transparency and troubleshooting, offered as a separate package. # Introduction @@ -24,6 +24,8 @@ Using an MDM? See: - [Connect Workspace ONE to Smallstep](../tutorials/connect-workspace-one-to-smallstep.mdx) (Windows) +Running into trouble? See the [Smallstep Agent troubleshooting guide](./troubleshooting-agent.mdx). + # System requirements ## Windows @@ -79,7 +81,14 @@ The agent connects to the following Smallstep hosts: # Downloads -Stable, unversioned URLs that always point at the latest release on the `stable` channel: +## All versions + +See [releases.smallstep.com](https://releases.smallstep.com) for all release history of +the Smallstep Agent, Smallstep Desktop app, and more. + +## Latest stable agent packages + +Here are URLs that always point at the latest stable release of the agent: **macOS** @@ -99,10 +108,10 @@ Stable, unversioned URLs that always point at the latest release on the `stable` - [step-agent_amd64_latest.pkg.tar.zst](https://packages.smallstep.com/stable/linux/step-agent_amd64_latest.pkg.tar.zst) - [step-agent_arm64_latest.pkg.tar.zst](https://packages.smallstep.com/stable/linux/step-agent_arm64_latest.pkg.tar.zst) -For versioned artifacts — with SHA-256 and signature-verification commands — see [releases.smallstep.com](https://releases.smallstep.com). - # Linux installation +Smallstep also offers Debian and RPM package repositories. + ## Quick install On a Linux system with `bash` and `curl`, run the following: @@ -344,18 +353,7 @@ In Chrome, you should now have access to certificates managed by Smallstep. For regular usage, add `P11_KIT_SERVER_ADDRESS` to your environment more permanently. For example, you might add `P11_KIT_SERVER_ADDRESS=unix:path=$XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock` to your global `/etc/environment` file. -#### Troubleshooting - -The agent produces a log file or journal entries in systemd, depending on how it is installed and run. - -You can use tools like `pkcs11-tool` for troubleshooting PKCS#11 support: - -```bash -pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so \ - --list-slots -``` - -See the [p11-kit](https://p11-glue.github.io/p11-glue/p11-kit/manual/) documentation for more details. +If PKCS#11 isn't working as expected, see [PKCS#11 troubleshooting](./troubleshooting-agent.mdx#pkcs11-not-working-linuxmacos). ## Uninstall diff --git a/platform/troubleshooting-agent.mdx b/platform/troubleshooting-agent.mdx index ce735424..6fcc5492 100644 --- a/platform/troubleshooting-agent.mdx +++ b/platform/troubleshooting-agent.mdx @@ -462,6 +462,19 @@ This outputs check results in JSON format: - Chrome/Firefox don't see Smallstep certificates - NetworkManager can't use agent certificates +**Diagnose:** + +The agent produces a log file or journal entries in systemd, depending on how it is installed and run. Start there. + +You can also use tools like `pkcs11-tool` to enumerate the slots exposed by the PKCS#11 server: + +```bash +pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so \ + --list-slots +``` + +The location of `p11-kit-client.so` may vary by distribution. + **Solutions:** 1. Verify PKCS#11 socket exists and is accessible 2. Set environment variable correctly: @@ -471,6 +484,7 @@ This outputs check results in JSON format: 3. Install p11-kit if not present 4. Test with `pkcs11-tool --list-slots` 5. See [PKCS#11 configuration guide](./smallstep-agent.mdx#openssl-and-pkcs11-support) +6. See the [p11-kit documentation](https://p11-glue.github.io/p11-glue/p11-kit/manual/) for general PKCS#11 reference #### Cannot access a resource (wi-fi, VPN, web app)