# Constellation Fleet Agent

The **Constellation Fleet Agent** is a one-command installer plus a small CLI
that accepts telemetry from applications on a
local Unix socket and forwards it to Constellation through a collector-owned
queue. Publishing applications do not receive the API credential; the Fleet
Agent stores it and authenticates delivery on their behalf.

```text
application ──line protocol──▶ Unix socket ──▶ agent buffer ──▶ Constellation
```

The installed agent uses pinned stock Telegraf for collection and buffering,
with a Constellation gRPC egress component enabled by default. An optional
HTTP path can be selected when Telegraf-owned remote retry semantics are
preferable to gRPC's smaller typed payload.

To try it without a Linux host, see [Local development](#local-development):
stock Telegraf against the repository's local test server, with no connection
to the production API. A production install needs a token, root access and
outbound network access.

## Install

**Prerequisites:** a 64-bit (amd64/arm64) Linux host with systemd, root
access, outbound network access to Constellation, and `curl`. The installer also expects `gpg` (only when it needs to
install Telegraf itself — see below), `awk`, `getent`, `groupadd`, and
`usermod`, all standard on Debian/Ubuntu and RHEL/Fedora/Amazon Linux
family distributions; it checks for all of these upfront and fails before
touching the network if any are missing. You'll also need a
`CONSTELLATION_API_TOKEN` — obtain one from your Constellation account team or
console before starting.

```bash
# Export the token in your shell first (not on a command line). `sudo env
# VAR=...` would put it in `ps` and the auth log; --preserve-env passes it by
# name only.
curl -fsSL https://install.constellation.space/agent | \
  sudo --preserve-env=CONSTELLATION_API_TOKEN sh

sudo constellation-agent status
sudo constellation-agent verify --ground-station-id gs-sea-1 \
  --ground-antenna-id gs-sea-1-ant-1 --satellite-id sat-9
```

The installer:

- pins and verifies Telegraf and any required egress component;
- stores the API credential in a root-only environment file;
- creates a disk-backed queue and restricted Unix socket;
- installs and starts the systemd-managed collector;
- validates and verifies the generated configuration before reporting ready.

Re-running the same command later re-applies configuration and is safe to use
as the upgrade path.

### If Telegraf is already on the host

Installing here replaces the host's `telegraf.service` ExecStart with
Constellation's config, which silently stops any inputs/outputs that Telegraf
was already running for other purposes. The installer refuses to do this
automatically: if it finds a Telegraf it didn't install itself, or one whose
version doesn't match the pin, it fails with instructions rather than take
over silently. Set `CONSTELLATION_ALLOW_TELEGRAF_TAKEOVER=1` to adopt an
existing installation, or `CONSTELLATION_ALLOW_TELEGRAF_VERSION_MISMATCH=1` to
proceed against an unverified version. `--uninstall` restores a pre-existing
Telegraf's prior configuration; it only leaves Telegraf stopped if this
installer provisioned it in the first place.

### Air-gapped or private hosts

A fully offline install needs every artifact supplied locally; copying only
the Telegraf package fails partway through:

| Variable | Required for |
|---|---|
| `CONSTELLATION_TELEGRAF_PACKAGE` | the Telegraf `.deb`/`.rpm`, if Telegraf isn't already installed |
| `CONSTELLATION_TELEGRAF_SIGNATURE` | the matching InfluxData `.asc` signature — required alongside the package above |
| `CONSTELLATION_INFLUXDATA_KEY` | the InfluxData signing key, otherwise fetched from `repos.influxdata.com` |
| `CONSTELLATION_CLI_PACKAGE` | the `constellation-agent` CLI binary, otherwise fetched from the release bucket |
| `CONSTELLATION_GRPC_PACKAGE` | the gRPC shim binary, needed by default unless `CONSTELLATION_EGRESS=http` |

Each still has its checksum verified the same way a network fetch would.

### Grant an application access

The socket is writable by members of the `constellation` group. On a fresh
host, create a dedicated publishing account and add it to the group. This
guide uses `constellation-publisher`:

```bash
id constellation-publisher >/dev/null 2>&1 || \
  sudo useradd --system --no-create-home --shell /usr/sbin/nologin constellation-publisher
sudo usermod -aG constellation constellation-publisher
id -nG constellation-publisher | tr ' ' '\n' | grep -x constellation
```

Group membership permits telemetry writes; it does not expose the API token.

## Send telemetry

Each record is one ground antenna tracking one satellite: the
`ground_station_id`, `ground_antenna_id` and `satellite_id` from your
**network config**, plus fields from the platform's closed v2 list. Station
positions and satellite TLEs are not telemetry; they live in the network
config. The platform writes the records whose ids are in the network config and
reports the rest; a field off the list is dropped from its record and reported.

For a validated smoke test or occasional shell automation, use the installed
command:

```bash
constellation-agent emit \
  --ground-station-id gs-sea-1 \
  --ground-antenna-id gs-sea-1-ant-1 \
  --satellite-id sat-9 \
  --field elevation_deg=22.8 \
  --field c_n0_dbhz=71.4 \
  --field carrier_locked=true
```

Use `--print` or `--dry-run` to validate and display the encoded line without
connecting. JSON is also accepted on standard input:

```bash
printf '%s\n' '{
  "ground_station_id": "gs-sea-1",
  "ground_antenna_id": "gs-sea-1-ant-1",
  "satellite_id": "sat-9",
  "fields": {"elevation_deg": 22.8, "c_n0_dbhz": 71.4, "carrier_locked": true}
}' | constellation-agent emit --json
```

`emit` is a one-shot development interface. Applications that
publish continuously should connect directly and reuse the socket.

CLI field values use line-protocol scalar syntax: `2i` is an integer, `2` is a
float, `true` is a Boolean, and ordinary text is a string. Quote a
numeric-looking string explicitly, for example `--field 'uplink_status="001"'`.

Discover the socket from the installed environment file and write one
newline-terminated Influx line-protocol record:

```bash
. /etc/constellation/socket.env
printf 'link,ground_station_id=gs-sea-1,ground_antenna_id=gs-sea-1-ant-1,satellite_id=sat-9 elevation_deg=22.8,carrier_locked=true %s\n' \
  "$(date +%s%N)" | socat - "UNIX-CONNECT:$CONSTELLATION_SOCKET_PATH"
```

Every record needs:

- a measurement name (the platform ignores it; use `link`);
- the `ground_station_id`, `ground_antenna_id` and `satellite_id` tags, and
  optionally `radio_id` and `contact_id`;
- at least one field from the v2 list;
- optionally, an observation timestamp in Unix nanoseconds.

> The agent drops a line missing an id tag before sending it. The platform
> writes the rest of a batch around a record with an unknown id or a wrongly
> typed field, and reports each one: the agent logs them on gRPC egress, and on
> HTTP egress they are in the response.

The field list, escaping, type, framing, timestamp, and failure contract is in
[the socket interface](../../contracts/telemetry/socket-interface.md). Follow it when values are not
constants; malformed lines can be discarded after the application write has
already succeeded.

### Application example

This example uses only the Python standard library and discovers the socket
path the same way the shell example above does, rather than hardcoding it, so
it keeps working if `CONSTELLATION_SOCKET_PATH` is ever non-default. Long-running
publishers should keep the connection open rather than reconnecting for every
sample.

```python
import socket
import time

def read_socket_path(env_file="/etc/constellation/socket.env"):
    with open(env_file) as f:
        for line in f:
            key, _, value = line.strip().partition("=")
            if key == "CONSTELLATION_SOCKET_PATH":
                return value
    raise RuntimeError(f"CONSTELLATION_SOCKET_PATH not found in {env_file}")

socket_path = read_socket_path()

with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as client:
    client.connect(socket_path)
    while True:
        line = (
            "link,ground_station_id=gs-sea-1,ground_antenna_id=gs-sea-1-ant-1,satellite_id=sat-9 "
            f"elevation_deg=22.8,c_n0_dbhz=71.4,carrier_locked=true {time.time_ns()}\n"
        )
        client.sendall(line.encode("utf-8"))
        time.sleep(10)
```

The example uses constant identifiers. Applications interpolating arbitrary
strings must implement the escaping and validation rules in the socket
contract.

## Delivery semantics

A completed socket write proves only that the local kernel accepted the bytes
while the agent socket was present. It does not prove that the agent parsed the
record, committed it to its queue, delivered it remotely, or made it visible in
topology.

The agent owns remote authentication, batching, and outage buffering. The
application should not retry a completed write merely because it cannot
observe remote delivery; doing so can create duplicates. Use the end-to-end
verification and agent logs instead:

```bash
sudo constellation-agent verify --ground-station-id gs-sea-1 \
  --ground-antenna-id gs-sea-1-ant-1 --satellite-id sat-9
sudo constellation-agent logs
sudo constellation-agent logs -f
```

`verify` writes one real record for that link through the socket
(`contact_id=verify-<nonce>`, `track_mode="constellation-agent-verify"`) and
reads it back from `GET /v2/topology`. Those values show as the link's newest
until real telemetry replaces them.

The installed default flush interval is one second, configurable with
`CONSTELLATION_FLUSH_INTERVAL`. LP encoding and the local socket are not the
material latency cost; waiting for the next flush, network transit, storage,
and topology projection dominate.

## Operations

```bash
sudo constellation-agent status       # service state
sudo constellation-agent verify ...   # socket-to-topology proof (needs the three ids)
sudo constellation-agent test         # config test using a scratch socket
sudo constellation-agent logs 200     # recent logs
sudo constellation-agent logs -f      # follow logs
sudo constellation-agent debug on     # mirror LP records into the journal
sudo constellation-agent debug off
```

`verify`, `test`, and `debug` require root because they read protected agent
configuration or alter the systemd service. Direct application publishing does
not require root after group access is granted.

To remove the agent, re-run the installer script with `--uninstall` (add
`--purge` to also delete buffered-but-undelivered telemetry):

```bash
curl -fsSL https://install.constellation.space/agent -o agent-install.sh
sudo sh agent-install.sh --uninstall        # or: --uninstall --purge
```

If this installer provisioned Telegraf itself, uninstall leaves it stopped and
disabled. If Telegraf predated this installer on the host, uninstall restores
its prior configuration and restarts it — see
[If Telegraf is already on the host](#if-telegraf-is-already-on-the-host).

To opt into HTTP egress during installation:

```bash
export CONSTELLATION_EGRESS=http
curl -fsSL https://install.constellation.space/agent | \
  sudo --preserve-env=CONSTELLATION_API_TOKEN,CONSTELLATION_EGRESS sh
```

The default gRPC `outputs.execd` path retries transient RPC failures in the
egress process with exponential backoff while holding the batch and blocking
further reads from Telegraf; each wait is jittered between half and all of the
current backoff. A batch over the platform's record cap is split in halves and
resent. Permanent rejections, including a batch with no writable record, are
logged once and dropped; partial acceptance is logged with its first five
rejections and not retried because doing so would duplicate accepted records. The optional HTTP path keeps acknowledgement and retry inside
Telegraf's own output contract, at the cost of a larger payload than gRPC's
typed encoding.

## Limits and compatibility

| Setting | Default | Notes |
|---|---:|---|
| Flush interval | 1 second | configurable with `CONSTELLATION_FLUSH_INTERVAL` |
| Buffered records | 100,000 | approximately 12 MB; about 2 hours at 13 records/s |
| Disk-buffer rate | approximately 300 records/s | measured on NVMe; expect less on eMMC or SD |
| Memory-buffer rate | approximately 596,000 records/s | loses buffered records on process or host failure |

Set `CONSTELLATION_BUFFER_STRATEGY=memory` during installation only when
throughput matters more than restart durability.

Current platform compatibility caveats:

- integer fields widen to floats — `7i` reads back as `7.0`;
- the agent's own Telegraf health metrics are not sent: v2 has no record shape
  for them. Use `constellation-agent status` and `logs` on the host.

Booleans read back as JSON `true` and `false` on both egress paths, and string
fields come back under `fields`, as written.

Write the correct LP types despite the remaining read-path limitations so
producers do not need to change when the platform behavior is corrected.

## Public contracts

- [Socket write contract](../../contracts/telemetry/socket-interface.md) — the
  application-to-agent interface.
- [Native ingest proto](../../contracts/telemetry/ingest.proto) — the
  agent-to-platform gRPC contract.

There is no supported Python or TypeScript SDK; use an ordinary HTTP client
when a product needs the platform read APIs.

## Local development

The installed agent and CLI are static Go binaries; target machines do not
require a Python runtime. Develop against the real API, not a stand-in: from
the repository root, `make dev-up` serves it on `127.0.0.1:8080` with the key
`tok-local`, and `make bazel-test` runs the agent's tests.

## Egress internals

The agent is **stock Telegraf**: it owns the process, the socket, the disk
queue, retries and the systemd lifecycle. There is no bespoke daemon or spool.

- The HTTP config (written by [`install/agent-install.sh`](install/agent-install.sh)) — stock `outputs.http` to
  `POST /v2/telemetry`. Telegraf's JSON serializer emits
  `{name, timestamp, tags, fields}` and a `json_transformation` remaps it to the
  v2 record `{time, ground_station_id, ground_antenna_id, satellite_id,
  radio_id?, contact_id?, fields}`, leaving out any line without all three ids. No plugin or compiled
  artifact: the config file is the whole footprint. Needs Telegraf 1.26 or
  later; tested on 1.39.2.
- The gRPC config (also written by the installer) — `outputs.execd` streaming line
  protocol to the [`grpc_output`](grpc_output) child
  (`telegraf-constellation-grpc`), which translates it to
  `constellation.ingest.v2.TelemetryIngest/Write`. It drops a line without
  all three id tags, and logs the records the platform reports it did not
  write. The child inherits the token
  from Telegraf's environment, so the application still never holds a
  credential.

gRPC is the installer default (`CONSTELLATION_EGRESS=grpc`); its endpoint is
derived from `CONSTELLATION_API_URL`, or set `CONSTELLATION_ENDPOINT` (for
example `ingest.dev.api.constellation.space:443`). Set
`CONSTELLATION_EGRESS=http` for the HTTP path. The installer writes the chosen
block into `/etc/telegraf/telegraf.d/constellation.conf`.

Notes and limits:

- **Delivery latency.** A record reaches `GET /v2/topology` about
  `flush_interval/2 + 0.3s` after the socket write; ~0.3s is the transit and
  ingest floor. Measured on an AL2023 node against production, both egress
  paths land within noise of each other: 0.64s (gRPC) and 0.61s (HTTP) median
  at the `1s` default, ~0.3s at `CONSTELLATION_FLUSH_INTERVAL=200ms`. The gRPC
  child adds a second batching stage, so its ticker is held at 50ms
  (`CONSTELLATION_SHIM_FLUSH_INTERVAL`) rather than tracking `flush_interval`.
  gRPC's advantage over HTTP is payload size and a typed contract, not speed.
- Metric fields are flat scalars; nested structures are not representable.
- **Throughput ceiling.** `buffer_strategy = "disk"` fsyncs per metric:
  288-298 metrics/s on NVMe, and `metric_batch_size` does not move it. Memory
  buffering measured ~596,000/s on the same host. Budget ~300 metrics/s per
  node, expect materially less on eMMC or SD, and benchmark before provisioning
  a fast sensor.
- When the buffer fills, Telegraf overwrites the **oldest** metrics, so a
  sustained overrun loses the beginning of an outage rather than the end.
- Boolean fields cannot be aggregated in Flux: `mean` errors, `min`/`max`
  panic. Cast with `toFloat()` in alert rules.

## Releasing

Push the tag `agent-v<AGENT_VERSION>` (the version in `install/agent-install.sh`).
CodeBuild builds, signs `SHA256SUMS` with the release KMS key, and publishes to
the install site. The published installer is stamped at release with the
digests of that release's binaries, and is covered by the signed `SHA256SUMS`;
the checked-in `install/agent-install.sh` is a template and refuses to run.
Verify a release with the committed public key:

```bash
cosign verify-blob --key cosign.pub --bundle SHA256SUMS.sigstore.json SHA256SUMS
```

`cosign.pub` is committed in this directory once the signing key exists; fetch it from the repository.

## Repository layout

```text
install/     fleet-agent installer (also writes the Telegraf config)
cli/         the constellation-agent CLI
grpc_output/ Go source for the gRPC execd child
```

## License

Apache-2.0
