> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyshift.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Linux Integration

> Roll out the Anyshift Linux agent to your hosts with Ansible, AWS SSM or cloud-init.

# Linux Integration

Install the Anyshift Linux agent on your hosts so Annie can ask them what is listening and which process owns it. The agent dials your Tower over TLS; you roll it out with the tools you already use.

## Quickstart

Install the agent on a host and enrol it with the Ansible role. The role installs the package, writes the configuration file (readable by root only) and starts the service.

```bash theme={null}
export ANYSHIFT_TOWER_ADDRESS=tower.example.com:443
export ANYSHIFT_ENROLLMENT_TOKEN="$(your-secret-store get anyshift-token)"
VERSION=0.1.9
ansible-playbook -i inventory.ini site.yml -e "anyshift_agent_version=$VERSION"
```

The token comes from your secret store or ansible-vault. Never pass it with `-e`, on a command line, or in an SSM command parameter.

## Prerequisites

* A Tower address (`host:port`) and an enrollment token.
* Ubuntu 22.04 or 24.04, Debian 13, Amazon Linux 2023 or Rocky 8, on x86\_64 or aarch64, with systemd.
* The agent package for your version. Releases carry the `.deb` and `.rpm` packages (v0.1.9 is the current one). The agent repository is private, so get the release assets from your Anyshift contact and host them on a mirror you control (S3, an artifact store); each method below takes the mirror's address. Package repositories (apt and dnf) are the planned replacement for this step.

## Roll out

> [tab] Ansible
>
> The role installs the package first, then writes `/etc/anyshift/anyshift-linux-agent.conf` (`root:root`, mode `0600`), then starts the service once. A second run changes nothing.
>
> The agent repository is private. Get the role (the `anyshift_linux_agent` directory) from your Anyshift contact and copy it to `roles/anyshift_linux_agent` next to your playbook.
>
> ```yaml theme={null}
> - name: Install and enrol the Anyshift Linux agent
>   hosts: anyshift_agents
>   become: true
>   vars:
>     anyshift_agent_tower_address: "{{ lookup('ansible.builtin.env', 'ANYSHIFT_TOWER_ADDRESS') }}"
>     anyshift_agent_enrollment_token: "{{ lookup('ansible.builtin.env', 'ANYSHIFT_ENROLLMENT_TOKEN') }}"
>   roles:
>     - anyshift_linux_agent
> ```
>
> Copy the package to the control host and add `anyshift_agent_package_local_path: /srv/anyshift/anyshift-linux-agent_{{ anyshift_agent_version }}_amd64.deb` (`_arm64.deb` on aarch64 Debian and Ubuntu hosts; the `.rpm` with `x86_64` or `aarch64` in its name on RPM hosts), or point `anyshift_agent_package_url` at your mirror. Add `anyshift_agent_package_sha256` (from `SHA256SUMS`) to have the role check a URL download.
>
> Use `serial: 10` for a rolling rollout.

> [tab] AWS SSM
>
> Create a Command document that installs the agent and reads the token at run time from a Parameter Store SecureString. The document takes the parameter's name, never the token. Get the document file, `anyshift-linux-agent-install.yaml`, from your Anyshift contact, together with the Ansible role.
>
> ```bash theme={null}
> aws ssm create-document --name AnyshiftLinuxAgentInstall --document-type Command --document-format YAML \
>   --content file://anyshift-linux-agent-install.yaml
>
> VERSION=0.1.9
> # Your mirror of the release assets (the agent repository is private): the files are $BASE_URL/v$VERSION/<asset> and SHA256SUMS.
> BASE_URL=https://mirror.example.com/anyshift
>
> # Write the token to a private temp file with shell builtins and pass the file, never the value:
> # an argument is visible to every user through `ps` and stays in shell history.
> # The subshell runs aws in the background and waits, so Ctrl-C, kill or hangup stops it at once and the EXIT trap removes the file; the rm after the call removes it as soon as aws returns, whatever its exit code.
> # The send-command below is chained with && so a failed upload (expired credentials, network) never deploys with a stale token.
> # --overwrite updates the parameter on a token rotation, so the command can be rerun.
> ( umask 077; tok=$(mktemp) || exit; pid=; trap 'rm -f "$tok"' EXIT; trap 'kill $pid 2>/dev/null; exit 130' INT; trap 'kill $pid 2>/dev/null; exit 143' TERM HUP; printf '%s' "$ANYSHIFT_ENROLLMENT_TOKEN" > "$tok" || exit 1; aws ssm put-parameter --name /anyshift/enrollment-token --type SecureString --overwrite --value "file://$tok" & pid=$!; wait $pid; rc=$?; rm -f "$tok"; exit $rc ) \
>   && aws ssm send-command --document-name AnyshiftLinuxAgentInstall \
>   --targets Key=tag:anyshift-agent,Values=true \
>   --parameters "Version=$VERSION,TowerAddress=tower.example.com:443,TokenParameterName=/anyshift/enrollment-token,ReleaseBaseUrl=$BASE_URL" \
>   --max-concurrency 5% --max-errors 2%
> ```
>
> The instance profile needs `ssm:GetParameter` on the parameter, and `kms:Decrypt` if it uses a customer-managed key. The document passes its parameters to the script as environment variables (`interpolationType: ENV_VAR`), which needs SSM Agent 3.3.2746.0 or later (older agents do not support it). Use a State Manager association with the same document to enrol new tagged hosts automatically.

> [tab] cloud-init
>
> Stage the configuration file with `permissions: '0600'` in the instance user-data, install the package, then copy the file into place and start the service. The file is staged under `/run` and copied after the install because the RPM owns `/etc/anyshift/anyshift-linux-agent.conf`: a file already there would be moved aside and replaced by the blank default.
>
> ```yaml theme={null}
> #cloud-config
> write_files:
>   - path: /run/anyshift-linux-agent.conf
>     owner: root:root
>     permissions: '0600'
>     content: |
>       TOWER_ADDRESS=tower.example.com:443
>       ENROLLMENT_TOKEN=<TOKEN>
> runcmd:
>   # BASE is your mirror of the release assets (the agent repository is private): $BASE/v$V/<asset>
>   - - sh
>     - -ec
>     - |
>       V=0.1.9; BASE=https://mirror.example.com/anyshift; a=$(uname -m)
>       case $a in x86_64) m=amd64 ;; aarch64) m=arm64 ;; *) echo "unsupported architecture $a" >&2; exit 1 ;; esac
>       s=/run/anyshift-linux-agent.conf; d=$(mktemp -d); trap 'rm -rf "$d" "$s"' EXIT
>       if command -v apt-get >/dev/null 2>&1; then
>         f=anyshift-linux-agent_${V}_$m.deb
>         curl -fsSL -o "$d/$f" "$BASE/v$V/$f"
>         DEBIAN_FRONTEND=noninteractive apt-get install -y -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold --allow-downgrades "$d/$f"
>       else
>         f=anyshift-linux-agent-$V-1.$a.rpm
>         curl -fsSL -o "$d/$f" "$BASE/v$V/$f"
>         dnf install -y --allowerasing --nogpgcheck "$d/$f"
>       fi
>       install -m 0600 -o root -g root "$s" /etc/anyshift/anyshift-linux-agent.conf
>       systemctl enable anyshift-linux-agent
>       systemctl restart anyshift-linux-agent
> ```
>
> The package is downloaded into a root-only temporary directory (`mktemp -d`), not a shared path. This example does not verify a checksum; add a `sha256sum -c` against `SHA256SUMS` from your mirror before installing if you need it.
>
> User-data is readable through the instance metadata service and is kept in the instance logs. For production, fetch the token from Parameter Store at boot instead of putting it in user-data.

Check the enrolment on the host with `systemctl is-active anyshift-linux-agent` and `journalctl -u anyshift-linux-agent -n 50`.

## Upgrade, roll back and remove

* **Upgrade:** run the same method with a new version. A running agent restarts once; a stopped agent stays stopped.
* **Roll back:** run it with the previous version (for example `VERSION=0.1.7`). The configuration file is kept. By hand on Debian and Ubuntu, `apt-get install -y` refuses to downgrade: add `--allow-downgrades`; on RPM hosts use `dnf downgrade` with the older `.rpm`. The cloud-init example runs once at first boot, so use the Ansible role or the SSM document to roll back a running host.
* **Remove:** `anyshift_agent_state=absent` with the role, or `apt-get purge anyshift-linux-agent` / `dnf remove anyshift-linux-agent`. The role keeps the configuration file unless you also set `anyshift_agent_remove_config=true`.

> [accordion] Where the token goes
>
> Put the Tower address and the token in the configuration file (`root:root`, mode `0600`) or in `ANYSHIFT_AGENT_*` environment variables of the service. Do not put them on a command line (visible to every local user), in an SSM command parameter (stored in the command history), or in a world-readable file.

> [accordion] Python for Ansible
>
> The role is tested with ansible-core 2.21. Ansible runs modules with the target's Python, and ansible-core 2.21 supports target Python 3.9 to 3.14. Ubuntu 22.04 (3.10), Ubuntu 24.04 (3.12), Debian 13 (3.13) and Amazon Linux 2023 (3.9) work as they are. Rocky 8's default Python 3.6 is too old: install `python3.11` and set `ansible_python_interpreter=/usr/bin/python3.11` for those hosts. ansible-core 2.16 is end of life and cannot run on Debian 13.

> [accordion] Packages are unsigned
>
> Until the package repositories are available, the packages are unsigned: the GPG check is off. The SSM document checks the package against `SHA256SUMS`, the role does so only when you set `anyshift_agent_package_sha256`, and the cloud-init example checks nothing. Pin the sha256 in production.

> [accordion] Hosts without systemd
>
> Set `anyshift_agent_manage_service: false`. The role installs the package and writes the configuration file; run the agent under your own supervisor. On a host where systemd is running, the package itself still enables the unit; run `systemctl disable anyshift-linux-agent` if you do not want that.

> [accordion] What is tested
>
> The Ansible role is exercised on all five distros (install, enrol, upgrade, roll back, remove) against a mock Tower. The SSM document and the cloud-init example are only syntax-checked: they have not been run against a real AWS account.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.