Skip to content

Commit 74d7c2a

Browse files
DigiCertMikeDigiCertMike
committed
added readme file for kemp loadbalancer integration
1 parent 1536d25 commit 74d7c2a

File tree

1 file changed

+171
-1
lines changed
  • TrustLifeCycleManager/Integrations/Kemp_Loadbalancer

1 file changed

+171
-1
lines changed

‎TrustLifeCycleManager/Integrations/Kemp_Loadbalancer/README.md‎

Lines changed: 171 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,171 @@
1-
As of October 6th, 2024, firmware version 7.2.60.0.22484 and later have a native Digicert ACME client included
1+
# Kemp LoadMaster — DigiCert TLM Agent AWR Post-Enrollment Scripts
2+
3+
Automated certificate deployment to [Kemp LoadMaster](https://kemptechnologies.com/loadmaster) load balancers using [DigiCert Trust Lifecycle Manager (TLM)](https://www.digicert.com/trust-lifecycle-manager) Agent post-enrollment hooks (AWR).
4+
5+
Available in **Bash** (Linux) and **PowerShell** (Windows) — both scripts are functionally equivalent.
6+
7+
---
8+
9+
## Overview
10+
11+
These scripts run automatically after the DigiCert TLM Agent enrolls or renews a certificate. They perform four steps:
12+
13+
1. **Combine** the issued certificate and private key into a single PEM bundle.
14+
2. **Check** whether a certificate with the configured name already exists on the LoadMaster (`listcert`).
15+
3. **Upload** the PEM to the LoadMaster via `addcert`, replacing the existing certificate if present.
16+
4. **Assign** the certificate to a target Virtual Service via `modvs`.
17+
18+
The result is fully automated, zero-touch certificate lifecycle management for TLS-terminated Virtual Services on Kemp LoadMaster appliances.
19+
20+
## Prerequisites
21+
22+
| Requirement | Details |
23+
|---|---|
24+
| **DigiCert TLM Agent** | Installed and configured with certificate enrollment. The agent provides the `DC1_POST_SCRIPT_DATA` environment variable consumed by these scripts. |
25+
| **Kemp LoadMaster** | REST API enabled. Navigate to *System Configuration → Certificates & Security → API Access* in the LoadMaster UI. |
26+
| **API Credentials** | A user account with API access on the LoadMaster. Credentials are passed inline in the base URL (see [Arguments](#arguments)). |
27+
| **Network Access** | The host running the TLM Agent must be able to reach the LoadMaster API port (commonly `8444/tcp`). |
28+
29+
### Bash-specific
30+
31+
- `curl` (with TLS support)
32+
- `base64`, `grep`, `sed`, `awk` (standard on most Linux distributions)
33+
- Optional: `xmllint` for robust XML parsing of `listcert` responses (falls back to `grep` if unavailable)
34+
35+
### PowerShell-specific
36+
37+
- PowerShell 5.1+ (Windows PowerShell) or PowerShell 7+ (cross-platform)
38+
- No external modules required — uses `System.Net.HttpWebRequest` directly for maximum compatibility
39+
40+
## Files
41+
42+
| File | Platform | Description |
43+
|---|---|---|
44+
| `kemp_loadmaster_awr.sh` | Linux / macOS | Bash implementation using `curl` for API calls |
45+
| `kemp_loadmaster_awr.ps1` | Windows | PowerShell implementation using `HttpWebRequest` |
46+
47+
## Arguments
48+
49+
Both scripts receive their configuration via the TLM Agent `DC1_POST_SCRIPT_DATA` environment variable, which contains a Base64-encoded JSON payload. The `args` array within this payload maps to the following arguments:
50+
51+
| Argument | Name | Required | Description | Example |
52+
|---|---|---|---|---|
53+
| `args[0]` | Base URL | Yes | LoadMaster API endpoint including scheme, credentials, host, and port | `https://user:pass@loadmaster.example.com:8444` |
54+
| `args[1]` | VS IP | Yes | Virtual Service IP address to update | `172.31.7.5` |
55+
| `args[2]` | VS Port | Yes | Virtual Service port to update | `443` |
56+
| `args[3]` | Cert Name | Yes | Certificate identifier on the LoadMaster (how it appears in the LM UI) | `my-certificate` |
57+
| `args[4]` | *(Reserved)* | No | Reserved for future use | — |
58+
59+
> **Note:** Credentials in the base URL are automatically obfuscated in all log output.
60+
61+
## Configuration
62+
63+
Before using, edit the following variables at the top of each script:
64+
65+
### Bash
66+
67+
```bash
68+
LEGAL_NOTICE_ACCEPT="true" # Must be set to "true" to run
69+
LOGFILE="/path/to/kemp.log" # Log file location
70+
```
71+
72+
### PowerShell
73+
74+
```powershell
75+
$LEGAL_NOTICE_ACCEPT = "true" # Must be set to "true" to run
76+
$LOGFILE = "C:\Program Files\DigiCert\TLM Agent\log\kemp_data.log" # Log file location
77+
```
78+
79+
## TLM Agent AWR Setup
80+
81+
1. In DigiCert ONE, navigate to **Trust Lifecycle Manager → Automation → Admin Web Request (AWR)**.
82+
2. Create or edit a post-enrollment script entry.
83+
3. Upload the appropriate script (`kemp_loadmaster_awr.sh` for Linux agents, `kemp_loadmaster_awr.ps1` for Windows agents).
84+
4. Configure the arguments array with your LoadMaster details:
85+
86+
```
87+
Argument 1: https://<api_user>:<api_password>@<loadmaster_host>:<api_port>
88+
Argument 2: <virtual_service_ip>
89+
Argument 3: <virtual_service_port>
90+
Argument 4: <certificate_name>
91+
```
92+
93+
5. Save and trigger a certificate enrollment or renewal to test.
94+
95+
## API Flow
96+
97+
The scripts interact with the Kemp LoadMaster REST API as follows:
98+
99+
```
100+
┌─────────────────┐ ┌──────────────────┐
101+
│ TLM Agent │ │ Kemp LoadMaster │
102+
│ (AWR Script) │ │ REST API │
103+
└────────┬────────┘ └────────┬─────────┘
104+
│ │
105+
│ GET /access/listcert │
106+
│──────────────────────────►│ Check if cert exists
107+
│◄──────────────────────────│ XML response
108+
│ │
109+
│ POST /access/addcert │
110+
│ ?cert=<name> │
111+
│ [&replace=1] │
112+
│ Body: PEM bundle │
113+
│──────────────────────────►│ Upload certificate
114+
│◄──────────────────────────│ Success/Error
115+
│ │
116+
│ GET /access/modvs │
117+
│ ?vs=<ip>&port=<port> │
118+
│ &prot=tcp │
119+
│ &CertFile=<name> │
120+
│──────────────────────────►│ Assign cert to VS
121+
│◄──────────────────────────│ Success/Error
122+
│ │
123+
```
124+
125+
## Logging
126+
127+
Both scripts produce timestamped logs with detailed status information:
128+
129+
- Environment variable validation
130+
- JSON payload extraction and argument parsing
131+
- Certificate and key file metadata (size, type, chain length)
132+
- API request URLs (with obfuscated credentials)
133+
- HTTP status codes and response summaries
134+
- Success/failure status for each deployment step
135+
136+
Sensitive information (passwords, private keys) is never written to the log.
137+
138+
## Error Handling
139+
140+
The scripts validate and exit with a non-zero code on:
141+
142+
- Legal notice not accepted
143+
- Missing `DC1_POST_SCRIPT_DATA` environment variable
144+
- JSON decode/parse failure
145+
- Missing required arguments (base URL, VS IP, VS port, cert name)
146+
- Certificate or key files not found
147+
- PEM creation failure
148+
- API upload failure (non-2xx response)
149+
150+
The PowerShell version includes additional handling for HTTP 422 responses (invalid certificate format) with troubleshooting guidance.
151+
152+
## Security Considerations
153+
154+
- **Credential obfuscation** — All log entries mask usernames and passwords embedded in URLs, showing only the first three characters.
155+
- **PEM cleanup** — The combined PEM file (cert + key) is created as a temporary artifact with restricted permissions (`chmod 600` on Linux, ACL-restricted on Windows) and is cleaned up after upload.
156+
- **TLS verification** — The LoadMaster API is accessed with TLS certificate verification disabled (`curl -k` / `SkipCertValidation`) to support self-signed management certificates. Adjust if your LoadMaster has a trusted certificate.
157+
- **No secrets in logs** — Raw JSON payloads and private key content are never logged.
158+
159+
## Troubleshooting
160+
161+
| Symptom | Possible Cause | Resolution |
162+
|---|---|---|
163+
| `ERROR: Legal notice not accepted` | `LEGAL_NOTICE_ACCEPT` not set to `"true"` | Edit the variable at the top of the script |
164+
| `ERROR: DC1_POST_SCRIPT_DATA environment variable is not set` | Script not running as an AWR post-enrollment hook | Ensure the script is configured in TLM as a post-enrollment script |
165+
| HTTP 422 on `addcert` | Certificate format issue | Verify the cert and key are valid PEM, the key matches the cert, and the chain is complete |
166+
| `modvs returned non-success status` | VS IP/port mismatch or cert name not found | Confirm the Virtual Service exists and the cert name matches what was uploaded |
167+
| Connection timeout | Network or firewall blocking access | Verify the agent host can reach the LoadMaster API port |
168+
169+
## License
170+
171+
Copyright © 2026 DigiCert, Inc. All rights reserved. See the legal notice header in each script file for full terms.

0 commit comments

Comments
 (0)