System Service

VeilNet CLI guide

This guide uses veilnet-conflux as the CLI binary name in all examples. The actual filename depends on the release asset you download—adjust the commands to match your executable name/path (e.g. ./veilnet-conflux).

Host requirements

On Linux hosts, the following packages are required for veilnet-conflux to work:

• ca-certificates
• iptables
• iproute2
• systemd-resolved

Install (Debian/Ubuntu)

sudo apt-get update
sudo apt-get install -y ca-certificates iptables iproute2 systemd-resolved

Install (RHEL/Fedora/CentOS)

sudo dnf install -y ca-certificates iptables iproute iproute-tc systemd-resolved

Register

Registers with Guardian using a registration token, saves config, and (by default) installs/starts the system service.

sudo veilnet-conflux register -t "$VEILNET_REGISTRATION_TOKEN"

Check service status

sudo veilnet-conflux status

Unregister / teardown

sudo veilnet-conflux unregister -t "$VEILNET_REGISTRATION_TOKEN"

Command overview

The CLI supports:

• Service lifecycle
  • run (default): run the Conflux process in the foreground
  • install: install system service (does not update registration data)
  • start: start system service
  • stop: stop system service
  • status: status of system service
  • remove: remove system service (does not update registration data)
• VeilNet actions
  • register: register a new Conflux with Guardian, save config, reinstall service (unless --debug)
  • unregister: unregister with Guardian, delete config, remove service (requires -t registration token)
  • info: query local Conflux runtime info (via local gRPC)
    • info conflux (default)
    • info realm
    • info veil
    • info tracer
  • taint add <taint> / taint remove <taint>: add/remove taints at runtime + persist to config

Global flags

• -v, --version: print version and exit

Configuration storage

The CLI reads/writes a single JSON config file named conflux.json:

• Linux: /root/.config/conflux/conflux.json
• macOS: /var/root/Library/Application Support/conflux/conflux.json
• Windows: %ProgramData%\conflux\conflux.json (default C:\ProgramData\conflux\conflux.json)

Notes:

• This path is selected by OS in anchor.GetConfigDir().
• Most workflows expect the service to run as root, so config lives under the root-owned location above.

register: register a Conflux (and install the service)

What it does

• Calls Guardian: POST <guardian>/conflux/register with Authorization: Bearer <registration-token>
• Receives a Conflux ID and Conflux token
• Builds and (unless --debug) saves conflux.json
• Installs/reinstalls the system service (unless --debug)
• In --debug mode: starts the embedded Anchor subprocess and runs until SIGINT/SIGTERM; does not save config or install the service

Flags / env vars

• Registration token
  • flag: -t <token>
  • env: VEILNET_REGISTRATION_TOKEN
• Mode
  • flag: -r / --rift (default false) — rift mode
  • env: VEILNET_CONFLUX_RIFT
  • flag: -p / --portal (default false) — portal mode
  • env: VEILNET_CONFLUX_PORTAL
• Guardian URL
  • flag: --guardian <url>
  • default: https://guardian.veilnet.app
  • env: VEILNET_GUARDIAN
• Identity / auth fields (optional; forwarded to Guardian during registration)
  • --tag <string> env VEILNET_CONFLUX_TAG
  • --jwt <string> env VEILNET_CONFLUX_JWT
  • --jwks-url <url> env VEILNET_CONFLUX_JWKS_URL
  • --audience <string> env VEILNET_CONFLUX_AUDIENCE
  • --issuer <string> env VEILNET_CONFLUX_ISSUER
• Runtime network fields (stored locally; used when starting Anchor)
  • --ip <string> env VEILNET_CONFLUX_IP
• Taints
  • --taints <value> (repeatable) env VEILNET_CONFLUX_TAINTS
  • In debug mode: after Anchor starts, the CLI will also call gRPC to apply taints live.
• Debug
  • -d / --debug env VEILNET_CONFLUX_DEBUG
• Tracing (OpenTelemetry/OTLP)
  • --tracer (default false) env VEILNET_TRACER
  • --otlp-endpoint <string> env VEILNET_OTLP_ENDPOINT
  • --otlp-use-tls (default false) env VEILNET_OTLP_USE_TLS
  • --otlp-insecure (default false) env VEILNET_OTLP_INSECURE
  • --otlp-ca-cert <path> env VEILNET_OTLP_CA_CERT
  • --otlp-client-cert <path> env VEILNET_OTLP_CLIENT_CERT
  • --otlp-client-key <path> env VEILNET_OTLP_CLIENT_KEY

Example

sudo VEILNET_REGISTRATION_TOKEN="..." \
  VEILNET_CONFLUX_IP="203.0.113.10" \
  veilnet-conflux register --tag "edge-1" --taints "prod" --taints "us-east"

info: inspect the running Conflux

These commands talk to the local Anchor gRPC server at 127.0.0.1:1993 (insecure). They require the Conflux/Anchor to be running locally (via system service or --debug mode).

• veilnet-conflux info conflux (default) — ID, Tag, UID, CIDR, Rift, Portal, Public
• veilnet-conflux info realm — Realm, Realm ID, Subnet
• veilnet-conflux info veil — Host, Port, Region
• veilnet-conflux info tracer — Enabled, Endpoint, Use TLS, Insecure, CA, Cert, Key

Example:

sudo veilnet-conflux info veil

taint: manage taints (live + persisted)

Taints are strings (e.g. key=value or a simple value like dev). The CLI:

1. Calls Anchor over gRPC to add/remove the taint.
2. Loads conflux.json, updates taints, and saves it back.

Examples:

sudo veilnet-conflux taint add prod
sudo veilnet-conflux taint remove prod

Service management (install/start/stop/status/remove/run)

run (default)

Running with no args behaves like run:

sudo veilnet-conflux
# same as:
sudo veilnet-conflux run

In service mode, this is what systemd uses as ExecStart (no args), so it boots into the foreground “run” behavior.

install

Installs and starts the service.

• Linux: writes /etc/systemd/system/veilnet.service, then runs:
  • systemctl daemon-reload
  • systemctl enable veilnet.service
  • systemctl start veilnet.service

It does not register or update config.

sudo veilnet-conflux install

start / stop / status / remove

Thin wrappers over system service management:

sudo veilnet-conflux start
sudo veilnet-conflux stop
sudo veilnet-conflux status
sudo veilnet-conflux remove