A10 Thunder module
Puts the certificate on an A10 Networks Thunder ADC (ACOS) over aXAPI v3. The certificate, its private key and its chain are one file. The first deploy uploads it; every later deploy replaces that same file in place. Every client-ssl template that names the file — and every virtual port that uses those templates — serves the new certificate a few seconds later, so a binding made once follows every renewal.
Every behaviour on this page was measured on ACOS 6.0.7 (vThunder) with 10 new TLS connections per second and idle keep-alive clients on the virtual server, and an untouched control virtual server alongside. Renewals, a change of key type (RSA ↔ ECDSA), a rename and a rollback caused no failed handshake and no broken keep-alive connection; the new certificate was served within about 5 seconds.
Overview
- Type:
a10, credential type:a10_password(JSON{"username","password"}), slotdefault. - Per target: log in and select the partition → read the version, the certificate files, the client-ssl templates and the virtual ports that use them → upload the file, or replace it in place → name it in the configured templates and SNI entries where it is not named yet →
write memory→ log off. - Rollback: supported — a rollback uploads a previous retained version under the same name (Rollback). Auto-rollback is available.
What the module deliberately does NOT do
- No virtual servers. A template is never attached to a virtual port. A template the target names that does not exist is created with this certificate only; attach it once on the device.
- No removals from templates. ACOS refuses to remove a certificate entry from a template a virtual port uses, so the module only ever puts entries in.
- No server-ssl templates. Backend client certificates are not written.
- No configuration sync. On an aVCS or VRRP-A pair the module writes to the unit that answers (warning
A10_HA_UNKNOWN); synchronising the peer is your job. - No overwrite of foreign files. A10 files carry no owner. A file under the chosen name that CertAutoPilot did not write is never overwritten (
A10_CONFLICT).
Requirements
A dedicated ACOS administrator, reachable over HTTPS on the management address.
Minimum access
Give the administrator access axapi and:
| Target partition | Privilege |
|---|---|
shared (empty partition) | privilege write |
| an L3V partition | privilege partition-write <partition> — the account starts in its own partition and cannot switch to shared, so every target it serves must name that partition |
CLI and web GUI access are not needed. A read-only administrator is not enough: it reads everything but every write is refused (A10_PERMISSION). The previous-file delete (delete_old_cert) and the save (save_config, write memory) need nothing more.
admin certautopilot password <strong-password>
privilege write
access axapi
exit
write memory
Refused logins and the admin lockout
aXAPI has no API token: each run logs in with the username and password and logs off at the end. Admin lockout is off by default; when enabled it counts refused logins per user, and a locked account gets the same answer as a wrong password. So a refused login is never retried: nothing more is sent to that device in the run, and the same credential is not sent to it again for about 70 seconds from any run, health check or picker — on every node of a multi-node installation, not only the one that was refused (the refusal is recorded in the database, keyed by the device, the credential and the moment its secret was last entered; never by anything derived from the password). Entering the credential's secret again counts as a new credential, so a corrected one works at once. A node the device accepted the same credential from in the last 10 minutes does not wait for another node's refusal (a device can refuse only some addresses — trusted hosts); a credential read from a secret store without versions is held only by the node that was refused.
The device keeps at most 30 aXAPI sessions (measured); CertAutoPilot holds at most four at a time per device.
Target configuration
| Field | Default | Description |
|---|---|---|
host | — | Management host name or IP address — no scheme, port or path. For an HA pair use the floating management address. |
port | 443 | Management HTTPS port. |
partition | shared | L3V partition the file and the templates live in (1–14 letters, digits, -, _). Files are per partition. |
cert_name | cap-<token>-<slug> | File name: letters, digits, ., _, -, at most 63, not starting with . or -, no ... Empty = one auto-named file per certificate. |
templates | — | client-ssl templates whose certificate entry for the certificate's key type should name the file (at most 32). |
sni | — | {template, server_name} rows: server-name entries that should serve the file (at most 64, no wildcards). |
delete_old_cert | false | After a rename, delete the previous file when no template names it any more (never during a rollback). |
save_config | true | Run write memory in the partition after a change. A save that failed (or a run that stopped after a write) is owed: the next run saves even when it writes nothing else. |
ssl_verify | false | Verify the management certificate (self-signed out of the box — pin it instead). |
ca_cert | — | Extra CA trusted while ssl_verify is on. |
tls_fingerprint_sha256 | — | Pins the served management certificate (the health check and the dry run show it). Without ssl_verify or a pin, deploy, dry run and health check warn TLS_UNVERIFIED_PASSWORD. |
http_timeout | 30 | Seconds, 5–300. |
How a deploy works
- Local checks — names, partition, templates, SNI; the certificate is RSA or ECDSA (the device refuses Ed25519); the key belongs to the certificate. Nothing is sent when one fails.
- Read — version and serial, HA state, certificate files, client-ssl templates, virtual ports.
- Upload — a PKCS#12 holding the certificate, the key and the chain, under a random one-time password, uploaded under the file name. On a renewal this replaces the file in place. The device serves the embedded chain without any
chain-certsetting. - Templates — for each template that does not name the file, its entry for the certificate's key type is set to the file (one RSA and one ECDSA entry per template; a new entry of the same type replaces the old one, hitless). A missing template is created.
- SNI — each template's server-name list is written as a whole with this file in the configured entries; other entries are kept.
- Previous files, save, log off.
What interrupts traffic
Nothing the module does, measured under load: replacing the file in place (also with a new key or another key type), replacing a template's certificate entry, rewriting the SNI list, removing an SNI entry and write memory.
Community reports say ACOS 5.2.1 and 6.0.4 kept serving the old certificate after a same-name replace. That was not seen on 6.0.7; on older releases check the served certificate after the first renewal.
Ownership
A10 files have no comment or tag, so the per-certificate remote state on the target is the only ownership record:
- A file under the name that this certificate's state names is this certificate's.
- A file that carries this very certificate (an earlier upload whose answer was lost) is taken over.
- A file the previous run tried to create under this name, when that upload's answer was lost (the connection dropped or the device answered a server error), is this certificate's too: the state records it as pending, so the next run updates it in place even when it now deploys a renewed certificate. An upload the device clearly refused records nothing.
- Any other file under the name is refused with
A10_CONFLICT— nothing is written. A file another certificate on the same target recorded is named in the message. - A template entry or SNI entry that names a file CertAutoPilot did not write is replaced with the warning
A10_ADOPTED; the file itself stays. One that names another CertAutoPilot certificate's file is refused (A10_CONFLICT) — also when that file has changed its key type in place since: its template entry keeps the RSA or ECDSA place it was added to (measured; the device shows nothing of it), so an entry of the old type from another certificate would replace it.
Previous file
Only a rename creates one. It stays while a template names it (A10_OLD_CERT_KEPT); with delete_old_cert on it is deleted once nothing names it, never during a rollback. Renaming back to a name the certificate used before is not a conflict: CertAutoPilot remembers its earlier files, so the file under that name is updated in place (or uploaded again when it was deleted).
State
The state records the device (host, serial), the partition, the file, the leaf and chain it carries, its key type, and where the module wrote it. A state recorded on another device or partition is ignored (A10_TARGET_MOVED). A re-run with the same certificate and chain writes nothing.
The state is read again once the run holds the device's lock, so two certificates deployed to one device one after the other each see what the other has just written there — a file or template entry the first one wrote is never taken for a foreign one by the second.
Partitions
Every request runs in the target's partition, selected at the start of every session — shared too. Files and templates are per partition; the file the module writes lives in the target's partition and its templates name it there.
Partition names are case-sensitive on the device (measured: CapCase and capcase are two partitions), so the state compares them exactly. The shared partition is always written shared — a target that spells it Shared is refused when it is saved.
An administrator limited to one partition (privilege partition-write <partition>) starts every session in its own partition and cannot leave it. A target that names no partition means shared, so with such an account it is refused with A10_PERMISSION before anything is read or written — name the account's partition on the target. (Measured: selecting shared is accepted for an account already there and answered Insufficient privilege for a partition-only account.)
HA
aVCS and VRRP-A are detected and reported with the warning A10_HA_UNKNOWN. Point the target at the floating management address; synchronising the configuration to the peer is the operator's job.
When the HA state cannot be read (an account limited to one partition may not read it), the same warning says so. In that case a changed device serial still counts as another device (A10_TARGET_MOVED); only a configured aVCS or VRRP-A pair, whose units answer with their own serials, is treated as one device.
Pickers
The target form and the override drawer read, live and read-only: partitions, client-ssl templates (and whether a virtual port uses them), and certificate files (with their owner on this target); SNI rows are typed as template and server name. Preview what a deploy would do shows the deploy's own plan for the placement being edited — the file, each template entry, each SNI entry, whether a virtual port would serve it, and any refusal — before anything is saved.
Per-distribution overrides
a10.cert_name (a target's own row only — it names one file on one device), a10.templates and a10.sni. Templates and SNI each replace the target's list as a whole from the first row that sets them (own > group > Default); None (an empty list over the API) clears it for this distribution — the file is then named in no template or SNI entry, not even the target's. See Overrides.
Dry run, validate, health check
- Dry run — every read, nothing written; lists the upload, template and SNI writes and the save. The private key is not given to a dry run, so the key check runs at deploy.
- Validate — the file exists and was last written with the expected certificate.
- Health check — login, partition, version, certificate list and HA state (
acos:,serial:,partition:,ha:checks).
Rollback
The previous retained version is uploaded under the same name — the same in-place replace. Nothing is deleted during a rollback.
Concurrency
Targets on one device run one after another (device lock a10:<host>:<port>); different devices run in parallel.
Error codes
| Code | Class | Meaning |
|---|---|---|
A10_CONNECT | network | Connection, DNS or TLS failure, or no aXAPI answer. Retried. |
A10_AUTH | auth | The password was refused, or held after a refusal ("not attempted"). Not retried. |
A10_PERMISSION | auth | The administrator lacks the right. Not retried. |
A10_API | io_transient | Any other device error, busy, or the session limit. Retried. |
A10_UPLOAD | io_transient | The upload failed; repeating it is safe. Retried. |
A10_TEMPLATE | io_transient | A template or SNI write failed. Retried. |
A10_VALIDATION | validation | Refused before writing: key type, key pair, names, template or SNI shape, an SNI row for a template that does not exist and is not in templates, a key-type change beside an entry of the new type. |
A10_CONFLICT | io_permanent | A file or entry CertAutoPilot does not own. Nothing written. |
See Error codes.
Known limitations
- RSA and ECDSA certificates only.
- Changing the key type in place while a template that names the file also holds another file of the new type is refused — set another certificate name.
- A file CertAutoPilot did not write that changed its key type in place keeps its template entry's original place too, and nothing on the device shows it: a certificate of that file's old key type deployed to the same template replaces its entry without the
A10_ADOPTEDwarning. For CertAutoPilot's own files the place is recorded and the deploy is refused instead. - Template and SNI changes are checked again on a fresh read of the template right before they are written, so an entry an operator adds while the file uploads is kept. The device has no conditional write, so an edit made in the moment between that read and the write can still be lost.
- Templates with server-name auto-map, and SNI entries for the same name that are alternate, regex, template-indirected or passphrase-protected, are refused rather than rewritten.
- HA is detected and reported (
A10_HA_UNKNOWN); the module does not manage the HA pair. - A template named only in an SNI row must already exist (the SNI write cannot create one); name it under
templatestoo and it is created with this certificate. - A shared-partition template that only another partition's virtual ports use reads as unused here (
A10_NOT_BOUND); a virtual port is only seen from its own partition.
See also
Video tutorial
Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →