F5 BIG-IP module

Uploads cert + key + chain to F5 BIG-IP LTM via iControl REST. If you name one or more Client SSL profiles, it also repoints their certKeyChain; if you name none, it only installs the certificate objects and leaves every profile alone — see deployment scopes. Supports TMOS 13.0+, partition scope, and intermediate-chain handling with fingerprint-based naming to avoid duplicate objects. (Attaching a profile to virtual servers is done outside CertAutoPilot.)

Overview

• Transport: iControl REST over HTTPS (use_ssl: true, port 443) or plain HTTP (use_ssl: false, port 80), or an explicit port.
• Auth: username + password (token login). Client-certificate authentication is not supported.
• Artifacts: three separate objects per certificate — /sys/file/ssl-cert, /sys/file/ssl-key, and (if the chain has intermediates) /sys/file/ssl-cert entries for chain members.
• Profile: the named /ltm/profile/client-ssl profiles are updated to reference the new trio — only when you name profiles on the target. See deployment scopes. server-ssl (backend) profiles are not supported.
• Rollback: supported — a rollback updates the cert/key objects and the clientssl profile back to a previous retained certificate version. See below.
• Minimum version: TMOS 13.0.

Deployment scopes

The module behaves in two quite different ways depending on whether the target names any Client SSL profiles. The difference decides what actually starts serving the new certificate, so choose deliberately.

Profile-aware — you name the profiles

Each run creates new versioned objects from the base name (<base>_v<unix>_<4hex>) and repoints each named profile's certKeyChain at them. Only the profiles you listed change; anything else on the appliance still references the previous objects. Use this when CertAutoPilot should own placement, or when one target serves many certificates that each belong in a different profile.

Import-only — you name no profiles

The certificate and key objects are updated in place, under the same name, inside a single transaction. No profile is read or modified.

The consequence is the useful part: every Client SSL profile on the device that references those objects starts serving the new certificate immediately — however many there are, and without CertAutoPilot knowing about them. You manage placement in F5; CertAutoPilot only keeps the material behind it fresh. (The transaction exists for exactly this reason: F5 re-validates cert/key consistency on every profile that references the pair, so updating the two objects separately would fail with 01070317:3 key and certificate do not match.)

Import-only needs an explicit Cert Name

This only works if the objects CertAutoPilot writes are the ones your profiles already reference — that is, the names must match. Leave Cert Name empty and CertAutoPilot generates a fresh per-certificate name (cap-<token>-<domain>) that no existing profile points at: the certificate lands on the appliance, and your profiles quietly keep serving the old one.

So for import-only, set Cert Name to the exact object name your profiles use. It stays stable across renewals, so you set it once. Because no profile is inspected, a run cannot tell you whether anything is actually serving the result — add a tls_fingerprint validation endpoint pointed at the VIP so a name mismatch surfaces as a failed deployment instead of a silent no-op.

Prerequisites

• Management IP (or hostname) reachable from the backend on the port it is dialed on: 443 with HTTPS, 80 with HTTP, or the explicit port.

• A dedicated user with the Administrator role. The module uploads files via the /mgmt/shared/file-transfer/uploads REST endpoint, which F5 restricts to Administrator — lesser roles such as Certificate Manager, Operator or Resource Administrator (version-dependent) are rejected with HTTP 401 on the first upload chunk. Disable the account's terminal access (shell none) so it cannot log in via SSH/tmsh:

  tmsh create auth user certautopilot password "StrongP@ssw0rd!" \
    partition-access add { all-partitions { role admin } } shell none
  tmsh save sys config

Create the module credential

1. Settings → Distribution → Credentials → New → F5 BIG-IP.
2. Username + password. Paste only once; stored encrypted.
3. Save.

Create an F5 target

1. Settings → Distribution → Targets → New. Module: F5 BIG-IP.
2. Fields:

   • Host — management IP or DNS name.

   • Port — leave empty for the scheme default: 443 with HTTPS (use_ssl on), 80 with HTTP.

   • Partition — default Common. F5's admin partition.

   • Credential.

   • Profile name(s) — leave empty for import-only mode (objects updated in place; every profile referencing them follows automatically). Otherwise, the Client SSL profile(s) the certificate manages (e.g. ClientSSL_example_com), entered as literal names — one or several, since the same certificate is often referenced by more than one profile on a device. Add or remove names at any time; each is applied independently on every deploy: a listed profile that does not exist on the device is logged and skipped (never a failure), and a failure on one profile never blocks the others being repointed — the run reports per-profile outcomes. If none of the listed profiles exist, the run fails (nothing would serve the new certificate).

     Note that per-profile isolation is about progress, not about the verdict: if any profile failed, the target result is still failed, marked as changed because the others did rotate. With auto_rollback_on_failure enabled on the distribution, that can roll the freshly renewed certificate off every managed profile because one of them failed — consider leaving auto-rollback off on multi-profile F5 targets. For per-certificate profile/cert names on a shared target, set them per distribution from the certificate's Distributions → Overrides drawer rather than encoding the domain into the target's profile names.

   • TLS Verify (ssl_verify) — off by default, so the management certificate is not verified at all. Turn it on once the management certificate chains to a CA the CertAutoPilot host trusts and covers the host name you entered (an IP address with verification on logs a SAN-mismatch warning).

   • Intermediate chain handling — strict (reject if chain is incomplete) or soft (warn-and-continue). Default: strict.

3. Save → health check queries /mgmt/tm/sys/version to confirm iControl + TMOS version.

Object naming

Cert Name is optional. Leave it empty and each certificate deploying through the target gets an auto-generated base name:

cap-<token>-<domain>        # token: 8-char hash derived from the certificate, stable across renewals

This is what makes one F5 target reusable by many certificates — every certificate owns its own uniquely-named objects on the appliance. A manually set Cert Name pins the target's objects to that exact base name instead (single-certificate usage, adopting existing objects, or import-only mode, where matching the existing name is what makes the deployment take effect).

In profile-aware mode, each run creates versioned objects from the base name (<base>_v<unix>_<4hex>) in their own transaction, then repoints each managed client-ssl profile's certKeyChain in its own transaction — so with several profiles, one profile's failure cannot take the others down. In import-only mode there are no versioned objects: the base-named cert and key are updated in place instead. Chain members are stored as cap_f5ic_<fingerprint-24> entries, so identical intermediates deduplicate across certificates.

The profile name stays stable across renewals so virtual servers keep their reference. An override can replace the profile set but not clear it: removing every name from an override simply falls back to the target's own profiles — per-distribution import-only mode is not expressible. Both the profile and the cert name can also be set per distribution (per target, with a * default row) from the certificate's Distributions → Overrides drawer — that is the recommended place for per-certificate placement on shared targets.

Config persistence and HA

Two steps after a successful deployment are warnings, not failures — the run still reports success if either fails.

• Saving the running config. The certificate is live immediately, but until save sys config succeeds it exists only in the running configuration: a reboot or a failover reverts to the previous certificate. A failed save shows as config_saved: false on the target detail; re-running the deployment retries it. Persisting the configuration is deliberately treated as the operator's responsibility — an earlier build failed the run on a save error, and a single appliance's transient blip then auto-rolled the fresh certificate off every appliance in the group.
• HA config-sync. When a device_group is configured, a sync is triggered after the change. If it fails, the standby unit keeps the previous certificate and will serve it after a failover. This is also warn-only, so check the run log rather than assuming the pair is consistent.

Target fields not covered above

Field	Meaning
profile_names	The list that actually selects profile-aware mode (a non-empty list switches scope). Max 32 entries, each ^[A-Za-z0-9._-]+$ and ≤255 chars, no blanks or duplicates. Setting both profile_name and profile_names is rejected.
key_name	Explicit SSL key object name; defaults to cert_name. Rejected unless an explicit cert_name is set, and ignored when an override or auto-naming changes the effective cert name — the key object then follows the per-certificate cert name, so several certificates never share (and overwrite) one key object.
cert_filename / key_filename	Fixed upload filenames — rejected unless an explicit cert_name is set, because per-certificate filenames are what stop one certificate clobbering another's files.
http_timeout	Per-request timeout in seconds (5–300, default 30).
save_config	Persist the running config after a change. Nullable; defaults to true. A failed save is a warning, not a failure (config_saved:false in the target detail).
skip_chain_linking	Do not install or link intermediates.

Rollback

Supported via previous-version re-deploy: a rollback updates the cert/key objects and the clientssl profile's certKeyChain back to a previous retained certificate version — the module's normal deploy path, fed older material. The profile name stays stable, so virtual servers keep their reference throughout. Eligibility, the version picker, and auto-rollback: Rollback.

Every deploy and every rollback mints a new versioned cert/key object pair (<base>_v<unix>_<4hex>) on the appliance, and the module never deletes the pair it displaces. CertAutoPilot records only the last 10 versions per certificate — enough to recognise its own leftovers when merging a certKeyChain, but not a complete inventory. Older objects stay on the BIG-IP unreferenced and unrecognised; remove them out-of-band (stale object cleanup).

Stale object cleanup

Old cert/key/chain objects remain by design — deleting them on the next deploy would break any profile still referencing them. Clean up out-of-band on a monthly cadence by listing /sys/file/ssl-cert and removing objects not referenced by any profile.

Troubleshooting

"BIG-IP version … is below minimum supported v13.0.0"

Reported as F5BIGIP_UPDATE right after the version check (the full message names bug ID599543, the in-place certificate overwrite defect). Upgrade the BIG-IP; versions before 13.0 are refused, nothing is changed on the device.

Chain errors (F5BIGIP_CHAIN / F5BIGIP_OWNERSHIP)

The module does not verify the chain against a trusted root — neither on the BIG-IP nor locally. What it does: parse the chain PEM, refuse more than 5 intermediates, look up each intermediate as cap_f5ic_<fingerprint-24> and compare identity (fingerprint, or serial + issuer). In strict mode a parse error, a failed lookup/upload/create, or an existing cap_f5ic_ object holding a different certificate (F5BIGIP_OWNERSHIP) fails the target; in soft mode it is a warning and the deployment continues without a chain reference. A missing issuer intermediate is not detected here — the certificate simply gets no chain reference (profile-aware) or you bind it manually (import-only).

Wrong password or role too weak (F5BIGIP_AUTH)

Any HTTP 401/403 in the run is F5BIGIP_AUTH and is not retried: a rejected token login (wrong password, or the account cannot log in through the tmos provider), a role denial on the upload endpoint, or a forbidden object/profile/transaction call. A device that does not answer at all (unreachable, TLS error, timeout) is F5BIGIP_CONNECT and is retried.

"upload chunk failed (HTTP 401)"

Authentication succeeded (the token was issued) but the user's role cannot access the file-upload endpoint — F5 reports this role denial as 401, not 403, so it looks like a wrong password. Assign the Administrator role to the service account; Certificate Manager and similar roles are not sufficient for /mgmt/shared/file-transfer/uploads.

Missing partition or profile

A partition that does not exist surfaces on the object create as F5BIGIP_UPDATE with the F5 message naming the folder (01020036:3: The requested folder … was not found). A listed client-ssl profile that does not exist is logged and skipped; when none of them exist the run fails with F5BIGIP_PROFILE. An in-place update whose explicit key_name object does not exist is F5BIGIP_NOT_FOUND. Create the object, or fix partition / profile_names / key_name.

Leftover files in /var/config/rest/downloads

The uploaded PEMs (including the unencrypted private key) are removed with unix-rm when the target finishes — success or failure. A removal that fails is logged as a warning naming the file; remove it on the device. Files are deliberately kept only after an object-commit timeout, because the transaction may still complete in the background.

"cannot contain more than one set of same certificate/key type"

F5 allows only one cert/key set per key type (RSA / ECDSA / DSA) in a client-ssl profile, and the profile already carries a foreign entry of the same key type as the new certificate. The module deliberately preserves entries it does not own (anything not named cap_f5_*) — except the F5 factory placeholder (/Common/default.crt + default.key, usually inherited from the parent clientssl profile), which it takes over automatically. If the conflicting entry is a real operator certificate, remove it from the profile (or let it be, and point the target at the correct profile).

See also

• Distribution overview
• NetScaler (comparable Citrix module)