This is the Docker Environment for the open source network managament plattform OpenNMS. It is designed for testing purposes and smaller production setups and provides the following software:
-
OpenNMS
-
PostgreSQL
-
Nginx
-
Alarmforwarder
-
Cassandra
-
Grafana
-
yourDashboard
The environment is based on Docker Engine and Docker Compose. All related Docker Images are provided on Docker Hub.
The script container_generator.py creates an environment based on a few questions (e.g. which images should be used, which passwords should be set for OpenNMS, …). The result contains a generated docker_compose.yml file and an init directory, which contains some configuration, that will be loaded on the environment’s first start.
The environment’s base is OpenNMS, PostgreSQL and Nginx. Nginx provides a central SSL reverse proxy for all webservers of the environment (e.g. OpenNMS WebUI, or Grafana WebUI,…). A management container can be accessed via SSH to change configuration files.
The Docker Environment (especially the setup of Docker Engine and Docker Compose) was tested with CentOS 7. It should also run on other distributions, maybe some changes on the setup of Docker Engine/Docker Compose are required.
The following points are known limitations and issues:
- Only small/medium sized environments
-
The Docker Environment has only been tested with running all the containers on one physical host. So, it is designed and tested for small and medium sized OpenNMS environments, where all the software can run on one host. In the future, there may be a cluster support.
- OpenNMS Horizon only
-
Currently, only OpenNMS Horizon is supported, but in the future, Meridian support will be available.
- Cassandra support for testing only
-
Cassandra support is only for testing purposes at the moment, as there is only one container which handles all the data.
- IPV6 NAT support
-
IPv6 support is provided with the ipv6helper container, which provides IPv6 NAT from the particular containers to the outside world. At this time, an incomming IPv6 connection from outside to the containers is not supported.
For the generation of the Docker Environment, the software Docker Engine and Docker Compose should be installed. After that, simply use the env_bootstrap/docker_compose.yml file to start the Generation Environment:
cd env_bootstrap
docker-compose up -dYou can then connect to the started container via SSH using the following command and the password secret1234:
ssh -p 2223 root@127.0.0.1In the box, start the script container_generator.py:
cd /opt/opennms-docker-env/scripts/container_generator/
./container_generator.pyThe script asks for some parameters for the generation of the environment and creates an output directory which contains the following data:
-
docker-compose.yml
-
init directory for initializing of the defined containers
-
if defined: download of the docker images
-
if defined: download of the required software (Docker Engine, Docker Compse)
-
if defined: install.sh for Docker Images and Docker Engine/Docker Compose setup
The generated environment can be installed on any latest Linux distribution. It has been tested under Centos 7. Simply use the files from the output directory. Execute install.sh to install Docker Engine, Docker Compose and the required images:
./install.shYou can now start the generated environment with docker-compose:
docker-compose up -dBy default, Docker Engine creates a network interface named docker0 with an IP address 172.17.0.0/16. If you need to change it, please create the following configuration file /etc/docker/daemon.json:
{
"bip": "192.168.0.1/24"
}Sometimes, it is required to move the OpenNMS RRD data to another physical disc, to improve the I/O performance. To do so in the Docker Environment, find the mountpoint of the RRDs with docker volume inspect:
docker volume inspect <opennms volume>After that, stop the environment, move the RRD files to the other disk, create a symbolic link and start the environment again. For example, if the mountpoint of the OpenNMS RRD volume is /var/lib/docker/volumes/output_rrd/_data, and the mountpoint of the other physical disk is _/mnt/opennms-rrd, you’ll can do the following:
docker-compose down
mv /var/lib/docker/volumes/output_rrd/ /mnt/opennms-rrd
ln -s /mnt/opennms-rrd /var/lib/docker/volumes/output_rrd/
docker-compose up -dThe Docker Environment can be managed by using the management container. It provides an SSH server which can be acccessed with the following command and the password chosen during the setup:
ssh -p 2222 root@hostIt contains some nice tools (e.g. ping, traceroute, telnet, snmpwalk, …) and access to the data and configuration files of all containers in /data/all-containers. It also contains a docker client to start/stop containers.
The following section describes the operational concepts of the Docker Environment.
To migrate an existing OpenNMS installation into the new Docker Environment, the following steps are required:
-
Back up the existing installation
-
Setup the OpenNMS Docker Environment, but do not start the environment yet
-
Place the (migrated, if necessary) data of the existing installation in the init directory of the Docker Environment
-
Start the environment
At first, the data of an existing setup must be secured. For OpenNMS, there are the configuration files, a database dump, RRD files and (if necessary) further files. If a version upgrade should be done with the migration, the secured data must also be migrated for the new version.
After that, the OpenNMS Docker Environment must be installed, but should not be started yet. The environment has the directory init, which contains a subdirectory for every container. The data for initializing of the environment must be placed there. Please see the section Import and Export of Data to see the directory structure for each container. On the environment’s first start, these data will be imported one-time (they will be copied and can be deleted from the init directory). The environment with the imported data can now be used.
Configuration changes for OpenNMS and the other provided software can be done with the management container. You can connect via SSH into the management container and find the data of all other containers in /data/all-containers/<container name>. Simply change the configuration files you like and restart the required container by using the docker commands:
docker ps
docker stop <container-name>
docker start <container-name>A docker ps returns a list with all running docker containers. You can also find the container name in the list. The docker start/stop commands will stop and start the container.
A manual backup of the Environment can be done by executing the following command in the management container:
/opt/managerscripts/command_for_all.sh exportWhen the backup has finished, the exported data are located in /data/export (in management container or on the named volume) and can be copied to an external storage medium.
A daily backup to a SMB fileserver or FTP server can also be done automatically using a cronjob. Simply use the environment variables of the management container:
CONF_BACKUP_ENABLED = TRUE
CONF_BACKUP_URL = smb://user:password@server/share/directory
#or in case of a FTP server:
CONF_BACKUP_URL = ftp://user:password@server/directoryA daily cronjob will execute the backup at 09:00 p.m. to the configured target.
|
Tip
|
The container_generator script will also ask you for the parameters above and can create the required configuration. |
A restore of the whole environment on a new hardware requires the following data:
-
supported operating system
-
generated Docker Environment in the original version (Docker Engine, Docker Compose, Docker Images, docker-compose.yml and the init directory)
-
backup of the environment
The generated Docker Enviroment consists of the following directoy structure:
docker-compose.yml
/init
/opennms
/postgres
/<...>The following steps has to be done for a restore:
-
setup of the operating system
-
setup of the generated Docker Environment (Docker-Engine, Docker Compose, images, configuration)
-
replacement of the init directory of the generated environment with the backup
-
start of the environment
A major update contains a change of the major version of OpenNMS. The database schema and configuration files needs to be migrated. For a major update, the following steps needs to be done:
-
preparation within a testing environment
-
creation of a new version of the Docker Environment
-
data export from the existing environment
-
migration of the exported data in the testing environment
-
-
update on live system
-
creation of a new version of the Docker Environment with the migrated data
-
stop of the old environment
-
start of the new environment
-
First of all, a testing environment with the new version of the Docker Environment will be created. After that, a data export from the existing environment will be done. The following command needs to be executed on the management container:
/opt/managerscripts/command_for_all.sh exportIn the testing environment, the exportet data will now be migrated step by step (e.g. OpenNMS configuration files, but also files from further containers). The intention is, to create the Docker Environment in a new version with the following directory structure:
docker-compose.yml
/init
/opennms #(1)
/postgres #(2)
/<...>-
migrated data for container OpenNMS
-
migrated data for container Postgres
If the migration has been finished and all tests have been passed successfully, the created environment with the migrated data can be installed in the live system. It is very important, that the parent directory for the new Docker environment has an other name as the parent directory for the existing environment. For example:
/opt
/onmsenv
/v1 #(1)
docker-compose.yml
/init
/opennms
/<...>
/v2 #(2)
docker-compose.yml
/init
/opennms
/<...>-
version 1 of the Docker Environment. Will also be used for the name prefix of named volumes.
-
version 2 of the Docker Environment. Will also be used for the name prefix of named volumes.
|
Tip
|
The name of the parent directory (e.g. v1 or v2) will also be used as prefix for the names of named volumes. Because of the diffetent names, you can switch between the environments on any time during the following steps. |
The old Docker Environment can now be stopped on the live system with the following commands:
cd /opt/onmsenv/v1
docker-compose downNow, the neu version can be started:
cd /opt/onmsenv/v2
docker-compose up -dIf all tests have beed passed successfully and the new environment is stable, the old names volumes can be deleted:
docker volume rm v1_opennms v1_postgres [...]The update has been done.
A minor update only contains a change of a minor version of OpenNMS or further add-ons. Existing data does not need to be migrated. Thus, the preparation in a testing environment is not required and the update can be done in a simpler and faster way.
|
Warning
|
Also a minor update should be prepared carefully und the general process should be tested in a testing environment. |
The following steps needs to be done for a minor update:
-
creation of a new version of the Docker Environment
-
setup of the environment on the live system
-
data export from the existing environment
-
replacement of the init directory of the generated environment with the export
-
stop of the old environment
-
start of the new environment
The particular steps correspond to the steps described in section Major Update
The import of data into the OpenNMS Docker Environment will only be done during the initializing on the container’s first start. All files in the directory data/init of the container will be included. Every container will only import his own data. For example, the OpenNMS container does only import the OpenNMS configuration files, while the OpenNMS database will be imported into the Postgres container. The structure in /data/init depends on the given container and will be described in the next sections of this document. The environment created by container_generator has the following structure:
docker-compose.yml
/init
/opennms #(1)
/postgres #(2)
/<...>-
Will be mapped in container OpenNMS to /data/init
-
will be mapped in container Postgres to /data/init
Data export of the Docker Environment will be done by executing the following command in the management container:
/opt/managerscripts/command_for_all.sh exportThis will execute the script /opt/containerscripts/export.sh in every container of the docker environment. The export.sh script exports the data for the particular container into the /data/export/<container>/ directory. In the generated Docker Environment, the directory /data/export/ mapped into all container as named volume.
|
Tip
|
The structure of /data/export matches with the structure of /data/init, which can be used to import data into a new environment. So, exported data can be reimported easily. |
The following sections describe the import of data for the containers.
The following directories can be used to initialize the OpenNMS container:
docker-compose.yml
/init
/opennms
/etc
/rrd
/lib_add
/web_addIn etc, OpenNMS configuration files can be placed for an import. Please consider the following points, when importing configuration files:
-
differences between OpenNMS versions
-
in some config files, the full path of the configuration directory is hard coded(e.g.: /var/lib/opennms/rrd vs. /opt/opennms/share/rrd)
-
some configuration files in the Docker environment may not be overwritten, this is
-
java.conf
-
The directory rrd contains RRD files to be imported. The following directory structre needs to be met:
/rrd
/response
/snmpAdditional JAR files for /opt/opennms/lib can be placed in lib_add. Also, existing files in the OpenNMS Docker image can be overwritten.
The container PostgreSQL is the database server for the environment. The import of data can be done with SQL dumps. The following directory structure can be used:
docker-compose.yml
/init
/postgres
/sqlDatabase dumps (e.g. from an OpenNMS or AlarmForwarder system) can be placed in the sql directory. Every dump must be created with specific options (--create and replacement of specific characters) and be named with the file extension *.sql. Please see the following examples for the creation of an OpenNMS and AlarmForwarder dump:
pg_dump --create -U opennms > db_opennms.sql && sed -i "s/LC_COLLATE = '.*' LC_CTYPE = '.*'//g" db_opennms.sql
pg_dump --create -U alarmforwarder > db_alarmforwarder.sql && sed -i "s/LC_COLLATE = '.*' LC_CTYPE = '.*'//g" db_alarmforwarder.sql|
Tip
|
The schema of an imported OpenNMS database will be updated automatically to the version used in the Docker image.(the OpenNMS version must not be older than the version where the database dump was created). |
For initializing of Nginx, the following directory structure can be used:
docker-compose.yml
/init
/nginx
/etc
/sslFor the import of data into the management container, please use the following directory structure:
docker-compose.yml
/init
/management
/etcMost of AlarmForwarder’s data were hold in the AlarmForwarder database, which will be imported into the Postgres container. The configuration can be imported usinig the following structure:
docker-compose.yml
/init
/alarmforwarder
/etc|
Warning
|
Cassandra support within the Docker Environment is experimental at the moment and for testing purposes only. |
Existing data can be imported using the following structure:
docker-compose.yml
/init
/cassandra
/schema
/snapshotThis directory contains the schema definitions for the particular keyspaces of a cassandra database. These could be created with the following command:
CQL="DESC KEYSPACE ${KEYSPACE};"
cqlsh -u ${CASSANDRA_USER} -p ${CASSANDRA_PASSWORD} -e \"${CQL}\" ${HOSTNAME}" > ${SCHEMAFILE}This directory contains snapshots of cassandra tables. Please see an example script for the creation of snapshots:
/opt/cassandra/bin/nodetool snapshot -t export
SNAPSHOT_PATHS=`find /opt/cassandra/data/data/ -name "export" -type d`
for SNAPSHOT_PATH in ${SNAPSHOT_PATHS}
do
SNAPSHOT_SUBDIR=${SNAPSHOT_PATH#/opt/cassandra/data/data}
TARGET_SUBDIR=${SNAPSHOT_SUBDIR%/snapshots/export}
if [[ $TARGET_SUBDIR != /system* ]] ;
then
TARGET_DIR=${DUMPDIR}/snapshot/${TARGET_SUBDIR}
mkdir -p ${TARGET_DIR}
cp ${SNAPSHOT_PATH}/* ${TARGET_DIR}
fi
done
/opt/cassandra/bin/nodetool clearsnapshot -t exportThe following directories can be used to initialize the Grafana container:
docker-compose.yml
/init
/grafana
/conf
/dataFor the import of data in PRIS, please use the following directory structure:
docker-compose.yml
/init
/pris
/requisitions