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"}), slot default.
• 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_commit off, 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-KEY header, 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_name at 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 partial and 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 firewall administrator account (a dedicated one is strongly recommended — the partial commit is scoped to it). A superuser or device-admin dynamic role always suffices; for a custom Admin Role, enable four checkboxes on its XML API tab: Configuration (the module reads the certificate object for idempotency), Operational Requests (system info and commit-job polling), Commit, and Import — missing any one fails the deploy with an authorization error. A vsys-scoped admin can only manage its own vsys; use a device-wide account when the target imports to the shared location.
• 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.

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

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_commit back 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.

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 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.
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 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. Retried.
CREDENTIAL_MISSING	auth	No default credential was resolved for the target at run time. Not retried.

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.

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

• Distribution overview
• Rollback
• Module credentials
• Validation (TLS fingerprint)

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.