5.3. named-manager.conf --- named program's manager configuration

5.3.1. Description

named-manager.conf enables Akira managed-mode configuration of named and specifies the Akira backend connection identity used by named. On startup, named looks for /etc/loop/named-manager.conf. If the file exists, named parses it and enters Akira managed-mode. In this mode, named.conf is not used for named's configuration. Instead, named obtains configuration from the Akira network management service over a manager WebSocket, or from the /var/lib/loop/named-managed.conf cache if the Akira service cannot be reached. If neither source can be used, named falls back to its built-in default configuration while continuing to retry connecting to the configured Akira service.

If /etc/loop/named-manager.conf does not exist, named reads named.conf(5) normally and does not connect to the Akira network management service.

5.3.2. Configuration grammar

The named-manager.conf file contains only the manager statement. Statements end with a semicolon. Comments use the same syntax as named.conf(8) comments.

5.3.2.1. manager statement

manager {
        server <quoted_string>;
        uuid <quoted_string>;
        realm <quoted_string>;
        key <quoted_string>;
        tls-ca-file <quoted_string>; // optional
};

The manager statement enables Akira managed-mode. In this mode, named treats the configured named.conf file as a bootstrap configuration file for establishing a connection to the Akira network management service. The operational DNS configuration is obtained from the Akira service over the manager WebSocket, or from a cached /var/lib/loop/named-managed.conf file if the Akira service cannot be reached. If neither configuration source is available, named falls back to its built-in default configuration while continuing to retry connecting to the configured Akira service.

The manager statement is only valid at the top level of named.conf, and may occur only once.

server

Specifies the base Akira network management service WebSocket URL. Its value must be an absolute ws:// or wss:// URL and must not include a query string or fragment. named appends the manager control endpoint (/ws) and a short-lived JWT token to the URL when it attempts to open the WebSocket connection.

ws:// connects directly over TCP. wss:// uses TLS and verifies the server certificate before the WebSocket upgrade is sent.

uuid

Specifies the UUID of this nameserver object in Akira. The value must be a canonical UUID string. named includes this UUID in its manager JWT and Akira uses it to find the nameserver object and its control secret.

realm

Specifies the UUID of the Akira realm that owns the nameserver object. The value must be a canonical UUID string. Akira verifies that the manager connection belongs to this realm before accepting the control WebSocket.

key

Specifies the shared manager-control HMAC secret for this nameserver. The value must be Base64 encoding of exactly 32 bytes. The same secret must be stored in Akira as the nameserver object's control HMAC secret. It is used to authenticate the manager JWT and to sign manager control-channel messages.

tls-ca-file

Optionally specifies a PEM CA bundle used to verify the Akira server certificate for wss:// manager connections. If omitted, named uses the platform's default certificate authorities. This option has no effect for ws:// connections.

Example:

manager {
        server "wss://akira.example.net/manager";
        uuid "11111111-2222-4333-8444-555555555555";
        realm "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee";
        key "YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE=";
};

When the manager connection is established, named performs a signed nonce handshake, asks the remote Akira network management service for its version, compares the received major version with its own major version, and then asks Akira for named configuration. Newer Akira configuration is written atomically to /var/lib/loop/named-managed.conf and then applied through the normal named.conf(5) configuration reload path. Akira may later request a forced reconfigure; such a remote control command fetches a fresh configuration and overwrites /var/lib/loop/named-managed.conf even when the timestamp is not newer.

5.3.3. Files

/etc/loop/named-manager.conf

The optional Akira manager bootstrap configuration file.

/var/lib/loop/named-managed.conf

The Akira-supplied operational configuration cache, stored in named's current directory while manager mode is active.

5.3.4. See also

named.conf(5), akira(8), named(8)