# Onyx Inventory agent

The agent runs on Debian and Ubuntu amd64. It opens an outbound HTTPS connection to the inventory server. Client machines do not need an inbound port.

This version collects hostname, operating system, kernel, processor, memory, system model, network addresses, installed APT packages, local accounts, and systemd services. Password hashes, CPU feature flags, serial numbers, and service command-line arguments are not collected. Directory accounts are not enumerated. Collection runs at 02:00 in the machine's local time zone. If the machine is off then, one catch-up report is sent after it boots. Reports stay in a local queue until the server accepts them.

## Install

```sh
sudo dpkg -i onyx-inventory-agent_0.1.3_amd64.deb
```

The installer asks for a one-time enrollment token. After the files are in place it restarts `onyx-inventory-agent.service`, and that clean start enrolls with the token. Leave the prompt blank to install without enrolling. The service then waits until a token is configured. An unattended install does the same when no token was preseeded.

The question is skipped when the machine is already enrolled. The answer is removed from the installer database after it is written to the agent configuration.

## Enroll later

If the install prompt was left blank, create a token in the admin page, then either:

```sh
sudo onyx-inventory-agent enroll --token 'the-token'
```

or put the token in `/etc/onyx-inventory/agent.conf` and restart the service:

```
server_url=https://si.onyxis.io
enrollment_token=the-token
```

```sh
sudo systemctl restart onyx-inventory-agent
```

The token is single-use and is removed from the configuration after enrollment. The machine credential is stored in `/var/lib/onyx-inventory/identity.json` and is readable only by root.

## Operation

```sh
onyx-inventory-agent status
sudo onyx-inventory-agent collect
systemctl status onyx-inventory-agent
```

`collect` sends a manual report and does not replace the 02:00 report.

Queued reports are in `/var/lib/onyx-inventory/queue`. A report is deleted only after the server stores it. The queue keeps at most 30 reports or 64 MiB. When that limit is reached, new reports are refused and the existing unsent reports stay in place. `status` shows the error. Reports the server rejects are moved to `/var/lib/onyx-inventory/rejected`.

Removing the package stops the service and keeps the configuration, credential, and queued reports. Purging the package deletes `/etc/onyx-inventory` and `/var/lib/onyx-inventory`. An upgrade keeps the machine identity, configuration, and queue.

## Build

From `agent/`, with Rust and a C compiler installed:

```sh
sh packaging/build-deb.sh
```

The package is written to `agent/dist/`. Publish that `.deb` to the private APT repository. The package does not contain an enrollment token or a machine credential.
