# Install

Source: https://www.pingtower.com/docs/addons/install/

One command on a fresh Linux box, after you have verified what you are about to run.

<div class="docs-steps">


1. **Get a release and verify it**

   Download the tarball and the `SHA256SUMS` and `SHA256SUMS.sig` beside it from the [addons download table](/addons/#download). Get the release public key, [`addons-release.pub`](/dist/addons/addons-release.pub), and check the sums file was signed by this project, then that your tarball matches it. Skipping either lets a tampered tarball and a tampered checksum file agree with each other.

   ```sh
   printf 'release@pingtower.com namespaces="pingtower-addons-release" %s\n' \
     "$(cut -d' ' -f1,2 addons-release.pub)" > allowed_signers
   ssh-keygen -Y verify -f allowed_signers -I release@pingtower.com \
     -n pingtower-addons-release -s SHA256SUMS.sig < SHA256SUMS
   sha256sum --ignore-missing -c SHA256SUMS
   ```

   Addons signatures live in their own `pingtower-addons-release` namespace, so an addons signature can never pass as a daemon release or vice versa. Needs stock OpenSSH 8.2 or later.

2. **Unpack and run the installer**

   ```sh
   tar xzf addons_<version>_linux_<arch>.tar.gz
   cd addons_<version>_linux_<arch>
   sudo ./install.sh --dry-run   # prints the exact action list, changes nothing
   sudo ./install.sh
   ```

   This creates an unprivileged `addons` system user and group, installs the binary to `/usr/local/bin/addons`, creates `/etc/addons` and `/var/lib/addons/spool`, writes the example config to `/etc/addons/agent.yaml` and a token stub to `/etc/addons/agent.env` (only if they do not already exist), and installs and enables the `addons.service` systemd unit.

   Every tarball carries a signed `MANIFEST.sha256` covering its own files. The installer verifies that signature and every file's hash before it creates the user or writes anything, and refuses outright on any mismatch.

3. **Provision the agent's source token**

   Each agent is one source on the tower. Create it under the project it should report to; the response carries the `pti_` token, shown once.

   ```sh
   curl -s -X POST https://api.pingtower.com/v1/projects/<project>/sources \
     -H "Authorization: Bearer ptk_…" \
     -d '{"name": "probe-fra-01"}'
   # → {"name":"probe-fra-01","token":"pti_<tenant>_…"}

   sudo $EDITOR /etc/addons/agent.env
   # PINGTOWER_INGEST_TOKEN=pti_<tenant>_…
   ```

4. **Edit the config**

   `/etc/addons/agent.yaml` starts as the example: a made-up agent id and one `httpcheck` against example.com. Replace them with the real identity and the checks this box should run. See [Configure](/docs/addons/config/).

5. **Start it and confirm events arrive**

   ```sh
   sudo systemctl enable --now addons
   journalctl -u addons -f
   ```

   Within one sample interval the checks show up as events on the project. Within one heartbeat interval, five minutes by default, the agent's own heartbeat does too.


</div>


## Try one check before installing anything

`addons check` runs a single check once and prints the event it would send. Add `--report` to send it. The token comes from the environment, never a flag, so it stays out of shell history.

```sh
export PINGTOWER_INGEST_TOKEN=pti_<tenant>_…
export PINGTOWER_URL=https://api.pingtower.com   # or your own box
addons check httpcheck --param url=https://example.com --report
# UP in 101ms — sent, template f5b97ca2801d, alerted
```

## Upgrading

Same installer, newer tarball. It replaces only the binary and the unit file, restarts the service if it was running, and leaves the config, the token and the spool exactly as they were. A partial spool from before the upgrade drains normally once the new binary starts.

## Container

There is no published image yet. The repository's Dockerfile builds one from a distroless base, running as an unprivileged user; mount the config and the env file and give it a writable volume for the spool. Privileged addons and kernel-attached sensors need the matching mounts and capabilities.