Install NicTool with Docker - nosolutions/NicTool GitHub Wiki


This guide is unfinished. When completed, this message will be removed.


This guide will go into how to build and run NicTool with the Dockerfiles in the repo. This is not intended to be a tutorial on Docker itself and doesn't cover installation and set up of Docker. At the end of this guide, an example using Docker Compose to coordinate running of the individual components is included.

This guide separates the responsibilities of NicTool into two main components/containers:

  • web - The web components of NicTool, running both the client, server and exporter with Apache2 in a single container. supervisord is used to handle both Apache and cron processes.
  • db - The MySQL database.

Set Up Networking

Set up a bridge network that the NicTool container and the MySQL container can use to talk to one another.

sudo docker network create nictool

This creates a new bridge network called "nictool" (you can choose another name if you wish). DNS resolution within this network is automatic and done by container name - the subdomain is the network name. So if you were to spin up a database on this network with a container name of db01, the FQDN of the container would be db01.nictool - even though it's not necessary to fully qualify when resolving.

Set Up the Database

This step is required before you set up the container for NicTool.

As NicTool depends on MySQL, a separate container will need to be run for the database. Alternatively, the container can just talk to a pre-existing MySQL installation. This guide covers running a MySQL container alongside the NicTool container.

For compatibility reasons, the 5.5 tag of the official MySQL docker image is used. 5.6 may work, but 5.7 does not work yet.

While the MySQL image creates volumes on its own when you first run it as a container, it's a little more sane to create a named volume for the container to use rather than using the default.

sudo docker volume create nt_data

This creates a volume named nt_data - the absolute path on the Docker host will be /var/lib/docker/volumes/nt_data/_data - when we start the container, we'll tell it to map our named volume to /var/lib/mysql in the container. This essentially allows database data to persist across container stops/starts etc.

WARNING: With MySQL, starting a new database container that maps to an existing volume with data in it will likely cause the new database container to crash.

The final step before running the database container is choosing a MySQL root password. Per the docs for the official MySQL Docker image, this is a required environment variable that must be passed to the container the first time it's run. Once you've chosen a password, start the container.

sudo docker run -d -v nt_data:/var/lib/mysql --net=nictool --name=nictool-db -e MYSQL_ROOT_PASSWORD=my-secret-pw mysql:5.5

There's a lot going on with this command, so the options will be outlined below for clarity. When you run this in production, some of these options you're going to want to keep track of.

  • docker run - Runs a container on a specified image. If the image is not found locally it will be pulled from Docker Hub.
  • -d - Runs the container in detached mode.
  • -v nt_data:/var/lib/mysql - Maps the nt_data named volume to /var/lib/mysql within the container.
  • --net=nictool - Connects the container to the nictool network.
  • --name=nictool-db - Sets the container's name. If left out, a name will be automatically chosen. Keep track of this for production
  • -e MYSQL_ROOT_PASSWORD=my-secret-pw - Sets the MYSQL_ROOT_PASSWORD environment variable to my-secret-pw and passes it into the container. Keep track of this for production.
  • mysql:5.5 - Specifies the name of the image and its tag, which is 5.5. If the tag is left out, the latest tag is implied.

If all goes well, you should have your database container up and running. Verify with docker ps.

NOTE: No port mappings have been performed here because the assumption is that only NicTool will talk to this database over the nictool bridge network, but if desired you can expose TCP:3306 in order to access the database from elsewhere outside the docker host.

Set Up NicTool

During the build, the NicTool Dockerfile does the following things for you:

  • Runs Debian 8.8 as a base
  • Installs any system dependencies for running NicTool
  • Sets up the NicTool database
  • Creates a nictool user
  • Generates a self-signed SSL certificate that Apache will use for NicTool
  • Copies two run scripts for two nameservers for automated exports via cron (more on this later)
  • Installs the crontab for the automated exports
  • Generates an SSH key for the nictool user to be installed in authorized_keys on your DNS servers

The nt_vars File

The Dockerfile uses some environment variables that are copied to the image and sourced during the build process. These variables are stored in a file called nt_vars within the conf subdirectory. After the variables are used, the file is deleted from the image and the variables are unset. Here's a list of each environment variable and what it needs to be set to:

  • DB_HOSTNAME - the hostname of the database (the value set for this MUST match the container name you specified for your database earlier)
  • DB_ROOT_PASSWORD - the MySQL root password (the value set for this MUST match the MYSQL_ROOT_PASSWORD environment variable you used when you started your MySQL container)
  • NICTOOL_DB_NAME - the name for the NicTool database
  • NICTOOL_DB_USER - the MySQL user for the NicTool database
  • NICTOOL_DB_USER_PASSWORD - the password for the MySQL user for the NicTool database
  • ROOT_USER_EMAIL - the e-mail address for the root user of the NicTool Web UI
  • ROOT_USER_PASSWORD - the password for the root user of the NicTool Web UI
  • CERT_CN - The CN (FQDN) for the self-signed SSL cert
  • CERT_COUNTRY - The two-letter country code for the self-signed SSL cert
  • CERT_STATE - The state/province for the self-signed SSL cert
  • CERT_LOCALITY - The city/locality for the self-signed SSL cert
  • CERT_ORG - The company name for the self-signed SSL cert
  • CERT_OU - The organizational unit for the self-signed SSL cert
  • CERT_EMAIL - The email address to be used for the self-signed SSL cert

Here's an example of a complete nt_vars file:

ROOT_USER_EMAIL="[email protected]"
CERT_EMAIL="[email protected]"

export CERT_CN
export CERT_ORG
export CERT_OU

Other Configuration Files

In addition to the nt_vars file, a few other files are required to build the container:

  • nictool.conf - the Apache vhost declarations for NicTool. You MUST edit this to change the ServerName directives to fit your environment.
  • nictoolclient.conf - NicTool client configuration. You can edit this, but the defaults are usually fine.
  • nictoolserver.conf - NicTool server configuration. You MUST edit this to reflect your database connection settings.
  • crontab - The crontab file used for automated exports.
  • supervisord.conf - The configuration file used for supervisord.
  • run_ns\d - By default two of these are included and set to query the NicTool database for NSID's 4 and 5. You can add more nameservers if you wish - you would need to modify the following files:
    • Dockerfile
    • crontab
    • The run script itself to query for additional nameservers.

Building the Image

In order for to run when you build the NicTool image for the first time, you'll need to attach it to the bridge network you created earlier. You can do this on the command line.

sudo docker build --network=nictool -t nictool-web .

The -t nictool-web specifies the tag for the created docker image. Since there's no specified version (eg nictool-web:1.0) then the latest tag is implied here.

Running the Image

After the build process completes, fire up the image, exposing port 80 and 443. You'll also need to attach it to your bridge network so the webserver can communicate with the database server.

sudo docker run -d -p 80:80 -p 443:443 --net=nictool --name=nictool-web nictool-web

You should now be able to access NicTool in a browser by accessing the IP or FQDN of your Docker host. Note: If you also want to expose the port for the SOAP API from the container to the Docker host, you could add another -p 8082:8082 flag to the commandline.

Once the image is running, log into the NicTool web UI with the root user and password, then delete the default configured nameservers, and add your own.

Automated Exports / Nameserver Setup

(The following assumes Debian and no previous nictool user)

As mentioned previously, cron is used to push data out to configured nameservers. Make sure there's a nictool account and you update its ~/.ssh/authorized_keys. If running BIND, you'll want to make sure the user is also in the bind group (and also make sure your permissions are good for the data directory you set for the nameserver in the web UI).

export NTE_USER=nictool
adduser $NTE_USER
usermod -a -G bind $NTE_USER

If you want, you can also add this to the bottom of /etc/ssh/sshd_config to prevent password-based auth as the nictool user.

Match user nictool
PasswordAuthentication no

Now you can set up authorized_keys and paste in the dumped public key from the image build.

su - -s /bin/bash nictool
vim .ssh/authorized_keys
chmod 600 .ssh/authorized_keys

That should wrap up any setup needed on the nameservers.

The rest of the steps to turn on automated exports involve modifying the Makefiles for your configured nameservers within the container itself.

docker exec -it nictool-web /bin/bash

nano /usr/local/nictool/ns1/data-{NAMESERVER}/Makefile
nano /usr/local/nictool/ns2/data-{NAMESERVER}/Makefile

Where here {NAMESERVER} is the FQDN of the nameserver you configured in the web UI. From here on out (and using BIND as an example) just uncomment the rsync/ssh targets and you should be good to go.