nginz-iot-bridge configuration

nginz-iot-bridge runs external clients outside nginx workers and the authoritative broker loop. It ships in every self-hosted tier with the public C SDK; it is not a standalone product.

Command line

nginz-iot-bridge --test-config --manifest /etc/nginz-iot/bridges.toml
nginz-iot-bridge --foreground --manifest /etc/nginz-iot/bridges.toml
nginz-iot-bridge --version

PostgreSQL sink

[process]
runtime_dir = "/run/nginz-iot/bridge/integration-postgres"
pid_file = "/run/nginz-iot/bridge/integration-postgres/bridge.pid"
state_file = "/run/nginz-iot/bridge/integration-postgres/bridge.state"
metrics_file = "/run/nginz-iot/bridge/integration-postgres/bridge.prom"
foreground = true

[node]
node_id = "edge-node-a"
generation = 1
writer_term = 1

[bridge]
bridge_id = "integration-postgres"
execution_lanes = 4
mock_sink = false
live_send = true
sink_kind = postgres
postgres_dsn = "host=postgres dbname=iot user=bridge sslmode=verify-full"
postgres_table = "citusio_telemetry"
postgres_provision_schema = false
store_provider = postgres
store_dsn = "host=postgres dbname=iot user=bridge_outbox sslmode=verify-full"

[rings]
namespace = "/nginz-iot-integration-edge"
iotd_admin_namespace = "/nginz-iot-integration-edge"
slot_size = 4096
input_capacity = 1024
admin_capacity = 16
iotd_admin_capacity = 64

Use least-privilege sink and outbox roles. Keep passwords out of the file and supply them through the provider’s supported secret mechanism.

Shared guardian and crash boundary

The packaged nginz-iot-bridge.service reads /etc/nginz-iot/bridges.toml. Its bounded manifest maps each target identity to /etc/nginz-iot/bridges/<bridge_id>.toml; the target identity must match bridge_id.

One stable guardian owns supervision only. It starts a separate worker for each bridge, and every worker has its own lifecycle files, bridge-qualified rings, connector pool, retry queue, adapter address space, health, and restart deadline. A native client or adapter crash therefore restarts only that worker, without putting the guardian to sleep or disturbing healthy workers. nginx and nginz-iotd remain running. Restart the guardian to apply manifest changes. Host exhaustion, shared providers, and hostile code are outside this process-isolation guarantee.

Other sinks and SDK adapters

Webhook and MQTT profiles add their bounded endpoint, TLS, authentication, timeout, and retry fields. Public SDK adapters use a canonical sdk_adapter_path, sdk_trusted_prefix, v2 entrypoint, bounded batch settings, timeout, and secret reference.

Every sink must define bounded concurrency, buffering, retry, and dead-letter behavior. Ring generation and writer term must match the producer.

See Public Bridge SDK for adapter vtable, trust prefix, and packaged reference libraries. Inspect sink health from the console Bridges page or the operator CLI (ngz-iot bridges).