machine-telemetry/

Machine Telemetry Reference Package

This directory is the reproducible package source for the first AnixOps Control + Agent + WebUI reference package. It contains package metadata, configuration, and a dependency-free WebUI module. The Agent executable is an explicit build input and is never replaced with a placeholder.

Source Layout

packages/machine-telemetry/
|-- build.py
|-- verify_signature.py
|-- config.defaults.json
|-- config.schema.json
|-- manifest.template.json
|-- tests/release_gate.sh
|-- tests/test_build.py
|-- tests/test_verify_signature.py
|-- tests/webui_smoke.mjs
`-- webui/index.mjs

build.py creates one combined package archive. For a Linux AMD64 build the archive contains:

agent/linux-amd64/plugin
config.defaults.json
config.schema.json
package.json
webui/index.mjs

The generated signed-manifest input declares both control and agent targets and maps agent-linux-amd64 to agent/linux-amd64/plugin. Other GOOS/GOARCH pairs use the same naming rule.

Systemd Services Table

From 4.1 the package declares telemetry.systemd.read and serves the read-only per-node services table at GET /api/v3/plugins/machine-telemetry/nodes/:id/services (administrators; the node page's 服务 section). Collection is off on every node until enabled in the Agent installation's configuration:

{"systemd_services": {"nodes": {"12": {"enabled": true, "include": ["nginx*.service"], "exclude": []}}}}

The Agent collector reads its own node's entry with sdk/telemetry/systemdreport.ParseConfig. Details, the response and the privacy rules: docs/architecture/package-reports.md.

Privacy

The services report is opt-in per node (owner decision H24) and keeps only the latest value:

• Sent, per .service unit: the name, ActiveState, SubState, CPU averaged over 10 minutes and its peak, current memory and its peak; per report, whether the node supports collection and, if not, why.
• Never sent: Description, ExecStart or any other unit property, command line, environment, PID, path or log line. user@* and run-* units are left out, at most 512 units are sent, and names are at most 256 bytes. Control refuses a payload with Description or ExecStart and drops every unknown field.
• Kept: the latest report per node only, no history; stale after 25 minutes. Administrators read it in the panel; on PostgreSQL only this package's role can read kapi_package_report_v1.

Upgrade notes (the matching Agent, enabling it per node): docs/UPGRADE.md, "v4.2: The Systemd Services Panel".

Build

The input binary must be a non-empty regular executable file. The package builder does not compile or download it.

python3 packages/machine-telemetry/build.py build \
  --agent-binary /absolute/path/to/machine-telemetry-agent \
  --goos linux \
  --goarch amd64 \
  --output-dir /tmp/machine-telemetry-dist

The output directory contains:

• machine-telemetry-1.1.0.tar: deterministic combined package artifact;
• manifest.json: canonical manifest bytes to sign with the official Ed25519 release key;
• build-report.json: input and output digests without timestamps or host paths;
• SHA256SUMS.txt: SHA-256 checksums for every generated output except itself.

The tar writer fixes entry order, ownership, permissions, timestamps, and format. Identical source and Agent binary bytes therefore produce an identical artifact and manifest. Reproducibility of the input Agent binary remains the responsibility of its Go release build. The builder enforces the current 64 MiB Control/Agent artifact limit and 2 MiB WebUI bundle limit.

Verify

Verification checks the outer checksums, manifest-to-artifact binding, WebUI digest, architecture entrypoint, tar metadata, package file index, and every inner file digest.

python3 packages/machine-telemetry/build.py verify \
  --output-dir /tmp/machine-telemetry-dist

The builder runs the same verification automatically before reporting a successful build.

The release contract verifies an external Ed25519 signature without requiring a private key in the package source tree. The public key may be PEM or the raw Base64 value used by plugins.official_public_key:

python3 packages/machine-telemetry/verify_signature.py \
  --manifest /tmp/machine-telemetry-dist/manifest.json \
  --artifact /tmp/machine-telemetry-dist/machine-telemetry-1.1.0.tar \
  --signature /path/to/manifest.sig \
  --public-key /path/to/official-public-key.pem

Test

The tests use a temporary executable fixture only to exercise the packer. No fixture artifact is emitted into the source tree.

python3 -m unittest discover \
  -s packages/machine-telemetry/tests \
  -p 'test_*.py' \
  -v

python3 packages/machine-telemetry/build.py self-test

node packages/machine-telemetry/tests/webui_smoke.mjs

bash packages/machine-telemetry/tests/release_gate.sh

The test suite builds twice and compares every output byte, verifies archive metadata and digests, rejects a tampered artifact, rejects a non-executable Agent input, and enforces that webui/index.mjs has no static or dynamic imports. The Node smoke test executes the factory with the versioned host API, checks the namespace-constrained request, and renders a telemetry response without Vue or other installed dependencies.

Signing Boundary

This directory never stores a release private key or emits a signature. Sign the exact generated manifest.json bytes in the release pipeline, then submit the Base64 signature with the manifest and artifact through the Control package repository API.

tests/release_gate.sh is the CI contract: it builds twice, verifies the unsigned package, creates only a temporary test key, checks PEM and raw Base64 public-key verification, and rejects missing or tampered signatures. The temporary signing key is deleted before the script exits and is never uploaded.

The WebUI module does not embed its own SHA-256. Doing so would create an unsatisfiable self-hash. The signed manifest binds the bundle path and digest, and the Control and browser loaders verify those bytes before import.