The official Docker images of openITCOCKPIT are available here:
The Docker images of openITCOCKPIT are available for the
arm64 CPU architectures and can also be used on a SoC like the Raspberry Pi 4.
Docker and Docker Compose are required. Please follow the official documentation, if you do not have Docker installed yet.
- 2 CPU cores (x86-64 or arm64)
- 2 GB RAM
- 40 GB of free hard disk space
The amount of disk space used depends on the number of monitored hosts and services.
The configuration of openITCOCKPIT can be customized via the
openitcockpit.env file. It is recommended,
to change the login data before the first start of the container:
Alternatively, you can also create a new user or change the password.
It is also recommended to replace the password of Grafana admin user. To do this, set the following two variables to the same value:
To generate a secure password, the command
pwgen -s -1 16 can be used.
As usual with Docker containers, other settings like ports or volumes can be adjusted in the
compose.yml if needed.
By default, openITCOCKPIT provides these ports:
- 80 (HTTP)
- 443 (HTTPS)
The default login credentials are:
The easiest way to check out fully containerized openITCOCKPIT is to use
gitto create a local copy of the repository that contains all the data you need.
git clone https://github.com/it-novum/openITCOCKPIT-ce-docker.git
Change to docker directory
openitcockpit.envfile and change the values username an password.
The containers are started with the help of the command
docker compose up -d
To update the containers of openITCOCKPIT, please follow these steps:
Update the local copy of your repository:
git pull origin main
Stop running containers
docker compose down
Run the Docker compose command to update and launch the containers:
docker compose up --pull always -d
The Docker registry of openITCOCKPIT includes the following tags for all containers:
latest- latest stabel version of openITCOCKPIT (recommended)
A version such as
4.6.4- These tags contain the specified version of openITCOCKPIT and can be used to obtain a specific stable version.
nightly- An untested build of openITCOCKPIT which has been automatically created and released. Can be used for testing new versions and features. Not intended for production use!
Execute commands in a container¶
- Run the
docker pscommand to read the ID of the desired container.
- In the next step, you need to 'jump' into the container using the
docker exec -it d92a1431e619 bash
Starting MySQL console¶
- 'Jump' into the
openitcockpit-cecontainer with the
- Run the command
mysql --defaults-file=/opt/openitc/etc/mysql/mysql.cnfto get a MySQL shell.
Query Gearman status¶
- 'Jump' into the
openitcockpit-cecontainer with the
- Run the command
gearadmin --status -h gearmandto get a gearman status output.
If you have customized the hostname of the gearman job server, you can read the value directly from the environment variable:
gearadmin --status -h $OITC_GEARMAN_ADDRESS.
Normally, you do not have to restart services manually. However, via the
openitcockpit-ce container it is possible to restart certain services in other containers.
oitc supervisor --help command can be used for this.
oitc supervisor status naemon
oitc supervisor restart nginx
oitc supervisor stop nginx
oitc supervisor start nginx
Install your own monitoring plugins¶
openITCOCKPIT supports two different methods to extend the monitoring capabilities with custom check plugins. The containerized method is recommended for users that have experience with building and maintaining container images.
If you prefer a bare-metal server or virtual machine for this have a look at the traditional method.
openitcockpit/mod_gearman_worker is responsible for running monitoring plugins. This container is always based on
the current LTS version of Ubuntu and can be used as a base image for new containers.
Therefore, you must first create your own
Dockerfile, which will install all the plugins you want. In this example, the container will be extended with the plugin
# Install plugin dependencies
ENV DEBIAN_FRONTEND noninteractive
RUN apt-get update && \
apt-get install -y perl wget curl bind9-host bc openssl nmap
# Install the plugin
RUN wget https://github.com/matteocorti/check_ssl_cert/releases/download/v2.69.0/check_ssl_cert-2.69.0.tar.gz &&\
tar xfv check_ssl_cert-2.69.0.tar.gz &&\
cp check_ssl_cert-2.69.0/check_ssl_cert /opt/openitc/nagios/libexec/check_ssl_cert &&\
chmod +x /opt/openitc/nagios/libexec/check_ssl_cert
Create the new Docker image:
docker build --rm -t openitcockpit/custom_mod_gearman_worker:latest .
The last step is, to add your own Docker image to the
compose.yml file. Find the container
openitcockpit/mod_gearman_worker and replace the image with your ownimage.
After restarting the containers, your custom container will be used.
[Ubuntu][11:49]root@srvcontainerswarm04/tmp/custom_mod_gearman# docker exec -it dffc5ffe8681 bash
root@dffc5ffe8681:/# /opt/openitc/nagios/libexec/check_ssl_cert -H openitcockpit.io
SSL_CERT OK - openitcockpit.io:443, https, x509 certificate 'openitcockpit.io' from 'Let's Encrypt' valid until Aug 6 21:32:16 2023 GMT (expires in 76 days)|days_chain_elem1=76;20;15;; days_chain_elem2=847;20;15;; days_chain_elem3=497;20;15;;
openITCOCKPIT make use of
Mod-Gearman to distribute the execution of check plugins across multiple servers (or containers).
If you don't feel comfortable by building and maintaining your own container image, openITCOCKPIT provides a package, so you can use any Debian, Ubuntu or Red Hat Enterprise Linux based system as a worker system. Depending on your workload, it could make sense to spin-up multiple worker instances.
For security reasons we highly recommend to enable encryption.
First you need to prepare your current container setup a bit.
To be able to connect an external Mod-Gearman Worker to openITCOCKPIT, you have to expose the
Gearman-Job-Serverto your network. First, edit the file
compose.ymland search for the
gearmandservice. Replace the line
- "4730" # Gearman-Job-Server
- "4730:4730" # Gearman-Job-Server
Disable processing of host and service checks of openITCOCKPIT
To make sure that all host and services checks get executed by your own custom worker, it is important to disable the default check execution of openITCOCKPIT. To do so, edit the file
openitcockpit.envand set the following values:
##### ## Naemon Environment Variables ##### MOD_GEARMAN_ENCRYPTION=yes MOD_GEARMAN_KEY=should_be_changed ##### ## Mod_Gearman_Worker Environment Variables ##### MOD_GEARMAN_WORKER_EVENTHANDLER=no MOD_GEARMAN_WORKER_NOTIFICATIONS=yes MOD_GEARMAN_WORKER_SERVICES=no MOD_GEARMAN_WORKER_HOSTS=no MOD_GEARMAN_WORKER_ENCRYPTION=yes MOD_GEARMAN_WORKER_KEY=should_be_changed
To apply the changes, restart the containers. The
openitcockpit/mod_gearman_workercontainer will still be used to send notifications. This behavior can also be changed, but to do so is only recommended for power users.
Now it is time to setup a VM (or server) which you want to use for check execution. We recommend to start with a blank VM of the latest Ubuntu LTS release.
Load the repository.
Please make sure to enable the openITCOCKPIT repository on your system.
apt-get install openitcockpit-mod-gearman-worker-go
All check plugins are located at
/opt/openitc/nagios/libexec. You can add any custom plugin you need to this (or any other) location.
Connect worker to openITCOCKPIT Server
Open the file
/opt/openitc/mod_gearman/etc/worker.cfgand set the hostname or IP-Address of your openITCOCKPIT Server.
server=srvpod03.example.org:4730 # Also make sure to set same encryption parameters encryption=yes key=should_be_changed
To apply the settings, restart the service:
systemctl restart mod-gearman-worker.service
By default, openITCOCKPIT has no encryption enabled for Mod-Gearman. This is due to the fact, that by default all communication is only available through the containers that are part of the same container network.
In case you have exposed the Gearman Port (4730) or are using any external Mod-Gearman Workers, we recommend to enable encryption. Mod-Gearman has a shared secret, so you need to make the changes on all affected systems!
For containers edit the file
openitcockpit.env and adjust the following variables:
## Naemon Environment Variables
## Mod_Gearman_Worker Environment Variables
For traditional setups, edit the configuration file
key option contains the shared secret and should be replaced with a secure string.
To apply the changes restart all containers or the
Portainer Community Edition is a web interface that makes it convenient and easy to manage Docker containers.
Through Stacks, the Portainer interface allows you to manage Docker Compose files. To do this, click
Add stack under
As name you can set
You can either add the Docker Compose File via the web editor, or alternatively get it directly from the GitHub repository
Please note that all references to the
openitcockpit.envfile must be replaced by
To do this, look for these entries
env_file: - openitcockpit.env
env_file: - stack.env
Advanced modeand copy the contents of the file openitcockpit.env. Alternatively, you can select
Load variables from .env filethen upload the file
The startup process of the openITCOCKPIT container can take some time. The container checks the state of the database at each startup and performs any updates.
As soon as the openITCOCKPIT frontend is accessible, the container outputs the message
openITCOCKPIT is now ready.
MySQL Binary Log¶
By default, the binary log of the MySQL server is disabled in the
The binary log is required for replication between multiple MySQL servers but can also be useful in case of database recovery.
Further information can be found in the MySQL documentation.
If you want to enable the binary log, you need to remove the
--skip-log-bin parameter from the
compose.yml file. The retention period of the binary logs can be controlled by the
--binlog-expire-logs-seconds=2592000 parameter, which is set to 30 days by default.