Install NicTool with Docker - nosolutions/NicTool GitHub Wiki
IMPORTANT
This guide is unfinished. When completed, this message will be removed.
Overview
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 thent_data
named volume to/var/lib/mysql
within the container.--net=nictool
- Connects the container to thenictool
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 theMYSQL_ROOT_PASSWORD
environment variable tomy-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, thelatest
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 inauthorized_keys
on your DNS servers
nt_vars
File
The 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 theMYSQL_ROOT_PASSWORD
environment variable you used when you started your MySQL container)NICTOOL_DB_NAME
- the name for the NicTool databaseNICTOOL_DB_USER
- the MySQL user for the NicTool databaseNICTOOL_DB_USER_PASSWORD
- the password for the MySQL user for the NicTool databaseROOT_USER_EMAIL
- the e-mail address for the root user of the NicTool Web UIROOT_USER_PASSWORD
- the password for the root user of the NicTool Web UICERT_CN
- The CN (FQDN) for the self-signed SSL certCERT_COUNTRY
- The two-letter country code for the self-signed SSL certCERT_STATE
- The state/province for the self-signed SSL certCERT_LOCALITY
- The city/locality for the self-signed SSL certCERT_ORG
- The company name for the self-signed SSL certCERT_OU
- The organizational unit for the self-signed SSL certCERT_EMAIL
- The email address to be used for the self-signed SSL cert
Here's an example of a complete nt_vars
file:
DB_HOSTNAME="nictool-db"
DB_ROOT_PASSWORD="sup3rs3kr1t"
NICTOOL_DB_NAME="nictool"
NICTOOL_DB_USER="nictool"
NICTOOL_DB_USER_PASSWORD="n1ct00l!"
ROOT_USER_EMAIL="[email protected]"
ROOT_USER_PASSWORD="d3adb33f"
CERT_CN="nictool-web.example.com"
CERT_COUNTRY="US"
CERT_STATE="Virginia"
CERT_LOCALITY="Richmond"
CERT_ORG="ACME Inc."
CERT_OU="IT"
CERT_EMAIL="[email protected]"
export DB_HOSTNAME
export DB_ROOT_PASSWORD
export NICTOOL_DB_NAME
export NICTOOL_DB_USER
export NICTOOL_DB_USER_PASSWORD
export ROOT_USER_EMAIL
export ROOT_USER_PASSWORD
export CERT_CN
export CERT_COUNTRY
export CERT_STATE
export CERT_LOCALITY
export CERT_ORG
export CERT_OU
export CERT_EMAIL
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 theServerName
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 forsupervisord
.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 create_tables.pl
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
ssh-keygen
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.