Skip to main content

Deploying the Agent

Once the agent is registered and config.yml is updated with the assigned agent_id and api_key, you can deploy it as a permanent system service.

Step 1 — Prepare the Agent Directory​

# Create the agent directory
mkdir -p /opt/pmp4pg-agent
mkdir -p /var/log/pmp4pg-agent
mkdir -p /var/lib/pmp4pg-agent
mkdir -p /etc/pmp4pg/agent

# Extract the agent archive
tar -xzf pmp4pg-agent-v1.0.0-linux-amd64.tar.gz -C /opt/pmp4pg-agent

# Make the binary executable
chmod +x /opt/pmp4pg-agent/pmp4pg-agent

# Copy the config
cp config.yml /etc/pmp4pg/agent/config.yml

# Create a dedicated system user (no login shell)
useradd -r -s /sbin/nologin -d /opt/pmp4pg-agent pmp-agent

# Set ownership
chown -R pmp-agent:pmp-agent /opt/pmp4pg-agent
chown -R pmp-agent:pmp-agent /var/log/pmp4pg-agent
chown -R pmp-agent:pmp-agent /var/lib/pmp4pg-agent
chown pmp-agent:pmp-agent /etc/pmp4pg/agent/config.yml

Step 2 — Create the systemd Service​

cat > /etc/systemd/system/pmp4pg-agent.service << 'EOF'
[Unit]
Description=PMP4PG Monitoring Agent
After=network.target postgresql.service
Wants=postgresql.service

[Service]
Type=simple
User=pmp-agent
Group=pmp-agent
WorkingDirectory=/opt/pmp4pg-agent
ExecStart=/opt/pmp4pg-agent/pmp4pg-agent \
  --config /etc/pmp4pg/agent/config.yml
Restart=on-failure
RestartSec=15
StandardOutput=journal
StandardError=journal
SyslogIdentifier=pmp4pg-agent

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/var/log/pmp4pg-agent /var/lib/pmp4pg-agent

[Install]
WantedBy=multi-user.target
EOF

# Reload systemd
systemctl daemon-reload

Step 3 — Enable and Start the Agent​

# Enable the service to start on boot
systemctl enable pmp4pg-agent

# Start the agent
systemctl start pmp4pg-agent

# Check status
systemctl status pmp4pg-agent

Expected output:

● pmp4pg-agent.service - PMP4PG Monitoring Agent
     Loaded: loaded (/etc/systemd/system/pmp4pg-agent.service; enabled)
     Active: active (running) since ...

Step 4 — Verify the Agent is Running​

# Follow live logs
journalctl -u pmp4pg-agent -f

Expected log output on successful startup:

INFO  PMP4PG Agent starting — version 1.0.0
INFO  Agent ID: a3f1c2d4-8b5e-4f2a-9c1d-0e7f3b2a6d8c
INFO  Connected to PostgreSQL 16.2 on localhost:5432
INFO  Starting ASH collector — interval: 2s
INFO  Starting heartbeat sender — interval: 30s
INFO  Starting pg_stat_statements collector — interval: 60s
INFO  Starting pg_stat_database collector — interval: 60s
INFO  Starting database_size collector — interval: 10m
INFO  Starting os_metrics collector — interval: 60s
INFO  Agent running.

Managing the Agent Service​

ActionCommand
Startsystemctl start pmp4pg-agent
Stopsystemctl stop pmp4pg-agent
Restartsystemctl restart pmp4pg-agent
Statussystemctl status pmp4pg-agent
Logs (live)journalctl -u pmp4pg-agent -f
Logs (last 100 lines)journalctl -u pmp4pg-agent -n 100 --no-pager
Disable autostartsystemctl disable pmp4pg-agent

Upgrading the Agent​

# Stop the agent
systemctl stop pmp4pg-agent

# Replace the binary
tar -xzf pmp4pg-agent-vX.Y.Z-linux-amd64.tar.gz -C /opt/pmp4pg-agent
chmod +x /opt/pmp4pg-agent/pmp4pg-agent
chown pmp-agent:pmp-agent /opt/pmp4pg-agent/pmp4pg-agent

# Restart
systemctl start pmp4pg-agent
note

The config.yml (including agent_id and api_key) does not change on upgrade. No re-registration is required.

Deploying to Multiple Servers​

For each additional PostgreSQL server to monitor:

  1. Copy the agent binary to the new server
  2. Create a fresh config.yml with the correct PostgreSQL connection and central.api_url
  3. Generate a new registration token from the platform
  4. Run --register on the new server
  5. Update config.yml with the new agent_id and api_key
  6. Create the systemd service and start

Each server gets its own unique agent_id and api_key. Never reuse credentials across servers.

Next Steps​