connectors.yaml

Connector instances live in one file, read by the same strict YAML loader as the sensor registry and the site configuration. An unknown field, a duplicate instance name or a plaintext secret is a start error, not a warning.

Enable the framework

# in the service environment file, mode 0600, root-owned
NDR_CONNECTORS_ENABLED=true
NDR_CONNECTORS_PATH=/etc/ndr/connectors.yaml   # this is the default

With the flag unset, the file is not read at all. That is the default, and an existing installation keeps its behaviour until an operator switches it on.

The file

connectors:
  - id: unifi-network
    instance: unifi-home          # several instances of one connector are allowed
    tenant: example
    enabled: true
    config:
      url: https://controller.example.invalid:11443
      site: default
      tls_fingerprint_sha256: "<read from the controller itself>"
      poll_interval: 60s
    secrets:
      username: file:/etc/ndr/unifi-username
      password: file:/etc/ndr/unifi-password

Field	Meaning
id	Which connector. Must be one the core knows.
instance	Your name for this instance. Must be unique — a duplicate is a start error.
tenant	Which tenant the data belongs to. The connector cannot influence this.
enabled	false makes the instance inert. It keeps its cursor and deletes nothing.
config	Validated against the connector’s declared schema, field by field, with bounds.
secrets	References only. Never values.

Secret references

Two forms, and nothing else:

secrets:
  password: file:/etc/ndr/some-secret     # a regular file under /etc/ndr
  token: env:NDR_SOME_TOKEN               # from the mode-0600 service environment

A file: reference must be a regular file under /etc/ndr, non-empty, and unreadable by group and others. A symlink, a directory, a wrong mode or a world-readable file fails the start.

A literal secret in connectors.yaml is refused outright. The interface never displays a secret back, not even masked — it can only set one.

Several instances of the same connector

Two firewalls, two DNS filters, two controllers: allowed, and each runs independently with its own cursor, its own backoff and its own health line.

connectors:
  - id: unifi-network
    instance: unifi-home
    tenant: example
    enabled: true
    config: { url: https://controller.example.invalid:11443, site: default, poll_interval: 60s }
    secrets: { username: file:/etc/ndr/unifi-username, password: file:/etc/ndr/unifi-password }

  - id: unifi-network
    instance: unifi-lab
    tenant: example
    enabled: false
    config: { url: https://lab.example.invalid:11443, site: lab, poll_interval: 300s }
    secrets: { username: env:NDR_UNIFI_LAB_USERNAME, password: env:NDR_UNIFI_LAB_PASSWORD }

Validate before restarting

ndr connectors validate

This checks the file exactly the way startup would — same loader, same schema, same secret rules — and opens no network connection. Run it before restarting the service, every time. See the CLI.

Polling floors

Every poll interval has an enforced minimum, declared by the connector. Setting a value below the floor is a configuration error, not a value that gets quietly raised. The floors exist because polling costs the foreign system work, and a misconfigured interval is how a monitoring tool becomes the incident.