Skip to main content

F5 BIG-IP module

Uploads cert + key + chain to F5 BIG-IP LTM via iControl REST and creates or updates the named SSL profile's certKeyChain. Supports TMOS 13.0+, partition scope, and intermediate-chain handling with fingerprint-based naming to avoid duplicate objects. (Attaching the profile to virtual servers is done outside CertAutoPilot.)

Overview​

  • Transport: iControl REST (HTTPS).
  • Auth: username + password, or username + client TLS certificate.
  • 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: /ltm/profile/client-ssl or /ltm/profile/server-ssl is created/updated to reference the new trio.
  • Rollback: not supported. Old cert/key/chain objects remain. See below.
  • Minimum version: TMOS 13.0.

Prerequisites​

  • Management IP (or hostname) reachable from the backend on port 443.

  • 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 — default 443.
    • Partition — default Common. F5's admin partition.
    • Credential.
    • Profile name — the literal name we will use for the Client SSL profile (e.g. ClientSSL_example_com). It is a plain string, not a template. 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 name.
    • Profile type — client-ssl or server-ssl.
    • TLS skip verify — for self-signed management certs during bring-up only.
    • 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 or adopting existing objects).

Per run, versioned objects are created from the base name (<base>_v<unix>_<4hex>) and the client-ssl profile's certKeyChain is repointed inside a transaction. 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. 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.

Rollback — not supported​

After a successful distribution, the old cert/key/chain objects remain in /sys/file. The profile's trio references the new ones. Rolling back means updating the profile to point at the old trio — we don't do that automatically because it disrupts running traffic unpredictably. Operate via F5's own change-management tooling (iApp or Ansible playbook) if you need reversible changes.

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​

"TMOS version < 13.0 not supported"​

Upgrade the BIG-IP. iControl REST before 13.0 has different endpoints that we don't target.

"Chain verification failed"​

The cert's intermediate chain doesn't verify against a trusted root on the BIG-IP, or the issuer's intermediate is missing from the deployment. Options: (a) add the missing intermediate to the chain; (b) set Intermediate chain handling to soft if your deployment tolerates it.

"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.

"Forbidden — role lacks permission"​

The user isn't Administrator, or the partition doesn't exist. Create it or grant access.

"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​