Configuration

Configuration

Axiom Border reads a single file, configuration.yaml, from the directory given by the AXIOM_CONFIG_DIR environment variable (default: config). An example file, configuration_example.yaml, is supplied alongside it — copy it rather than editing it in place, so you always keep an untouched reference.

cp config/configuration_example.yaml config/configuration.yaml

You will rarely edit the file by hand: the console’s Configuration view and the REST API write this same file — see Changing the configuration below.

sudo systemctl restart axiom-border

Changing the configuration

Three paths write the same file. The web console is the recommended one: it edits the settings a running deployment actually tunes, validates them before writing, and on a managed deployment restarts the service for you. The REST API covers automation and driving a probe without shell access. Editing the file over a shell always works — it is just the least guarded of the three.

​

Web console REST API

Open Configuration in the side menu. The view edits configuration.yaml itself, one group of settings per tab:

Each field is labelled in plain language rather than by its YAML key — nmap: period for schedule, vulnScan: depth for level — and the reference further down this page maps them to the keys they write. The two notices at the top are permanent, not the result of saving: they are there to tell you before you edit that nothing applies until the service restarts, and that the file holds credentials which are preserved for you.

Tab	What it edits
Automatic scans	The securityProbes switches and intervals: enable and schedule for nmap, vulnScan and snmp; the vulnerability scan’s level, severity and OT switches; the interfaces and flushInterval of sniffing
OpenGate	The whole opengate block — connection, collect and provision
MQTT	The whole mqtt block — the embedded broker with its WebSocket and TLS listeners, the internal publisher and the operations client

Everything else — logger, login, influxdb, apiPort, pagination and the per-probe details not listed above, scan targets included — is changed through the API or the file.

Network status has a shortcut straight here: its Automatic scans action opens this view on the first tab, which is where you land when a scheduled scan looks stale or too frequent.

The forms are a window onto the file, not a copy of it. Saving rewrites the whole file but preserves everything the forms do not manage: comments, credentials, and every key outside the three tabs. Leaving a field blank removes its key from the file, returning that setting to its unset behaviour. Durations, ports and cron expressions are checked as you edit, and Save stays disabled while any field holds an invalid value — an invalid document never reaches the probe.

What happens after Save depends on the deployment:

• On a managed deployment, the console asks the deployment manager (Keystone) to restart the service and waits until it reports healthy again — when the green confirmation appears, the change is already live. The console is unresponsive for the few seconds the restart takes.
• On a plain systemd installation, the file is written and an amber banner stays on screen until you restart the service yourself: sudo systemctl restart axiom-border.
• If the automatic restart fails, the write has still succeeded. Restart by hand — keystonectl restart axiom-border, or sudo systemctl restart axiom-border — and the saved configuration applies.

Changing apiPort or the login credential raises an explicit lockout warning: the file is written anyway, so before restarting make sure you can reach the new port or know the new password.

GET /config returns the current YAML and PUT /config replaces it. This exists so a probe can be configured for a customer environment without shell access to the host.

# 1. Authenticate
curl -X POST http://localhost:8083/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"<user>","password":"<your-password>"}'

# 2. Download the current file as a starting template (authenticated — it contains secrets)
curl -H "Authorization: Bearer <jwt-token>" \
  http://localhost:8083/config -o configuration.yaml

# 3. Edit it, then upload the COMPLETE file
curl -X PUT http://localhost:8083/config \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/x-yaml" \
  --data-binary @configuration.yaml

# 4. Apply
sudo systemctl restart axiom-border

The PUT response reports what happened:

{
  "restartRequired": true,
  "message": "configuration written; restart axiom-border to apply",
  "backup": "/opt/axiom-border/config/configuration.yaml.bak",
  "warnings": ["apiPort changes 8083 -> 9083 (may affect API access after restart)"]
}

Field	Meaning
restartRequired	Always true — configuration only takes effect at startup
message	Confirmation text
backup	Path of the previous file’s backup. Omitted when there was no previous file
warnings	Present only when non-empty. Raised when apiPort or the login credentials change, because either can lock you out

Console and API end in the same validated write, with three guarantees:

• Validation before writing. The document is validated exactly as at startup and checked for the six mandatory fields. Invalid YAML or a missing field returns HTTP 400 and nothing is written.
• Atomic replacement. The file is written to a temporary file in the same directory and renamed.
• Backup of the previous file, forced to 0600 because it contains secrets.

Where the file lives

Overriding any field with an environment variable

Every key can be overridden from the environment by upper-casing it and replacing dots with underscores. A .env file in the working directory is also loaded.

This is the recommended way to handle secrets: keep the tokens and passwords out of the YAML file entirely and inject them through the environment or your secret manager.

Required fields

Only six fields are validated as mandatory. If any is missing, the configuration is rejected:

login.user · login.pass · influxdb.url · influxdb.token · influxdb.org · apiPort

Everything else is optional and has a documented default.

logger

Backend logging, to console and to size-rotated files.

login

The single credential that protects the whole API except /auth/login.

Generate the digest before writing it:

echo -n "yourPassword" | sha256sum

At login, the probe hashes the submitted password and compares it against this value.

influxdb

Connection to the metrics database (InfluxDB 2.x) that stores metrics, audit records, scan results and alarms.

Default bucket set: network_bucket, ssh_bucket, metrics_bucket, usb_bucket, eg_alarms, audit_logs, networktraffic, availability, scanmetrics. The four per-channel event buckets are populated by the oda-lite collector, the rest by the probe itself — see Metrics ingestion.

The probe starts even when the metrics database is unreachable, and every feature that depends on it is inoperative until it recovers. This is deliberate for edge deployments where the database may be a separate node that boots later.

alerts and audit

Top-level keys

pagination

Controls the two read modes over the metrics database. Every field has a default, so the block can be omitted entirely.

trainerDetails

HTTP client settings for the AI container. Only relevant on Linux with a container engine available — see AI capabilities.

Three sub-blocks — metrics, healthCheck and predict — share the same four fields. The {port} literal in each URL is substituted at runtime with the port of the corresponding AI agent.

securityProbes

Security probes run two ways: automatically on an interval (schedule), and manually from the API or UI. Results are stored in local state and in the metrics database — scanmetrics for aggregates, availability for up/down.

securityProbes.nmap

Host discovery, port scanning and optional fingerprinting. Requires the nmap binary on PATH.

securityProbes.vulnScan

Template-based vulnerability scanning, including the embedded OT/ICS suite. The scan engine ships inside the product — there is no scanner binary to install.

level to tag mapping:

Templates directory resolution order: the templatesDir field of the scan request, then securityProbes.vulnScan.templatesDir, then defaultTemplatesDir, then a vulnscan-templates directory next to the product binary. Relative paths resolve against the working directory.

allowTemplateUpdates behaviour:

• true (default, including when the key is absent): best-effort refresh to the latest template release. Being offline or having GitHub blocked does not abort the scan — local templates are kept. An empty directory triggers a full download.
• false: strict offline kill-switch. The network is never touched, even when the directory is empty. If nothing is on disk the scan fails with a clear error.

allowIntrusive governs the write/control layer of the OT suite over both REST and MQTT. A request asking for intrusive mode while this is false is rejected, and the execution ends as failed with an explicit message. The scheduled probe is never intrusive regardless of this flag.

enableOT adds the read-only ot tag to the scheduled sweep even when level would not include it. It never enables the intrusive layer. Some older PLCs are fragile in the face of unexpected connections; enable it only if the OT network tolerates periodic probing.

Recommended steady state for a probe on an industrial segment:

securityProbes:
  vulnScan:
    enabled: true
    level: "medio"
    enableOT: true            # continuous read-only OT visibility
    allowIntrusive: false     # write layer bolted shut
    allowTemplateUpdates: false   # air-gapped: never reach for the network
    defaultTemplatesDir: "/opt/axiom-border/vulnscan-templates"

securityProbes.snmp

With neither oids nor walkRoot set there is nothing for the probe to do.

securityProbes.sniffing

Continuous traffic capture with periodic persistence to the networktraffic bucket.

Interface naming is platform-specific and is the most common source of a probe that captures nothing:

On Windows, the friendly name (Ethernet, Wi-Fi) does not work. Discover the NPF path with nmap --iflist and read the WINDEVICE column.

opengate

Optional cloud integration: inventory reporting (collect) and provisioning (provision). The whole section is inert when enabled: false.

opengate.collect

opengate.provision

mqtt

Three independent blocks: broker is the MQTT broker embedded in the product, client is the internal publisher of executions and alarms, and ops is the client that listens for OpenGate operations and answers them.

mqtt.broker

mqtt.client

Auto-reconnect is always on, retrying every 5 seconds, with a 10 second initial connection timeout. Neither is configurable.

mqtt.ops

If broker, topicSubscribe or topicPublish is empty, the operations module does not start.