Docker Compose Installation & Setup Guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 34

Docker Compose
Installation & Setup Guide.
NS1 Private DNS 1.0 • Revised August 8, 2018
 
2018 © NS1, Inc.
Private DNS 1.0
TABLE OF CONTENTS
1. Overview 3
2. Before You Begin 4
2.1. System Requirements 4
2.1.1. Hardware 4
2.1.2. Operating Systems 4
2.1.3. Docker 4
2.1.4. Software 5
2.1.5. Network 5
2.2. Securing System Access 5
2.3. Transport Layer Security 6
3. Installation 6
3.1. Accessing Files & Images 6
3.2. Configuring Compose Files 7
3.3. Installation Commands 7
4. Setup & Configuration 8
4.1. Setup with CLI 8
4.1.1. Common CLI Setup Options 8
4.1.2. Data CLI Setup 10
4.1.3. DNS CLI Setup 12
4.1.4. Web CLI Setup 13
4.1.5. Xfr CLI Setup 14
4.2. Setup with Web Interface 15
4.2.1. Data Setup 15
4.2.2. DNS Setup 16
4.2.3. Web Setup 16
4.2.4. Xfr Setup 17
5. Administrative Actions 18
5.1. Admin Actions with CLI 18
5.1.1. Data CLI Actions 18
5.1.2. DNS CLI Actions 19
5.1.3. Web CLI Actions 19
5.1.4. Xfr CLI Actions 20
5.2. Admin Actions with the Web Interface 21
5.2.1. Data Actions 21
2018 © NS1 Inc.
Page | 1
Private DNS 1.0
5.2.2. DNS Actions 21
5.2.3. Web Actions 22
5.2.4. Xfr Actions 22
6. Import New GeoIP Data 23
7. Upgrading 23
8. Uninstalling 24
9. Appendix A. Bootstrap an Operator 25
10. Appendix B: Managing Operators 26
10.1. View Operator(s) 26
10.2. Create an Operator 26
10.3. Update an Operator 26
10.4. Delete an Operator 26
11. Appendix C: Managing Organizations 28
11.1. View Organizations 28
11.2. View an Organization 28
11.3. Creating an Organization 28
11.4. Update an Organization 28
11.5. Delete an Organization 29
11.6. Reset a User’s Password 29
12. Appendix D: Managing API Keys, Users & Teams 30
12.1. Example: Adding a New User to an Organization as Operator 30
12.2. Example: Adding a Zone as Operator User 31
13. Appendix E: Unavailable API Endpoints in Private DNS 32
14. Appendix F: System Topologies 33
14.1. Architecting for Highly Available DNS 33
 
2018 © NS1 Inc.
Page | 2
Private DNS 1.0
1. Overview
NS1’s Private DNS is a solution that can be installed on customers’ networks. It is the
software version of NS1’s industry-leading SaaS platform, bringing DNS and traffic
management capabilities out of the cloud and into owned environments.
 
2018 © NS1 Inc.
Page | 3
Private DNS 1.0
2. Before You Begin
This guide assumes the reader has familiarity with the principles of DNS, networking, and
working knowledge of Docker and container-based systems.
2.1. System Requirements
The following sections contain both hard requirements and general guidance (e.g.
hardware) for the system. For questions or concerns about target environments, please
contact support@ns1.com for more information.
2.1.1. Hardware
The following is the minimum hardware recommended to run a single container image:
2 CPUs
2 GB RAM
20 GB of free disk space
Important note: NS1 highly recommends monitoring disk usage on each host to prevent
service disruption.
2.1.2. Operating Systems
Linux Ubuntu 18.04 (Docker CE 18.05 Edge and higher only) / 17.04 / 16.04 / 14.04 x64
CentOS 7 x86
Red Hat x86_64
Important note: If running multiple containers on the same host machine, a Linux kernel
must support the SO_REUSEPORT socket option to allow multiple sockets on the same host
to bind to the same port.
Important note: Running Private DNS on Mac OS or Windows 10 Pro / Enterprise 64-bit is
not supported by NS1.
2.1.3. Docker
To run multi-container applications with Docker Compose, Private DNS requires Docker
Version 17.03.x or 17.06.x (CE or EE) or higher. More information about Docker
requirements along with installation steps is found at the following locations:
Docker: https://docs.docker.com/engine/installation/
Docker Compose: https://docs.docker.com/compose/install/.
2018 © NS1 Inc.
Page | 4
Private DNS 1.0
2.1.4. Software
Web interface configuration was designed to work with current Evergreen browser
versions. Note that newer versions of each browser may be available since this release and
therefore may not be tested yet by NS1. The following browser versions were tested prior
to this release:
Chrome 67.0.3396.87 (Official Build) (64-bit)
Firefox 58.0
Edge 41.16299.15
EdgeHTML 16.16299
Safari 11.0.2
2.1.5. Network
While configuring the system, IPv4 addresses are recommended. Access to the public
internet is required to pull the latest container images from my.nsone.net.
Important notes:
For private networks without access to the public internet, NS1 recommends pulling
the container images on a separate machine first before transferring contents to a
hard disk or volume which is accessible by the private network.
If available, it is highly recommended to add each image version to a private
container registry.
The following network protocols are used by the system: HTTP/HTTPS, UDP, TCP, TLS.
2.2. Securing System Access
Host Access. Access to host machines on which each container is running should be
secured to system administrators only. NS1 highly recommends that administrators and
operators should be required to access this machine via secure shell (SSH) connection.
Basic Auth. To further secure containers’ web configuration interface, operators must sign
in using “Basic Auth” credentials. By default, Private DNS initializes Username to ns1and
Password to private.
Limiting Port Visibility. The web container should only be viewable on ports 80 and 443
from the localhost.
2018 © NS1 Inc.
Page | 5
Private DNS 1.0
2.3. Transport Layer Security
By default all network communication between the various Private DNS containers,
management portal and API endpoints, as well as the main portal and API endpoints is
encrypted using self signed certificates that are generated at initial runtime of each
container. It is expected behavior for a browser certificate trust warning to appear when
navigating to the web configuration interfaces of each container for the first time. Proceed
following the on screen browser instructions.
There are up to three different TLS configurations depending on the container:
TLS Configuration
Description
Availability
Transport TLS
This configuration manages how
communication between the various
containers is encrypted and verified.
Data
Web
Xfr
Dns
Cache
Management TLS
This configuration manages how
communication between clients and the
management interface is encrypted and
verified.
Data
Web
Xfr
Dns
Cache
Web TLS
This configuration manages how
communication between clients and the
main NS1 portal and API is encrypted and
verified.
Web
The web container uses a self-signed certificate. As a result, a certificate trust warning may
appear when making API calls or visiting the NS1 portal in a web browser. It is safe to
ignore this validation warning. You can replace this certificate with a custom certificate at a
later time.
3. Installation
This section provides instructions on installation using docker-compose.
3.1. Accessing Files & Images
NS1 hosts the installation files and container images within the NS1 Portal. NS1’s Customer
Success team will send an email invitation to Private DNS customers directing them to
https://my.nsone.net/. Once a password is created, navigate to the Downloads page.
2018 © NS1 Inc.
Page | 6
Private DNS 1.0
Container images can now be downloaded locally, unzipped, and pushed to a private
container registry.
Alternatively, use your API key to run the following command or download and run the
command here:
sh <(curl -Ls
https://raw.githubusercontent.com/ns1/ns1-privatedns/master/get-privatedns.sh -o -) -k
APIKEY
Then download the compose file here:
wget https://raw.githubusercontent.com/ns1/ns1-privatedns/master/docker-compose.yml
Important note: It is a violation of the NS1 license agreement to push container images to
a repository which is not for exclusive use by the licensee. Pushing images to a public
registry is unlawful redistribution of the software.
3.2. Configuring Compose Files
The example docker-compose.yml provided in the installation directory will start a single
container of each service on one host machine. In-line comments provide more
information about specific parameters. Configuration management tools and other
infrastructure as code frameworks are highly recommended to orchestrate a
production-grade deployment.
3.3. Installation Commands
Execute docker-compose.yml to start containers and volumes for installation. Pass in the
image version at the command line using the TAG parameter as shown below.
TAG=1.0.2 docker-compose -p privatedns up -d
Important note: Upgrading the host machine’s version of Docker Compose is
recommended. See https://docs.docker.com/compose/install/#upgrading for more
information.
 
2018 © NS1 Inc.
Page | 7
Private DNS 1.0
4. Setup & Configuration
When first setting up the system, the data container should be configured first.
Configuration of other containers can be done in any order.
4.1. Setup with CLI
Using the command line, the system is set up using the supd application. For usage
information of supd, add the --help or -h option. For example, the xfr container’s supd
help is accessed with the following command:
docker exec privatedns_xfr_1 supd --help
4.1.1. Common CLI Setup Options
Certain fields are common and shared among all containers. To view the usage information
of the run command for the specific container. For example,
docker exec privatedns_data_1 supd run --help
The following table describes shared options for the run command.
Options
Description
--recovery
Used by the system to recover from a failed
configuration
--bootstrap
Used by the system when first standing up with no
configuration available
-f, --force
overwrite any existing config options with CLI
parameters
--pop_id [value]
This specifies the location (datacenter/pop) of the
server where the data container is running
--server_id [value]
This identifies a specific server in a location where
the data container is running
--enable_ops_metrics
[value] 
If enabled this will export system metrics to the
specified metrics database(s)
--transport_enable_tls
[value]
Enable or disable transport TLS encryption, to use for
communicating with other cluster members. (defaults to
True)
--default_transport_tls_
settings [value]
Use the predefined TLS settings for transport networking
2018 © NS1 Inc.
Page | 8
Private DNS 1.0
--manual_transport_tls_s
ettings [value]
Define the TLS settings for transport networking, when
using manually mounted certificates
--manual_transport_tls_c
rl_file [value]
The CRL certificate to use for verifying client
certificates revocation status, when communicating
between cluster members
--manual_transport_tls_s
ni_zone [value]
The zone to use for TLS verification purposes, when
communicating between cluster members
--manual_transport_tls_c
lient_cert_verfiy
[value] 
Whether or not to enforce strict certificate
verification, when communicating between cluster
members. NOTE: You must set 'TLS certificate zone' for
this to work with custom certificates
--manual_transport_tls_v
ersion [value]
The minimum TLS version to enforce, when communicating
between cluster members
--manual_transport_tls_c
iphers [value]
The set of TLS ciphers to use, when communicating
between cluster members
--management_enable_tls
[value]
Enable or disable management TLS encryption, to use for
communicating with other cluster members. (defaults to
True)
--default_management_tls
_settings [value]
Use the predefined TLS settings for management
networking
--manual_management_tls_
settings [value]
Define the TLS settings for management networking, when
using manually mounted certificates
--manual_management_tls_
cert_bundle [value]
The combined certificate/key PEM file to present, when
communicating between cluster members
--manual_management_tls_
crl_file [value]
The CRL certificate to use for verifying client
certificates revocation status, when communicating
between cluster members
--manual_management_tls_
client_cert_verfiy
[value] 
Whether or not to enforce strict certificate
verification, when communicating between cluster members
--manual_management_tls_
version [value] 
The minimum TLS version to enforce, when communicating
between cluster members
--manual_management_tls_
ciphers [value] 
The set of TLS ciphers to use, when communicating
between cluster members
-h, --help
output usage information
 
2018 © NS1 Inc.
Page | 9
Private DNS 1.0
4.1.2. Data CLI Setup
To see the data container’s unique configuration options, view the usage information of the
run command.
docker exec privatedns_data_1 supd run --help
The following table describes options specific to the data container.
Options
Description
--number_of_stats_proces
sors [value]
The number of processors to run for query metrics
--query_metrics_ttl
[value] 
Duration to keep query metrics.
--telegraf_output_ns1_da
ta [value]
None
--telegraf_output_ns1_da
ta_enabled [value]
Use the default metrics store
--telegraf_output_influx
db [value]
Enable InfluxDB output for operational metrics
--telegraf_output_influx
db_data_host [value]
Hostname of InfluxDB host
--telegraf_output_influx
db_database [value] 
InfluxDB Database Name
--telegraf_output_influx
db_enable_auth [value]
Enable user/password authentication for InfluxDB
--telegraf_output_influx
db_username [value]
InfluxDB User
--telegraf_output_influx
db_password [value]
InfluxDB Password
--telegraf_output_influx
db_enable_tls [value]
Enable TLS for InfluxDB
--telegraf_output_influx
db_server_pem_key
[value] 
The PEM key for the InfluxDB server
--telegraf_output_influx
db_ca_pem_key [value]
The CA key used for validation if provided
--telegraf_output_influx
db_crt [value]
The CRT for the InfluxDB server
--telegraf_output_elasti
csearch [value] 
Enable Elasticsearch output for operational metrics
2018 © NS1 Inc.
Page | 10
Private DNS 1.0
--telegraf_output_elasti
csearch_data_host
[value] 
Elasticsearch Host
--telegraf_output_elasti
csearch_sniff_cluster
[value]
Enable sniffing Elasticsearch for additional hosts in
cluster
--telegraf_output_elasti
csearch_timeout [value]
Timeout for Connecting to Elasticsearch
--telegraf_output_elasti
csearch_index [value]
Elasticsearch Index
--telegraf_output_elasti
csearch_enable_auth
[value]
Enable user/password authentication for Elasticsearch
--telegraf_output_elasti
csearch_username [value]
Elasticsearch Username
--telegraf_output_elasti
csearch_password [value]
Elasticsearch Password
--telegraf_output_elasti
csearch_enable_tls
[value]
Enable TLs for Elasticsearch
--telegraf_output_elasti
csearch_server_pem_key
[value]
The PEM key for the Elasticsearch server
--telegraf_output_elasti
csearch_ca_pem_key
[value] 
The CA key used for validation of Elasticsearch
--telegraf_output_elasti
csearch_crt [value]
The CRT for the Elasticsearch server
--telegraf_output_elasti
csearch_enable_managed_t
emplate [value]
Whether to have the metrics process or Elasticsearch
manage the template
--telegraf_output_elasti
csearch_template_name
[value]
The name of the elasticsearch template
--telegraf_output_elasti
csearch_overwirte_templa
te [value]
Whether to be able to overwrite an existing template
--telegraf_output_opents
db [value]
Enable OpenTSB output for operational metrics
--telegraf_output_opents
db_host [value]
OpenTSDB Hostname
2018 © NS1 Inc.
Page | 11
Private DNS 1.0
--telegraf_output_opents
db_batch_size [value]
Batch Size of writes to OpenTSDB
--telegraf_output_graphi
te [value]
Enable graphite output for operational metrics
--telegraf_output_graphi
te_host [value]
Graphite server hostname
--telegraf_output_graphi
te_timeout [value]
Timeout for connecting to graphite
--telegraf_output_graphi
te_template [value]
Template format for metrics in graphite
--telegraf_output_graphi
te_enable_tls [value]
Enable TLS for graphite
--telegraf_output_graphi
te_server_pem_key
[value]
The PEM key for the graphite server
--telegraf_output_graphi
te_ca_pem_key [value]
The CA PEM key used for validation of graphite server
--telegraf_output_graphi
te_crt [value]
The CRT for the graphite server
4.1.3. DNS CLI Setup
To see the dns container’s unique configuration options, view the usage information of the
run command.
docker exec privatedns_dns_1 supd run --help
The following table describes options specific to the dns container.
Options
Description
--data_host [value]
Hostname or IP address of the data or cache container
--num_metrics_procs
[value]
The number of processors running to collect metrics for
DNS queries
--metrics_flush_interval
[value]
Interval for flushing metrics to the data container
--dns_recv_buffer
[value]
The size in bytes of the UDP receive buffers used by the
dns server. A setting of '0' uses the OS defined default
value.
--num_trex_procs [value]
Number of Authoritative DNS server processes to run
2018 © NS1 Inc.
Page | 12
Private DNS 1.0
--enable_ops_metrics
[value] 
Whether to send operational metrics to the data
container
--operation_mode [value]
Controls whether the server will act as authoritative
server or recursive resolver
--external_resolver
[value] 
IP address of resolver to handle ALIAS record resolution
and queries for non-authoritative zones if recursive
mode is enabled. Builtin resolver will be used if this
option is not specified
--forward_zones [value]
 
Additional zones and their authoritative servers to be
configured in the resolver as forwarded zones. This
allows the zones to be resolved if they are not
delegated from public DNS hierarchy
4.1.4. Web CLI Setup
To see the web container’s unique configuration options, view the usage information of the
run command.
docker exec privatedns_web_1 supd run --help
The following table describes options specific to the web container.
Options
Description
--data_host [value]
Hostname or IP address of data container
--api_hostname [value]
Hostname to use for API calls (bootstrap, organization
management require this to be set)
--portal_hostname
[value]
Hostname to use for portal access
--web_enable_tls [value]
Enable or disable web TLS encryption, to use for
communicating with the portal interface and api.
(defaults to True)
--default_web_tls_settin
gs [value]
Use the predefined TLS settings for web networking.
--manual_web_tls_setting
s [value]
Define the TLS settings for web networking, when using
manually mounted certificates.
--manual_web_tls_cert_bu
ndle [value]
The combined certificate/key PEM file to present, when
communicating between cluster members.
--manual_web_tls_crl_fil
e [value]
The CRL certificate to use for verifying client
certificates revocation status, when communicating
between cluster members.
--manual_web_tls_force_r
edir [value]
Enable or disable forcing redirect of http traffic to
https, for the web facing portal and api. (defaults to
2018 © NS1 Inc.
Page | 13
Private DNS 1.0
True)
--manual_web_tls_client_
cert_verfiy [value]
Whether or not to enforce strict certificate
verification, when communicating between cluster
members.
--manual_web_tls_version
[value]
The minimum TLS version to enforce, when communicating
between cluster members.
--manual_web_tls_ciphers
[value]
The set of TLS ciphers to use, when communicating
between cluster members.
--nameservers [value]
List of default name servers to set as NS records for
new zones. The first server in the list is also used as
primary name server in the SOA record. For example,
['ns1.example.net', 'ns2.example.net'].
--hostmaster_email
[value]
E-mail address to set as hostmaster in the SOA record
for new zones.
4.1.5. Xfr CLI Setup
To see the xfr container’s unique configuration options, view the usage information of the
run command.
docker exec privatedns_xfr_1 supd run --help
The following table describes options specific to the xfr container.
Options
Description
--data_host [value]
 
Hostname or IP address of data container
 
2018 © NS1 Inc.
Page | 14
Private DNS 1.0
4.2. Setup with Web Interface
Each container has a web interface for manual configuration.
4.2.1. Data Setup
To set up the data container via web interface:
1. Open a web browser to https://<data-hostname-ip>:3300
Note: The configuration port 3300 is set in the docker-compose file.
Optional configurations include:
2. Under the Identifiers grouping, enter a Location ID(datacenter/pop) of the server
where the container is run and Server ID to identify the specific host machine of the
container.
3. Under the Operational Details grouping, enter the Number of Metrics Processors
and the Query Metrics TTL to determine how long query metrics are retained.
4. Enable Metrics Export is configured to collect operational telemetry and
application metrics locally by default. Other export options allow metrics to also
feed into the following external data stores: InfluxDB, Elasticsearch, OpenTSDB, and
Graphite.
a. Each additional option besides of Default Internal Metrics requires additional
parameters to ensure successful connection to the external data store.
b. InfluxDB requires a Host, Database Name, Username, InfluxDB Password
and SSL/TLS key information to securely connect.
c. Elasticsearch cluster requires Hosts, Timeout, Index Name, Username,
Password, optional Template, and SSL/TLS information to securely connect.
d. OpenTSDB export requires a Host and Batch Size.
e. Graphite requires a Host, Timeout, Template, and SSL/TLS information to
securely connect.
5. Under the TLS Settings grouping, choosing to use Defaults for Transport TLS and
Management TLS will operate with the system’s self-signed certificates which were
generated on startup.
a. Manual Settings will require either bind mounting the certificates to Xyz or
uploading a certificate bundle by visiting the Certs and Files page.
Important note: If Enable Metrics Export is enabled on other containers, they will send
operational metrics back to data for aggregation and export to other data stores.
2018 © NS1 Inc.
Page | 15
Private DNS 1.0
4.2.2. DNS Setup
Before continuing with the dns container(s), the data container must be configured already.
For each dns container, to set up the dns container via web interface:
1. Open a web browser to https://<dns-hostname-ip>:3301
2. Under the Data Container Connection grouping, enter the Data Host.
3. To configure metrics settings under the Operational Details grouping, choose a
Number of Query Metrics Processors. NS1 recommends at least 2.
4. Enter a Metrics Flush Interval to determine at what interval metrics get sent back
to data. NS1 recommends 10s for this value.
5. Enter a DNS UDP Receive Buffer Length in bytes. A setting of '0' uses the OS
defined default value.
6. Enter the Number of Authoritative DNS Servers. NS1 recommends at least 2.
7. Under Resolving Configuration, toggle whether the container will operate as an
Authoritative Server or Recursive Resolver.
Optional configurations include:
8. Entering a Location ID(datacenter/pop) of the server where the container is run
9. Server ID to identify the specific host machine of the container
10. An External Resolver’s IP can be set to handle ALIAS record resolution and also
queries for non-authoritative zones in Recursive Resolver mode. By default, the
container’s built in resolver will be used if this value is not specified.
11. Forwarded Zones can be added individually with a Domain and one or more
forwarding IP Addresses and Port.
12. Under the TLS Settings grouping, choosing to use Defaults for Transport TLS and
Management TLS will operate with the system’s self-signed certificates which were
generated on startup.
a. Manual Settings will require either bind mounting the certificates to Xyz or
uploading a certificate bundle by visiting the Certs and Files page.
4.2.3. Web Setup
Before continuing with the web container, the data container must be configured already.
To set up the web container via web interface:
1. Open a web browser to https://<web-hostname-ip>:3302
2. Under the Data Container Connection grouping, enter the Data Host.
3. Enter an API Hostname which will be used for feed URLs.
4. Enter a Portal Hostname at which users can reach the NS1 Portal running in the
web container.
2018 © NS1 Inc.
Page | 16
Private DNS 1.0
Optional configurations include:
5. Entering a Location ID(datacenter/pop) of the server where the container is run
6. Server ID to identify the specific host machine of the container.
7. Under the Operational Details grouping, one more more Nameservers can be
added along with a Hostmaster E-mail address to be associated with new zones’
SOA records.
8. Under the TLS Settings grouping, choosing to use Defaults for Transport TLS,
Management TLS , and Web TLS will operate with the system’s self-signed
certificates which were generated on startup.
a. Manual Settings will require either bind mounting the certificates to Xyz or
uploading a certificate bundle by visiting the Certs and Files page.
4.2.4. Xfr Setup
Before continuing with the xfr container, the data container must be configured already. To
set up the xfr container via web interface:
1. Open a web browser to https://<xfr-hostname-ip>:3303
2. Under the Data Container Connection grouping, enter the Data Host.
Optional configurations include:
3. Entering a Location ID(datacenter/pop) of the server where the container is run
4. Server ID to identify the specific host machine of the container
5. Under the TLS Settings grouping, choosing to use Defaults for Transport TLS,
Management TLS , and Web TLS will operate with the system’s self-signed
certificates which were generated on startup.
a. Manual Settings will require either bind mounting the certificates to Xyz or
uploading a certificate bundle by visiting the Certs and Files page.
 
2018 © NS1 Inc.
Page | 17
Private DNS 1.0
5. Administrative Actions
Administrative actions are included with each container for operations such as restarting a
service or creating backups.
5.1. Admin Actions with CLI
Actions can be executed on the command line for each container.
5.1.1. Data CLI Actions
To see available actions of the dns container, view the usage information of supd.
docker exec privatedns_data_1 supd --help
The following table describes action commands.
Commands
Description
generate_runtime_logs
Generates an archive of runtime reports in
/ns1/data/log/health/
update_basic_auth
[options] 
Sets and updates your basic authorization credentials to
the container’s configuration UI
backup_db
Dumps database to data/backup/<timestamp>.tgz
restart_maindb
This will cause an outage for API and XFR (zone
transfer) services.
restart_metricsdb
This will cause an outage for metrics.
restart_msg_svs
This will cause an outage for data container services.
restart_metrics_svs
This will cause an outage for operational metrics.
restart_in_mem_db
This will cause an outage for creation of portal
sessions
health [options]
run all health checks. returns a json-formatted
object in k:v format
version
print the standalone version number.
You can also use -V. versionfile is located at
/etc/version
run [options]
run ansible via flags or environment variables.
flags supercede environment vars.
Defaults to ignoring existing config.yml
viewconfig [options]
Lists all current config parameters; adding -a will
display all available parameters, even null values
2018 © NS1 Inc.
Page | 18
Private DNS 1.0
5.1.2. DNS CLI Actions
To see available actions of the dns container, view the usage information of supd.
docker exec privatedns_dns_1 supd --help
The following table describes action commands.
Commands
Description
generate_runtime_logs
Generates an archive of runtime reports in
/ns1/data/log/health/
update_basic_auth
[options] 
Sets and updates your basic authorization credentials to
the container’s configuration UI
restart_dns
This will cause an outage for DNS.
restart_caching 
This will cause DNS caching to be delayed.
restart_metrics 
This will cause an outage for metrics reporting.
restart_resolver
This will cause an outage for DNS
health [options]
run all health checks. returns a json-formatted
object in k:v format
version
print the standalone version number.
You can also use -V. versionfile is located at
/etc/version
run [options]
run ansible via flags or environment variables.
flags supercede environment vars.
Defaults to ignoring existing config.yml
viewconfig [options]
Lists all current config parameters; adding -a will
display all available parameters, even null values
5.1.3. Web CLI Actions
To see available actions of the the web container, view the usage information of supd.
docker exec privatedns_web_1 supd --help
The following table describes action commands.
Commands
Description
generate_runtime_logs
Generates an archive of runtime reports in
/ns1/data/log/health/
update_basic_auth
Sets and updates your basic authorization credentials to
2018 © NS1 Inc.
Page | 19
Private DNS 1.0
[options] 
the container’s configuration UI
restart_apid
Restarting the API Service will cause an outage for the
API.
health [options]
run all health checks. returns a json-formatted
object in k:v format
version
print the standalone version number.
You can also use -V. versionfile is located at
/etc/version
run [options]
run ansible via flags or environment variables.
flags supercede environment vars.
Defaults to ignoring existing config.yml
viewconfig [options]
Lists all current config parameters; adding -a will
display all available parameters, even null values
5.1.4. Xfr CLI Actions
To see available actions of the xfr container, view the usage information of supd.
docker exec privatedns_xfr_1 supd --help
The following table describes action commands.
Commands
Description
generate_runtime_logs
Generates an archive of runtime reports in
/ns1/data/log/health/
update_basic_auth
[options] 
Sets and updates your basic authorization credentials to
the container’s configuration UI
restart_xfr_svs
This action restarts zone transfer services. Zone
transfers will be unavailable during the restart.
health [options]
run all health checks. returns a json-formatted
object in k:v format
version
print the standalone version number.
You can also use -V. versionfile is located at
/etc/version
run [options]
run ansible via flags or environment variables.
flags supercede environment vars.
Defaults to ignoring existing config.yml
viewconfig [options]
Lists all current config parameters; adding -a will
display all available parameters, even null values
2018 © NS1 Inc.
Page | 20
Private DNS 1.0
5.2. Admin Actions with the Web Interface
Actions are found on their own tab of each container configuration page.
5.2.1. Data Actions
The container’s actions can be executed from the Actions tab of the Configuration Manager
page.
Actions
Description
Generate Runtime Report
Generates an archive of runtime reports in
/ns1/data/log/health/
Set Basic Auth
Credentials 
Sets and updates your basic authorization credentials to
the container’s configuration UI
Backup Database
Dumps database to data/backup/<timestamp>.tgz
Restart Main Database
This will cause an outage for API and XFR (zone
transfer) services.
Restart Metrics Database
This will cause an outage for metrics.
Restart Messaging
Service 
This will cause an outage for data container services.
Restart Metrics Service
This will cause an outage for operational metrics.
Restart in Memory
Database 
This will cause an outage for creation of portal
sessions
5.2.2. DNS Actions
The container’s actions can be executed from the Actions tab of the Configuration Manager
page.
Actions
Description
Generate Runtime Report
Generates an archive of runtime reports in
/ns1/data/log/health/
Set Basic Auth
Credentials 
Sets and updates your basic authorization credentials to
the container’s configuration UI
Restart Authoritative
DNS Servers
This will cause an outage for DNS.
2018 © NS1 Inc.
Page | 21
Private DNS 1.0
Restart Caching Service
This will cause DNS caching to be delayed.
Restart Metrics Service
This will cause an outage for metrics reporting.
Restart Recursive DNS
Service
This will cause an outage for DNS
5.2.3. Web Actions
The container’s actions can be executed from the Actions tab of the Configuration Manager
page.
Actions
Description
Generate Runtime Report
Generates an archive of runtime reports in
/ns1/data/log/health/
Set Basic Auth
Credentials 
Sets and updates your basic authorization credentials to
the container’s configuration UI
Restart API Service
Restarting the API Service will cause an outage for the
API.
5.2.4. Xfr Actions
The container’s actions can be executed from the Actions tab of the Configuration Manager
page.
Actions
Description
Generate Runtime Report
Generates an archive of runtime reports in
/ns1/data/log/health/
Set Basic Auth
Credentials 
Sets and updates your basic authorization credentials to
the container’s configuration UI
Restart XFR Service
This action restarts zone transfer services. Zone
transfers will be unavailable during the restart.
 
2018 © NS1 Inc.
Page | 22
Private DNS 1.0
6. Import New GeoIP Data
The dns container images ships with a built-in GeoIP database to facilitate geographic
routing. This authoritative nameserver is populated from the free version of Maxmind
GeoIP2’s database files which NS1 has licensed for redistribution.
If available, a paid version of Maxmind’s GeoIP database files can be uploaded to each dns
container for more precise geo routing.
Important note: The dns container currently supports binary databases formatted
according to MaxMind DB File Format Specification v2.0.
1. Open a web browser to the dns container’s Certs and Files page.
2. Replace the default GeoIP-City.mmdb file by selecting Upload, browse to the file,
and select Open.
3. Replace the default GeoIP-ASN.mmdb file by selecting Upload, browse to the file,
and select Open.
4. Navigate to the Configuration Manager page, select the Actions tab, and select
Restart Authoritative DNS Service. When successfully restarted, the new GeoIP
data is loaded.
7. Upgrading
When a new version of a container is released, admins may choose to upgrade the docker
containers to apply the latest features and bug fixes to the system.
If a new version of one or more container images is available, admins should download the
images from https://my.nsone.net/. All containers can be updated at once with
docker-compose.
In the docker-compose.yml file, the ${TAG} parameter allows you to choose the image tag
at the command line. For example,
1. First, stop the system.
docker-compose -p privatedns stop
2. Remove the existing images and volumes.
docker-compose -p privatedns rm && docker volume prune
2018 © NS1 Inc.
Page | 23
Private DNS 1.0
3. And finally, bring the system up again passing in a different image tag at the
command line. In the docker-compose.yml file, the ${TAG} parameter allows you to
choose the image tag at the command line.
TAG=1.0.1 docker-compose -p privatedns up -d
Important note: Rollback to previous versions is also possible using the same process and
specifying the previous container image (e.g. 1.0.0).
8. Uninstalling
System uninstallation is simple. To remove the entire system, including volume data,
execute the following:
docker-compose -p privatedns down -v
Important note: This command is destructive and will remove volumes. Ensure data is
backed up appropriately.
 
2018 © NS1 Inc.
Page | 24
Private DNS 1.0
9. Appendix A. Bootstrap an Operator
When no operators exist in the main database, the bootstrap endpoint is enabled. Once
the system is ready for use, an initial operator must be boostrapped. Below is an example
cURL command.
curl -X POST \
https://{{web-host}}/v1/ops/bootstrap \
-H 'Content-Type: application/json' \
-d '{
"user": "root",
"name": "Root Operator",
"email": "ops@example.com",
"password": "rootpassword"
}'
Important Notes:
Bootstrap can only be performed once.
Save the API Key (key) and 2FA Secret (secret) of the first operator created during
bootstrap. If the API Key is lost and no other operators are created yet, the system is
rendered unmanageable and a new instance must be deployed.
The options -k or --insecure are needed on a cURL command if a valid SSL/TLS
certificate has not been uploaded for use by the web container. See Transport Layer
Security for more information about adding custom certificates.
Password length should be between 10 and 255 characters.
If the operator was successfully added, a JSON response will provide information such as
the 2FA Secret and API Key. For example,
{
"two_factor_auth": { "secret": "{{2fasecret}}", "type": "totp" },
"name": "Operator Name",
"id": "5b11a509d4f9fa0e5ec1373d",
"user": "operator",
"key": "{{operator_api_key}}",
"last_access": "2018-06-01T19:56:56.604228",
"password": "L0R3M1PSUm",
"email": "operator@example.com"
}
 
2018 © NS1 Inc.
Page | 25
Private DNS 1.0
10. Appendix B: Managing Operators
After bootstrap, other operator users can be added to the system. An operator user has full
access to every operation and all system data.
Important note: It is highly recommended to add additional operator users after
bootstrapping the first operator. If the bootstrapped operator’s API Key is lost and no other
operators are created yet, the system is rendered unmanageable and a new instance must
be deployed.
10.1. View Operator(s)
curl -X GET \
https://{{web-host}}/v1/ops/operators/{{id}} \
-H 'X-NSONE-Key: {{operator_api_key}}'
10.2. Create an Operator
curl -X PUT \
https://{{web-host}}/v1/ops/operators \
-H 'X-NSONE-Key: {{operator_api_key}}\
-d '{
"user": "operator",
"name": "Operator Name",
"email": "ops@email.com",
"password": "mypassword"
}'
10.3. Update an Operator
curl -X POST \
https://{{web-host}}/v1/ops/operators/{{id}} \
-H 'Content-Type: application/json' \
-H 'X-NSONE-Key: {{operator_api_key}}' \
-d '{
"name": "Changed Name",
"email": "changed@email.com"
}'
10.4. Delete an Operator
curl -X DELETE \
https://{{web-host}}/v1/ops/operators/{{id}} \
-H 'X-NSONE-Key: {{operator_api_key}}'
2018 © NS1 Inc.
Page | 26
Private DNS 1.0
Important note: Operators cannot delete their own accounts from the system. This
ensures bootstrapping system users is a one-time event.
2018 © NS1 Inc.
Page | 27
Private DNS 1.0
11. Appendix C: Managing Organizations
With the exception of operators, all users, zones, and records belong to an organization. To
continue with the initial setup of Private DNS, an operator must create the first
organization using the 'PUT' API call (Section 11.3) below.
11.1. View Organizations
curl -X GET \
'https://{{web-host}}/v1/ops/orgs' \
-H 'X-NSONE-Key: {{operator_api_key}}'
11.2. View an Organization
curl -X GET \
'https://{{web-host}}/v1/ops/orgs/{{org_id}}' \
-H 'X-NSONE-Key: {{operator_api_key}}'
11.3. Creating an Organization
curl -X PUT \
'https://{{web-host}}/v1/ops/orgs' \
-H 'X-NSONE-Key: {{operator_api_key}}' \
-d '{"name": "Organization Name"}'
In response, an org_id is created along with a unique object id. The first organization in
the Private DNS instance is set to 2000.
{
"org_id": 2000,
"name": "Organization Name",
"id": "5b16cb703ca56f"
}
11.4. Update an Organization
curl -X POST \
'https://{{web-host}}/v1/ops/orgs/{{org_id}}' \
-H 'X-NSONE-Key: {{operator_api_key}}' \
-d '{"name": "New Organization Name"}'
2018 © NS1 Inc.
Page | 28
Private DNS 1.0
11.5. Delete an Organization
Deleting an organization removes all data associated with the organization including: API
Keys, Users, Teams, Zone and Record data. For this reason, the DELETE operation can only
be performed using an operator user’s 2-factor authentication (2FA) token.
Important note: An operator’s 2FA secret was returned in response to operator creation.
A 2FA token can then be generated with any 6-digit TOTP generator that rotates at
30-second intervals.
curl -X DELETE \
'https://{{web-host}}/v1/ops/orgs/{{org_id}}?token={123456}' \
-H 'X-NSONE-Key: {{operator_api_key}}'
11.6. Reset a User’s Password
Operators can generate a new invite token for users if passwords are forgotten.
curl -X POST \
'https://{{web-host}}/v1/ops/account/{{org_id}}/user/{{user-name}}/password/reset' \
-H 'X-NSONE-Key: {{operator_api_key}}'
 
2018 © NS1 Inc.
Page | 29
Private DNS 1.0
12. Appendix D: Managing API Keys, Users &
Teams
API Keys, Users, and Teams are objects within an organization. Each can be managed by an
organization member with sufficient privileges; however, operators also have the ability to
act on behalf of an organization. This is necessary when setting up the first organization’s
users or API keys.
If an operator is acting on behalf of an organization, appending exclamation point (!) plus
the org_id (e.g. !2000) to an API key allows use of other endpoints described in NS1’s
Managed DNS API Documentation.
12.1. Example: Adding a New User to an Organization as
Operator
For example, an operator can add a user with the following cURL command:
curl -X PUT \
'https://{{web-host}}/v1/account/users/newuser' \
-H 'X-NSONE-Key: {{operator_api_key}}!{{org_id}}' \
-d '{"username":"newuser", "name":"New User","email":"newuser@exmple.com"}'
In response an invite token is generated for this user to set a password:
{
"username": "newuser",
"notify": {
"billing": false
},
"permissions": {},
"invite_token": "{{new_invite_token}}",
"ip_whitelist_strict": false,
"name": "New User",
"teams": [],
"ip_whitelist": [],
"last_access": null,
"2fa_enabled": false,
"email": "newuser@example.com"
}
An operator can then send an invitation URL to the portal user for setting an initial
password.
2018 © NS1 Inc.
Page | 30
Private DNS 1.0
https://{{web-host}}/#/invite/{{new_invite_token}}
12.2. Example: Adding a Zone as Operator User
And a zone can be added for an organization’s account using the following cURL command:
curl -X PUT \
'https://{{web-host}}/v1/zones/newzone.com' \
-H 'X-NSONE-Key: {{operator_api_key}}!{{org_id}}' \
-d '{"zone":"newzone.com", "nx_ttl":60}'
In the same way an operator can use the API on behalf of an organization, the operator can
also sign into the Private DNS portal by appending exclamation point (!) and org_id to the
operator username of the login page.
Important notes:
An operator singing into the portal on behalf of an organization is required to
provide a 2-factor authentication (2FA) token.
An operator’s 2FA secret was returned in response to operator creation. A 2FA token
can then be generated with any 6-digit TOTP generator that rotates at 30-second
intervals.

2018 © NS1 Inc.
Page | 31
Private DNS 1.0
13. Appendix E: Unavailable API Endpoints in
Private DNS
The NS1 Managed DNS API Documentation describe endpoints which are not applicable to
Private DNS including those pertaining to Account billing and overages. These endpoints
will return a 404: Not Found response. The following is a list of non-applicable endpoints:
Monitoring & Notifications
Monitoring Job endpoints
Notification List endpoints
Account Management
Overage Alert endpoints
Plan and Billing endpoints
Payment method endpoints
Pulsar
All Pulsar endpoints
 
2018 © NS1 Inc.
Page | 32
Private DNS 1.0
14. Appendix F: System Topologies
In a typical Private DNS deployment, core services (web, xfr, and data containers) are run in
a control or “core” node. In an on-premise deployment, the system’s core node is typically
deployed to the enterprise’s primary data. There can be (and usually are) more than one
dns container running at the system’s edge in “edge nodes”. For local development or a
proof of concept deployment, it is possible to run all containers on one host machine;
however, it is recommended that at leastdns be on its own host.
14.1. Architecting for Highly Available DNS
When initialized, each dns container caches authoritative zones and records; therefore, dns
containers can continue serving DNS responses even if the system core services are
unavailable. Depending on organization resources, prior experience, and preference,
network administrators typically choose one of two strategies to achieve high availability
(HA) of DNS services: anycasting with BGP or employing application- or appliance-based
load balancers.
Important note: No matter the chosen HA strategy, when setting up more than one DNS
service in multiple geographically distributed DNS nodes, filling in the Location ID and
Server ID should be used to properly identify the host machine.
2018 © NS1 Inc.
Page | 33

Navigation menu