Note
Before configuring edge services, you must install the edge services and deploy your nodes. Refer to the Cloud-Managed DDI Installation Instructions for details.
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.
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.
A service is a logical grouping of capabilities within the NS1 Connect platform. They include DNS, DHCP, Monitoring, and more. Services are deployed to edge nodes via their service components which are software modules representing specific capabilities related to that service. 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.
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, MONITOR) 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. Edge service components and nodes are configured, managed, and maintained by a system operator within your organization.
In the context of NS1 Cloud-Managed DDI, service management refers to the configuration of features and capabilities delivered by their corresponding components. On the other hand, Fleet management refers to managing nodes and orchestrating the deployment of a specific type of component to each node.
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 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.
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: $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 service with which the specified service component (i.e., a software module) is associated. The service name is either the default value set by NS1 or the name you set if you changed the service name via API.
The <component_name> is the name of the service component you are updating. Currently, this can only be either “dns” or “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 maintain the latest software 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 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: $API_KEY" https://api.prod.svc.ns1.dev/v1/service/229/dns -d '
{
"selector": "*",
"version": "latest",
"config": {
"operation_mode": "authoritative"
}
}' | jq .
Another example might include a DNS forwarding rule in the configuration.
curl -X POST -s -H "X-NSONE-KEY: $API_KEY" https://api.prod.svc.ns1.dev/v1/service/329/dns -d '
{
"selector": "*",
"version": "latest",
"config": {
"operation_mode": "authoritative",
"forward_zones_recurse": {
"test.com": [
"8.8.8.8@53"
]
}
}
}' | jq .
You can use a similar format to configure any edge service as part of the Cloud-Managed DDI solution. Refer to the next section for a list of all supported configuration options for the available edge service components.
This section includes all supported configuration options for each edge service and its associated components.
Note
Currently, the DNS service offers one associated component called “dns.” In the future, additional components will be available within the DNS service type to represent a specific set of capabilities related to the DNS service (e.g., authoritative, recursive, and XFR components). Refer to About authoritative & recursive resolver modes for more information.
EXAMPLE FORMAT
Refer to the example format below to apply configuration options to the DNS service component.
curl -X POST -s -H "X-NSONE-KEY: $API_KEY" https://api.prod.svc.ns1.dev/v1/service/{DNS_service_name}/dns -d '
{
"selector": "*",
"version": "latest",
"config": {
"<option>": "<value>",
"<option>": "<value>",
"<option>": "<value>",
}
}
}' | jq .
Table 1. Reference table: DNS service configuration options
Option |
Format |
Description |
Required |
|---|---|---|---|
DNS receive buffer |
|
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. |
Yes (if empty, defaults to 0) |
Number of name server processes |
|
Indicates the number (between 1-100) of authoritative DNS server processes to run. Default: Equal to the number of CPUs given to the host. |
Yes |
Operation mode |
|
Indicates whether the service component will operate as an authoritative DNS server or recursive resolver. Supported values: authoritative or recursive |
Yes (if empty, defaults to authoritative) |
Recursive resolver forwarding |
|
List of zones and recursive server addresses. Any query for a name in the configured zone will be forwarded to the corresponding recursive server for full resolution. Use this option if you want queries for certain names to be answered by a different resolver. This argument expects input in the format of: Additional resolvers per zone are separated by semicolons. Additional zones are separated by commas. For example: 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). |
No |
Forward zones |
|
List of zones and authoritative name server addresses. Any query for a name in the configured zone is sent to the corresponding authoritative server, but the full query resolution happens locally. Use this option to configure the resolution of domains that are not accessible from the public internet. This argument expects input in the format of: By default, the port is set to 53. Use semicolons to separate multiple resolvers in the list. Use commas to separate multiple zones. |
No |
Enable Cisco Umbrella |
|
Enables or disables recursive resolution via Cisco Umbrella. If enabled, any changes to "Resolving Configuration" will be ignored. |
Yes (if empty, defaults to false) |
Cisco Umbrella device ID |
|
Specifies a Cisco Umbrella device ID. Refer to this article for more information. Refer to this article for more information. |
Yes (if Cisco Umbrella is enabled) |
Cisco Umbrella organization ID |
|
Specifies a Cisco Umbrella organization ID. Refer to this article for more information. |
Yes (if Cisco Umbrella is enabled) |
EXAMPLE FORMAT
Execute the command below to view all configuration options for the DNS service component:
curl -X POST -s -H "X-NSONE-KEY: $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 .
Table 2. Reference table: DHCP service configuration options
Option |
Format |
Description |
Required |
|---|---|---|---|
Enable/disable DHCP high-availability (HA) |
|
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” |
Yes |
Designate HA primary |
|
Option to designate this service component as the primary DHCP component. Note: There must be one primary component designated to operate in HA mode. |
Yes (if DHCP HA is enabled) |
DHCP peers |
|
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. |
Yes (if DHCP HA is enabled) |
DHCP heartbeat delay |
|
Specifies a duration of time (in milliseconds) from the last heartbeat to sending the next heartbeat between peers in HA mode. |
Yes (if DHCP HA is enabled) |
DHCP maximum response delay |
|
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. |
Yes (if DHCP HA is enabled) |
DHCP maximum time for attempted communication before assumed fail |
|
Specifies the maximum time (in milliseconds) for the client to try to communicate with the DHCP server until the server assumes communication failed. |
No |
DHCP maximum number of unacknowledged clients permitted |
|
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. |
No |
DHCP server port |
|
(Advanced) Change if there is a conflict when using net=host. Default is 5300. |
No |
DHCP sender port |
|
(Advanced) Change if there is a conflict when using net=host. Default is 5301. |
No |
Queue port |
|
(Advanced) Change if there is a conflict when using net=host. Default is 5672. |
No |
Metrics port |
|
(Advanced) Change if there is a conflict when using net=host. Default is 8086. |
No |
Remote port |
|
(Advanced) Change if there is a conflict when using net=host. Default is 8443. |
No |
DHCP control port |
|
(Advanced) Change if there is a conflict when using net=host. Default is 8080. |
No |
Number of DHCP NCR reconnect attempts |
|
Specifies the number of attempts to reconnect to the message queue. Default is 5. |
No |
NCR reconnect maximum sleep time |
|
Indicates the maximum amount of sleep time (in seconds) between reconnect attempts to the message queue. Default is 32. |
No |
DHCP log verbosity |
|
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.” |
No |
DHCP lease importer |
|
Indicates whether or not to import 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.” |
No |