Page tree
Skip to end of metadata
Go to start of metadata

What is the openITCOCKPIT Agent?

Based on the programming language Python, the agent was developed as a universally applicable solution to read basic information about the system.

This involves the use of the CPU (total and per CPU core), the time of the last boot process to calculate the system runtime, information on the use of RAM and swap, logged-in users, hard drive consumption, system load, some sensors and the status of connected devices and virtual network devices.

Information about ongoing processes is also collected, e.g. the process ID, the name, data about RAM and CPU consumption, as well as its hard disk activity.

By default, the system polls new values every 30 seconds. Since the agent does not have to provide historical data, but only the current status of the system, outdated information is regularly overwritten with new information and is not saved.

In order to enable your own checks or the execution of existing Nagios plugins, a configuration file can be used to specify which commands (command or path to an executable file) are to be executed at specific time intervals and with defined timeouts.

Using this method, Nagios plugins can also be easily integrated into the agent.

The standard configuration can be configured via start parameters or a configuration file, e.g. be adjusted for the interval of the checks.

For external access to this data, the agent starts a local web server (configurable with IP address and port) and provides all current, collected data, formatted according to the JSON standard.

In addition, configuration options are available that allow the collected data to be automatically sent to an openITCOCKPIT instance.


It is available for Windows, macOS and the common Linux systems such as Debian, Ubuntu or Arch packages.

Download here: https://openitcockpit.io/agent


Usage

First of all log in to the webinterface of your openITCOCKPIT 4.

If you have already an host configured for the machine the Agent is running on, navigate to AdministrationopenITCOCKPIT AgentAgent Configuration. Choose the host the agent is installed on and follow the instructions there.

If you haven´t configured a host for the machine the Agent is running on yet, navigate to MonitoringHosts and click + New.

After your host configuration click Create host and setup agent to save the host and proceed directly with the built-in agent configuration.


Security concept

The agent's web server can offer an HTTPS connection instead of HTTP using your own or automatically generated web server certificates.

In order to protect the system information queried by the agent and to avoid misuse of the configuration interface via the web server, two independently functioning authentication mechanisms are integrated in the agent.

"Basic-Auth" method

A combination of user name and password can be configured to access the web server.

This is queried when accessing the website using the so-called "basic auth" procedure.

Certificate authentication

The openITCOCKPIT server is used as a CA (certification authority), i.e. for the generation of the required certificates.

A client certificate from a configured CA is required to access the agent's web server. Requests without a certificate issued by the same CA will be rejected.

If a certificate has been generated for an agent, the server also expects to use it, regardless of whether the agent is in pull or push mode.


Pull-Mode

The certificate (including updates) is transferred from openITCOCKPIT to the agent.

When configuring the agent in openITCOCKPIT, the "Try autossl mode" option has to be activated.


Push-Mode

The agent requests the certificate (including updates). A corresponding request is regularly sent to the openITCOCKPIT server.

For security reasons, this request must be manually trusted by a user in openITCOCKPIT in order to generate the certificate.


Required extension of the default configuration in Push-Mode:

config.cnf
[oitc]

# The UUID of the Host.
# You can find this information in the openITCOCKPIT interface
# Example: 402357e4-dc34-4f5b-a86d-e59cfbb3ffe7
hostuuid =

# Address of your openITCOCKPIT Server
# Example: https://openitcockpit.io/receiver
url = 

# API-Key of your openITCOCKPIT Server
apikey =


Installation

It is available for Windows, macOS and the common Linux systems such as Debian, Ubuntu or Arch packages.

Download here: https://openitcockpit.io/agent


Configuration

What is the Pull / Push mode?

If the agent is to be configured in Pull-mode, it must be accessible via the network.

openITCOCKPIT will try to connect to the agent using the host's IP address.

The test results are called up every minute.


If the agent is to be configured in Push-mode, it must establish a connection to the openITCOCKPIT server in your network.

The agent sends the test results to the openITCOCKPIT server at a certain interval.

Required extension of the default configuration:

config.cnf
[oitc]

# Enable Push Mode
enabled = true

# The UUID of the Host.
# You can find this information in the openITCOCKPIT interface
# Example: 402357e4-dc34-4f5b-a86d-e59cfbb3ffe7
hostuuid =

# Address of your openITCOCKPIT Server
# Example: https://openitcockpit.io/receiver
url = 

# API-Key of your openITCOCKPIT Server
apikey =



Entire configuration options

The agent can be configured after installation.

The agent's configuration file (INI format) is stored in different locations depending on the system. The following file paths apply:

Windows

C:\Program Files\openitcockpit-agent\config.cnf

C:\Program Files\openitcockpit-agent\customchecks.cnf

Linux

/etc/openitcockpit-agent/config.cnf

/etc/openitcockpit-agent/customchecks.cnf

macOS

/Applications/openitcockpit-agent/config.cnf

/Applications/openitcockpit-agent/customchecks.cnf


The agent can be configured in the following two places, as a start parameter or configuration option.

1. As a parameter for program start

The options defined in the list below as start parameters can be transferred as parameters to the agent's start file to be executed.

(This use in productive operation is not recommended!)

Example command
/usr/bin/openitcockpit-agent-python3.linux.bin --config /etc/openitcockpit-agent/config.cnf --verbose -s --port 80 --config-update-mode


2. In the configuration files

config.cnf
[default]

# Determines in seconds how often the agent will schedule all internal checks
interval = 30

# Port of the Agents buil-in web server
port = 3333

# Bind address of the build-in web server
address = 0.0.0.0

# If a certificate file is given, the agent will switch to https only
# Example: /etc/ssl/certs/ssl-cert-snakeoil.pem
certfile =

# Private key file of the given TLS certificate
# Example: /etc/ssl/private/ssl-cert-snakeoil.key
keyfile =

# Try to enable auto ssl mode for webserver
try-autossl = true

# File paths used for autossl (default: /etc/openitcockpit-agent/... or C:\Program Files\openitcockpit-agent\...):
# Example: /etc/openitcockpit/agent.csr
autossl-csr-file = 
# Example: /etc/openitcockpit/agent.crt
autossl-crt-file = 
# Example: /etc/openitcockpit/agent.key
autossl-key-file = 
# Example: /etc/openitcockpit/server_ca.crt
autossl-ca-file = 

# Print most messages
verbose = false

# Print all messages with stacktrace
# For developers
stacktrace = false

# Enable remote read and write of THIS config file and custom checks defenition
# Examples:
#   Read config: curl http://0.0.0.0:3333/config
#   Write config: curl -X POST -d '{"config": {"interval": "60", "port": "3333", "address": "0.0.0.0", "certfile": "/etc/ssl/certs/ssl-cert-snakeoil.pem", "keyfile": "/etc/ssl/private/ssl-cert-snakeoil.key", "verbose": "true", "stacktrace": "false", "config-update-mode": "true", "auth": "", "customchecks": "", "temperature-fahrenheit": "false", "oitc-host": "", "oitc-url": "", "oitc-apikey": "", "oitc-interval": "60", "oitc-enabled": "false"}, "customchecks": {}}' http://0.0.0.0:3333/config
config-update-mode = false

# Enable Basic Authentication
# Disabled if blank
# Example: auth = user:password
auth =

# Remote Plugin Execution
# Path to config will where custom checks can be defined
customchecks = /etc/openitcockpit-agent/customchecks.cnf

# Return temperature values as fahrenheit
temperature-fahrenheit = false

# Try to check docker containers and return stats in default output
dockerstats = false

# Try to check qemu virtual machines and return stats in default output
qemustats = false

# Enable default cpu status check
cpustats = true

# Enable default sensor status check
sensorstats = true

# Enable default process status check
processstats = true

# Add process child ids to the default process status check (computationally intensive)
processstats-including-child-ids = false

# Enable default network status check
netstats = true

# Enable default disk status check
diskstats = true

# Enable default network I/O calculation
netio = true

# Enable default disk I/O calculation
diskio = true

# Enable default windows services status check
winservices = true

# Enable default systemd services status check
systemdservices = true

# If you have an Alfresco enterprise instance, JMX is configured and java installed, you can enable alfrescostats
alfrescostats = false

# Set your Alfresco JMX username
alfresco-jmxuser = monitorRole

# Set your Alfresco JMX password
alfresco-jmxpassword = change_asap

# Set your Alfresco host address
alfresco-jmxaddress = 0.0.0.0

# Set your Alfresco JMX port
alfresco-jmxport = 50500

# Set your Alfresco JMX path (path behind the JMX address "service:jmx:rmi:///jndi/rmi://0.0.0.0:50500")
alfresco-jmxpath = /alfresco/jmxrmi

# Set you custom Alfresco JMX query. Leave empty to use the default.
alfresco-jmxquery = 

# Path to the java binary (java need to be installed on agent host system in case you want to use alfrescostats)
alfresco-javapath = /usr/bin/java


# By default openITCOCKPIT will pull check results from the openITCOCKPIT Agent.
# In a Cloud environments or behind a NAT network it could become handy
# if the openITCOCKPIT Agent will push the results to your openITCOCKPIT Server
[oitc]

# Enable Push Mode
enabled = false

# The UUID of the Host.
# You can find this information in the openITCOCKPIT interface
# Example: 402357e4-dc34-4f5b-a86d-e59cfbb3ffe7
hostuuid =

# Address of your openITCOCKPIT Server
# Example: https://openitcockpit.io/receiver
url = 

# API-Key of your openITCOCKPIT Server
apikey =

# Determines in seconds how often the agent will push
# check results to your openITCOCKPIT Server
interval = 60

customchecks.cnf
[default]
# max_worker_threads should be increased with increasing number of custom checks
# but consider: each thread needs (a bit) memory
max_worker_threads = 8

#[check_users]
# command = /usr/lib/nagios/plugins/check_users -w 5 -c 10
# interval = 30
# timeout = 5
# enabled = true

#[check_load]
# command = /usr/lib/nagios/plugins/check_load -r -w .15,.10,.05 -c .30,.25,.20
# interval = 60
# timeout = 5
# enabled = true


The following configuration options are available in the [default] section of the config.cnf file:

Values marked in bold correspond to the default setting.

Parameter

Start parameter

Example value

Description

interval

-i --interval

30

Determines in seconds how often the agent will schedule all internal checks

port

-p --port

3333

Port of the Agents build-in web server

address

-a –address

127.0.0.1

Bind ip address of the build-in web server

auth

--auth

user:password

Enable basic authentication and define the credentials

verbose

-v --verbose

true / false

This information is only required in the INI file configuration

Adding the start parameter enables the output of information and error messages

stacktrace

-s --stacktrace

true / false

This information is only required in the INI file configuration

Adding the start parameter enables the output of possible stack traces

config-update-mode

--config-update-mode

true / false

This information is only required in the INI file configuration

Enables remote access to read and write new configurations.

Configuration update via POST requests.

/config to retrieve the current configuration via the agent's web server.

temperature-fahrenheit

--temperature-fahrenheit

true / false

This information is only required in the INI file configuration

Changes temperature information, if activated, to the unit Fahrenheit.

Default is Celsius


-h --help


Outputs a help message and ends the program


-c --config

[..]/config.cnf

Path to the agent configuration file

customchecks

--customchecks

[..]/customchecks.cnf

Path to the configuration file for custom checks

dockerstats

--dockerstats

true / false

This information is only required in the INI file configuration

Tries to check Docker Container and adds its status to standard output

qemustats

--qemustats

true / false

This information is only required in the INI file configuration

Tries to check QEMU virtual machines and adds their status to the standard output

(Linux only, beta)

cpustats--no-cpustats

true / false

This information is only required in the INI file configuration

Deactivates the default cpu status check
sensorstats--no-sensorstats

true / false

This information is only required in the INI file configuration

Deactivates the default sensor status check
processstats--no-processstats

true / false

This information is only required in the INI file configuration

Deactivates the default process status check
processstats-including-child-ids--processstats-including-child-ids

true / false

This information is only required in the INI file configuration

Add process child ids to the default process status check (computationally intensive)

netstats--no-netstats

true / false

This information is only required in the INI file configuration

Deactivates the default network status check
diskstats--no-diskstats

true / false

This information is only required in the INI file configuration

Deactivates the default disk status check
netio--no-netio

true / false

This information is only required in the INI file configuration

Deactivates the default network I/O calculation
diskio--no-diskio

true / false

This information is only required in the INI file configuration

Deactivates the default disk I/O calculation
winservices--no-winservices

true / false

This information is only required in the INI file configuration

Deactivates the default windows services status check (Windows only)
systemdservices

true / false

Deactivates the default systemd services status check


Adding the following parameters can activate the SSL encrypted web server (https):

Parameter

Start parameter

Example value

Description

certfile

--certfile

/path/to/cert.pem

If a certificate file is given, the agent will switch to https only

keyfile

--keyfile

/path/to/key.pem

Private key file of the given TLS certificate

(is required to specify the "certfile" option)

try-autossl

--try-autossl

true / false

Diese Angabe wird nur in der INI-Datei Konfiguration benötigt

Try to enable auto ssl mode for webserver

Requires the configuration of an openITCOCKPIT server in push mode


The file paths for the "autossl" option for automatically generating SSL certificates can be adjusted with the following parameters:

Parameter

Start parameter

Example value

Description

autossl-csr-file

--autossl-csr-file

/etc/openitcockpit/agent.csr

Path to the csr file (Certificate request)

autossl-crt-file

--autossl-crt-file

/etc/openitcockpit/agent.crt

Path to the crt file (Certificate)

autossl-key-file

--autossl-key-file

/etc/openitcockpit/agent.key

Path to the key file (Certificate key)

autossl-ca-file

--autossl-ca-file

/etc/openitcockpit/server_ca.crt

Path to the ca file (Certificate of the Certification Authority)


An Alfresco Enterprise instance can be monitored with the following parameters:

Parameter

Start parameter

Example value

Description

alfrescostats
true / false

If you have an Alfresco enterprise instance, JMX is configured and java installed, you can enable alfrescostats

alfresco-jmxuser
monitorRoleSet your Alfresco JMX username
alfresco-jmxpassword
change_asapSet your Alfresco JMX password
alfresco-jmxaddress
0.0.0.0Set your Alfresco host address
alfresco-jmxport
50500Set your Alfresco JMX port
alfresco-jmxpath
/alfresco/jmxrmiSet your Alfresco JMX path (path behind the JMX address "service:jmx:rmi:///jndi/rmi://0.0.0.0:50500")
alfresco-jmxquery

Set you custom Alfresco JMX query. Leave empty to use the default.
alfresco-javapath
/usr/bin/javaPath to the java binary (java need to be installed on agent host system in case you want to use alfrescostats)



The following configuration options are available in the [oitc] section of the config.cnf file:

The use of these options, except "enabled" and "interval", is required for the functionality of the "autossl" optionin push mode.

Parameter

Start parameter

Example value

Description

enabled


true / false

This information is only required in the INI file configuration

Enable Push Mode

Requires the configuration of an openITCOCKPIT server

hostuuid

--oitc-hostuuid

402357e4-d…...

The UUID of the openITCOCKPIT host

url

--oitc-url

https://openitcockpit.io

Address of your openITCOCKPIT Server

apikey

--oitc-apikey

1XC8nZ2On…...

API-Key of your openITCOCKPIT Server

interval

--oitc-interval

30

Determines in seconds how often the agent will push check results to your openITCOCKPIT Server


If a configuration file is specified for your own checks, the following parameters can be used to configure them.

[default] section of the customchecks.cnf file:

Parameter

Example value

Description

max_worker_threads

8

Maximum number of threads that can be used to edit custom checks


If you want to add your own check, you must assign it a unique name. This is written as a section in square brackets.

[username] section of the customchecks.cnf file:

Parameter

Example value

Description

command

whoami

Command of the check to be carried out or path to the file to be executed

interval

120

Defines in seconds how often the agent performs the defined check

timeout

5

Specifies the time after which the check should be terminated at the latest

enabled

true / false

Activates or deactivates the check


Run a powershell script as custom check

Be sure the path to the customcheck.cnf is configured in your config.cnf in C:\Program Files\it-novum\openitcockpit-agent\.

Adjust the customcheck timeout if required. Try it with a timeout of 10 seconds. If you still get a timeout, we recommend to gradually increase the timeout value.

Your command should look like this example command.

Example PowerShell script
Write-Host "Hallo customcheck"
exit 3
In C:\Program Files\it-novum\openitcockpit-agent\customchecks.cnf
[check_xyz]
command = powershell.exe -File "C:\example.ps1"
interval = 60
timeout = 10
enabled = true


Open a CMD as Administrator.

You need to activate the execution of powershell script files.

Restart the agent to apply the customized configuration.

CMD as Administrator
powershell Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
sc.exe stop oitcAgentSvc
sc.exe start oitcAgentSvc

After that you can add the new check as service to a host using the openITCOCKPIT Agent Configuration.

(Follow the instructions as described in Usage)


Later change between pull and push mode

The pull mode has been configured, services have already been created and are being monitored

  1. Go to agent configuration for your host
  2. Choose the push mode
  3. Generate an Api-Key and insert it in the "openITCOCKPIT Api-Key" field.
  4. Check whether the displayed openITCOCKPIT server address can be reached from the agent's host. Correct them if necessary. The protocol (https) must always be specified.
  5. Press Next and copy the lower part of the generated agent configuration (from [oitc]). This part must be added to the agent configuration file on the system being monitored. If an [oitc] area already exists in the configuration, this must be overwritten!
  6. The agent must then be restarted to load the configuration. A short guide to this can be found in openITCOCKPIT under the generated configuration. The following commands can be used:
  7. Windows CMDsc stop oitcAgentSvc && sc start oitcAgentSvc
    Linuxsystemctl restart openitcockpit-agent
    macOS

    /bin/launchctl restart com.it-novum.openitcockpit.agent

  8. After restarting the agent, you should wait about 5-10 seconds so that the agent can send the first check results to openITCOCKPIT. Click on Next to continue.
  9. Additional monitoring services can be added on request. In any case (even without a selection), click Next again to save the configuration.
  10. Finally, an export must be carried out in order to transfer the changes to the monitoring system.
  11. The host's services monitored by the agent should now update automatically every minute.


The push mode has been configured, services have already been created and are being monitored

  1. Switch to agent configuration of the host concerned
  2. Choose the pull mode
  3. If the agent's web server port was changed beforehand, this change must be made in the agent configuration interface of the openITCOCKPIT.
  4. The agent on the host being monitored must be stopped before proceeding. The following commands can be used for the respective system:
  5. Windows CMDsc stop oitcAgentSvc
    Linuxsystemctl stop openitcockpit-agent
    macOS

    /bin/launchctl stop com.it-novum.openitcockpit.agent

  6. Press Next to display the generated configuration. Open the configuration file of the agent on the system to be monitored and make sure that the option "enabled = false" is set in the [oitc] area!
  7. The agent must then be started to load the configuration. This can be done as follows:
  8. Windows CMDsc start oitcAgentSvc
    Linuxsystemctl start openitcockpit-agent
    macOS

    /bin/launchctl start com.it-novum.openitcockpit.agent

  9. Click on Next to continue.
  10. The options shown come from outdated, cached data that the agent previously sent to openITCOCKPIT in push mode. You must continue with Next (with or without selection).
  11. Finally, an export must be carried out in order to transfer the changes to the monitoring system.


Access to the agent's web server

The agent provides the results of the checks via the integrated web server. The output is in JSON format.

Unless otherwise configured, the web server can be called up in a web browser by specifying a URL from the IP address of the executing host.

e.g. http://0.0.0.0:3333/

The complete structure of the output can be found in the real edition of the running agent.


The following higher-level objects are partially output in JSON format, each of them contains further objects with the check results.

  • disks (Storage devices with mount point, file system and storage space information)
  • disk_io (Read and write statistics of the storage devices)
  • net_io (Input and output statistics of the network devices)
  • net_stats (Network devices with available speed, ...)
  • sensors (Connected sensors, e.g. CPU temperature, battery status)
  • cpu_total_percentage (CPU computing time used in percent)
  • cpu_percentage (CPU processing time used per core in percent)
  • cpu_total_percentage_detailed (CPU computing time in percent per system resource)
  • cpu_percentage_detailed (CPU computing time in percent per system resource per core)
  • system_load (System load 1, 5, 15 as array)
  • users (Users logged on to the system, their terminal (PID), time of login)
  • memory (Memory information, used, active, buffered, ...)
  • swap (Swap storage information, total, used, ...)
  • processes (Information about running processes, CPU, RAM, PID, ...)
  • agent (Agent version, time of last check, system version, ...)
  • dockerstats (Active Docker Container, ID, CPU, RAM, Block IO, PID)
  • qemustats (Information about active QEMU machines (on a Proxmox and most qemu linux hosts))

.....


Get / update configuration via API

For security reasons, the configuration via API should only be activated after a successful SSL configuration.

Warning: Remote code execution is possible if the certificate has been stolen or SSL has not been configured.

You can update the main configuration as well as the configuration for custom checks during operation by sending a post request with json formatted data.

Required adjustment of the default configuration:

config.cnf
[oitc]

# Enable remote read and write of THIS config file and custom checks definition
config-update-mode = true
Example: get configuration
curl http://0.0.0.0:3333/config
Example: update configuration
curl -X POST -d '{"config": {"interval": "60", "port": "3333", "address": "0.0.0.0", "verbose": "true", "stacktrace": "false", "config-update-mode": "true", "temperature-fahrenheit": "false", "oitc-host": "", "oitc-url": "", "oitc-apikey": "", "oitc-interval": "60", "oitc-enabled": "false"}, "customchecks": {}}' http://0.0.0.0:3333/config
Example: update configuration (from file)
curl -X POST -d @new_config.json http://0.0.0.0:3333/config -u user:pass
Example file: new_config.json
{
   "config":{
      "interval":"30",
      "port":"3333",
      "address":"0.0.0.0",
      "certfile":"",
      "keyfile":"",
      "try-autossl":"true",
      "autossl-folder":"/etc/openitcockpit-agent",
      "verbose":"false",
      "stacktrace":"false",
      "config-update-mode":"true",
      "auth":"",
      "customchecks":"/etc/openitcockpit-agent/oitc_customchecks.conf",
      "temperature-fahrenheit":"false",
      "dockerstats":"true",
      "qemustats":"true",
      "cpustats":"true",
      "sensorstats":"true",
      "processstats":"true",
      "processstats-including-child-ids":"false",
      "netstats":"true",
      "diskstats":"true",
      "netio":"true",
      "diskio":"true",
      "winservices":"true",
      "systemdservices":"true",
      "alfrescostats":"false",
      "alfresco-jmxuser":"monitorRole",
      "alfresco-jmxpassword":"test123",
      "alfresco-jmxaddress":"10.10.10.1",
      "alfresco-jmxport":"50500",
      "alfresco-jmxpath":"/alfresco/jmxrmi",
      "alfresco-jmxquery":"",
      "alfresco-javapath":"/usr/bin/java",
      "oitc-hostuuid":"",
      "oitc-url":"",
      "oitc-apikey":"",
      "oitc-interval":"60",
      "oitc-enabled":"false"
   },
   "customchecks":{
      "default": {
         "max_worker_threads": 8
      },
      "username": {
         "command": "whoami",
         "interval": 30,
         "timeout": 5,
         "enabled": "1"
      },
      "uname": {
         "command": "uname -a",
         "interval": 15,
         "timeout": 5,
         "enabled": "0"
      }
   }
}


Get and update configuration with HTTPS and autossl.

The following command could be executed on an openITCOCKPIT server.

Example: get and save configuration (HTTPS/autossl)
curl https://192.168.122.1:3333/config --cert /opt/openitc/agent/server_ca.pem --key /opt/openitc/agent/server_ca.key -k -o agentconfig.json
Example: update configuration (HTTPS/autossl)
curl -X POST -d @agentconfig.json https://192.168.122.1:3333/config --cert /opt/openitc/agent/server_ca.pem --key /opt/openitc/agent/server_ca.key -k


Configuration via API via another host

The configuration via API should only be done using the agent configuration in openITCOCKPIT.

Manually changing the configuration can mean that openITCOCKPIT can no longer reach the agent.

Change e.g. the web server port or the activation / deactivation of HTTPS encryption should only be done in openITCOCKPIT!

If the configuration should be done productively via the Agent API, we recommend creating your own certificate for this purpose.

This can then simply be copied to another host from which the configuration will be updated.

Creation of your own certificate by the openITCOCKPIT Agent CA

openssl genrsa -out customcert.oitc.key 4096

openssl req -new -sha512 -key customcert.oitc.key -subj "/C=US/ST=CA/O=MyOrg, Inc./CN=customcert.oitc" -out customcert.oitc.csr -config <(cat /etc/ssl/openssl.cnf | sed "s/RANDFILE\s*=\s*\$ENV::HOME\/\.rnd/#/")

openssl x509 -req -in customcert.oitc.csr -CA /opt/openitc/agent/server_ca.pem -CAkey /opt/openitc/agent/server_ca.key -CAcreateserial -out customcert.oitc.crt -days 365 -sha512
Example: Using your own certificate to read the agent configuration
curl https://192.168.122.1:3333/config --cert customcert.oitc.crt --key customcert.oitc.key -k


Access the encrypted agent webserver

Create a .p12 file to import as certificate in your web browser (like Firefox) to be able to browse to the encrypted agent webserver.
Generate custom client certificates like described in the previous section (Creation of your own certificate by the openITCOCKPIT Agent CA).

Create the browser certificate from your generated client certificate
cat customcert.oitc.crt customcert.oitc.key > both_customcert.oitc.pem
openssl pkcs12 -export -in both_customcert.oitc.pem -out both_customcert.oitc.p12


openITCOCKPIT integration - Nice to know :)

- Create host (Button: Create host and and setup Agent)

- Setting up the agent on the host (to create the standard checks)

- The agent must be trusted for push mode with automatic certificate generation. This authorization can be withdrawn at any time.

- Agent configuration:

  • Basic Mode (Pull from Agent HTTP Webserver)
  • Advanced Security Mode (Pull from Agent HTTPS Webserver or Push) with automatic certificate generation
  • Agent output is evaluated and the data to be monitored should be selected
  • Save configuration

- openITCOCKPIT creates the services based on the check-specific agent service templates (standard values can be adjusted there)

  • Services are configured passively and receive a "dummy command" and the service_type = 16 in the database.

- Export

  • The host gets an active, automatically generated service that connects to the agent every minute to query the current data.

- Check data sent by the agent to openITCOCKPIT in push mode are evaluated directly. The latest version is always saved in the database to enable a later fluid agent configuration.


Certificate authentication

As standard, openITCOCKPIT is the CA (certification authority) for generating the agent's required certificates for an HTTPS connection.


Push Mode:

The agent creates a certificate request that is sent to the openITCOCKPIT server.

Im openITCOCKPIT muss in der Agent Overview im Bereich Untrusted Agents dem Agent mit entsprechendem Host und IP manuell vertraut werden.

In openITCOCKPIT, the agent with the corresponding host and IP must be trusted manually in the Agent Overview in the Untrusted Agents area.

  • if the agent is not yet trusted, the agent receives a corresponding error message and tries again after 10 minutes.
  • if the agent has been trusted, the next request will be answered with the certificate.

Pull Mode:

If the AutoSSL option has been activated in the openITCOCKPIT configuration interface for the agent, a connection to the agent web server is established after the services have been created in order to obtain a new certificate request.

Since the "try-autossl" option is activated by default in the agent's configuration file, a certificate request is generated and returned. If this option is deactivated, nothing further happens.

If a valid certificate request has been returned to openITCOCKPIT, it is signed and the resulting certificate (as well as the current CA certificate) is sent to the agent.


A client certificate of a configured CA is then required to access the agent web server.

Requests to the agent web server without a certificate issued by the same CA are rejected.


Known problems

C - Compatibility with Linux systems

"glibc" or "libc6" is a central C library on Linux systems. Version 2.17 or higher is required to run the Python-based agent from source.

If you want to use the agent on a system with a "glibc" or "libc6" version <2.17, please contact our support.

"Network device IO", "Processes" or "Windows services" checks failed

Due to an error in the openITCOCKPIT 4 Beta version, the following service templates must be updated on some systems.

OITC_AGENT_NET_IO

OITC_AGENT_PROCESSES

OITC_AGENT_WINDOWS_SERVICES

The following SQL statements can be executed to correct the error.

use openitcockpit;
update servicetemplatecommandargumentvalues set value='' where value=' ' and servicetemplate_id in (select id from servicetemplates where template_name in ('OITC_AGENT_NET_IO','OITC_AGENT_PROCESSES','OITC_AGENT_WINDOWS_SERVICES'));
update servicecommandargumentvalues set value='' where value=' ' and service_id in (select id from services where service_type=16 and servicetemplate_id in (select id from servicetemplates where template_name in ('OITC_AGENT_NET_IO','OITC_AGENT_PROCESSES','OITC_AGENT_WINDOWS_SERVICES')));



  • No labels