System Service

VeilNet CLI guide

This guide uses veilnet-conflux as the CLI binary name in all examples. Download the latest release from GitHub Releases. 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 simple labels (e.g. dev, prod, us-east). You cannot use = in a taint. 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