snapshot¶
Which snapshots do you have, what does a question read, and what changed between two of them?
Synopsis¶
proteus snapshot list <device>
proteus snapshot show [selection flags]
proteus snapshot diff [--device <name>] [--label key=value] [--vsys <name>] [--from <time>] [--to <time>] [--limit N]
Examples¶
List the snapshots of a device¶
$ proteus snapshot list fw01
* 2026-09-28T08-00-00Z PAN-OS 11.2.5 1 documents, 0 failed
2026-09-22T08-00-00Z PAN-OS 11.2.5 1 documents, 0 failed
The list starts with the newest snapshot. The * marks the snapshot that
latest names, which every question reads by default.
Show what a question reads¶
$ proteus snapshot show --device fw01
fw01 snapshot 2026-09-28T08-00-00Z (19d)
note: snapshot 2026-09-28T08-00-00Z is 461h42m0s old, past the 24h0m0s limit
fw01.example.net, PA-VM, serial 000000000001
config 3252 bytes
vsys1 PAN-OS 11.2.5, security rules: 6
vsys2 PAN-OS 11.2.5, security rules: 3
snapshot show reports the device, the snapshot and its age, each document, and
the vsys with their rule counts. The note appears because the snapshot is older
than max_snapshot_age.
Check a configuration file¶
$ proteus snapshot show --file testdata/config/firewall-multivsys.xml
file testdata/config/firewall-multivsys.xml
vsys1 PAN-OS 11.2.5, security rules: 1
vsys2 PAN-OS 11.2.5, security rules: 0
vsys3 PAN-OS 11.2.5, security rules: 0
With --file, Proteus reads one configuration file and needs no store. Use it to
confirm that Proteus finds every vsys before you ask a question about the file.
Compare the last two snapshots¶
$ proteus snapshot diff
fw01 2026-09-22T08-00-00Z -> 2026-09-28T08-00-00Z
shared no changes
fw01/shared: 0 added, 0 removed, 0 changed
vsys:vsys1
fw01/vsys:vsys1: 1 added, 1 removed, 2 changed
changed address net-home
ip-netmask: 198.18.1.0/24 -> 198.18.2.0/24
removed address net-labor 198.18.0.0/15
changed security rule dc-to-home
disabled: (unset) -> yes
added security rule new-rule allow application=dns destination=any source=net-home
vsys:vsys2 no changes
fw01/vsys:vsys2: 0 added, 0 removed, 0 changed
1 with changes, 0 without, 0 holes
{
"format": 2,
"command": "snapshot diff",
"detail": "summary",
"input": {
"from": "",
"limit": 0,
"selection": {},
"to": ""
},
"results": [
{
"answer": "fw01/shared: 0 added, 0 removed, 0 changed",
"device": "fw01",
"from": "2026-09-22T08-00-00Z",
"to": "2026-09-28T08-00-00Z",
"scope": "shared",
"added": 0,
"removed": 0,
"changed": 0
},
{
"answer": "fw01/vsys:vsys1: 1 added, 1 removed, 2 changed",
"device": "fw01",
"from": "2026-09-22T08-00-00Z",
"to": "2026-09-28T08-00-00Z",
"scope": "vsys:vsys1",
"added": 1,
"removed": 1,
"changed": 2
},
{
"answer": "fw01/vsys:vsys2: 0 added, 0 removed, 0 changed",
"device": "fw01",
"from": "2026-09-22T08-00-00Z",
"to": "2026-09-28T08-00-00Z",
"scope": "vsys:vsys2",
"added": 0,
"removed": 0,
"changed": 0
}
],
"summary": {
"answer": "1 with changes, 0 without, 0 holes",
"found": 4,
"with": 1,
"without": 0,
"omitted": 0
},
"holes": [],
"unresolved": [],
"notes": []
}
Without --from and --to, the diff compares the snapshot before latest with
latest. It compares each selected device per vsys and for shared, entry by
entry in the schema's terms. The JSON tab shows
proteus snapshot diff --output json --detail summary, which keeps the counts
and leaves out the changes.
Reading the output¶
snapshot list¶
| Part | Meaning |
|---|---|
* |
the snapshot that latest names |
2026-09-28T08-00-00Z |
the snapshot id: the UTC time of the fetch |
PAN-OS 11.2.5 |
the PAN-OS version of the device at that time |
1 documents, 0 failed |
the documents the fetch stored, and the documents that failed |
| a hole below the list | a snapshot whose meta.json is missing or unreadable; the command exits 3 |
snapshot show¶
| Line | Meaning |
|---|---|
fw01 snapshot <id> (<age>) |
the device, the snapshot a question reads, and its age |
file <path> |
the configuration file that --file names |
note: … |
a note about the snapshot, such as its age past max_snapshot_age |
<host>, <model>, serial <serial> |
the device as the snapshot records it |
fetched from the active HA peer <host> |
the device was passive, and fetch read its active peer |
<document> <n> bytes |
a stored document and its size |
<document> FAILED <error> |
a document that the fetch could not read |
<vsys> PAN-OS <version>, security rules: <n> |
a vsys, its PAN-OS version and its security rule count |
snapshot diff¶
| Line | Meaning |
|---|---|
fw01 <from> -> <to> |
the device and the two snapshots it compares |
shared, vsys:vsys1 |
a scope; no changes follows when nothing changed |
fw01/vsys:vsys1: 1 added, 1 removed, 2 changed |
the counts of the scope |
changed <kind> <name> |
an entry that exists in both snapshots with a different content |
<path>: <old> -> <new> |
one setting that differs in a changed entry |
added <kind> <name> <short line> |
an entry in the newer snapshot only |
removed <kind> <name> <short line> |
an entry in the older snapshot only |
1 with changes, 0 without, 0 holes |
the devices with changes, the devices without a change, and the holes |
A device without two snapshots to compare is a hole. The short line of an added or removed entry shows an object's value, or a rule's action and lists.
These markers appear in a setting line:
| Marker | Meaning |
|---|---|
(unset) |
the setting is absent on this side |
(set) |
the element is present and holds no value |
changed (secret, not shown) |
a secret changed; the value stays hidden |
(secret) |
a secret that is set on this side only |
changed (not described by the schema; values not shown) |
a value that the schema does not describe changed |
server order: ldap1, ldap2 -> ldap2, ldap1 |
a list of named entries inside an entry changed its order |
The diff compares these parts of each scope:
| Part | How it compares |
|---|---|
| objects of every kind | addresses, services, external lists, zones, schedules, profiles, profile groups, log settings and the rest |
| rules of every rulebase | security, NAT, PBF, decryption and the others |
| rules pushed from Panorama | in shared only; the kind names the rulebase, such as pre-rulebase security rule or post-rulebase security rule |
| a vsys's own rules | in that vsys only; the kind reads security rule |
| other settings of the scope | one entry of kind setting, named by its path below the scope, such as import/network/interface |
| a vsys user group | a list of named entries, of kind user-group |
| a list of members | a set, so a reorder is no change |
| a list of named entries inside an entry | in order, so a reorder shows as one line |
A changed entry lists every setting that differs, with its text and attributes.
An added or removed setting shows its value when it has one value that may show.
For example, changed setting import/network/interface has the line
interface: ethernet1/1 -> ethernet1/1, ethernet1/3 below it.
The diff skips the attributes that PAN-OS writes for its own bookkeeping: uuid,
admin, time and dirtyId. A rule that only moved counts as no change.
When the App-ID content version differs between the two snapshots, the note
note.app-version-changed names both versions.
In JSON and YAML, the changes have these keys:
| Key | Content |
|---|---|
fields |
the settings of a changed entry, each with path, old and new; an absent side is empty |
new, old |
the value of an added or a removed entry |
"secret": true |
a secret; old and new read (secret) |
"undescribed": true |
a value the schema does not describe; old and new are empty |
summary.found |
every change |
summary.omitted |
the changes that --limit leaves out; 0 when none |
Secrets and undescribed values¶
The diff never shows a secret. A secret is a key, a password or a password hash, such as a certificate's private key, a server profile's password or a local user's password hash.
Some credentials count as secrets although the schema does not mark them as encrypted:
- an SNMP v2c trap community
- a SCEP fixed challenge
- the URL, payload, header and parameter values of an HTTP server profile
- the values of an MFA server profile
The diff also hides a value that the schema does not describe. A newer PAN-OS release can add such an element or attribute, and it may hold a secret. An added or removed object that holds a secret or such a value shows no short line. A rule's short line shows only the lists that the schema describes.
App-ID data¶
The applications that a rule, a filter or a container selects come from the
firewall's App-ID content. The configuration does not hold them. fetch reads the
content version from show system info. When the store holds no file of that
version, fetch asks the firewall for its predefined applications and
containers. It keeps the fields that Proteus needs and writes one file:
<store>/.content/<content version>.v1.xml.gz
| Case | Result |
|---|---|
| a later fetch of the same content version | reuses the file and does not ask the firewall again |
| the first fetch of a new content version | takes longer, because the answer is large |
| a file that no snapshot names and that is older than one hour | each run removes it |
| the firewall refuses the data, or its content version has an unknown form | the note note.fetch-applications-missing; the fetch is still complete, and rules that name an application stay in doubt |
| the call fails on the way, or the file cannot be written | the snapshot is stored, and fetch exits 3 |
| the firewall returns the applications without the containers | the file records that, and a rule that names a container stays in doubt |
Snapshots describes how the store shares
the file and how meta.json names its version. To fetch a file again, delete it.
To use the data with --file, copy the file beside the configuration file and
name it apps.xml.gz.
Old and damaged snapshots¶
Every question takes --at <time> and reads each device's newest snapshot at or
before that time. A date means the end of that day.
| Case | Result |
|---|---|
a damaged snapshot at the asked time, whose meta.json cannot be read |
the answer reads the next older one, with note.snapshot-skipped naming the skipped one |
| no older snapshot can be read | the device is a hole that names the damaged snapshots |
a damaged latest, without --at |
the device is a hole; Proteus does not fall back to an older snapshot |
a snapshot older than max_snapshot_age (default 24h) |
the answer carries note.snapshot-stale; change the limit with --max-age 7d |
Flags¶
snapshot list takes one device name and no flags of its own.
snapshot show takes every selection flag:
--device, --label, --vsys, --at, --fresh and --file.
snapshot diff takes --device, --label and --vsys, and these flags:
| Flag | Default | Description |
|---|---|---|
--from <time> |
the snapshot before --to |
compare from the newest snapshot at or before this time |
--to <time> |
latest |
compare to the newest snapshot at or before this time |
--limit N |
all | keep only the first N changes; the summary counts the rest |
--detail |
full |
with --output json or yaml: summary or full |
--from and --to take a snapshot id, an RFC 3339 time or a date. Any other
value is a usage error (exit 2) that names the flag.
--limit takes 1 or more, and --limit 0 is a usage error (exit 2). It counts the
changes in output order over all scopes and devices together. The scope where the
limit falls shows its first changes, and its count line adds how many it shows:
fw01/vsys:vsys1: 1 added, 1 removed, 2 changed (2 of 4 changes shown)
The scopes after it are left out, and the last line ends
; 2 of 4 shown, narrow by device. Holes and notes are never cut. When all
changes of a device are left out, its note prints below as note: fw02: <text>.
With --detail summary, each scope counts all of its changes.
Limits¶
snapshot diffdoes not compare the App-ID applications. A note only says that the content version changed.snapshot diffdoes not compare the predefined services, because they are not configuration.
See Limits.