PAN-OS module
Imports the certificate into a Palo Alto Networks PAN-OS firewall as a named certificate object over the XML API, then commits the change. It is the firewall sibling of the F5/NetScaler modules: the object name never changes across renewals, so whatever your SSL/TLS service profiles, GlobalProtect portals or decryption policies reference keeps working without CertAutoPilot ever touching them.
Overview
- Type:
panos, credential type:panos_credentials(JSON{"username","password"}or{"username","api_key"}), slotdefault. - Per target: authenticate (API key, or key generation from the username/password) → read the certificate object → import the cert + key + chain as one PKCS#12 under the resolved name → partial commit scoped to the API user → poll the commit job to completion.
- Rollback: supported — a rollback re-imports a previous retained certificate version under the same object name and commits (Rollback). With
auto_commitoff, a rollback — like any deploy — lands in the candidate configuration only: the firewall keeps serving the rolled-back-from certificate until an administrator commits. - Minimum PAN-OS version: 9.0 (the API key travels in the
X-PAN-KEYheader, never in a URL).
What the module deliberately does NOT do
- It never binds. Creating or updating SSL/TLS service profiles, GlobalProtect portals/gateways or decryption policies is your job, done once. Because renewals re-import under the same name, those bindings then follow every renewal on their own.
- It never deletes. No certificate object is ever removed from the firewall — not old ones, not on rollback, not on any failure path. Superseded objects accumulate with an expired status under Device → Certificate Management; PAN-OS does not alarm on expiring imported certificates (its expiration check covers only the firewall's own device certificate), so leftovers are cosmetic — housekeep them manually if the list bothers you, but never delete the object your profiles currently reference.
- It never touches certificates it did not upload. The module writes only to its own resolved object name. Pointing
cert_nameat an existing object is treated as deliberate adoption: the first run that finds an object it has no record of warns loudly before importing over it, and the dry run says the same. Once that deployment is recorded the warning stops — so review the first run. - It never commits anyone else's work. The commit is
partialand scoped to<admin><member>your-api-user</member></admin>, so another administrator's half-finished candidate configuration is never pushed. (Give CertAutoPilot its own dedicated firewall account and this scoping is airtight.)
Requirements
- PAN-OS 9.0 or later.
- A dedicated firewall administrator account — the partial commit commits every pending change of that username (see Minimum access).
- Network reachability from CertAutoPilot to the firewall's management interface over HTTPS (default port 443).
- The certificate must be CA-issued: PAN-OS refuses a self-signed non-CA certificate ("identical subject and issuer") at import.
Minimum access
Give the dedicated administrator an Admin Role profile of type Device (Device → Admin Roles) with only these rights on its XML API tab:
- Configuration — reads the certificate object (idempotency) and, for the pickers, the vsys list.
- Operational Requests — system info and commit-job polling.
- Import — uploads the PKCS#12.
- Commit — the partial commit; not needed when every target has
auto_commitoff.
Missing any one fails the run with an authorization error. Web UI and Command Line access and the other XML API rights are not needed. Use a Device role, not a Virtual System role: a vsys-scoped administrator cannot import to the shared location (empty vsys) or read the device's vsys list. Superuser or the Device Administrator dynamic role also work but give far more.
Target configuration
| Field | Meaning |
|---|---|
host | Management hostname or IPv4 — bare, no scheme or port (use port). |
port | Management HTTPS port. Default 443. |
cert_name | Optional fixed object name. Empty (recommended) means the per-certificate auto name cap-<token>-<slug> — stable across renewals, unique per certificate. Max 63 characters. |
vsys | Optional vsys id (e.g. vsys2). Empty imports to the shared location, visible from every vsys. Setting it on a firewall with multi-vsys disabled fails the health check and the deploy with a clear error. Adding a vsys to a target that already deployed to shared creates a new object in the vsys and leaves the shared one in place (never deleted); if the device rejects the duplicate name, the run fails visibly — pin a different cert_name to resolve it. |
auto_commit | Default on: import, then partial-commit and wait for the job. Off: import to the candidate configuration only — see below. |
ssl_verify | Default off, because the management interface serves a self-signed certificate out of the box. Turn it on once you have installed a trusted management certificate (or add its private CA with ca_cert). |
ca_cert | Optional PEM CA certificate(s) added to the host's trust roots while ssl_verify is on — the firewall's private CA. Refused (400) while ssl_verify is off. See Trusting the firewall's certificate. |
tls_fingerprint_sha256 | Optional SHA-256 fingerprint of the certificate the firewall serves; checked on every connection, with ssl_verify on or off. The health check shows the value. See Trusting the firewall's certificate. |
http_timeout | Per-request timeout in seconds. Default 30; values below 5 are raised to 5. |
commit_timeout | How long to wait for the commit job, in seconds (60–1800). Default 600. Keep it comfortably below the distribution execution timeout (Settings → General, default 30 minutes) — a commit cut off by the job budget is reported with less precise diagnostics, though the next run still heals it. |
Per distribution, cert_name can be overridden from the certificate's Distributions → Overrides drawer (specific target > default * entry > target spec > auto name).
Trusting the firewall's certificate
Two optional ways to trust the management certificate, both empty by default — a target that sets neither behaves exactly as before 1.7.0:
- Verify it. Turn
ssl_verifyon; when the certificate comes from a private CA, paste that CA inca_cert(PEM, one or more certificates, up to 64 KiB) and it is added to the host's trust roots for this target.ca_certis only read whilessl_verifyis on — saving it with verification off is refused (400). - Pin it. Put the SHA-256 fingerprint of the certificate the firewall serves in
tls_fingerprint_sha256(64 hex characters, colons optional, any case). The pin is checked on every connection whetherssl_verifyis on or off, so a self-signed management certificate can be trusted exactly. The health check shows the value to paste: its checks listtls_fingerprint_sha256:AB:CD:…. A wrong pin refuses the connection before anything is sent: the target fails withTLS_TRUST_REFUSED(not retried — the other targets of the run are not rolled back for it) and the error names the fingerprint the firewall presented — update the pin when the management certificate changes.
A deploy, dry run or health check that sends a password to a firewall that is neither verified nor pinned reports the warning TLS_UNVERIFIED_PASSWORD with the served fingerprint (an API-key credential is not warned). Clear it by pinning that fingerprint or by turning ssl_verify on (with ca_cert for a private CA). The TLS options are part of the credential-binding rule: for a target whose credential is bound, the person who entered the secret or an organization owner may change them freely; anyone else may only add a check — pin the served fingerprint while ssl_verify stays on, or add a pin or a ca_cert to a target that verified nothing. Turning ssl_verify off (even while adding a pin — that swaps the chain check for a certificate of the editor's choosing), adding a ca_cert beside the system roots while ssl_verify is on (a new trust anchor), or replacing or removing a pin or a CA is refused with 422 CREDENTIAL_TLS_CHANGE_NOT_ALLOWED, and a new PAN-OS target that only pins (ssl_verify off with a fingerprint) is judged like one that does not verify at all.
The module config carries one tuning field, concurrency (API only): how many targets one run deploys in parallel, default 5, clamped to 1–50. Targets on the same firewall are always serialized regardless of it.
auto_commit off: import without committing
With auto_commit off the module imports the certificate into the candidate configuration and stops. The run succeeds, but the result carries a visible commit pending warning — the new certificate does not serve until an administrator commits, in their own change window.
Two behaviors make this safe to leave off long-term:
- Every subsequent run keeps re-reporting the pending state until a commit happens; a green run never hides the fact that nothing is live yet.
- The moment a run executes with
auto_commitback on (or the next renewal fires with it on), the module detects the correct material already sitting in candidate config and finishes with a commit-only pass — no redundant re-import.
The same healing applies when a commit fails or times out: the import is recorded as uncommitted, and the next run completes just the commit. A timed-out commit job may still finish in the background on its own — the module reports the state as unknown rather than guessing.
Choosing from the firewall (live pickers)
Two fields on a PAN-OS target can be read from the firewall:
- Vsys — the firewall's virtual systems. On a single-vsys firewall the row says so, because there the right answer is to leave the field empty (the shared location): naming a vsys when multi-vsys is off is refused.
- Certificate Name — the certificate objects in the target's location (the named vsys, else shared), with their subject and expiry. This is the list an adoption picks from, on the target and on a certificate's per-target override row.
Both read the candidate configuration, which is where an import lands before a commit — so an object imported but not yet committed is listed, exactly as the module's own idempotency check sees it.
Listing is read-only: it reads configuration and changes nothing, and no commit is performed. Every field still accepts a typed value.
Identity and renewals
The certificate object name is the identity. Auto names are cap-<token>-<slug> (token derived from the certificate, stable across renewals), so one firewall serves any number of certificates without collisions, and a renewal is an in-place content replacement of the same object. If the same material is already on the box and committed, the run skips without touching the device.
The chain is embedded inside the single object (leaf first, intermediates behind it) — no separate intermediate objects are created, so there is nothing to collide with existing CA objects on the firewall. The firewall serves that embedded chain: a TLS handshake against an SSL/TLS service profile bound to the object presents the leaf and the intermediates (verified live on PAN-OS 11.2; adding the intermediate as its own object changes nothing in the handshake). Device → Certificate Management → Certificates lists the object as one row, without the tree PAN-OS draws when an issuer exists as a separate object — that view is cosmetic, not what clients receive.
Credential
panos_credentials, JSON — one of:
{"username": "certautopilot", "password": "..."}
{"username": "certautopilot", "api_key": "..."}
username is always required, even with an API key: the partial commit names its administrator, and an API key alone cannot. With a password, the module generates the API key itself at each run (sent as a POST body, never in a URL); with api_key, key generation is skipped.
PAN-OS 12 and the API Key Certificate. From PAN-OS 11.1 the firewall may warn that password-based key generation is deprecated: Palo Alto's replacement is the API Key Certificate infrastructure (Setup → Management → Authentication Settings), with legacy keys deprecated in PAN-OS 12.0/12.1 and disabled in 13.0. CertAutoPilot works with both — the key still travels in the X-PAN-KEY header. Note that enabling the API Key Certificate invalidates all existing API keys (as do the certificate's expiry and the account's password change): a stored api_key credential must then be regenerated, while a password credential keeps working because the module generates a fresh key on every run.
HA pairs
Point the target at the active peer's management address. Palo Alto's guidance is that configuration changes always be made on the active (or active-primary) member; a change committed on the passive peer can be silently overwritten the next time the active synchronizes. The HA synchronization reference excludes only device-management and syslog-over-SSL certificates from config sync, so a serving certificate imported and committed on the active is normally synchronized to the peer — but the GlobalProtect guide still recommends importing on each firewall of an active/passive pair, so verify on your version that the peer shows the object after the first deploy. If it does not, add a second CertAutoPilot target for the peer (the same object name is fine — each firewall is deployed independently). Two hard requirements either way: the master key must be identical on both peers (the synced private key is encrypted under it), and only committed changes sync — an auto_commit-off import never reaches the peer.
Panorama-managed firewalls
CertAutoPilot writes to the firewall's local configuration. Panorama does not normally remove local objects it does not manage, but two interactions matter: (1) with the default "Merge with Device Candidate Config" enabled, a Panorama push also commits any pending local candidate changes — including a CertAutoPilot import still waiting on auto_commit — and the push can fail if that pending change is incomplete; (2) a Panorama Push & Commit that replaces the firewall configuration wholesale, or a template carrying a certificate object with the same name, will overwrite or collide with the local object (a same-named pushed object fails the commit with a duplicate-object error). The default auto names (cap-<token>-<slug>) will not collide with human-named template objects. If your fleet is strictly Panorama-managed and local changes are reverted as policy, distribute through Panorama (template import + push) rather than pointing this module at the managed firewall — Panorama support is on the roadmap.
Verification
The health check authenticates and reads system information (it reports the PAN-OS version and, as tls_fingerprint_sha256:…, the certificate the firewall served — the value for a pin), and fails early when vsys is set on a firewall whose multi-vsys is disabled. The dry run authenticates and reads the certificate object — it does not read system information, so the vsys-on-single-vsys mistake is caught by the health check and the deploy, not by the dry run — and reports whether an execution would create the object, update it, only commit pending material, or skip (including the case where the right material already sits uncommitted in the candidate config with auto_commit off, which the deploy skips with the commit-pending warning). Post-deploy validation endpoints work as with any module — pointing one at a GlobalProtect portal or an inbound-inspected service is the strongest end-to-end proof. They cannot be combined with auto_commit off: an uncommitted certificate would fail fingerprint validation on every run and permanently downgrade the distribution to partial, so saving a PAN-OS target that has both is refused (endpoints with method none are allowed). Endpoints supplied through a certificate's Target Overrides are not checked against auto_commit.
Error codes
| Code | Class | Meaning |
|---|---|---|
PANOS_CONNECT | network | TCP/TLS connection to the management interface failed. Retried. |
TLS_TRUST_REFUSED | validation | The target's own TLS trust options refused the connection — the firewall presented a certificate other than the pinned tls_fingerprint_sha256, or the options could not be applied. Nothing was sent; not retried, and the other targets of the run are not rolled back for it. Cross-module code, see Trusting the firewall's certificate. |
PANOS_AUTH | auth | Authentication rejected — bad username/password or API key, a malformed or incomplete credential (missing username), any device error or non-XML answer during key generation, or an auth rejection (403 / code 16) while polling the commit job. Not retried. |
PANOS_IMPORT | io_transient | The device rejected or failed the import. Retried — a same-name re-import is idempotent. Note the device's own rules: self-signed non-CA certificates are refused, and the PKCS#12 passphrase is limited to 31 characters (the module complies). |
PANOS_COMMIT | io_transient | The partial commit failed or its job timed out. Retried; a timed-out job may still complete in the background, and the next run finishes with a commit-only pass. |
PANOS_NOT_FOUND | validation | A referenced object does not exist on the firewall. Not retried. |
PANOS_VALIDATION | validation | The device rejected the request as invalid — bad object name, vsys set while multi-vsys is off, malformed input. Not retried. |
PANOS_API | io_transient | An unclassified device-internal error, or a "Session timed out" answer (code 22) from a busy management plane — the same key keeps working, so it is not an authentication failure. While the commit job is being polled the poll simply goes on; elsewhere the run is retried. |
CREDENTIAL_MISSING | auth | No default credential was resolved for the target at run time. Not retried. |
Warnings (not errors): PANOS_COMMIT_PENDING — imported but not committed because auto_commit is off; TLS_UNVERIFIED_PASSWORD — the password went to a firewall that is neither verified nor pinned (see Trusting the firewall's certificate). Both are listed under Warning codes.
Troubleshooting
The run is green but the firewall still serves the old certificate
Check the run's warnings: with auto_commit off the import sits in the candidate configuration until someone commits. Commit in the firewall UI/CLI, or turn auto_commit on and re-run — the module will finish with a commit-only pass.
"vsys ... but multi-vsys is disabled"
The target sets vsys on a firewall that has multi-vsys off. Clear the field to use the shared location.
Commit fails with "certificate length ... is greater than the size of buffer"
PAN-OS 10.2.0 limited the imported leaf certificate to 2048 bytes (4096 from 10.2.3; the limit is gone from 10.2.8 and 11.1.0). A large leaf — RSA-4096 with many SANs — can trip it. Upgrade the firewall past 10.2.8/11.1.0, or issue the certificate with a smaller key or SAN set.
The Certificates screen shows one entry — where is the chain?
Inside that entry. PAN-OS keeps every certificate of the imported PKCS#12 under the one object name and presents them all in the TLS handshake (openssl s_client -connect <fw>:443 -showcerts against a bound profile lists the leaf and the intermediates). The screen does not expand an embedded chain into a tree the way it does for separately imported CA objects, so a single row is the expected look. Only import the intermediate as its own object if something other than TLS serving needs it as a CA object (a certificate profile, decryption trust) — that is not part of this module.
Import fails with "identical subject and issuer"
PAN-OS refuses self-signed non-CA certificates. Issue the certificate from a CA (any CA — including your internal one); CertAutoPilot-managed ACME and AD CS certificates always qualify.
See also
Concurrency
Different firewalls are deployed in parallel (up to 5 by default, concurrency 1–50). One device identity — panos:<host>:<port>, host lower-cased, port 443 when unset — drives all three serialization points: targets that share it are serialized inside the run, a distributed device lock serializes across runs, and fan-out batching keeps its targets in one batch — a PAN-OS box processes one commit at a time, so this keeps two certificates from queueing commits against each other. Two targets naming the same host on different management ports count as two devices.
Video tutorial
Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →