Controls

ControlsBlock pydantic-model

Bases: BindBaseModel

Controls block for BIND9 configuration.

Specifies control channels to be used to manage the name server via rndc.

NOTE: If no controls statement is present, BIND9 sets up default control channels on loopback addresses (127.0.0.1 and ::1) with port 953.

Grammar:

controls {
    inet ( <ipv4_address> | <ipv6_address> | * )
            [ port ( <integer> | * ) ]
            allow { <address_match_element>; ... }
            [ keys { <string>; ... } ]
            [ read-only <boolean> ];
};

Show JSON schema:

{
  "$defs": {
    "InetControl": {
      "description": "Inet control channel specification for BIND9.\n\nSpecifies a TCP socket as a control channel for rndc.\n\nNOTE: Unix control channel has been removed in BIND9.\n\nGrammar:\n```\ninet ( <ipv4_address> | <ipv6_address> | * )\n     [ port ( <integer> | * ) ]\n     allow { <address_match_element>; ... }\n     [ keys { <string>; ... } ]\n     [ read-only <boolean> ];\n```",
      "properties": {
        "comment": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional comment for this block",
          "title": "Comment"
        },
        "ip_address": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "format": "ipv4",
              "type": "string"
            },
            {
              "format": "ipv6",
              "type": "string"
            },
            {
              "enum": [
                "*",
                "::"
              ],
              "type": "string"
            }
          ],
          "description": "IP address to listen on. Can be:\n- IPv4 address (e.g., 127.0.0.1)\n- IPv6 address (e.g., ::1)\n- '*' for all IPv4 interfaces\n- '::' for all IPv6 interfaces",
          "title": "Ip Address"
        },
        "port": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "integer"
            }
          ],
          "default": 953,
          "description": "Port number or '*'. Default is 953.\nNOTE: '*' cannot be used for port in BIND9 controls.",
          "title": "Port"
        },
        "allow": {
          "description": "Address match list for IP-based access control.\nAny server_key elements in this list are ignored.",
          "items": {},
          "title": "Allow",
          "type": "array"
        },
        "keys": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "List of authorized server keys.\nEach listed key is authorized to execute commands over the control channel.",
          "title": "Keys"
        },
        "read_only": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "string"
            },
            {
              "type": "integer"
            },
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "If enabled (yes), limits to read-only commands:\nnta -dump, null, status, showzone, testgen, zonestatus.\nDefault is read-write access.",
          "title": "Read Only"
        }
      },
      "required": [
        "ip_address",
        "allow"
      ],
      "title": "InetControl",
      "type": "object"
    }
  },
  "description": "Controls block for BIND9 configuration.\n\nSpecifies control channels to be used to manage the name server via rndc.\n\nNOTE: If no controls statement is present, BIND9 sets up default control channels\non loopback addresses (127.0.0.1 and ::1) with port 953.\n\nGrammar:\n```\ncontrols {\n    inet ( <ipv4_address> | <ipv6_address> | * )\n            [ port ( <integer> | * ) ]\n            allow { <address_match_element>; ... }\n            [ keys { <string>; ... } ]\n            [ read-only <boolean> ];\n};\n```",
  "properties": {
    "comment": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional comment for this block",
      "title": "Comment"
    },
    "controls": {
      "description": "List of control channel specifications.\nEmpty list disables control channels.\nMultiple inet statements can be used.",
      "items": {
        "$ref": "#/$defs/InetControl"
      },
      "title": "Controls",
      "type": "array"
    }
  },
  "title": "ControlsBlock",
  "type": "object"
}

Fields:

• comment (string_BIND | None)
• controls (list[InetControl])

Validators:

• validate_controls_configuration → controls

controls pydantic-field

controls: list[InetControl]

List of control channel specifications. Empty list disables control channels. Multiple inet statements can be used.

InetControl pydantic-model

Bases: BindBaseModel

Inet control channel specification for BIND9.

Specifies a TCP socket as a control channel for rndc.

NOTE: Unix control channel has been removed in BIND9.

Grammar:

inet ( <ipv4_address> | <ipv6_address> | * )
     [ port ( <integer> | * ) ]
     allow { <address_match_element>; ... }
     [ keys { <string>; ... } ]
     [ read-only <boolean> ];

Show JSON schema:

{
  "description": "Inet control channel specification for BIND9.\n\nSpecifies a TCP socket as a control channel for rndc.\n\nNOTE: Unix control channel has been removed in BIND9.\n\nGrammar:\n```\ninet ( <ipv4_address> | <ipv6_address> | * )\n     [ port ( <integer> | * ) ]\n     allow { <address_match_element>; ... }\n     [ keys { <string>; ... } ]\n     [ read-only <boolean> ];\n```",
  "properties": {
    "comment": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional comment for this block",
      "title": "Comment"
    },
    "ip_address": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "format": "ipv4",
          "type": "string"
        },
        {
          "format": "ipv6",
          "type": "string"
        },
        {
          "enum": [
            "*",
            "::"
          ],
          "type": "string"
        }
      ],
      "description": "IP address to listen on. Can be:\n- IPv4 address (e.g., 127.0.0.1)\n- IPv6 address (e.g., ::1)\n- '*' for all IPv4 interfaces\n- '::' for all IPv6 interfaces",
      "title": "Ip Address"
    },
    "port": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        }
      ],
      "default": 953,
      "description": "Port number or '*'. Default is 953.\nNOTE: '*' cannot be used for port in BIND9 controls.",
      "title": "Port"
    },
    "allow": {
      "description": "Address match list for IP-based access control.\nAny server_key elements in this list are ignored.",
      "items": {},
      "title": "Allow",
      "type": "array"
    },
    "keys": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "List of authorized server keys.\nEach listed key is authorized to execute commands over the control channel.",
      "title": "Keys"
    },
    "read_only": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "If enabled (yes), limits to read-only commands:\nnta -dump, null, status, showzone, testgen, zonestatus.\nDefault is read-write access.",
      "title": "Read Only"
    }
  },
  "required": [
    "ip_address",
    "allow"
  ],
  "title": "InetControl",
  "type": "object"
}

Fields:

• comment (string_BIND | None)
• ip_address (ip_v4_address_BIND | ip_v6_address_BIND | Literal['*', '::'])
• port (port_BIND)
• allow (address_match_list_BIND)
• keys (list[server_key_BIND] | None)
• read_only (boolean_BIND | None)

ip_address pydantic-field

ip_address: (
    ip_v4_address_BIND
    | ip_v6_address_BIND
    | Literal["*", "::"]
)

IP address to listen on. Can be: - IPv4 address (e.g., 127.0.0.1) - IPv6 address (e.g., ::1) - '*' for all IPv4 interfaces - '::' for all IPv6 interfaces

port pydantic-field

port: port_BIND = 953

Port number or ''. Default is 953. NOTE: '' cannot be used for port in BIND9 controls.

allow pydantic-field

allow: address_match_list_BIND

Address match list for IP-based access control. Any server_key elements in this list are ignored.

keys pydantic-field

keys: list[server_key_BIND] | None = None

List of authorized server keys. Each listed key is authorized to execute commands over the control channel.

read_only pydantic-field

read_only: boolean_BIND | None = None

If enabled (yes), limits to read-only commands: nta -dump, null, status, showzone, testgen, zonestatus. Default is read-write access.