Install on Linux with apt

Stairwell publishes a signed APT repository at downloads.stairwell.com. On Debian and Ubuntu hosts you register the repository once and then install and upgrade the forwarder with apt, which means the forwarder joins your normal patching cycle instead of needing its own process. This is the install path to prefer on Debian-family hosts, and especially if you manage them with configuration management.

If you are on a RHEL-family host, or you would rather install from a downloaded package, see Install on Linux with a Script.

What do I need before I start?

• Your environment ID and a forwarder authentication token for it. See Environments.
• A Debian-family host on amd64. The repository publishes amd64 only.
• curl and gpg available on the host.
• Root or sudo.
• auditd installed and enabled. The forwarder needs it to observe file events, and the package declares a dependency on the audit library but does not enable the daemon for you.
• A clean connectivity result from that network. See Pre-Deployment Check.

Step 1: import the signing key

The repository is signed, so import the key into its own keyring rather than into apt's global trust store.

curl -fsSL https://downloads.stairwell.com/debian/stairwell.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/stairwell-archive.gpg

Confirm you imported the key you meant to. The fingerprint is:

0C29 2467 0F5D 1DBD 677F  3B2A 3273 3D33 2CAE 793F

gpg --show-keys --with-fingerprint /usr/share/keyrings/stairwell-archive.gpg

The key is a 4096-bit RSA key with the user ID Stairwell <[email protected]>. If the fingerprint does not match, stop and work out why before you register the repository: a keyring is trust, and checking it is the one step in this procedure that cannot be done later.

Step 2: register the repository

One suite, stable, with one component, main.

echo "deb [signed-by=/usr/share/keyrings/stairwell-archive.gpg] https://downloads.stairwell.com/debian stable main" \
  | sudo tee /etc/apt/sources.list.d/stairwell.list

The signed-by clause ties this repository to that one keyring, so the Stairwell key can only ever validate Stairwell packages. Do not drop it.

Step 3: ensure auditd is running

sudo systemctl enable --now auditd

Do this before installing rather than after. A forwarder that starts without auditd running installs cleanly, registers, and does not see file events, which is a silent partial failure rather than an error.

Step 4: install the forwarder

sudo apt update
sudo apt install stairwell

Step 5: configure credentials

The package installs the service; it does not know your environment. Write the configuration file with your environment ID and token, then start the service. The file, its keys, and a script that does all of this in one pass are covered in Install on Linux with a Script; the short version is /etc/stairwell/config.json holding your EnvId and Token, followed by:

sudo systemctl enable --now stairwell.service

Deliver the token through your secrets management system. It is the same token on every host in the environment, so it should not be sitting in a playbook or a shell history.

How do I confirm it worked?

Confirm the package came from the repository and which version is installed:

apt-cache policy stairwell

The output should show downloads.stairwell.com/debian stable/main as the source and the version you expected as installed. If the installed version is from a local file instead, an earlier manual install is pinned ahead of the repository.

Then confirm the service is up:

systemctl status stairwell.service
journalctl -u stairwell.service -f

Then confirm collection in Stairwell:

1. Open Assets and find the host, with a recent check-in. See Assets.
2. Open the asset and confirm objects are arriving. Give it a few minutes.
3. Confirm the environment and the policy are the ones you intended.

A running service with nothing arriving in Stairwell is auditd or the network, in that order of likelihood. Check auditd first because it is local, then run swell verify connectivity from the host. See Connectivity Requirements.

How do upgrades work?

Through apt, like any other package. Linux forwarders cannot be upgraded over the air from the Stairwell console the way Windows and macOS forwarders can, so this is the upgrade mechanism rather than a convenience.

sudo apt update
sudo apt install --only-upgrade stairwell

/etc/stairwell/config.json is preserved across an upgrade and the service restarts. Two practices worth adopting:

• Stage the rollout. Upgrade a slice of hosts, confirm they report the new version in Stairwell, then continue. Package managers make it easy to upgrade a fleet in one command, which is exactly why it is worth not doing.
• Pin deliberately if you pin at all. If a compatibility constraint holds you on a version, pin it in apt so a routine apt upgrade does not move you off it by surprise.

How do I do this with configuration management?

The steps above wrap cleanly in Ansible, Salt, Chef, or Puppet. Whatever the tool, the same four things happen:

1. The signing key is placed at /usr/share/keyrings/stairwell-archive.gpg.
2. The repository is registered at /etc/apt/sources.list.d/stairwell.list.
3. auditd is enabled and the stairwell package is installed.
4. The configuration file is templated with credentials from your secrets manager, and the service is enabled.

Make the key import and the repository registration idempotent, and make step four a template rather than an unconditional overwrite, so per-host configuration is not clobbered on the next run. Install on Linux with a Script has a worked Ansible play you can adapt.

What if my hosts cannot reach the internet?

Mirror the repository internally. The Stairwell repository is an ordinary Debian repository, so it mirrors with the tooling you already use, and hosts then point at your mirror instead of at downloads.stairwell.com. Keep the signature checking in place on the mirrored copy.

If a host cannot take a forwarder at all, for example a network or security appliance whose vendor does not permit third-party agents, use swell on a schedule instead. See Install swell on a Linux Appliance.

Troubleshooting

NO_PUBKEY or a signature error on apt update. The keyring is missing or empty. Re-run the import in step 1 and confirm /usr/share/keyrings/stairwell-archive.gpg exists and is not zero bytes.

404 Not Found on the repository URL. Either the suite and component are wrong, in which case compare your sources line against step 2, or the host cannot reach downloads.stairwell.com. Corporate proxies and egress firewalls routinely block unrecognized domains; allowlist it. See Connectivity Requirements.

Unable to locate package stairwell. apt update has not run since you added the sources file, or the host is not amd64. The repository publishes amd64 only.

Package installs, service runs, nothing arrives in Stairwell. Configuration or auditd. Confirm /etc/stairwell/config.json holds a valid environment ID and token, confirm auditd is active, then check connectivity.

What should I read next?

• Install on Linux with a Script, for the configuration file reference and the scripted install.
• Forwarder Downloads, for the current version, tested distributions, and release notes.
• Asset Configuration, for the policy settings that control collection and resource use.