F5 BIG-IP: SSL certificates with ACME

Q: Which BIG-IP user should the script use?

Create a dedicated iControl REST user with the Certificate Manager role (or Administrator if you do not use granular roles). The user must be able to upload files, create and update ssl-cert and ssl-key, and update the Client SSL profile. Use a strong password and store it with restrictive read access ( chmod 600 ) on the proxy host.

Q: What if F5 runs in an HA pair (Active/Standby)?

Upload to the active unit, then call POST /mgmt/tm/cm/config-sync to sync the configuration to standby. Our example covers the single-unit case; add the sync call if you have HA. ConfigSync transfers both the certificate files and the profile update.

Built-in ACME from BIG-IP 21.1.0. Use Lego and iControl REST on older versions. FairSSL handles domain validation with AutoDNS.

BIG-IP 21.1.0 and newer: built-in ACME BIG-IP before 21.1.0: Lego and iControl REST

Supported versions

Platform	Versions	Runs on	ACME client
F5 BIG-IP	VersionsBIG-IP 21.1.0 and newer	Runs onThe device itself	ACME clientThe device’s built-in ACME client with EAB

BIG-IP 21.1.0 and newer: built-in ACME

Create an ACME profile in the FairSSL control panel and obtain the directory URL, EAB KID and EAB HMAC key through ACME Easy Guide. Select Appliance and F5 BIG-IP (21.1.0+). Keep the HMAC key confidential.

1. Check the version and domains

Use BIG-IP/TMOS 21.1.0 or newer and an administrator account for the setup. All names must be allowed by the ACME profile and configured for AutoDNS at FairSSL. FairSSL handles domain validation. Use the external Lego/iControl REST method on older BIG-IP versions.

2. Configure DNS and an internal proxy

Create a resolver under Network → DNS Resolvers → DNS Resolver List. Then create an internal proxy under System → Services → Internal Proxies and select the resolver. For a direct connection, disable Use Proxy Server; the internal proxy is still required. Allow DNS resolution and outbound HTTPS to FairSSL through TMM routing. Connectivity from the management interface alone is not sufficient.

3. Create the ACME account key

Open System → Certificate Management → Traffic Certificate Management. Create a self-signed certificate with a private key, for example fairssl-acme-account, using Issuer: Self. Select this object as the Account Key during registration. It is a separate account key, not the traffic certificate or EAB HMAC key.

4. Create the FairSSL ACME provider

Open Traffic Certificate Management → ACME Provider List → Create. Use the name fairssl-acme, select the internal proxy and fill in the fields below. CA Certificate must trust the HTTPS certificate of the FairSSL ACME server; use ca-bundle.crt if it contains the required trust. Paste the EAB HMAC value exactly as supplied.

Copy the values into the matching ACME Provider fields. Do not append /directory to the URL or Base64-encode the HMAC key again.

ACME Provider
F5	FairSSL / BIG-IP
CA Certificate	`ca-bundle.crt`
Directory URL	`https://fairssl.dk/acme`
Account Key	`fairssl-acme-account`
External Account Binding Key	`EAB KID`
External Account Binding MAC Key	`EAB HMAC`
External Account Binding Algorithm	`HS256`
Contacts	`mailto: followed by your contact email address`
Challenge Type	`HTTP-01`

5. Register the account

Accept Terms and Conditions, select Create Account and save with Finished. Check Account Status: Valid. Keep the account key and provider configuration for renewals. Do not reuse a single-use EAB key for repeated account registrations. HTTP-01 is the F5 client setting; FairSSL validates centrally with AutoDNS. FairSSL therefore does not require public port 80 on BIG-IP. The flow without an HTTP listener still awaits testing on BIG-IP.

6. Order the traffic certificate

Create a new certificate under Traffic Certificate Management with Issuer: Certificate Authority. Fill in Common Name and Subject Alternative Name. Include all names, including the Common Name, with DNS: before each SAN name, for example DNS:www.example.com. Under Certificate Order Properties, select Provider: ACME Provider, ACME Order Provider: fairssl-acme and Type: New. Identifiers must contain the same domain names. Click Finished, open the Key tab and click Update to start the order. Check issuance, names and expiry date.

7. Apply the certificate and check renewal

Open Local Traffic → Profiles → SSL → Client. Select the issued certificate, its matching private key and the correct intermediate chain under Certificate Key Chain. The provider’s ca-bundle.crt is not the website’s intermediate chain. Assign the profile to the relevant HTTPS virtual server and check the certificate actually served using the correct hostname/SNI. F5 documents automatic renewal; preserve the ACME account and monitor expiry. Confirm a renewal in your environment. HA, AS3 and wildcards have not been tested in this guide.

F5 documentation · Send feedback to FairSSL

BIG-IP before 21.1.0: Lego and iControl REST

✓ A proxy host (Linux, e.g. an existing management server) runs Lego v5.0.4+.
✓ Lego issues the certificate via FairSSL AutoDNS. No DNS API access required.
✓ A deploy hook uploads cert + key via iControl REST and updates the Client SSL profile.
✓ If F5 runs as an HA pair the script calls ConfigSync to standby.
✓ cron runs Lego daily. ARI drives renewal.

Setup

Step 1: Create an iControl REST user on F5

In the BIG-IP web UI: go to System → Users → User List and create a local user (e.g. acme-deploy) with the Certificate Manager role for partition Common (or whichever partition your SSL profiles live in). Use a strong password.

Step 2: Install Lego

arch=$(dpkg --print-architecture)
case "$arch" in amd64|arm64) ;; *) echo "Adjust arch"; exit 1 ;; esac
version=$(curl -fsSL https://api.github.com/repos/go-acme/lego/releases/latest \
  | sed -n 's/.*"tag_name": "\(v[^"]*\)".*/\1/p' | head -1)
curl -fL "https://github.com/go-acme/lego/releases/download/${version}/lego_${version}_linux_${arch}.tar.gz" \
  | sudo tar -xz -C /usr/local/bin lego
sudo install -d -m 0700 /etc/ssl/f5

Step 3: Create the deploy script

The script uploads cert and key with POST /mgmt/shared/file-transfer/uploads, creates or updates ssl-cert and ssl-key objects via cmd=install, and updates the Client SSL profile. Optionally add a ConfigSync block if you run HA.

sudo tee /usr/local/bin/f5-deploy.sh > /dev/null << 'SCRIPT'
#!/bin/bash
set -euo pipefail
F5_HOST="bigip.example.com"
F5_USER="acme-deploy"
F5_PASS="YOUR_API_PASSWORD"
CERT_NAME="fairssl-acme-cert"
KEY_NAME="fairssl-acme-key"
PROFILE="fairssl-clientssl"   # Client SSL profile name in partition Common

CERT="$LEGO_HOOK_CERT_PATH"
KEY="$LEGO_HOOK_CERT_KEY_PATH"

# 1. Upload cert + key to /var/config/rest/downloads
curl -sS -k --user "$F5_USER:$F5_PASS" \
  -H "Content-Type: application/octet-stream" \
  -H "Content-Range: 0-$(($(stat -c%s "$CERT")-1))/$(stat -c%s "$CERT")" \
  --data-binary "@$CERT" \
  "https://$F5_HOST/mgmt/shared/file-transfer/uploads/$CERT_NAME.crt"

curl -sS -k --user "$F5_USER:$F5_PASS" \
  -H "Content-Type: application/octet-stream" \
  -H "Content-Range: 0-$(($(stat -c%s "$KEY")-1))/$(stat -c%s "$KEY")" \
  --data-binary "@$KEY" \
  "https://$F5_HOST/mgmt/shared/file-transfer/uploads/$KEY_NAME.key"

# 2. Install cert + key as objects (overwrites if they exist)
curl -sS -k --user "$F5_USER:$F5_PASS" \
  -H "Content-Type: application/json" \
  -d "{ \"command\": \"install\", \"name\": \"$CERT_NAME\", \"from-local-file\": \"/var/config/rest/downloads/$CERT_NAME.crt\" }" \
  "https://$F5_HOST/mgmt/tm/sys/crypto/cert"

curl -sS -k --user "$F5_USER:$F5_PASS" \
  -H "Content-Type: application/json" \
  -d "{ \"command\": \"install\", \"name\": \"$KEY_NAME\", \"from-local-file\": \"/var/config/rest/downloads/$KEY_NAME.key\" }" \
  "https://$F5_HOST/mgmt/tm/sys/crypto/key"

# 3. Update the Client SSL profile
curl -sS -k --user "$F5_USER:$F5_PASS" \
  -X PATCH -H "Content-Type: application/json" \
  -d "{ \"cert\": \"$CERT_NAME\", \"key\": \"$KEY_NAME\" }" \
  "https://$F5_HOST/mgmt/tm/ltm/profile/client-ssl/~Common~$PROFILE"

# 4. (Optional) ConfigSync to standby in an HA pair
# curl -sS -k --user "$F5_USER:$F5_PASS" \
#   -H "Content-Type: application/json" \
#   -d '{"command": "run", "utilCmdArgs": "config-sync to-group /Common/device-trust-group"}' \
#   "https://$F5_HOST/mgmt/tm/cm"
SCRIPT
sudo chmod 700 /usr/local/bin/f5-deploy.sh

Step 4: Issue the certificate

sudo /usr/local/bin/lego run \
  --domains "vip.example.com" \
  --server https://fairssl.dk/acme \
  --eab --eab.kid YOUR_EAB_KID --eab.hmac YOUR_EAB_HMAC \
  --accept-tos --email acme-client@fairssl.dk \
  --http --http.webroot "/var/www/html" \
  --path "/etc/ssl/f5" \
  --deploy-hook "/usr/local/bin/f5-deploy.sh"

Step 5: Schedule daily

# /etc/cron.d/lego-f5
17 04 * * * root /usr/local/bin/lego run \
  --domains "vip.example.com" \
  --server https://fairssl.dk/acme \
  --accept-tos --email acme-client@fairssl.dk \
  --http --http.webroot "/var/www/html" \
  --path "/etc/ssl/f5" \
  --renew-days 7 \
  --deploy-hook "/usr/local/bin/f5-deploy.sh"

Step 6: Verify

In the BIG-IP web UI under System → Certificate Management → Traffic Certificate Management → SSL Certificate List: confirm fairssl-acme-cert exists with the new expiry date.
Under Local Traffic → Profiles → SSL → Client: confirm the fairssl-clientssl profile uses the new cert + key.
Test publicly with FairSSL\'s SSL scanner.
HA deployments: verify from the standby BIG-IP that the configuration is synchronised.

Certificates on many servers and appliances

A publicly trusted SSL certificate can be valid for at most 199 days now, 99 days by 15 March 2027 and 46 days by 15 March 2029. Each certificate then has to be replaced at least twice a year now and at least eight times a year from 2029, on every server, firewall and load balancer that uses it. sslbrain from FairSSL runs as an appliance in your own network and renews and installs the certificates from one place, including on devices without an agent.

How sslbrain renews and installs certificates on F5 BIG-IP

Frequently asked questions

Find answers to the most common questions about SSL certificates and FairSSL.

Which method should I use?

Built-in ACME from BIG-IP 21.1.0. Use Lego and iControl REST on older versions. FairSSL handles domain validation with AutoDNS. The new guide to built-in ACME is awaiting feedback.

What is iControl REST?

iControl REST is F5's REST API for BIG-IP. It covers the full configuration surface, including SSL certificate management via /mgmt/tm/sys/file/ssl-cert and /mgmt/tm/sys/file/ssl-key. The API is enabled by default on modern BIG-IP versions and is used by F5's official Ansible modules, Terraform provider and a wide range of automation tooling.

tmsh or iControl REST?

iControl REST is more flexible and can be called from any host with curl. tmsh is better if you are already on the BIG-IP box or have a bastion. Our example uses iControl REST because the proxy host sits outside F5.

Which BIG-IP user should the script use?

Create a dedicated iControl REST user with the Certificate Manager role (or Administrator if you do not use granular roles). The user must be able to upload files, create and update ssl-cert and ssl-key, and update the Client SSL profile. Use a strong password and store it with restrictive read access (chmod 600) on the proxy host.

How is the Client SSL profile updated?

After the certificate and key are uploaded, the script updates the Client SSL profile via PATCH /mgmt/tm/ltm/profile/client-ssl/<profile> with the new cert and key fields. Existing Virtual Servers using the profile pick up the new certificate as soon as F5 reloads the profile.

What if F5 runs in an HA pair (Active/Standby)?

Upload to the active unit, then call POST /mgmt/tm/cm/config-sync to sync the configuration to standby. Our example covers the single-unit case; add the sync call if you have HA. ConfigSync transfers both the certificate files and the profile update.

What happens at renewal with Lego?

Lego runs daily. When ARI or the 7-day fallback triggers a renewal, a new certificate is fetched and the deploy hook uploads the files, updates the Client SSL profile and syncs (if HA). Virtual Servers start serving the new certificate on the next connection without being restarted.

Ready to automate F5 certificates?

Create a free account and order your first certificate. A DV certificate is issued in under 2 minutes.

Create free account Compare certificates