Starting the monitor

Starting from the command line

Once the monitor image has been installed, use the docker run command to start the monitors container (and thus the monitor itself). Note, the user starting the container must belong to the docker group on the host OS.

When starting the container there are a number of required arguments:

docker run \
    --detach \
    --name hamonitor \
    --net host \
    --privileged \
    --restart unless-stopped \
    --volume <host directory>:/tmp/hamonitor \
    --volume /lib/modules:/lib/modules \
    dkr.high-availability.com/hamonitor:v2.1 \
    --publish 13514

Once the container has been started it will run unattended; if the docker host is restarted then the container will restart automatically.

The docker run command both creates the container and starts it. Once a container has been created there is no need to use the run command again as it will attempt to create an already existing container (and return an error). To start and stop the monitor use the docker start and stop commands:

# docker stop hamonitor

# docker start hamonitor

Note that the --publish argument should always be last on the command line and that a suitable value for the <host directory> parameter should be provided (see the description below for more details). These arguments have the following effect:

--detach

Runs the monitor in the background.

--name hamonitor

Assigns a friendly name to the container that can then be used as a more memorable argument to other docker commands (such as docker start and stop) as opposed to the less memorable image ID that docker uses (i.e. fa37f3788bb3).

Furthermore, note that although an ID is unique to an installed image, a new image ID is generated on every upgrade, meaning any process that refers to a specific image ID will have to be modified should the image ID change (shell scripts for example). Using a friendly name avoids this problem.

--net host

Use the host’s network stack for the container.

--privileged

Gives all capabilities to the container and access to the host’s devices (those that reside under /dev).

--restart unless-stopped

Specifies the restart policy for the container, in this case always restart the container if it stops, unless it is manually stopped in which case it will not be restarted even if the docker daemon itself restarts (alternatively, if always is specified instead of unless-stopped then a stopped container will be restarted if the docker daemon restarts). Also note that should the monitor process terminate for any reason the container itself will exit and docker will restart another instance of the container.

--volume <host directory>:/tmp/monitor

Maps the directory <host directory> on the docker host to the directory /tmp/hamonitor in the container.

The container directory portion of this mapping (/tmp/hamonitor) is used by the monitor to store all it’s permanent data (encrypted database, logs etc) and cannot be changed. The <host directory> portion should be any suitable local filesystem directory on the docker host; it is recommended this is a local filesystem as opposed to a remotely mounted one (SMB/NFS etc.) to avoid network outages etc. adversely affecting the running monitor.

By using a mapping from the docker host to the container rather than using a local filesystem within the container gives a number of advantages:

Upgrades can be performed without having to first backup data in the container (and then re-import afterwards).
The monitor data can be backed up without the need for the container to be running.
It simplifies migration of the container to another host

--volume /lib/modules:/lib/modules

Exposes the host’s modules directory to the container. This is required for iSCSI monitoring as the iscsi_tcp kernel module is required when monitoring iSCSI connections (the monitor automatically loads the module when iSCSI monitoring is detected in its configuration file).

dkr.high-availability.com/hamonitor:v1.0

The name of the docker image to run. Note the version number (v1.0 in this case) should correspond to the version downloaded.

--publish <port-no>

The TCP port that the monitors REST API listens on for incoming requests; port 13514 is used by default if one is not provided on the command line.