Agent Installation

Agent Installation

The QCecuring SSL-CLM Agent enables secure, distributed certificate lifecycle execution on remote infrastructure. Deploy agents on servers that need:

• Local CA access (e.g., Microsoft AD CS on a domain-joined server)
• File-based certificate deployment (NGINX, Apache, JKS stores)
• IIS certificate management
• Local network discovery
• Store scanning

The agent does not expose inbound ports — all communication is outbound via HTTPS/mTLS.

---

Supported Platforms

OS	Version	Architecture
Windows Server	2016, 2019, 2022	x64
Ubuntu	20.04, 22.04, 24.04	x64, ARM64
RHEL / CentOS	8, 9	x64
Debian	11, 12	x64
SUSE	15	x64

---

Prerequisites

Requirement	Details
Java	21+
Network	Outbound HTTPS to SSL-CLM platform (port 8080 or 443)
Bootstrap Token	Generated from the platform UI
Disk	~100 MB for agent + logs
RAM	256 MB minimum, 512 MB recommended

---

Step 1 — Generate Bootstrap Token

1. In the SSL-CLM UI, navigate to Infrastructure → Agents
2. Click + Register Agent
3. Enter the agent hostname
4. Click Generate Token
5. Copy the one-time bootstrap token

The token is:

• Single-use — Consumed on first registration
• Time-limited — Expires after 24 hours (configurable)
• Non-recoverable — Cannot be viewed again after generation

---

Step 2 — Install Java

Linux (Ubuntu/Debian)

sudo apt update && sudo apt install -y openjdk-21-jre-headless
java -version

Linux (RHEL/CentOS)

sudo dnf install -y java-21-openjdk-headless
java -version

Windows

Download and install Java 21 from Adoptium. Verify:

java -version

---

Step 3 — Download the Agent

Download the agent JAR from the platform:

• Navigate to Infrastructure → Agents → Download Agent
• Or obtain from your deployment package

Place on the target server:

mkdir -p /opt/ssl-clm-agent
cp ssl-clm-agent-<version>.jar /opt/ssl-clm-agent/

---

Step 4 — First Run (Bootstrap)

Linux

java -jar /opt/ssl-clm-agent/ssl-clm-agent.jar \
  --backend.url=https://ssl-clm.example.com:8080 \
  --bootstrap.token=YOUR_BOOTSTRAP_TOKEN

Windows (PowerShell)

$env:BACKEND_URL = "https://ssl-clm.example.com:8080"
$env:AGENT_BOOTSTRAP_TOKEN = "YOUR_BOOTSTRAP_TOKEN"
java -jar C:\ssl-clm-agent\ssl-clm-agent.jar

What Happens During Bootstrap

1. Agent sends the bootstrap token to the platform
2. Platform validates the token (one-time use)
3. Platform issues an mTLS client certificate to the agent
4. Agent stores the certificate and key locally
5. Agent begins heartbeat reporting
6. Agent appears in the Agents list as BOOTSTRAPPING → ONLINE

After successful bootstrap, the token is consumed and not needed again.

---

Step 5 — Configuration File

After bootstrap, create a persistent configuration:

Linux: /opt/ssl-clm-agent/application.properties

# Platform connection
backend.url=https://ssl-clm.example.com:8080

# Intervals (milliseconds)
agent.heartbeat.fixedDelayMs=30000
agent.jobs.fixedDelayMs=10000

# mTLS (auto-configured after bootstrap)
backend.mtls.enabled=true
backend.mtls.client-cert-path=/opt/ssl-clm-agent/certs/client.pem
backend.mtls.client-key-path=/opt/ssl-clm-agent/certs/client-key.pem
backend.mtls.ca-cert-path=/opt/ssl-clm-agent/certs/ca.pem

# Microsoft CA (enable if agent manages ADCS)
agent.msca.enabled=false
# agent.msca.ca-identifier=WIN-SERVER\\my-ca

# Logging
logging.level.root=INFO
logging.file.name=/var/log/ssl-clm-agent/agent.log

Windows: C:\ssl-clm-agent\application.properties

backend.url=https://ssl-clm.example.com:8080
agent.heartbeat.fixedDelayMs=30000
agent.jobs.fixedDelayMs=10000
backend.mtls.enabled=true
agent.msca.enabled=true
agent.msca.ca-identifier=WIN-SERVER\\my-ca
logging.level.root=INFO

---

Step 6 — Run as a Service

Linux (systemd)

Create /etc/systemd/system/ssl-clm-agent.service:

[Unit]
Description=SSL-CLM Agent
After=network.target

[Service]
Type=simple
User=ssl-clm-agent
WorkingDirectory=/opt/ssl-clm-agent
ExecStart=/usr/bin/java -jar /opt/ssl-clm-agent/ssl-clm-agent.jar
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo useradd -r -s /bin/false ssl-clm-agent
sudo chown -R ssl-clm-agent: /opt/ssl-clm-agent
sudo systemctl daemon-reload
sudo systemctl enable ssl-clm-agent
sudo systemctl start ssl-clm-agent
sudo systemctl status ssl-clm-agent

Windows (NSSM)

nssm install SSLCLMAgent "C:\Program Files\Java\jdk-21\bin\java.exe" "-jar C:\ssl-clm-agent\ssl-clm-agent.jar"
nssm set SSLCLMAgent AppDirectory "C:\ssl-clm-agent"
nssm start SSLCLMAgent

---

Step 7 — Verify

1. Check the platform UI: Infrastructure → Agents — agent should show ONLINE
2. Check agent logs:

   # Linux
   journalctl -u ssl-clm-agent -f
   # Or
   tail -f /var/log/ssl-clm-agent/agent.log

3. Test with a job: trigger a discovery scan or CA refresh from the UI

---

MSCA-Specific Configuration

For agents managing Microsoft AD CS:

agent.msca.enabled=true
agent.msca.ca-identifier=WIN-SERVER\\my-ca-name

Additional Windows requirements:

• Server must be domain-joined
• Agent process must run as a domain user with enrollment permissions
• certutil must be available in PATH

Optional environment variables for AD CS authentication:

ADCS_SERVER=WIN-SERVER
ADCS_USERNAME=DOMAIN\ServiceAccount
ADCS_PASSWORD=StrongPassword

---

File Permissions (Linux)

For agents deploying to web servers, ensure the agent user has write access:

# For NGINX cert paths
sudo chown ssl-clm-agent: /etc/nginx/ssl/
sudo chmod 750 /etc/nginx/ssl/

# For Apache cert paths
sudo chown ssl-clm-agent: /etc/ssl/certs/ /etc/ssl/private/

# For reload commands (sudoers)
echo "ssl-clm-agent ALL=(root) NOPASSWD: /bin/systemctl reload nginx, /bin/systemctl reload apache2" | sudo tee /etc/sudoers.d/ssl-clm-agent

---

Security Hardening

Practice	Implementation
Run as dedicated user	ssl-clm-agent user with minimal permissions
mTLS only	Disable plain HTTP after bootstrap
Restrict outbound	Firewall allows only HTTPS to platform
Rotate credentials	Agent cert auto-renewed by platform
Log monitoring	Forward agent logs to SIEM
Least privilege	Only grant file/service permissions needed

---

Troubleshooting

Issue	Possible Cause	Resolution
Bootstrap fails	Token expired or already used	Generate a new token
Connection refused	Wrong backend URL or port	Verify URL and firewall rules
mTLS handshake error	CA cert mismatch	Ensure agent CA cert matches platform
Agent OFFLINE after reboot	Service not enabled	systemctl enable ssl-clm-agent
Deploy job fails	File permission denied	Check agent user has write access to cert paths
MSCA operations fail	Not domain-joined or wrong CA identifier	Verify domain membership and certutil -ping

---

Next Steps

After the agent is running:

1. Configure Certificate Stores assigned to this agent
2. Add a Certificate Authority (if agent-based CA)
3. Run a discovery scan using this agent
4. Deploy a certificate to verify end-to-end flow