Configuring DNS & DHCP edge services – NS1 Help Center

Table of contents:

Introduction
About services and service components
Before you begin
Overview
DNS edge services
DHCP edge service

Introduction

Note

Before configuring edge services, you must install the edge services and deploy your nodes. Refer to the Cloud-Managed DDI Installation Instructions: NS1 Cloud-Managed DDI.

NS1’s Cloud-Managed DDI is a hybrid solution where NS1 manages core, cloud-based services while various edge service components run on customer-controlled nodes across a distributed network. You can manage all services, components, and nodes within the NS1 Connect platform using NS1’s Fleet and Service Management tools.

Cloud-Managed DDI incorporates both cloud-managed and edge services. Cloud-managed services are deployed to the NS1 control plane and are hosted, managed, and maintained by NS1. The control plane runs the NS1 REST API, NS1 Connect portal, notification subsystems, and hosts configuration data in the system’s central database.

Edge services (e.g., DNS, DHCP) are distributed across a DDI network via their service components which specify which mode or capability of that service should be running on that node. Note that edge service components and nodes are configured, managed, and maintained by a system operator within your organization.

Note

Currently, all service and node configuration is done programmatically via the NS1 API. For a complete index of API endpoints, refer to the NS1 API documentation.

About services and service components

A service is a logical grouping of capabilities within the NS1 Connect platform. Services are deployed to edge nodes via their service components which are software modules representing specific capabilities related to that service.

Currently, NS1 offers two types of edge services: DNS and DHCP. Within the DNS edge service, there are different types of service components: “dns” (i.e., authoritative DNS or recursive DNS), and “xfr” (i.e., DNS zone transfers). Within the DHCP service, there is only one supported service component: “dhcp”.

When deploying a service to a node, you will specify which of that service’s associated components to deploy so that each node is provisioned automatically with only the components needed. This approach gives you flexibility over what runs within your network and allows you to add and remove service components dynamically as required.

Edge service category

Service component

DNS

dns -The “dns” service component can be deployed to a node to indicate that node should run DNS services. You can adjust the configuration options to customize the behavior of the service — including whether this instance of the DNS service should operate in “authoritative” or “recursive” DNS mode.
xfr - The “xfr” service component can be deployed to a node to indicate that node should run zone transfer (XFR) operations.

DHCP

dhcp - The “dhcp” service component is the only service component for the DHCP service. It can be deployed to a node to indicate that node should run all available DHCP services.

Before you begin

You must deploy the NS1 Cloud-Managed DDI service components on the appropriate hosts before applying the configuration settings below. Refer to the Installation Instructions: NS1 Cloud-Managed DDI for details.
You must have a valid API key created within the NS1 Connect portal. The API key must have the “Manage account settings” permission enabled.

Overview

After deploying a node, you can update the configuration options for the service component (i.e., a software module) running on the node via API. For example, the following command demonstrates the format of the API command used to update the service components running on one or more nodes:

curl -X POST -H "X-NSONE-Key: $NSONE_API_KEY" https://api.prod.svc.ns1.dev/v1/service/<service_name>/component/<component_name>
{  
    "selector": "",  
    "version": "",  
    "config": {}
}

where:

The <service_name> is the name of the DNS or DHCP service associated with the specified service component. The service name is either the default value (i.e., numeric identifier) set by NS1 or the name you set if you changed the service name via API. You can find the name of your services by executing the command below:
```
curl -s -H "X-NSONE-Key: $NSONE_API_KEY"  https://api.prod.svc.ns1.dev/v1/service | jq .
```
The <component_name> is the name of the service component you are updating. There are two types of DNS service components, "dns" (for authoritative or recursive DNS services) or "xfr" (for zone transfer services), depending on the type of DNS service you want to configure. There is only one DHCP service component, "dhcp".
The selector specifies on which nodes to update the running service component. Enter a value of "*" to update all nodes or enter one or more tags (kvps) to push the update only to nodes containing those tags (e.g., selector: “pop=lga08”). Additionally, you can use the selector to define logical expressions (i.e., AND, OR, and NOT) to achieve a specific outcome based on your needs. For example:
- Separate two tags (kvps) with a colon to indicate an “OR” statement (e.g., pop=lga08:pop=lga09)
- Separate two tags with a colon and ampersand to indicate an “AND” statement (e.g., pop=lga08:&pop=lga09)
- Enter an exclamation mark before an expression to indicate a “NOT” statement (e.g., pop=lga08:&!region=US)
You can combine multiple expressions to make an advanced statement. For example pop=lga08:pop=lga09:&!region=US would tell the system to evaluate pop=lga08:pop=lga09. If this OR returns true, the expression !region=US is evaluated at the end. If this last one also returns true, then the entire selector has a match.
The version is the version number of the service component (i.e., a software module) running on the node. Set to “latest” to deploy the latest version.
The config object (or array of objects) specifies the configuration options for the service component. Configuration options vary based on the type of service component you are configuring. Refer to the tables below for details.

The sections below explain the process and provide examples for deploying each type of service and service component to an edge node in your Cloud-Managed DDI network.

DNS edge services

There are two types of DNS service components you can deploy in your network:

Authoritative or recursive DNS ("dns") - Indicates this node should run standard DNS operations. Note that you must specify the operation mode in the configuration to indicate whether the particular instance of the DNS service should run in “authoritative” or “recursive” mode.
Zone transfer ("xfr") - Indicates this node should run zone transfer (XFR) operations.

To configure one of these service components, you must first identify the name of the DNS service with which the component is associated. You can find the name of your existing services by executing the command below:

curl -s -H "X-NSONE-Key: $NSONE_API_KEY"  https://api.prod.svc.ns1.dev/v1/service | jq .

The response includes all of your NS1 edge services. You may have multiple DNS services (i.e., groups of DNS services). Locate the DNS service containing the service component you want to configure. Tip: By default, this is typically a three-digit number, but you may have changed this to a custom string during installation and deployment.

Once you identify the relevant DNS service name (i.e., three-digit number or custom string) and the type of service component (i.e., “dns” or “xfr”) you want to configure, you can apply relevant configuration options.

The example format below demonstrates the API structure for applying configuration options to a “dns” or “xfr” service component.

curl -X POST -s -H "X-NSONE-KEY: $NSONE_API_KEY" https://api.prod.svc.ns1.dev/v1/service/{DNS_service_name}/{component} -d '
{
    "selector": "*",
    "version": "latest",
    "ddns_enabled": true,
    "config": {
        "<option>": "<value>",
        "<option>": "<value>",
        "<option>": "<value>",
        }
    }
}' | jq .

where:

<DNS_service_name> is the unique name of your DNS service (i.e., group of DNS services). The name of the DNS service is defined during installation and node deployment. By default, this is typically a three-digit number set by NS1, but it can be changed during installation. Tip: You can find the name of your services by executing the command below:
```
curl -s -H "X-NSONE-Key: $NSONE_API_KEY"  https://api.prod.svc.ns1.dev/v1/service | jq .
```
<component> is the type of DNS component you are configuring. This can either be "dns" or "xfr"

Note

Including the ddns_enabled flag and setting the value to “true” allows the DNS service component to receive dynamic DNS updates. In order to fully implement dynamic DNS, you must attach the relevant zones to a DNS view and configure an access control list (ACL) to accept updates.

Authoritative DNS

You can deploy the authoritative DNS service component to an edge node in your network. If a node is configured to run authoritative DNS services (i.e., “dns”), then the node only serves authoritative data from its database and refuses requests for recursion.

This section includes an API example for configuring authoritative DNS on a node and provides a list of configuration options that can be applied to the “dns” service component running in authoritative mode.

Example 1. API example: Configuring authoritative DNS

The following example updates the “dns” type service component configuration within a DNS service named “229.” The example sets all “dns” service components within the “229” service to “authoritative” mode (Using JSON to specify "operation_mode": "authoritative" in the config’s JSON) and sets them to the latest software version.

curl -X POST -s -H "X-NSONE-KEY: $NSONE_API_KEY" https://api.prod.svc.ns1.dev/v1/service/229/dns -d '
{
    "selector": "*",
    "version": "latest",
    "ddns_enabled": true,
    "config": {
        "operation_mode": "authoritative"
    }
}' | jq .

Another common example is shown below. It demonstrates setting the operation mode to “authoritative” and then specifying a DNS forwarding rule in the configuration. This is a common use case demonstrating an authoritative service configured with recursive settings, allowing you to run an authoritative server, but ensuring ALIAS records for any name within the zone (e.g., “test.com”) are resolved by the specified IP address and port.

curl -X POST -s -H "X-NSONE-KEY: $NSONE_API_KEY" https://api.prod.svc.ns1.dev/v1/service/329/dns -d '
{
    "selector": "*",
    "version": "latest",
    "ddns_enabled": true,
    "config": {
        "operation_mode": "authoritative",
        "forward_zones_recurse": {
            "test.com": [
                "8.8.8.8@53"
            ]
        }
    }
}' | jq .

Refer to the next section for a complete list of configuration options that can be applied to a “dns” service component operating in authoritative mode.

Table 1. Configuration options (for Authoritative DNS)

Option	Format	Description
Operation mode	`"operation_mode": "authoritative"`	Indicates whether the service component will operate as an authoritative DNS server or recursive resolver. Supported values: authoritative or recursive. Default is authoritative. Note: If you want a DNS service to operate in Recursive DNS mode, please refer to the Recursive DNS configuration below.
DNS port	`"dns_port": integer`	(Required) The port for the DNS service component. Default is 53.
DNS receive buffer	`"dns_recv_buffer”: integer`	A number greater or equal to 0 indicates the size (in bytes) of the UDP receive buffers used by the DNS server. A value of '0' uses the OS-defined default value. Default is 0.
Number of name server processes	`"num_trex_procs": integer`	Indicates the number (between 1-100) of authoritative DNS server processes to run. Default: Equal to the number of CPUs given to the host.

Note

Some of the “Recursive DNS configuration” options listed in the next section can also apply to the DNS service component running in “authoritative” mode. For example, the "forward_zones_recurse" option can be used to ensure ALIAS records are resolved using a specified IP address and port of the recursive resolver.

Recursive DNS

You can deploy the DNS service component and configure it to run in “recursive” DNS mode. If a node is configured to run in recursive DNS mode, then the node either responds to those queries from its database or its cache, or it sends queries to other servers in order to get the final answers to the original queries. This is called iterative resolution in which the recursive server repeatedly makes non-recursive queries on the client’s behalf and follows referrals and/or aliases to get the final answer.

Response Policy Zone (RPZ) feature is also supported by the DNS component running in recursive mode. DNS Response Policy Zones (DNS RPZ) is a method that allows a name server administrator to overlay custom information and provide alternate responses to queries. The primary use case for RPZ is to prohibit users from accessing malicious resources and provide additional security to your network by blocking query responses to access those resources or providing a safe answer. For example,

Users who want to access a bad hostname or domain name can be blocked or redirected to a safe page.
If the answer of a query is a known malicious IP address or subnet, That answer can be blocked or modified with another IP address or hostname.

RPZ is represented as a DNS zone file with some formatting in defining the resource records and answers that have special meaning and are parsable by Recursive DNS. To enable this feature, you must specify the source of the RPZ file. This zone can either be transferred using HTTP protocol or unauthenticated DNS zone transfer (AXFR).

This section includes an API example and provides a list of configuration options that can be applied to the “dns” service component configured to run in recursive mode.

Example 2. API example: Configuring recursive DNS

The example below demonstrates the basic configuration of a DNS service component running in recursive mode.

curl -X POST -s -H "X-NSONE-KEY: $NSONE_API_KEY" https://api.prod.svc.ns1.dev/v1/service/<service_name>/dns -d '
{
    "selector": "*",
    "version": "latest",
    "ddns_enabled": true,
    "config": {
        "operation_mode": "recursive",
    }
}' | jq .

Table 2. Configuration options (for Recursive DNS)

Option	Format	Description
Operation mode	`"operation_mode": "recursive"`	(Required) Indicates whether the service component will operate as an authoritative DNS server or recursive resolver. Supported values: authoritative or recursive. Default is authoritative. Note: If you want a DNS service to operate in Authoritative DNS mode, please refer to the Authoritative DNS configuration above for a full list of configuration options.
DNS port	`"dns_port": integer`	(Required) The port for the DNS service component. Default is 53.
Recursive resolver forwarding	`"forward_zones_recurse": {"<zone>": ["<IP>@<port>"]}`	Configure recursive zone forwarding for the recursive resolver. Any queries that the resolver may need to send for the listed zones or sub-zones will be forwarded to the configured recursive DNS server to complete the resolution. Use this option if you want queries for certain domains to be answered by a different recursive resolver. This argument expects input in the format of: `{"<zone>":["<resolver_ip>@<resolver port>"]}` Additional resolvers per zone are separated by semicolons. Additional zones are separated by commas. For example: {"test.com":["8.8.8.8@53"],"test2.com":["9.9.9.9@53"]} By default, the port is set to 53. To configure the DNS service component to send all recursive queries to another resolver, specify a dot (.) as the zone (e.g., .@53). Note that the included recursive resolver is used for ALIAS record resolution if the container is in authoritative mode.
Forward zones	`"forward_zones": {"<zone>": ["<IP>@<port>"]}`	Configures zone forwarding for the recursive resolver. Any queries that the resolver may need to send for the listed zones will be sent directly to the configured authoritative DNS server. Use this option to configure the resolution of zones that are not resolvable from the public DNS or to support DNS split-view. This argument expects input in the format of: `{"<zone>":["<server_ip>@<port>"]}` By default, the port is set to 53.
Enable Cisco Umbrella	`"enable_umbrella": true/false`	Enables or disables recursive resolution via Cisco Umbrella. If enabled, any changes to "Resolving Configuration" will be ignored. Default is false.
Cisco Umbrella device ID	`"umbrella_device_id": "string"`	(Required if Cisco Umbrella is enabled) Specifies a Cisco Umbrella device ID.
Enable reverse look-ups for private IP addresses	`"rdns_allow_private_arpa": true/false`	Enable this option to allow queries to reverse zones for private IP addresses. If disabled, reverse zones for private IP addresses are treated as AS112 zones. Default is true.
Outgoing port range to allow	`"rdns_outgoing_port_permit": "array"`	Indicates the range of ports to allow for outgoing queries (e.g., ["1025-10000", "20000-65535"]). Default is 1025-65535.
Outgoing port range to avoid	`"rdns_outgoing_port_avoid": "array"`	Indicates the range of ports to avoid for outgoing queries (e.g., ["1025-10000", "20000-65535"]). Default is empty.
Advertised EDNS buffer size	`"rdns_edns_buffer_size": integer`	EDNS buffer size (between 512-65535) to advertise to requesting clients. Default is 1232.
Maximum UDP response size	`"rdns_max_udp_size": integer`	Maximum size (between 512-65535) for UDP response messages. Defaults to 4096.
Base cache size	`"rdns_cache_size": integer`	Base size (between 50-8000) of the cache for DNS records in megabytes. Additional caches may be set up based on this value. The operating system may add additional overhead. Expect that the real memory usage may be as much as 4 times higher than the entered value. Defaults to 250.
Maximum cache TTL	`"rdns_cache_max_ttl": integer`	Maximum time-to-live (TTL) value (in seconds) for cached records. Default is 86400.
Minimum cache TTL	`"rdns_cache_min_ttl": integer`	Minimum time-to-live (TTL) value (in seconds) for cached records. Default is 5.
Maximum cache TTL for negative responses	`"rdns_cache_max_negative_ttl": integer`	Maximum time-to-live (TTL) value (in seconds) for cached negative responses (i.e., responses that indicate the record name or type does not exist). Default is 3600.
Disable outgoing IPv6	`"rdns_disable_ipv6": true/false`	Set to “true” to disable IPv6 protocol when contacting authoritative name servers. Default is false.
QNAME minimisation	`"rdns_qname_minimisation": true/false`	Set to “true” to enable QNAME minimization defined in RFC 9156. Minimization improves client privacy. Default is true.
Query rate limit	`"rdns_rate_limit": integer`	Specifies the rate limit for queries to authoritative name servers. The value is expressed in queries per second per zone. Cached responses are not subject to this limit. This option is disabled by default.
Query rate limit for a zone	`"rdns_rate_limit_zone": '["<zone_name1>=integer", "<zone_name2>=integer"]'`	An array specifying the rate limit override for one or more zones (by zone name). This allows setting higher limits for zones like TLDs. This option is disabled by default.
IP rate limit	`"rdns_ip_rate_limit": integer`	Specifies the query rate limit for client IP addresses. The value is expressed in queries per second per IP address. This option is disabled by default.
Enable serving stale data	`"rdns_serve_stale": true/false`	Set to “true” to allow the component to serve stale data to improve DNS resiliency (RFC 8767). Serving stale data allows responding with expired data from the cache if the authoritative name servers cannot be reached. Default is true.
Stale data TTL	`"rdns_serve_stale_ttl": integer`	Indicates the time-to-live (TTL) value (in seconds) for storing expired data in the cache. The value determines the amount of time stale data can be served to clients before being discarded completely. Default is 86400 (i.e., 1 day).
Log verbosity	`"rdns_verbosity": "integer"`	Indicates the verbosity level (i.e., an integer between 0-5). A value of “0” indicates that only errors will be logged. A value of “1” indicates operational information will be logged. A value of “2” indicates detailed operational information, including per-query data, will be logged. A value of “3” indicates query-level information, including output per query, will be logged. A value of “4” indicates algorithm-level information will be included in the log. A value of “5” indicates client identifiers for cache misses will be included in the log. Default is “1”.
Log queries	`"rdns_log_queries": true/false`	Indicates whether or not to log each DNS query in the log file.
Log replies	`"rdns_log_replies": true/false`	Indicates whether or not to include a reply to each log query. The reply includes the log timestamp, IP address, name, type, class, return code, time-to-resolve, from cache and response size. Set to “true” to enable replies. Default is “false”.
Response Policy Zone	`"rdns_rpz": ["<zone>=<source>;<source>;", "<zone>=<source>"]`	Response Policy Zones is a mechanism that allows modifying responses to DNS client requests. The policy is expressed as a zone file and it can be fetched from an HTTP server or using an unauthenticated zone transfer. The source can be an URL with the zone file to download or an address of the primary DNS server as '<ip>@<port>'. For example: "rdns_rpz": ["example.com=192.0.2.1;192.0.2.2", "example.test=https://192.0.2.1/example.test.db"]

Zone transfer (XFR) configuration

You can deploy the zone transfer (XFR) service component to a node in your Cloud-Managed DDI network. This section includes an API example for configuring XFR on a node and provides a list of configuration options that can be applied to the “xfr” service component.

Note

NS1 recommends deploying only one XFR edge service component in your Cloud-Managed DDI network — otherwise, zone transfer tasks are load balanced between the XFR services and you cannot choose the destination.

This section includes an API example and provides a list of configuration options that can be applied to the “xfr” service component.

Example 3. API example: Configuring XFR service component

The example below will configure the XFR component in the specified service to deploy XFR on all available nodes (*) the latest version on port 53.

curl -X POST -s -H "X-NSONE-KEY: $NSONE_API_KEY" https://api.prod.svc.ns1.dev/v1/service/<service_name>/xfr -d '
{
    "selector": "*",
    "version": "latest",
    "config": {
        "xfr_port": "53"
    }
}' | jq .

Note that you can find the name of your services by executing the command below:

curl -s -H "X-NSONE-Key: $NSONE_API_KEY"  https://api.prod.svc.ns1.dev/v1/service | jq .

Table 3. Configuration options (for XFR)

Option	Format	Description
XFR port	`"xfr_port": 53`	(Required) The port for the DNS service component. Default is 53.

DHCP edge service

Within the DHCP service (type), there is only one service component, "dhcp," that can be deployed to run DHCP services. You may have multiple DHCP service "groups" with unique configuration settings. You must first identify the name of the DHCP service with which the component is associated. You can find the name of your existing services by executing the command below:

curl -s -H "X-NSONE-Key: $NSONE_API_KEY"  https://api.prod.svc.ns1.dev/v1/service | jq .

The response includes all of your NS1 edge services. Locate the DHCP service containing the service component you want to configure. Tip: By default, this is typically a three-digit number, but you may have changed this to a custom string during installation and deployment.

This section includes an API example and configuration options that can be applied to the "dhcp" service component.

Example 4. API example: Configuring DHCP

Execute the command below to view all configuration options for the DHCP service component.

curl -X POST -s -H "X-NSONE-KEY: $NSONE_API_KEY" https://api.prod.svc.ns1.dev/v1/service/<DHCP_service_name>/dhcp -d '
{
    "selector": "*",
    "version": "latest",
    "config": {
        "<option>": "<value>",
        "<option>": "<value>",
        "<option>": "<value>",
        }
    }
}' | jq .

Note

If configuring high-availability (HA) among two DHCP service components, you must ensure that port TCP/5353 is exposed to enable bidirectional communication. Refer to Configuring high availability (HA) for DHCP services for details.

Table 4. Configuration options (for DHCP)

Option	Format	Description
Enable or disable DHCP high availability	`"dhcp_ha": "enabled/disabled"`	(Required) Option to run this DHCP service component in high-availability (HA) mode (as opposed to a single container), allowing for failover to secondary DHCP components. Supported values: “enabled” or “disabled”
Designate HA primary	`"dhcp_is_primary": true/false`	(Required if DHCP HA is enabled) Option to designate this service component as the primary DHCP component. Note: There must be one primary component designated to operate in HA mode.
DHCP peers	`"dhcp_peers": "string"`	(Required if DHCP HA is enabled) A list of partner DHCP component hostnames that will load balance DHCP requests. Note: Currently, DDI only supports a total of one peer. Each DHCP component must specify the other DHCP component as its peer in the set.
DHCP heartbeat delay	`"dhcp_heartbeat_delay": integer`	(Required if DHCP HA is enabled) Specifies a duration of time (in milliseconds) from the last heartbeat to sending the next heartbeat between peers in HA mode.
DHCP maximum response delay	`"dhcp_max_response_delay": integer`	(Required if DHCP HA is enabled) Specifies a duration of time (in milliseconds) from the last successful communication with peers in HA mode until the server assumes that communication with peers has been interrupted.
DHCP maximum time for attempted communication before assumed fail	`"dhcp_max_ack_delay": integer`	Specifies the maximum time (in milliseconds) for the client to try to communicate with the DHCP server until the server assumes communication failed.
DHCP maximum number of unacknowledged clients permitted	`"dhcp_max_unacked_client": integer`	Indicates the number of unacknowledged clients (i.e., DHCP client that has been sending requests for a lease or renewal and that has not yet received a response from the server) permitted before this server assumes the peers are offline and transitions to a "down" state. Default is 0.
DHCP server port	`"dhcp4_server_port": integer`	(Advanced) Change if there is a conflict when using net=host. Default is 5300.
DHCP sender port	`"dhcp4_sender_port": integer`	(Advanced) Change if there is a conflict when using net=host. Default is 5301.
Queue port	`"queue_port": integer`	(Advanced) Change if there is a conflict when using net=host. Default is 5672.
Metrics port	`"metrics_port": integer`	(Advanced) Change if there is a conflict when using net=host. Default is 8086.
Remote port	`"remote_port": integer`	(Advanced) Change if there is a conflict when using net=host. Default is 8443.
DHCP control port	`"dhcp_control_port": integer`	(Advanced) Change if there is a conflict when using net=host. Default is 8080.
Number of DHCP NCR reconnect attempts	`"dhcp_ncr_reconnect_attempts": integer`	Specifies the number of attempts to reconnect to the message queue. Default is 5.
NCR reconnect maximum sleep time	`"dhcp_ncr_reconnect_max_backoff_sec": integer`	Indicates the maximum amount of sleep time (in seconds) between reconnect attempts to the message queue. Default is 32.
DHCP log verbosity	`"dhcp_loglevel": "string"`	Set the log level for the DHCP server. Modifying the default value may cause an influx of logs. Supported values: “debug,” “info,” “warn,” “error,” or “fatal.” Default is “info.”
DHCP lease importer	`"dhcp_lease_importer": "string"`	Indicates whether or not to import the lease state from the control plane in the case that the local lease state is wiped out. Default value is “disabled.” Supported values: “enabled” or “disabled.”

Articles in this section

Introduction

Note

Note

About services and service components

Before you begin

Overview

DNS edge services

Note

Authoritative DNS

Note

Recursive DNS

Zone transfer (XFR) configuration

Note

DHCP edge service

Note

Related articles