--- title: "Geneos containers" description: "" url: "https://docs.itrsgroup.com/docs/geneos/7.11.0/administration/orchestrated-environments/geneos_containers/index.html" --- ## Overview Gateways, Netprobes, and Webservers are available as Docker images to run as containers. This is especially useful for deploying Geneos in orchestrated environments. For information about running Gateway in Kubernetes, see the [Deploying Gateway into Kubernetes](https://github.com/ITRS-Group/geneos-deployment/tree/master/kube) GitHub page. ### Intended audience Users of Geneos containers should be familiar with configuring Docker containers and managing orchestrated environments. You must ensure that containers are started with access to all ports required for the Gateway or Netprobe features you want to use. Additionally, you may need to mount directories on the host system to provide configuration files. Please consult the official Docker or Kubernetes documentation if you require more information about managing containers. ## Prerequisites To run the Geneos containers, you must have either of the following installed: - Docker - Kubernetes In addition, you must ensure all Geneos components have network access to each other. When using multiple containers together this may require configuring a network bridge. ## Install To run Geneos containers, you must download the container image from the ITRS Docker registry. To access the ITRS Docker registry, run: ``` docker login docker.itrsgroup.com ``` This prompts you to provide login details, these are the same as the credentials you have been provided to access the ITRS website. If you do not have login credentials, you can request these from the [ITRS Registration](https://resources.itrsgroup.com/?register) page. ### Available versions Container images are available for the following Geneos components: - Gateway and Netprobe - available beginning Geneos 5.4.x and newer released versions. - Webserver - available beginning Geneos 7.2.x and newer released versions. The image names use the format `:`. You can pull the most recent version by using `:latest`. For example: - `gateway:5.4.0`, `gateway:5.5.0`, `gateway:5.5.1`, `gateway:latest`, and so on. - `netprobe:5.4.0`, `netprobe:5.5.0`, `netprobe:5.5.1`, `netprobe:latest`, and so on. - `webserver:7.2.0`, `webserver:latest`, and so on. ### Customize containers By default, the Geneos containers are packaged with the minimum base image and do not include Perl and Python, which are required to run action and command scripts triggered by Gateway or Netprobe. The following steps demonstrate how to customize the Geneos Gateway container to include Perl: 1. Access the ITRS Docker registry: ``` docker login docker.itrsgroup.com ``` 2. Pull the Gateway or the Netprobe image: ``` docker pull docker.itrsgroup.com/gateway ``` 3. Create a Docker file: ``` FROM docker.itrsgroup.com/gateway:latest USER root RUN \ microdnf -y update && \ microdnf -y install perl ``` 4. Build the Docker file to create the custom image: ``` docker build -t gateway:6.2-custom . ``` 5. Test the Docker image: ``` docker run -d --rm --name my_gateway -p 7039:7039 gateway:6.2-custom ``` ## Configure You can mount directories on the host machine to provide configuration files for Geneos containers. You must ensure any directories you want to mount exist before starting containers. ### Gateway configuration Gateway is configured at startup by reading a `gateway.gci` file. By default, the Gateway container will use an example configuration stored at `/gateway/config/gateway.gci` in the container. The `gateway.gci` file sets the location the Gateway looks for setup files and data. By default, these are `/gateway/persist/setup` and `/gateway/persist/data` respectively. Note the following special conditions when configuring Gateway in Docker: - If a Gateway Hub location is specified in the `gateway.gci` file, the Gateway container will attempt to fetch its setup files using centralised configuration. For more information, see [Obtain Gateway setup from Gateway Hub in Centralised Gateways User Guide](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-hub/gateway-centralised-config/index.html#obtain-gateway-setup-from-gateway-hub). - If a Gateway container is configured to connect to Gateway Hub, it will wait for a connection to be established before starting the Gateway. The timeout duration is set, in seconds, by the `WAIT_TIME` environment variable. The default value is `45`. If the environment variable `REQUIRE_HUB` is set to `TRUE` then a timeout will terminate the process, otherwise after the timeout Gateway will start without Gateway Hub. - If centralised configuration is required, then Gateway startup will fail if Gateway Hub is not available. - The Gateway container does not create log files. Logging is performed using Docker and to read the Gateway log, run `docker logs `. - If you are mounting local directories, you can add `--user $(id -u):$(id -g)` as an option when starting the container so that files are created and edited using your user ID. - If you are using script commands, by default Gateway will check the `/gateway` directory for available scripts. You must specify an absolute path to use scripts from a mounted directory. For more information about script commands, see [Configuration in Gateway Commands](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/monitoring-and-alerts/geneos_commands_tr/index.html#configuration). - If you want to use the hot standby feature you must use two Gateway containers. You cannot use this feature with a mixture of Gateway containers and regular Gateways. For more information about Gateways, see [Gateway Introduction](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway_introduction/index.html) and [Gateway Installation Guide](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway_installation_guide/index.html). #### Alternative configuration and setup files You can mount directories on the host machine to provide alternative configuration or setup files. This is a standard Docker feature. For example, to start the Gateway container with an alternate setup directory run: ``` docker run -d --rm --name itrs_gw -v $(pwd)/setup:/gateway/persist/setup -p 7038:7038 docker.itrsgroup.com/gateway: ``` You can also provide an alternative `gateway.gci` configuration file by setting the `GATEWAY_CONFIG` environment variable in the container with the contents of the alternate `gateway.gci` file. For example, to start the Gateway with a `gateway.gci` configuration file as follows: ``` -resources-dir /opt/gateway/resources -demo -setup /gateway/persist/setup/gateway.setup.xml -gateway-hub https://hub.itrsgroup.com:8081 ``` Set `GATEWAY_CONFIG` when running the container: ``` docker run -d --rm --name itrs_gw -e GATEWAY_CONFIG="-resources-dir /opt/gateway/resources -demo -setup /gateway/persist/setup/gateway.setup.xml -gateway-hub https://hub.itrsgroup.com:8081" -p 7038:7038 docker.itrsgroup.com/gateway: ``` ### Netprobe configuration Netprobes are configured at startup by reading a `netprobe.gci` file. By default, the Netprobe container will use an example configuration stored at `/netprobe/config/netprobe.gci` in the container. The `netprobe.gci` file sets the location the Netprobe looks for setup files, by default this is `/netprobe/persist/setup`. Note the following special conditions when configuring a Netprobe in Docker: - Certain plugins require root access. For these plugins, you must add `--user root` as an option when starting the container. - The Netprobe container does not create log files. Logging is performed using Docker and to read the Netprobe log, run `docker logs `. - If you are mounting local directories, you can add `--user $(id -u):$(id -g)` as an option when starting the container so that files are created and edited using your user ID. For more information about Netprobes, see [Netprobe Overview](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/introduction/netprobe-overview/index.html) and [Netprobe setup](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/configuration/netprobe-setup/index.html). #### Alternative configuration and setup files You can mount directories on the host machine to provide alternative configuration or setup files. This is a standard Docker feature. For example, to start the Netprobe container with alternate configuration and setup directories run: ``` docker run -d --rm --name itrs_np -v $(pwd)/netprobe.gci:/netprobe/{*}config{*}/netprobe.gci -v $(pwd)/setup.xml:/netprobe/setup.xml -p 7036:7036 docker.itrsgroup.com/netprobe: ``` You can also provide an alternative `netprobe.gci` configuration file by setting the `NETPROBE_CONFIG` environment variable in the container with the contents of the alternate `netprobe.gci` file. For example, to start the Netprobe with a `netprobe.gci` configuration file as follows: ``` -ssl-certificate /gateway/tls/security.pem -secure ``` Set `NETPROBE_CONFIG` when running the container: ``` docker run -d --rm --name itrs_np -e NETPROBE_CONFIG="-ssl-certificate /gateway/tls/security.pem -secure" -p 7036:7036 docker.itrsgroup.com/netprobe: ``` ### Webserver configuration The script `/opt/webserver/run_webserver.sh` starts the Webserver using configuration files stored in `/webserver/config`: - config.xml - log4j2.properties - log4j.properties - logging.properties - login.conf - security.properties - security.xml - sso.properties - users.properties If any of these files are missing, a default file will be copied from `/opt/webserver/config`. Uploaded dashboards are stored in the `/webserver/config/dashboards` directory. #### Alternative configuration and setup files You can mount directories on the host machine to provide alternative configuration or setup files. This is a standard Docker feature. For example, run the following command to start the Webserver container with alternate configuration directories: ``` docker run -d --rm --name itrs_ws -v $(pwd)/config:/webserver/config -p 8080:8080 docker.itrsgroup.com/web-server: ``` If run with an empty directory, it will be populated using the default values from `/opt/webserver/config` on the initial run. Configuration and dashboards will be persisted in the provided configuration directory across restarts. It is also possible to provide a pre-populated configuration directory that will be read by the Webserver start script. ## Centrally configured Gateways You can start a Gateway container using a setup files provided by Gateway Hub central configuration. For more information about centralised configuration, see [Centralised Gateways](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-hub/gateway-centralised-config/index.html). You must specify the Gateway Hub you wish to connect to in your `gateway.gci` file. An example file is provided below: ``` # Gateway2 Config File -resources-dir /opt/gateway/resources -gateway-name "Demo Gateway" -gateway-hub https://:8081 -demo ``` To start a Gateway container using the a `gateway.gci` file on the host machine, run: ``` docker run --name itrs_gw --rm -v $(pwd)/gateway.gci:/gateway/config/gateway.gci -p 7039:7039 docker.itrsgroup.com/gateway: ``` This will start the Gateway and attempt to fetch setup files from the specified Gateway Hub. If no setup files exist, a blank configuration will be created and added to the central store. If your Gateway or Gateway Hub is using custom ports, ensure these are accessible by the host machine and the Gateway container. ## Publish to Gateway Hub You can publish metrics data from a Gateway container to Gateway Hub. The Gateway must trust certificates provided by Gateway Hub. You will need to add the `ca.crt` file of the certificate authority that signs Gateway ub certificates to Gateway's trusted list. For a default installation of Gateway Hub this file is located at `/opt/hub//tls/ca.crt`. To start a Gateway container using a `ca.crt` file on the host machine, run: ``` docker run --name itrs_gw --rm -v $(pwd)/ca.crt:/gateway/tls/ca.crt -p 7039:7039 docker.itrsgroup.com/gateway: ``` To start publishing metrics to Gateway Hub you must configure this in the Gateway setup. You can do this using the Gateway Setup Editor following the instructions in [Gateway Hub Quickstart](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-hub/gateway-hub-quick/index.html). Alternatively, you can add the following XML to your setup file: ``` true hub_hostname:9092 kafka.security.protocol=ssl kafka.ssl.ca.location=/gateway/tls/ca.crt ```