Provisioning¶

Provisioning is how an appliance learns which account it belongs to and where its backend is. It's driven by one small file — provision.conf — plus a set of environment variables the collector reads at runtime.

You normally never write these by hand: the dashboard generates the installer bundle (or seed ISO) for you. This page documents what's inside so you can verify, customise, or troubleshoot.

`provision.conf`¶

This file lives at /etc/acutis-provision.conf on the install media and is read once on first boot, then deleted so the token can't be reused.

Field	Required	Purpose
`PROVISION_TOKEN`	Yes	One-time site token. On the self-service path it is the tenant API key; on the MSP path it's redeemed at `/api/v1/provision/activate` to mint a new tenant.
`BACKEND_URL`	Yes	Base URL of your Acutis backend, e.g. `https://app.acutisgo.com`. Everything else is derived from this.
`TENANT_ID`	Optional	Set it to take the self-service path (token = api_key, tenant already known). Leave it out to take the MSP path (activate to create a new tenant).
`COLLECTOR_KEY`	Optional	Shared transport secret echoed in the collector's payload body. On the MSP path the activate response supplies it automatically.

A minimal self-service provision.conf looks like:

PROVISION_TOKEN=<your tenant api key>
BACKEND_URL=https://app.acutisgo.com
TENANT_ID=<your tenant id>

Set the production backend URL — do not rely on the built-in default

The collector's compiled-in default for FASTAPI_COLLECTOR_URL is a legacy development address (https://192.168.0.24/...) and is not valid for production. Always set BACKEND_URL in provision.conf to your real backend (for the Acutis cloud that is https://app.acutisgo.com). First boot derives FASTAPI_COLLECTOR_URL as <BACKEND_URL>/api/v1/collector/submit and writes it into the runtime environment file — so a correct BACKEND_URL is all you need.

Runtime environment (`/etc/acutis-collector.env`)¶

After first boot, the resolved secrets live in a root-only file (0600, owned by root:root) — deliberately not the systemd unit, which would be world-readable. The collector service loads it via EnvironmentFile=.

Variable	Meaning
`FASTAPI_COLLECTOR_URL`	Full submit endpoint, e.g. `https://app.acutisgo.com/api/v1/collector/submit`. The base of this URL is reused for every other backend call (device list, vault, check-in, CLI queue, self-update).
`TENANT_API_KEY`	Sent as the `X-API-Key` header on every backend call. This is how the appliance authenticates.
`TENANT_ID`	Your site/tenant id — scopes vault lookups and telemetry.
`COLLECTOR_KEY`	Shared secret included in the submit/check-in payload body, validated by the backend on `/collector/submit`.

How the appliance authenticates¶

Every request the appliance makes to the backend carries the header:

X-API-Key: <TENANT_API_KEY>

The backend resolves the tenant from that key and refuses anything outside it. If the key is stale, rotated, or revoked, the appliance logs a loud error (HTTP 401/403 from /api/v1/collector/devices or the vault) and reuses its last known-good device list rather than inventing devices — so a bad key degrades safely instead of polling phantom hosts. The fix is to re-provision TENANT_API_KEY.

Re-downloading rotates the key

Downloading a fresh installer bundle (or provision.conf) from the dashboard mints a new api_key and retires the old one. That's intentional — it's admin-only so a viewer can't knock a live collector offline. Re-download = re-provision.

TLS options¶

The appliance separates backend-bound TLS from device-bound TLS — they're controlled independently.

Backend channel — `BACKEND_CA_CERT`¶

Set BACKEND_CA_CERT to a path containing your backend server's certificate (or CA bundle) to enable full identity pinning on the collector↔backend connection. With it set and the file present, the appliance validates the backend's cert on every call — submit, vault retrieval, self-update, everything.

If unset: traffic is still HTTPS-encrypted, but the certificate is not validated (acceptable for a backend behind a self-signed cert on a trusted path, but pinning is strongly recommended for production).
Using https:// for BACKEND_URL is what keeps collector↔backend credentials off the wire in cleartext in the first place — always use https://.

Device channel — `DEVICE_CA_CERT` / `DEVICE_TLS_VERIFY`¶

These govern TLS to your devices (PAN-OS XML API, hypervisor APIs) — completely separate from the backend setting. They exist as a single switch instead of scattered verify=False calls.

Variable	Effect
`DEVICE_CA_CERT`	Path to a CA/bundle that signs your devices' management certs. If set and present, device API identity is pinned.
`DEVICE_TLS_VERIFY`	Set to `true`/`1`/`yes` to require valid device certs without supplying a bundle.

Default (both unset): device API calls do not validate certs — convenient for LAN gear with self-signed certs, and the collector logs a one-time WARN so you know it's off.
Production guidance: pin device identity (DEVICE_CA_CERT, or at minimum DEVICE_TLS_VERIFY=true) so a host impersonating your firewall on the LAN can't harvest the admin password.

To set any of these, add them to /etc/acutis-collector.env and restart the service:

sudo nano /etc/acutis-collector.env
# add e.g.  BACKEND_CA_CERT=/etc/acutis/backend-ca.pem
sudo systemctl restart network-collector

Other tunables (optional)¶

Variable	Default	Purpose
`POLL_INTERVAL`	`60`	Seconds between poll cycles.
`GATEWAY_IP` / `SUBNET`	auto-detected	Override the auto-detected gateway/subnet if detection is wrong.
`MAX_CACHED_PAYLOADS`	`5000`	Cap on locally buffered telemetry during a backend outage (newest kept).
`OLLAMA_AGENT_ENABLED`	`auto`	Local AI field agent: `auto` (on iff a local model answers), `true`, or `false`.

Next: Onboarding devices.

Provisioning¶

provision.conf¶

Runtime environment (/etc/acutis-collector.env)¶