Agent-Push-Client

Client to push monitoring data from local or remote queried agents to the Agent-Push-Server. The Agent-Push-Client was developed as an alternative to the missing push agent for checkmk Community.

Security notes

• Always use TLS in production.

  Clients authenticate with a bearer token sent in the Authorization header. Without TLS this secret is transmitted in cleartext. Always use https URLs for the server connection.

• Remote agent data is unencrypted.

  Data collected remotely from check_mk_agent via TCP Port 6556 is unencrypted and not authenticated. This should only be used in trusted networks.

• Always check configuration permissions.

  The access rights for the configuration files are fundamental to the security of the stored access credentials. Please refer to the documentation in the "Copy example configuration files" sections.

Dependencies

System (Debian-related)

• git
• python3 (tested with 3.12)
• python3-venv

Python modules

• see requirements.txt

Installation (Docker)

Please note: Running as a docker container, query local agent is disable as it would query the agent inside container.

Requirements

Docker needs to be installed.

Build image

1. Clone repository

   git clone https://github.com/mape2k/agent-push-client

2. Build docker image

   docker build -t mape2k/agent-push-client:latest agent-push-client/.

Running image

1. Copy example configuration files

   sudo cp agent-push-client/config/config.example.toml agent-push-client/config.toml
   sudo chown 10001:10001 agent-push-client/config.toml
   sudo chmod 0400 agent-push-client/config.toml    

2. Adjust configuration file agent-push-client/config.toml

3. Copy example docker compose file

   sudo cp agent-push-client/docker-compose.example.yml agent-push-client/docker-compose.yml

4. Adjust docker compose file agent-push-client/docker-compose.yml

5. Run docker image with compose

   cd agent-push-client
   docker compose up

Installation

You should run this application using a dedicated user.

Requirements

Install system requirements and create user.

Debian

sudo apt-get update
sudo apt-get install python3-venv git
sudo useradd --no-create-home --home-dir /nonexistent \
  --shell /usr/sbin/nologin --user-group agent-push-client

Gentoo

sudo emerge dev-vcs/git
sudo useradd --no-create-home --home-dir /nonexistent \
  --shell /usr/sbin/nologin --user-group agent-push-client

Agent-Push-Client

1. Clone repository

   cd /opt
   sudo git clone https://github.com/mape2k/agent-push-client
   sudo chown --recursive root:root /opt/agent-push-client

2. Initialize virtual environment

   sudo python3 -m venv /opt/agent-push-client/virtualenv

3. Install python requirements in virtual environment

   sudo /opt/agent-push-client/virtualenv/bin/pip install -r /opt/agent-push-client/requirements.txt

4. Copy example configuration files

   sudo mkdir /etc/agent-push-client
   sudo cp /opt/agent-push-client/config/config.example.toml /etc/agent-push-client/config.toml
   sudo chown root:agent-push-client /etc/agent-push-client/config.toml
   sudo chmod 0640 /etc/agent-push-client/config.toml    

5. Adjust configuration file /etc/agent-push-client/config.toml

Debian (systemd)

1. Copy systemd unit file

   sudo cp /opt/agent-push-client/contrib/systemd/agent-push-client.service /etc/systemd/system/agent-push-client.service

2. Adapt /etc/systemd/system/agent-push-client.service if you change installation directory or use another user.

3. Copy sudoers file (if you want to collect data from local agent with sudo)

   sudo cp /opt/agent-push-client/contrib/sudo/agent-push-client /etc/sudoers.d/agent-push-client

4. Reload systemd daemon to reload unit file and start and enable service

   sudo systemctl daemon-reload
   sudo systemctl enable agent-push-client.service --now

Gentoo (OpenRC)

1. Copy OpenRC config and init file

   sudo cp /opt/agent-push-client/contrib/openrc/agent-push-client.confd /etc/conf.d/agent-push-client
   sudo cp /opt/agent-push-client/contrib/openrc/agent-push-client.initd /etc/init.d/agent-push-client

2. Copy logrotate file

   sudo cp /opt/agent-push-client/contrib/logrotate/agent-push-client /etc/logrotate.d/agent-push-client

3. Copy sudoers file (if you want to collect data from local agent with sudo)

   sudo cp /opt/agent-push-client/contrib/sudo/agent-push-client /etc/sudoers.d/agent-push-client

4. Add agent-push-client to default start and start service

   sudo rc-update add agent-push-client
   sudo /etc/init.d/agent-push-client start

Update (Docker)

1. Update repository

   cd agent-push-client
   git pull

2. Rebuild docker image

   docker build -t mape2k/agent-push-client:latest .

3. Adjust configuration file config/config.toml

4. Check for differences in docker-compose.examle.yml to your docker-compose.yml.

5. Re-run docker image with compose

   docker compose down
   docker compose up

Update (Debian / Gentoo)

1. Update repository

   cd /opt/agent-push-client
   git pull

2. Update virtual environment

   sudo python3 -m venv --upgrade /opt/agent-push-client/virtualenv

3. Update python requirements in virtual environment

   sudo /opt/agent-push-client/virtualenv/bin/pip install --upgrade -r /opt/agent-push-client/requirements.txt

4. Adjust configuration file /etc/agent-push-client/config.toml

Debian

1. Check for differences in systemd service and sudo files.

2. Restart

   sudo systemctl restart agent-push-client.service

Gentoo

1. Check for differences in init, conf.d and sudo files.

2. Restart

   sudo /etc/init.d/agent-push-client restart

Changelog

1.1.0

• Breaking
  • Source timeout is now the total budget per collection (connect and data transfer), previously it applied per connect/read operation
• Security
  • Limit collected agent data to 5 MiB to protect client memory
  • Warn when the server URL uses plain http
  • Restrict sudoers rule to check_mk_agent without arguments
  • Document config file permissions (plaintext secret) and add security notes to README
• Fixed
  • Validate server.url and server.secret at startup with clear error messages
  • SIGHUP no longer terminates the daemon (reload was never supported); remove ExecReload
  • Align OpenRC respawn behavior with systemd (fail loudly on crash)
  • Log "collected" only after successful collection; fix log message typo
• Changed
  • Declare urllib3 as direct dependency

1.0.0

• Initial implementation

Disclosure

Parts of this project were generated or assisted using Claude Code.