Ctrlk
BlogSupport
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Network configuration

Configure the on-appliance network stack: physical interfaces, Docker internal subnet, outbound proxy, NTP servers, SSL serving certificate, trusted CA bundle. All six endpoints carry a 1/sec/IP rate limit and several are ⚠️ Operationally Dangerous (see per-operation descriptions).

Configure (or disable) a physical network interface

post

Configure a physical NIC on the broker:

  • interface_type='' — disable the interface.

  • interface_type='dhcp' — enable DHCP.

  • interface_type='static' — enable static configuration (additionally requires address and netmask; gateway optional).

⚠️ Operationally Dangerous. A bad configuration can render the VM unreachable. Console-recovery is required to undo a misconfiguration.

Authorizations
AuthorizationstringRequired

Short-lived (10-minute TTL) opaque API token issued by generateToken. Sent as Authorization: Bearer <token>. A token that expires mid-request does NOT abort the response (DRF authenticates once at request start).

Body

When interface_type='static', both address and netmask must additionally be non-empty (enforced by Pydantic's _static_requires_address model validator).

interface_typestring · enumRequired

'' disables the interface. 'dhcp' enables DHCP. 'static' requires address and netmask.

Possible values:
namestring · min: 1 · max: 64Required

Interface name (e.g., eth0, eth1).

addressstringOptional

IPv4 address. Required when interface_type='static'.

Default: ""
netmaskstringOptional

IPv4 netmask. Required when interface_type='static'.

Default: ""
gatewaystringOptional

Default gateway. Optional; at most one gateway is allowed across all interfaces.

Default: ""
dnsstring[] · max: 8Optional

DNS servers (up to 8 entries).

Default: []
is_adminbooleanOptional

Whether this interface serves the broker's admin UI.

Default: false
Responses
200

Operation succeeded; response carries the empty envelope.

application/json

Canonical envelope for every successful (2xx) JSON response. Wraps the per-endpoint payload (or null when the operation carries no body content).

replyany · nullableOptional

Endpoint-specific payload. Schema varies; see each operation's 200.content.schema.

post/public_api/v1/network/interface
POST /public_api/v1/network/interface HTTP/1.1
Host: broker.example.local
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 56

{
  "interface_type": "dhcp",
  "name": "eth1",
  "is_admin": false
}
{
  "reply": null
}

Set the Docker internal subnet

post

Replace the parent address pool used by Docker's per-network allocator on the broker. Docker's allocator carves slices of width parent_prefix + DOCKER_SUBNET_ADDITIONAL_BITS (currently +2) from this pool — a /18 parent therefore yields /20 per-network bridges. To leave room for more than one per-network bridge, supply a parent prefix of /22 or wider.

⚠️ Operationally Dangerous. The Docker daemon is restarted, which restarts every container on the bridge network. Expect 30-60 seconds of broker-wide unavailability — including this PAPI itself, which will return 502/connection-refused during the window. Treat as fire-and-poll.

A subnet that overlaps an existing physical interface is rejected with 409.

Authorizations
AuthorizationstringRequired

Short-lived (10-minute TTL) opaque API token issued by generateToken. Sent as Authorization: Bearer <token>. A token that expires mid-request does NOT abort the response (DRF authenticates once at request start).

Body

Body for setInternalSubnet. The docker_subnet is the parent address pool, not a single bridge subnet — see the endpoint description for pool semantics.

docker_subnetstring · min: 1 · max: 64Required

Parent address pool CIDR. Per-network bridges are carved from this pool at parent_prefix + 2 width (e.g., a /18 yields /20 bridges).

Example: 172.20.0.0/18
Responses
200

Operation succeeded; response carries the empty envelope.

application/json

Canonical envelope for every successful (2xx) JSON response. Wraps the per-endpoint payload (or null when the operation carries no body content).

replyany · nullableOptional

Endpoint-specific payload. Schema varies; see each operation's 200.content.schema.

post/public_api/v1/network/internal_subnet
POST /public_api/v1/network/internal_subnet HTTP/1.1
Host: broker.example.local
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "docker_subnet": "172.20.0.0/18"
}
{
  "reply": null
}

Configure the outbound HTTP/SOCKS proxy

post

Configure the outbound proxy used by all broker services for upstream connectivity.

  • proxy_type='' disables the proxy.

  • When proxy_type is set, host and port are required.

  • pwd follows tristate semantics:

    • omitted / null — keep the existing stored password.

    • "" — clear the password.

    • "value" — set the password to value.

Side effect: triggers restart_services_and_applets() — services handling the in-flight API request are deliberately excluded so the response can return cleanly.

Authorizations
AuthorizationstringRequired

Short-lived (10-minute TTL) opaque API token issued by generateToken. Sent as Authorization: Bearer <token>. A token that expires mid-request does NOT abort the response (DRF authenticates once at request start).

Body

pwd follows tristate semantics — omit (null) to preserve the stored password, set to "" to clear it, set to a value to replace it. When proxy_type is non-empty, both host and port are required (cross-field rule, enforced server-side).

proxy_typestring · enumRequiredPossible values:
hoststringOptionalDefault: ""
portinteger · min: 1 · max: 65535 · nullableOptional
userstringOptionalDefault: ""
pwdstring · password · nullableOptional

Tristate: null/absent = keep existing, "" = clear, "value" = set.

Responses
200

Operation succeeded; response carries the empty envelope.

application/json

Canonical envelope for every successful (2xx) JSON response. Wraps the per-endpoint payload (or null when the operation carries no body content).

replyany · nullableOptional

Endpoint-specific payload. Schema varies; see each operation's 200.content.schema.

post/public_api/v1/network/proxy
POST /public_api/v1/network/proxy HTTP/1.1
Host: broker.example.local
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "proxy_type": "http",
  "host": "proxy.example.com",
  "port": 3128,
  "user": "broker-svc",
  "pwd": "<password>"
}
{
  "reply": null
}

Replace the configured NTP servers

post

Replace the broker's NTP server list. At least one entry is required, at most MAX_NTP_SERVERS (10).

Reachability is NOT pre-validated. Servers that are unreachable from the broker are silently accepted (parity with the WebUI). The broker reports NTP-sync failures through normal monitoring channels.

Authorizations
AuthorizationstringRequired

Short-lived (10-minute TTL) opaque API token issued by generateToken. Sent as Authorization: Bearer <token>. A token that expires mid-request does NOT abort the response (DRF authenticates once at request start).

Body

Body for setNtp. Replaces the broker's NTP server list (between 1 and 10 entries).

ntpstring[] · min: 1 · max: 10Required

Hostname or IP of an NTP server.

Responses
200

Operation succeeded; response carries the empty envelope.

application/json

Canonical envelope for every successful (2xx) JSON response. Wraps the per-endpoint payload (or null when the operation carries no body content).

replyany · nullableOptional

Endpoint-specific payload. Schema varies; see each operation's 200.content.schema.

post/public_api/v1/network/ntp
POST /public_api/v1/network/ntp HTTP/1.1
Host: broker.example.local
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 46

{
  "ntp": [
    "time.cloudflare.com",
    "pool.ntp.org"
  ]
}
{
  "reply": null
}

Install a custom SSL serving certificate

post

Install a custom private key + certificate-chain pair as the broker's HTTPS serving identity (replacing the self-signed default that ships with a fresh broker).

Both ssl_key and ssl_cert are base64-encoded PEM payloads. Each is capped at MAX_BASE64_CERT_BYTES (~1.4 MiB encoded) to bound the body size.

⚠️ Operationally Dangerous. The nginx serving cert is replaced; a malformed PEM may break HTTPS access (in-flight sessions remain valid; the next handshake uses the new cert).

Authorizations
AuthorizationstringRequired

Short-lived (10-minute TTL) opaque API token issued by generateToken. Sent as Authorization: Bearer <token>. A token that expires mid-request does NOT abort the response (DRF authenticates once at request start).

Body

Body for setSslCertificate. The ssl_key and ssl_cert are base64-encoded PEM payloads, each capped at ~1.4 MiB encoded.

ssl_keystring · password · min: 1 · max: 1500000Required

Base64-encoded PEM private key (capped at ~1.4 MiB encoded).

ssl_certstring · min: 1 · max: 1500000Required

Base64-encoded PEM certificate chain (capped at ~1.4 MiB encoded).

ssl_key_namestring · max: 128Optional

Optional display name for the certificate (max 128 chars).

Default: ""
Responses
200

Operation succeeded; response carries the empty envelope.

application/json

Canonical envelope for every successful (2xx) JSON response. Wraps the per-endpoint payload (or null when the operation carries no body content).

replyany · nullableOptional

Endpoint-specific payload. Schema varies; see each operation's 200.content.schema.

post/public_api/v1/network/ssl_certificate
POST /public_api/v1/network/ssl_certificate HTTP/1.1
Host: broker.example.local
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 142

{
  "ssl_key": "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0t...",
  "ssl_cert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...",
  "ssl_key_name": "custom-broker-2026"
}
{
  "reply": null
}

Install a custom trusted CA bundle

post

Install a custom trusted-CA bundle on the broker so it trusts certificates issued by an internal / private CA when reaching out to upstream HTTPS services (proxies, SAML IdPs, syslog secure_TCP targets, etc.).

file is a base64-encoded PEM CA bundle, capped at MAX_BASE64_CA_BYTES (~1.4 MiB encoded).

Returns 500 (not 200) when update-ca-certificates fails on the appliance.

Authorizations
AuthorizationstringRequired

Short-lived (10-minute TTL) opaque API token issued by generateToken. Sent as Authorization: Bearer <token>. A token that expires mid-request does NOT abort the response (DRF authenticates once at request start).

Body

Body for setTrustedCa. The file is a base64-encoded PEM CA bundle, capped at ~1.4 MiB encoded.

filestring · min: 1 · max: 1500000Required

Base64-encoded PEM CA bundle (capped at ~1.4 MiB encoded).

Responses
200

Operation succeeded; response carries the empty envelope.

application/json

Canonical envelope for every successful (2xx) JSON response. Wraps the per-endpoint payload (or null when the operation carries no body content).

replyany · nullableOptional

Endpoint-specific payload. Schema varies; see each operation's 200.content.schema.

post/public_api/v1/network/trusted_ca
POST /public_api/v1/network/trusted_ca HTTP/1.1
Host: broker.example.local
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 50

{
  "file": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
}
{
  "reply": null
}
PreviousRegistration
NextLocal log bundle

Last updated

Was this helpful?