Skip to content
NextPKI Developers

Install the sensor

Installation has two steps: exchange a bootstrap token for an mTLS identity, then run. The token is single-use and short-lived - it is a claim check, not a credential you keep.

1. Create a bootstrap token

Section titled “1. Create a bootstrap token”

In the Console, go to Settings → Bootstrap tokens and create one. You can pin it to a machine ID so it can only be redeemed by the host you intend, and set a TTL (default 24 hours, maximum 7 days).

2. Register

Section titled “2. Register”
Terminal window
nextpki-sensor bootstrap \
  --token "$NEXTPKI_BOOTSTRAP_TOKEN" \
  --endpoint bootstrap.eu.nextpki.com:9090 \
  --machine-id "$(hostname)"

The sensor generates a key pair locally, sends a CSR, and receives a client certificate. Nothing secret travels upward - the private key is created on the host and never leaves it.

Afterwards the data directory holds:

File Mode Contents
identity.json 0644 Sensor ID, tenant, machine ID
cert.pem 0644 mTLS client certificate
key.pem 0600 Private key - never transmitted
ca.pem 0644 CA bundle used to verify NextPKI

Default location is $XDG_DATA_HOME/nextpki-sensor on Linux and macOS, and %APPDATA%\nextpki-sensor on Windows. Override with --data-dir.

The token is consumed at this point. Redeeming it a second time fails.

3. Run

Section titled “3. Run”
Terminal window
nextpki-sensor run \
  --targets 10.0.0.0/24,mail.example.com:993 \
  --exclude 10.0.0.1 \
  --scan-profile conservative \
  --scan-interval-secs 3600

Every flag has an environment variable equivalent (NEXTPKI_TARGETS, NEXTPKI_EXCLUDE, NEXTPKI_SCAN_PROFILE, …), which is usually what you want in a service unit. Run nextpki-sensor --help for the full list.

4. Confirm it arrived

Section titled “4. Confirm it arrived”

The sensor appears in the Console under Sensors, moving from pending to active once its first report lands. A sensor that stays pending did not manage to reach the ingest endpoint - check network requirements.

A local health endpoint is available for your own monitoring, on 127.0.0.1:18080/healthz by default.

Building from source

Section titled “Building from source”

Building it yourself is explicitly permitted - see licensing. Clone the repository and build with a Rust toolchain (1.80 or newer):

Terminal window
cargo build --release

No code generation step and no protobuf compiler are needed - the generated bindings are committed, and the .proto sources sit beside them so you can check them against each other.