This guide covers installing the debian-agent on a server and obtaining enrollment tokens for client registration.
scp debian-agent_1.0.28_amd64.deb root@your-server:/tmp/dpkg -i /tmp/debian-agent_1.0.28_amd64.debThe package automatically:
/usr/local/bin/debian-agentsystemctl status debian-agent ● debian-agent.service - Debian Agent - Secure System Administration API Loaded: loaded (/etc/systemd/system/debian-agent.service; enabled) Active: active (running)
debian-agent versionEnrollment tokens are required for clients to register and obtain mTLS certificates.
debian-agent token list HASH PREFIX CREATED EXPIRES USED USED BYABC-123-XYZ 2024-01-15 10:30 2024-01-15 11:30 no XY9-456-ZVF 2024-01-15 09:00 2024-01-15 10:00 yes client-01debian-agent token add ABC-123-XYZGenerate random token TOKEN=$(cat /dev/urandom | tr -dc 'A-Z0-9' | fold -w 3 | head -3 | paste -sd'-')debian-agent token add $TOKENecho "Enrollment token: $TOKEN"/etc/debian-agent/config.json:{ "enrollment": { "token_ttl_seconds": 86400 }}systemctl restart debian-agentdebian-agent token revoke ABC-123-XYZ
Once you have a token, provide these details to the client administrator:
| Parameter | Value |
|---|---|
| Server URL | https://<server-ip>:28811 |
| Enrollment Endpoint | POST /register |
| Token | ABC-123-XYZ |
The client generates a key pair and sends the public key:
On client: Generate ECDSA key pair: openssl ecparam -name secp384r1 -genkey -noout -out client.key openssl ec -in client.key -pubout -out client.pub
Register with the server curl -k https://192.168.1.100:28811/register -H "Content-Type: application/json" -d '{"token": "ABC-123-XYZ", "cn": "client-hostname","public_key_pem":"'"$(cat client.pub)"'"}'
Response contains the signed client certificate and CA certificate for mTLS.
Configuration file: /etc/debian-agent/config.json
Key Settings
| Setting | Default | Description |
|---|---|---|
listen_addr |
0.0.0.0 |
Bind address |
listen_port |
28811 |
HTTPS port |
listen_interface |
`` | Bind to specific interface (e.g., eth0) |
tls.require_mtls_on_api |
true |
Require client certs for API |
enrollment.token_ttl_seconds |
3600 |
Token expiration (seconds) |
scheduler.interval_hours |
6 |
Background refresh interval |
{ "listen_interface": "eth1", "listen_port": 28811}
{ "security": { "enable_ip_whitelist": false }}
Allow incoming connections on the agent port:
ufw allow 28811/tcp iptables iptables -A INPUT -p tcp --dport 28811 -j ACCEPT
journal journalctl -u debian-agent -ftail -f /var/log/debian-agent/agent.log
| Issue | Solution |
|---|---|
| Service won't start | Check logs: journalctl -u debian-agent -e |
| Token rejected | Verify token format (XXX-000-XXX) and expiration |
| Connection refused | Check firewall and listen_addr setting |
| Certificate errors | Regenerate PKI: rm -rf /var/lib/debian-agent/pki /var/lib/debian-agent/tls && systemctl restart debian-agent |
From the server (uses Unix socket, no auth needed)
curl --unix-socket /run/debian-agent/admin.sock http://localhost/healthz
Remote with mTLS
curl --cert client.crt --key client.key --cacert ca.crt https://server:28811/api/v3/status
| Path | Purpose |
|---|---|
/etc/debian-agent/config.json |
Configuration |
/var/lib/debian-agent/pki/ |
CA certificate and key |
/var/lib/debian-agent/tls/ |
Server certificate |
/var/lib/debian-agent/agent.db |
Database (tokens, certs) |
/var/log/debian-agent/agent.log |
Log file |
/run/debian-agent/admin.sock |
Local admin socket |