Create and manage Docker instances

Prerequisites for using nShield Monitor with Docker

Docker container setup

The nShield Monitor Docker container ships as a .tar.gz file, for example nShieldMonitor-x.x.x.xxxx.tar.gz.

Before you can use the container, you must load it into a private Docker repository using:

docker load < nShieldMonitor-x.x.x.xxxx.tar.gz

Virtualization

The machine running nShield Monitor as a Docker container must have virtualization support (VT-x or AMD-V) enabled in its processor settings. To check if the processor has virtualization support, open a terminal and run:

LC_ALL=C lscpu | grep Virtualization

If the command does not return a response, then the processor does not support hardware virtualization. This means you need to enable virtualization support in the BIOS of the Docker host. The procedure for doing this depends on whether the machine is a physical or virtual machine and the virtualization technology it uses.

Docker volume files

You must have copied the following Docker volume files from the installation source to their permanent location on the Docker host for data to persist during the lifecycle of the nShield Monitor instance:

  • nsmvolume1

  • nsmvolume2

  • nsmvolume3

  • nsmvolume4

  • nsmvolume5

Start an nShield Monitor Docker container

You must be a privileged user to use Docker.

You can start the nShield Monitor Docker container using either docker compose or docker run.

docker compose uses a YAML file to specify the parameters for the Docker container. With docker run, you specify the parameters in a single command in the console.

docker compose

docker compose uses the docker-compose.yml file to start up the nShield Monitor Docker container. Specify all the parameters for the container in the docker-compose.yml file.

To start an nShield Monitor Docker container using docker compose, in a privileged command-prompt, run:

docker compose up

To specify the parameters, set out the docker-compose.yml file as illustrated by the following example. All sections and parameters are mandatory unless otherwise stated.

version: '3.3'
services:
  nsm:
    privileged: true
    environment:
      - CPU=4 (1)
      - RAM=4096 (2)
      - HDA=/tmp/1 (3)
      - HDB=/tmp/2
      - HDC=/tmp/3
      - HDD=/tmp/4
      - HDE=/tmp/5
    devices:
      -/dev/kvm
    volumes: (3)
      -'<path to volumes>/nsmvolume1:/tmp/1'
      -'<path to volumes>/nsmvolume2:/tmp/2'
      -'<path to volumes>/nsmvolume3:/tmp/3'
      -'<path to volumes>/nsmvolume4:/tmp/4'
      -'<path to volumes>/nsmvolume5:/tmp/5'
      -'<path to bridge.conf>:/etc/qemu'
    ports: (4)
      -'446:443'
      -'16166:16163'
      -'166:161/udp'
      -'167:162/udp'
      -'57:53'
      -'126:123'
      -'517:514'
      -'29:25'
      -'465:465'
      -'28:21'
    image:'<nsrepo>/nsm:x.x.x' (5)
    stdin_open: true
    tty: true
1 The number of CPU cores to be allotted to the container. This parameter is optional.
2 The RAM, in bytes, to be allocated to the container. This parameter is optional. If you do not specify a value, it defaults to 2096 MB.
3 The environment variables HDA to HDE must correspond to the volumes. For example:

nsmvolume1, mounted as /tmp/1, is assigned to HDA. nsmvolume2, mounted as /tmp/2, is assigned to HDB, and so on.
4 Ports are declared in x:y pairs, where x denotes the port on the Docker host machine and y denotes the corresponding port on the nShield Monitor Docker machine.

Ensure the host port numbers are not used by other applications.
5 Change <nsrepo> for the repository where nShield Monitor resides.

Connect to the nShield Monitor container

After starting the nShield Monitor instance using docker compose, identify the container ID and connect to it using docker attach:

  1. Retrieve the container IDs of the available nShield Monitor instances:

    docker ps

  2. Note the CONTAINER ID of the required nShield Monitor instance from the output:

    CONTAINER ID   IMAGE                   COMMAND            CREATED      STATUS         PORTS NAMES
88c61c1eb5d1   nsmrepo/nsm:x.x.x       "nShieldMonitor"   8 days ago   Up 7 seconds   ...   nsm2
e7055016fb53   684a666d22ee            "nShieldMonitor"   9 days ago   Up 9 days      ...   nsm3

  3. Using the CONTAINER ID from the previous step, connect to the container console:

    docker attach <CONTAINER ID>

    For example:

    docker attach 88c61c1eb5d1

After connecting to a console, continue using nShield Monitor in the same console.

docker run

docker run enables you to specify all parameters in a single command line at the console instead of using a docker-compose.yml file. You must be logged in as a privileged user to run this command.

After running the command, you can access nShield Monitor in the same console. There might be a delay between running the command and nShield Monitor being accessible.

docker run --privileged --device=/dev/kvm:/dev/kvm --device=/dev/net/tun:/dev/net/tun --cap-add NET_ADMIN  -it --rm --device /dev/kvm --name mynet -v <path to volumes>/nsmvolume1:/tmp/1 -v <path to volumes>/nsmvolume2:/tmp/2 -v <path to volumes>/nsmvolume3:/tmp/3 -v <path to volumes>/nsmvolume4:/tmp/4 -v <path to volumes>/nsmvolume5:/tmp/5 -e HDA=/tmp/1 -e HDB=/tmp/2 -e HDC=/tmp/3 -e HDD=/tmp/4 -e HDE=/tmp/5 -e BOOT=c -e CPU=4 -e RAM=4096 -v <path to bridge.conf>:/etc/qemu -p 44:443 -p 16163:16163 -p 166:161/udp -p 167:162/udp -p 57:53 -p 126:123 -p 517:514 -p 29:25 -p 465:465 -p 28:21 nsrepo/nsm:x.x.x

Or:

docker run --privileged --device=/dev/kvm:/dev/kvm --device=/dev/net/tun:/dev/net/tun --cap-add NET_ADMIN -e "AUTO_ATTACH=yes" -it --rm --device /dev/kvm --name ns37 --mount type=bind,source=<path to volumes>/nsmvolume1,target=/tmp/1 --mount type=bind,source=<path to volumes>/nsmvolume2,target=/tmp/2 --mount type=bind,source=<path to volumes>/nsmvolume3,target=/tmp/3 --mount type=bind,source=<path to volumes>/nsmvolume4,target=/tmp/4 --mount type=bind,source=<path to volumes>/nsmvolume5,target=/tmp/5 -e HDA=/tmp/1 -e HDB=/tmp/2 -e HDC=/tmp/3 -e HDD=/tmp/4 -e HDE=/tmp/5 -v <path to bridge.conf>:/etc/qemu -p 83:80 -p 443:443 -p 16163:16163 -p 161:161/udp -p 162:162/udp -p 54:53 -p 123:123 -p 514:514 -p 26:25 -p 465:465 -p 21:21 nsrepo/nsm:x.x.x

All parameters passed in the command are mandatory unless otherwise specified in the following table:

Parameter Details

--privileged

Runs the nShield Monitor container in privileged mode.

--device=/dev/kvm

--device=/dev/net/tun

Both devices must exist on the host.

--cap-add NET_ADMIN

This is a necessary capability for the container.

--it

Enables interactive mode.

--rm

Removes the container on exit. Data persists in the volumes.

Optional

--name <container-name

Specifies the container to use.

Optional

-v /root/ns2/nsmvolume<x>:/tmp/<x>

and

-e HD<X>=/tmp<x>

Creates volume to environment variable mapping.

The volumes (-v) must correspond to the environment variables (-e) from HDA to HDE. For example, -v <path to volumes>/nsmvolume1:/tmp/1 corresponds with -e HDA=/tmp/1, and -v <path to volumes>/nsmvolume2:/tmp2 with -e HDB=/tmp/2.

-e CPU=4

Specifies the number of cores to allot to the Docker container.

Optional

-e RAM=4096

Specifies the amount of RAM to allot to the Docker container.

Optional. If you do not specify a value, it defaults to 2096 MB.

-v <path to bridge.conf>:/etc/qemu

The location of the bridge.conf file, which must contain the line: allow all.

-p <x>:<y>

Ports (-p) are declared in x:y pairs, where x denotes the port on the Docker host machine and y denotes the corresponding port on the nShield Monitor Docker machine.

Ensure the host port numbers are not used by other applications.

nsrepo/nsm:x.x.x

Specifies the Docker repository where nShield Monitor resides. Ensure you change nsrepo for the name of the repository in use.

Connect to the web UI for the nShield Monitor

To access the nShield Monitor web UI from a browser on a machine that is not the Docker host, use the Docker host IP address followed by the host port that is mapped to port 443 on the container (https://<docker-host-ip>:<host-port>/login). This port mapping was specified in either the docker-compose.yml file or in the docker run command, depending on how you started it.

To access the web UI from the Docker host machine, you need to inspect the container’s settings to determine the IP address assigned to it. Docker manages the network settings of a container.

  1. Retrieve the container IDs of the available nShield Monitor instances:

    docker ps

  2. Note the CONTAINER ID of the required nShield Monitor instance.

    CONTAINER ID   IMAGE                   COMMAND            CREATED      STATUS         PORTS NAMES
88c61c1eb5d1   nsmrepo/nsm:x.x.x       "nShieldMonitor"   8 days ago   Up 7 seconds   ...   nsm2
e7055016fb53   684a666d22ee            "nShieldMonitor"   9 days ago   Up 9 days      ...   nsm3

  3. Using the CONTAINER ID, inspect the network settings of the container console:

    docker inspect <CONTAINER ID>

  4. Use the IPAddress in the output to access the container.

    • If you used docker run to start the nShield Monitor container, the output appears as follows:

      "NetworkSettings": {
           "Gateway": "172.17.0.1",
           "IPAddress": "172.17.0.3",
           "Networks": {
                "bridge": {
                    "Gateway": "172.17.0.1",
                    "IPAddress": "172.17.0.3",
                }
            }
}

      In this example, you would access the container via https://172.17.0.3/login.

      If a port other than 443 was mapped, the access URL changes to https://172.17.0.3:<host_port>/login, for example https://172.17.0.3:444/login.

    • If you used docker compose to start the nShield Monitor container, the output appears as follows:

      "NetworkSettings": {
           "Gateway": "",
           "IPAddress": "",
           "Networks": {
                "ns2_default": {
                    "Gateway": "172.23.0.1",
                    "IPAddress": "172.23.0.2",
                }
            }
}

      In this example, you would access the container Web UI via https://172.23.0.2:<host_port>/login.

Assign a usable IP to a nShield Monitor container

To change the Web UI access IP for the container:

  1. List the available networks:

    docker network ls

  2. From the list, note the name of the network in which you started the container, for example:

    NETWORK ID     NAME          DRIVER    SCOPE
a9cd9ed46e6b   bridge        bridge    local
6af6b576d8a3   host          host      local
42d390a3fdb1   none          null      local
240d738c0a8b   ns2_default   bridge    local
    If you started with docker run, the network is the default bridge network. If you started with docker compose, the network is a specific bridge network that has the same name as the container, for example ns2_default.

  3. Inspect the network relevant to the container, for example:

    docker network inspect bridge

    or

    docker network inspect ns2_default

  4. Note the Subnet and Gateway settings displayed in the output:

            "IPAM": {
            "Driver": "default",
            "Options": null,
            "Config": [
                {
                    "Subnet": "172.17.0.0/16",
                    "Gateway": "172.17.0.1"
                }
            ]
        },

  5. If required, use this information to reconfigure the container in the nShield Monitor CLI.

    This is an advanced configuration. You must specify all parameters correctly for the Docker container to be accessible on the network. For more information on using these commands, see Network commands.

    1. Configure the network with DHCP configuration inside the nShield Monitor Docker container, because Docker uses it to assign unique IP addresses to each container.

      network configure dhcp

    2. If you assign a specific IP address to the container, make sure that the parameters fall within the subnet that the earlier docker inspect command returned:

      network configure static

Troubleshooting container startup errors:

Port binding errors

Rerun the command and specify a different host port in the docker compose or docker run command.

Write lock errors

You must assign a unique set of volumes to each container. Containers cannot share the same set of volumes. Copy a new set of the provided Docker volumes to launch a new instance of an nShield Monitor Docker container. After starting the container, you can access it using docker attach.

Formatting and directory errors

Ensure that the volumes are present at the location specified by the docker run or docker compose syntax and that they are regular files.