diff --git a/products/panos/docs/panos-upgrade-assurance.mdx b/products/panos/docs/panos-upgrade-assurance.mdx
index c2d6a08e7..bbf785166 100644
--- a/products/panos/docs/panos-upgrade-assurance.mdx
+++ b/products/panos/docs/panos-upgrade-assurance.mdx
@@ -22,7 +22,7 @@ The `panos-upgrade-assurance` includes the set of libraries written in `Python`
Both checks and snapshots can be used to verify the state of a device during an upgrade process. What more, it is possible to generate a report for these checks.
-The libraries were written to support Ansible and XSOAR integrations. They depend on [pan-os-python](/panos/docs/panospython/) libraries and therefore are quite easy to fit into the [PanOS Ansible modules collection](https://galaxy.ansible.com/paloaltonetworks/panos).
+The libraries were written to support Ansible and XSOAR integrations. They depend on [pan-os-python](/panos/docs/panospython/) libraries and therefore are quite easy to fit into the [PanOS Ansible modules collection](https://galaxy.ansible.com/paloaltonetworks/panos). Equivalent yaml configurations are provided in the documentation as a reference to use with the PanOS Ansible modules collection.
The libraries are available in two form factors:
diff --git a/products/panos/docs/panos-upgrade-assurance/api/check_firewall.md b/products/panos/docs/panos-upgrade-assurance/api/check_firewall.md
index 1ef0c0faf..4f9efe1c9 100644
--- a/products/panos/docs/panos-upgrade-assurance/api/check_firewall.md
+++ b/products/panos/docs/panos-upgrade-assurance/api/check_firewall.md
@@ -459,6 +459,26 @@ __Returns__
* [`CheckStatus.ERROR`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkstatus) when the certificate's
properties (installed or required) are not supported.
+### `CheckFirewall.check_non_finished_jobs`
+
+```python
+def check_non_finished_jobs() -> CheckResult
+```
+
+Check for any job with status different than FIN.
+
+__Returns__
+
+
+`CheckResult`: Object of [`CheckResult`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkresult) class taking value of:
+
+* [`CheckStatus.SUCCESS`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkstatus) when all jobs are in FIN state.
+* [`CheckStatus.FAIL`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkstatus) otherwise, `CheckResult.reason`
+ field contains information about the 1st job found with status different than FIN (job ID and the actual
+ status).
+* [`CheckStatus.SKIPPED`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkstatus) when there are no jobs on a
+ device.
+
### `CheckFirewall.get_content_db_version`
```python
diff --git a/products/panos/docs/panos-upgrade-assurance/api/firewall_proxy.md b/products/panos/docs/panos-upgrade-assurance/api/firewall_proxy.md
index 88ca108dc..21b642ab5 100644
--- a/products/panos/docs/panos-upgrade-assurance/api/firewall_proxy.md
+++ b/products/panos/docs/panos-upgrade-assurance/api/firewall_proxy.md
@@ -956,3 +956,71 @@ __Returns__
}
```
+### `FirewallProxy.get_jobs`
+
+```python
+def get_jobs() -> dict
+```
+
+Get details on all jobs.
+
+This method retrieves all jobs and their details, this means running, pending, finished, etc.
+
+The actual API command is `show jobs all`.
+
+__Returns__
+
+
+`dict`: All jobs found on the device, indexed by the ID of a job.
+
+```python showLineNumbers title="Sample output"
+{'1': {'description': None,
+ 'details': {'line': ['ID population failed',
+ 'Client logrcvr registered in the middle of a '
+ 'commit/validate. Aborting current '
+ 'commit/validate.',
+ 'Commit failed',
+ 'Failed to commit policy to device']},
+ 'positionInQ': '0',
+ 'progress': '100',
+ 'queued': 'NO',
+ 'result': 'FAIL',
+ 'status': 'FIN',
+ 'stoppable': 'no',
+ 'tdeq': '00:28:32',
+ 'tenq': '2023/08/01 00:28:32',
+ 'tfin': '2023/08/01 00:28:36',
+ 'type': 'AutoCom',
+ 'user': None,
+ 'warnings': None},
+'2': {'description': None,
+ 'details': {'line': ['Configuration committed successfully',
+ 'Successfully committed last configuration']},
+ 'positionInQ': '0',
+ 'progress': '100',
+ 'queued': 'NO',
+ 'result': 'OK',
+ 'status': 'FIN',
+ 'stoppable': 'no',
+ 'tdeq': '00:28:40',
+ 'tenq': '2023/08/01 00:28:40',
+ 'tfin': '2023/08/01 00:29:20',
+ 'type': 'AutoCom',
+ 'user': None,
+ 'warnings': None},
+'3': {'description': None,
+ 'details': None,
+ 'positionInQ': '0',
+ 'progress': '30',
+ 'queued': 'NO',
+ 'result': 'PEND',
+ 'status': 'ACT',
+ 'stoppable': 'yes',
+ 'tdeq': '00:58:59',
+ 'tenq': '2023/08/01 00:58:59',
+ 'tfin': None,
+ 'type': 'Downld',
+ 'user': None,
+ 'warnings': None}}
+```
+
diff --git a/products/panos/docs/panos-upgrade-assurance/configuration_details.mdx b/products/panos/docs/panos-upgrade-assurance/configuration_details.mdx
index 3a8ae1942..2913773eb 100644
--- a/products/panos/docs/panos-upgrade-assurance/configuration_details.mdx
+++ b/products/panos/docs/panos-upgrade-assurance/configuration_details.mdx
@@ -16,6 +16,9 @@ keywords:
- upgrade assurance
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
# Configuration details
This documentation represents the current state of the available checks and snapshot state areas, along with the instructions on how to configure them properly.
@@ -52,27 +55,73 @@ Elements of this list can be either of the `str` or `dict` type:
- `str` - the element simply specifies the name of a check to run.
- `dict` - the element contains the check name and a configuration (if a particular check requires one); the dictionary format is as follows:
- ```yaml
+ ```mdx-code-block
+
+
+ ```
+
+ ```python
{
'check_name': {
- 'config_name': 'config_value'
+ 'config_name': 'config_value',
'config2_name': 'config2_value'
}
}
```
+ ```mdx-code-block
+
+
+ ```
+
+ ```yaml
+ check_name:
+ config_name: 'config_value'
+ config2_name: 'config2_value'
+ ```
+
+ ```mdx-code-block
+
+
+ ```
+
Following [`ConfigParser's`][cfgprs] [`dialect`][dialect], when no configuration is provided, **all** checks are triggered. *Notice* that in this situation checks that require configuration to run will return [`CheckStatus.SKIPPED`](/panos/docs/panos-upgrade-assurance/api/utils#class-checkstatus).
Example of the `checks_configuration` parameter:
-``` yaml
-[
- 'all',
- '!ha',
- {'content_version': {'version': '8634-7678'}}
+```mdx-code-block
+
+
+```
+
+```python
+checks_configuration = [
+ 'all',
+ '!ha',
+ {'content_version': {
+ 'version': '8634-7678'
+ }}
]
```
+```mdx-code-block
+
+
+```
+
+```yaml
+checks_configuration:
+ - 'all'
+ - '!ha'
+ - 'content_version':
+ version: '8634-7678'
+```
+
+```mdx-code-block
+
+
+```
+
This is interpreted as:
- run all checks
@@ -88,17 +137,43 @@ The [`CheckFirewall.run_readiness_checks()`](/panos/docs/panos-upgrade-assurance
Assuming that we run the checks with the following configuration:
- ``` yaml
- [
+ ```mdx-code-block
+
+
+ ```
+
+ ```python
+ checks_configuration = [
'ha',
'panorama',
]
```
+ ```mdx-code-block
+
+
+ ```
+
+ ```yaml
+ checks_configuration:
+ - 'ha'
+ - 'panorama'
+ ```
+
+ ```mdx-code-block
+
+
+ ```
+
The return `dict` should look as follows:
- ``` yaml
- {
+ ```mdx-code-block
+
+
+ ```
+
+ ```python
+ result = {
'ha': {
'state': False
'reason': '[FAIL] Device configuration is not synchronized between the nodes.'
@@ -110,10 +185,58 @@ The [`CheckFirewall.run_readiness_checks()`](/panos/docs/panos-upgrade-assurance
}
```
+ ```mdx-code-block
+
+
+ ```
+
+ ```yaml
+ result:
+ ha:
+ state: false
+ reason: '[FAIL] Device configuration is not synchronized between the nodes.'
+ candidate_config:
+ state: true
+ reason: '[SUCCESS]'
+ ```
+
+ ```mdx-code-block
+
+
+ ```
+
- `True`: results are also formatted as `dict` with the keys corresponding to checks names, but values are a string representations of the [`CheckResult`][chckres] class.
For the above example of checks, the result would be similar to:
+ ```mdx-code-block
+
+
+ ```
+
+ ```python
+ result = {
+ 'ha': '[FAIL] Device configuration is not synchronized between the nodes.'
+ 'candidate_config': '[SUCCESS].'
+ }
+ ```
+
+ ```mdx-code-block
+
+
+ ```
+
+ ```yaml
+ result:
+ ha: '[FAIL] Device configuration is not synchronized between the nodes.'
+ candidate_config: '[SUCCESS].'
+ ```
+
+ ```mdx-code-block
+
+
+ ```
+
``` yaml
{
'ha': '[FAIL] Device configuration is not synchronized between the nodes.'
@@ -123,39 +246,92 @@ The [`CheckFirewall.run_readiness_checks()`](/panos/docs/panos-upgrade-assurance
The list of checks to run looks as follows:
+```mdx-code-block
+
+
+```
+
```python
-[
- "active_support",
- 'candidate_config',
- 'expired_licenses',
- 'ntp_sync',
- 'panorama',
+checks_configuration = [
+ "active_support",
+ 'candidate_config',
+ 'expired_licenses',
+ 'jobs',
+ 'ntp_sync',
+ 'panorama',
+ # tests below have optional configuration
+ {
+ "certificates_requirements": {
+ "ecdsa": {"hash_method": "sha512"},
+ "rsa": {
+ "key_size": 1024,
+ "hash_method": "sha1"
+ }
+ }
+ },
+ {'content_version': {'version': '8634-7678'}},
+ {"expired_licenses": {"skip_licenses": ["Threat Prevention"]}},
+ {'free_disk_space': {'image_version': '10.1.6-h6'}},
+ {'ha': {'skip_config_sync': True}},
+ {'planes_clock_sync': {'diff_threshold': 30}}
+ # tests below require additional configuration
+ {'arp_entry_exist': {'ip': '10.0.1.1'} },
+ {'ip_sec_tunnel_status': {
+ 'tunnel_name': 'ipsec_tun'
+ }},
+ {'session_exist': {
+ 'source': '134.238.135.137',
+ 'destination': '10.1.0.4',
+ 'dest_port': '80'
+ }},
+]
+```
+
+```mdx-code-block
+
+
+```
+
+```yaml
+checks_configuration:
+ - "active_support"
+ - "candidate_config"
+ - "expired_licenses"
+ - "jobs"
+ - "ntp_sync"
+ - "panorama"
# tests below have optional configuration
- {
- "certificates_requirements": {
- "ecdsa": {"hash_method": "sha512"},
- "rsa": {
- "key_size": 1024,
- "hash_method": "sha1"
- }
- }
- },
- {'content_version': {'version': '8634-7678'}},
- {"expired_licenses": {"skip_licenses": ["Threat Prevention"]}},
- {'free_disk_space': {'image_version': '10.1.6-h6'}},
- {'ha': {'skip_config_sync': True}},
- {'planes_clock_sync': {'diff_threshold': 30}}
+ - certificates_requirements:
+ ecdsa:
+ hash_method: "sha512"
+ rsa:
+ key_size: 1024
+ hash_method: "sha1"
+ - content_version:
+ version: "8634-7678"
+ - expired_licenses:
+ skip_licenses:
+ - "Threat Prevention"
+ - free_disk_space:
+ image_version: "10.1.6-h6"
+ - ha:
+ skip_config_sync: true
+ - planes_clock_sync:
+ diff_threshold: 30
# tests below require additional configuration
- {'arp_entry_exist': {'ip': '10.0.1.1'} },
- {'ip_sec_tunnel_status': {
- 'tunnel_name': 'ipsec_tun'
- }},
- {'session_exist': {
- 'source': '134.238.135.137',
- 'destination': '10.1.0.4',
- 'dest_port': '80'
- }},
-]
+ - arp_entry_exist:
+ ip: "10.0.1.1"
+ - ip_sec_tunnel_status:
+ tunnel_name: "ipsec_tun"
+ - session_exist:
+ source: "134.238.135.137"
+ destination: "10.1.0.4"
+ dest_port: "80"
+```
+
+```mdx-code-block
+
+
```
Please see the sections below for details of each check:
@@ -175,19 +351,56 @@ parameter | description
**Sample configuration**
-```python showLineNumbers
-# with lookup limited to a single interface
-{
- 'ip': '10.0.1.1'
- 'interface': 'ethernet1/1'
-}
+```mdx-code-block
+
+
+```
-# with a lookup in all ARP entries
-{
- 'ip': '10.0.0.6'
-}
+```python showLineNumbers title="Lookup limited to a single interface"
+checks_configuration = [
+ {
+ 'arp_entry_exist': {
+ 'ip': '10.0.1.1'
+ 'interface': 'ethernet1/1'
+ }
+ }
+]
```
+```python showLineNumbers title="Lookup in all ARP entries"
+checks_configuration = [
+ {
+ 'arp_entry_exist': {
+ 'ip': '10.0.0.6'
+ }
+ }
+]
+```
+
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers title="Lookup limited to a single interface"
+checks_configuration:
+ - arp_entry_exist:
+ ip: '10.0.1.1'
+ interface: 'ethernet1/1'
+```
+
+```yaml showLineNumbers title="Lookup in all ARP entries"
+checks_configuration:
+ - arp_entry_exist:
+ ip: '10.0.0.6'
+```
+
+```mdx-code-block
+
+
+```
+
+
### `candidate_config`
Verifies if there are any changes on the device pending to be committed. This can be either a loaded named config which requires a full commit or just some small changes made manually or with an CLI/API.
@@ -218,18 +431,48 @@ key | description
**Sample configuration**
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-{
- "ecdsa": {
- "hash_method": "sha512"
- },
- "rsa": {
- "key_size": 1024,
- "hash_method": "sha1"
- }
-}
+checks_configuration = [
+ {
+ "certificates_requirements": {
+ "ecdsa": {
+ "hash_method": "sha512"
+ },
+ "rsa": {
+ "key_size": 1024,
+ "hash_method": "sha1"
+ }
+ }
+ }
+]
```
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+checks_configuration:
+ - certificates_requirements:
+ ecdsa:
+ hash_method: "sha512"
+ rsa:
+ key_size: 1024,
+ hash_method: "sha1"
+```
+
+```mdx-code-block
+
+
+```
+
+
### `content_version`
Compares currently installed Content DB version against either:
@@ -247,12 +490,38 @@ paramter | description
**Sample configuration**
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-{
- 'version': '6453-5673'
-}
+checks_configuration = [
+ {
+ 'content_version': {
+ 'version': '6453-5673'
+ }
+ }
+]
+```
+
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+checks_configuration:
+ - content_version:
+ version: '6453-5673'
+```
+
+```mdx-code-block
+
+
```
+
### `free_disk_space`
Checks if there is enough free space on the `/opt/panrepo` volume to download a PanOS image before an upgrade.
@@ -267,12 +536,38 @@ paramter | description
**Sample configuration**
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-{
- 'image_version': '10.1.6-h3'
-}
+checks_configuration = [
+ {
+ 'free_disk_space': {
+ 'image_version': '10.1.6-h3'
+ }
+ }
+]
```
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+checks_configuration:
+ - free_disk_space:
+ image_version: '10.1.6-h3'
+```
+
+```mdx-code-block
+
+
+```
+
+
### `expired_licenses`
Checks and reports expired licenses.
@@ -287,12 +582,39 @@ paramter | description
**Sample configuration**
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-{
- 'skip_licenses': ['WildFire License', 'Threat Prevention']
-}
+checks_configuration = [
+ { 'expired_licenses': {
+ 'skip_licenses': ['WildFire License', 'Threat Prevention']
+ }
+ }
+]
+```
+
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+checks_configuration:
+ - expired_licenses:
+ skip_licenses:
+ - 'WildFire License'
+ - 'Threat Prevention'
+```
+
+```mdx-code-block
+
+
```
+
### `ha`
Verifies if an HA pair is in a correct state. Only Active-Passive configuration is supported at the moment.
@@ -307,12 +629,38 @@ paramter | description
**Sample configuration**
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-{
- 'skip_config_sync': True
-}
+checks_configuration = [
+ {
+ 'ha' : {
+ 'skip_config_sync': True
+ }
+ }
+]
```
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+checks_configuration:
+ - ha:
+ skip_config_sync: true
+```
+
+```mdx-code-block
+
+
+```
+
+
### `ip_sec_tunnel_status`
Verifies if a given IPSec tunnel is in active state.
@@ -327,12 +675,46 @@ paramter | description
**Sample configuration**
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-{
- 'tunnel_name': 'ipsec_tunnel'
-}
+checks_configuration = [
+ {
+ 'ip_sec_tunnel_status': {
+ 'tunnel_name': 'ipsec_tunnel'
+ }
+ }
+]
+```
+
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+checks_configuration:
+ - ip_sec_tunnel_status:
+ tunnel_name: 'ipsec_tunnel'
```
+```mdx-code-block
+
+
+```
+
+### `jobs`
+
+Verify if there are any running/pending jobs in the job queue. Any job with a status different than `FIN` will cause
+the check to fail.
+
+Does not require configuration.
+
+**Method**: [`CheckFirewall.check_non_finished_jobs()`](/panos/docs/panos-upgrade-assurance/api/check_firewall#checkfirewallcheck_non_finished_jobs)
+
### `ntp_sync`
Verify if time on a device is synchronized with an NTP server. This check fails if no NTP synchronization is configured.
@@ -363,10 +745,35 @@ paramter | description
**Sample configuration**
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-{
- 'diff_threshold': 25
-}
+checks_configuration = [
+ {
+ 'planes_clock_sync': {
+ 'diff_threshold': 25
+ }
+ }
+]
+```
+
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+checks_configuration:
+ - planes_clock_sync:
+ diff_threshold: 25
+```
+
+```mdx-code-block
+
+
```
### `session_exist`
@@ -385,14 +792,42 @@ paramter | description
**Sample configuration**
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-{
- 'source': '134.238.135.137',
- 'destination': '10.1.0.4',
- 'dest_port': '80'
-}
+checks_configuration = [
+ {
+ 'session_exist': {
+ 'source': '134.238.135.137',
+ 'destination': '10.1.0.4',
+ 'dest_port': '80'
+ }
+ }
+]
```
+```mdx-code-block
+
+
+```
+
+```yaml
+checks_configuration:
+ - session_exist:
+ source: '134.238.135.137'
+ destination: '10.1.0.4'
+ dest_port: '80'
+```
+
+```mdx-code-block
+
+
+```
+
+
## State snapshots
State snapshots store information about the state of a particular device area. They do not take any configurations. They store every possible information about an area. Use reports or custom code to extract a subset of information if required.
@@ -408,7 +843,12 @@ The output of the [`CheckFirewall.run_snapshots()`](/panos/docs/panos-upgrade-as
The sample output containing a snapshot for *route tables*, *licenses*, and *IPSec tunnels* is shown below (one element per each area):
-```json
+```mdx-code-block
+
+
+```
+
+```json showLineNumbers
{
"ip_sec_tunnels": {
"ipsec_tun": {
@@ -451,10 +891,20 @@ The sample output containing a snapshot for *route tables*, *licenses*, and *IPS
}
```
+```mdx-code-block
+
+
+```
+
Following state areas are available:
-```yaml
-[
+```mdx-code-block
+
+
+```
+
+```python showLineNumbers
+snapshots_config = [
'nics',
'routes',
'license',
@@ -465,6 +915,27 @@ Following state areas are available:
]
```
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+snapshots_config:
+ - nics
+ - routes
+ - license
+ - arp_table
+ - content_version
+ - session_stats
+ - ip_sec_tunnels
+```
+
+```mdx-code-block
+
+
+```
+
Please see the sections below for details of each state snapshot:
### `arp_table`
@@ -515,35 +986,76 @@ The reporting part is actually the result of comparison of two snapshots. It is
Each report can be run with default or custom configuration. The following example shows reports with additional configuration (where applicable):
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-[
- {'ip_sec_tunnels: {
- 'properties': ['state']
- }},
- {'arp_table': {
- 'properties': ['!ttl'],
- 'count_change_threshold': 10
- }},
- {'nics': {
- 'count_change_threshold': 10
- }},
- {'license': {
- 'properties': ['!serial']
- }},
- {'routes: {
- 'properties': ['!flags'],
- 'count_change_threshold': 10
- }},
- 'content_version',
- {'session_stats': {
- 'thresholds': [
- {'num-max': 10},
- {'num-tcp': 10},
- ]
- }}
+reports = [
+ {'ip_sec_tunnels': {
+ 'properties': ['state']
+ }},
+ {'arp_table': {
+ 'properties': ['!ttl'],
+ 'count_change_threshold': 10
+ }},
+ {'nics': {
+ 'count_change_threshold': 10
+ }},
+ {'license': {
+ 'properties': ['!serial']
+ }},
+ {'routes': {
+ 'properties': ['!flags'],
+ 'count_change_threshold': 10
+ }},
+ 'content_version',
+ {'session_stats': {
+ 'thresholds': [
+ {'num-max': 10},
+ {'num-tcp': 10},
+ ]
+ }}
]
```
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+reports:
+ - ip_sec_tunnels:
+ properties:
+ - "state"
+ - arp_table:
+ properties:
+ - "!ttl"
+ count_change_threshold: 10
+ - nics:
+ count_change_threshold: 10
+ - license:
+ properties:
+ - "!serial"
+ - routes:
+ properties:
+ - "!flags"
+ count_change_threshold: 10
+ - content_version
+ - session_stats:
+ thresholds:
+ - num-max: 10
+ - num-tcp: 10
+```
+
+```mdx-code-block
+
+
+```
+
+
For most reports, a generic comparison method is used ([`SnapshotCompare.get_diff_and_threshold()`](/panos/docs/panos-upgrade-assurance/api/snapshot_compare#snapshotcompareget_diff_and_threshold)). It produces the standardized dictionary. For details, see documentation for this method. Common method assigns a report result to a report area providing a dictionary where keys are report areas and values are report results.
For details on which configuration can be passed, check each report area below (for each report, we will explain the above-mentioned configuration):
@@ -570,13 +1082,41 @@ The following configuration:
This report produces the standardized dictionary.
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-{
- 'properties': ['!ttl'],
- 'count_change_threshold': 10
-}
+reports = [
+ {
+ 'arp_table': {
+ 'properties': ['!ttl'],
+ 'count_change_threshold': 10
+ }
+ }
+]
```
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+reports:
+ - arp_table:
+ properties:
+ - '!ttl'
+ count_change_threshold: 10
+```
+
+```mdx-code-block
+
+
+```
+
+
### `content_version`
This is one of a few checks that does not take any configuration. It simply compares Content DB version from both snapshots. Results are presented as the standardized dictionary.
@@ -603,12 +1143,39 @@ captured in snapshots.
This report produces the standardized dictionary.
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-{
- 'properties': ['state']
-}
+reports = [
+ {
+ 'ip_sec_tunnels': {
+ 'properties': ['state']
+ }
+ }
+]
```
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+reports:
+ - ip_sec_tunnels:
+ properties:
+ - 'state'
+```
+
+```mdx-code-block
+
+
+```
+
+
### `license`
Compares installed licenses. This report does not only check if we have the same set of licenses in both snapshots but also compares license details, such as expiration date, etc.
@@ -629,10 +1196,36 @@ snapshots. It will ignore the `serial` property.
This report produces the standardized dictionary.
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-{
- 'properties': ['!serial']
-}
+reports = [
+ {
+ 'license': {
+ 'properties': ['!serial']
+ }
+ }
+]
+```
+
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+reports:
+ - license:
+ properties:
+ - '!serial'
+```
+
+```mdx-code-block
+
+
```
### `nics`
@@ -655,10 +1248,36 @@ The following configuration provides both: change in NICs\' state (implicitly) a
This report produces the standardized dictionary.
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-{
- 'count_change_threshold': 10
-}
+reports = [
+ {
+ 'nics': {
+ 'count_change_threshold': 10
+ }
+ }
+]
+```
+
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+reports:
+ - nics:
+ count_change_threshold: 10
+
+```
+
+```mdx-code-block
+
+
```
### `routes`
@@ -686,11 +1305,38 @@ The following configuration:
This report produces the standardized dictionary.
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-{
- 'properties': ['!flags'],
- 'count_change_threshold': 10
-}
+reports = [
+ {
+ 'routes': {
+ 'properties': ['!flags'],
+ 'count_change_threshold': 10
+ }
+ }
+]
+```
+
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+reports:
+ - routes:
+ properties:
+ - '!flags'
+ count_change_threshold: 10
+```
+
+```mdx-code-block
+
+
```
### `session_stats`
@@ -713,13 +1359,40 @@ The following configuration compares only stats for `num-max` and `num-tcp`. For
This report produces a `dict` as documented in the [`SnapshotCompare.get_count_change_percentage()`](/panos/docs/panos-upgrade-assurance/api/snapshot_compare#snapshotcompareget_count_change_percentage) method documentation.
+```mdx-code-block
+
+
+```
+
```python showLineNumbers
-{
- 'thresholds': [
- {'num-max': 10},
- {'num-tcp': 10},
- ]
-}
+reports = [
+ {
+ 'session_stats': {
+ 'thresholds': [
+ {'num-max': 10},
+ {'num-tcp': 10}
+ ]
+ }
+ }
+]
+```
+
+```mdx-code-block
+
+
+```
+
+```yaml showLineNumbers
+reports:
+ - session_stats:
+ thresholds:
+ - num-max: 10
+ - num-tcp: 10
+```
+
+```mdx-code-block
+
+
```
[cfgprs]: /panos/docs/panos-upgrade-assurance/api/utils#class-configparser
diff --git a/products/panos/docs/panos-upgrade-assurance/dialect.mdx b/products/panos/docs/panos-upgrade-assurance/dialect.mdx
index 85b05aa4b..031b090db 100644
--- a/products/panos/docs/panos-upgrade-assurance/dialect.mdx
+++ b/products/panos/docs/panos-upgrade-assurance/dialect.mdx
@@ -16,6 +16,9 @@ keywords:
- upgrade assurance
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
# `ConfigParser` class Dialect
The [`ConfigParser`][cfgprs] class is used throughout the project. It assumes and understands a specific dialect, hence it's vital to know it and understand it.
@@ -41,7 +44,12 @@ Below are the concepts of that dialect:
* when:
* the following list is passed:
- ``` yaml
+ ```mdx-code-block
+
+
+ ```
+
+ ```python showLineNumbers
[
'all',
{ 'content_version': {
@@ -50,6 +58,22 @@ Below are the concepts of that dialect:
]
```
+ ```mdx-code-block
+
+
+ ```
+
+ ```yaml showLineNumbers
+ - all
+ - content_version:
+ version: '1234-5678'
+ ```
+
+ ```mdx-code-block
+
+
+ ```
+
* `content_version` is a valid element
* then:
* `all` is expanded to all valid elements but
diff --git a/products/panos/docs/panos-upgrade-assurance/usage_examples.mdx b/products/panos/docs/panos-upgrade-assurance/usage_examples.mdx
index 49eb659ce..8176ef62b 100644
--- a/products/panos/docs/panos-upgrade-assurance/usage_examples.mdx
+++ b/products/panos/docs/panos-upgrade-assurance/usage_examples.mdx
@@ -16,6 +16,9 @@ keywords:
- upgrade assurance
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
# Usage Examples
## Importing Classes
@@ -24,25 +27,55 @@ To use **PAN-OS Upgrade Assurance** in a project, you may either:
- import the package as a whole:
- ``` python
+ ```mdx-code-block
+
+
+ ```
+
+ ```python showLineNumbers
import panos_upgrade_assurance
```
+ ```mdx-code-block
+
+
+ ```
+
- or be more specific about which modules you want to import:
- ``` python
+ ```mdx-code-block
+
+
+ ```
+
+ ```python showLineNumbers
from panos_upgrade_assurance import firewall_proxy
from panos_upgrade_assurance import check_firewall
from panos_upgrade_assurance import snapshot_compare
from panos_upgrade_assurance import utils
```
+ ```mdx-code-block
+
+
+ ```
+
- or, be even *more* specific by importing a specific class:
- ``` python
+ ```mdx-code-block
+
+
+ ```
+
+ ```python showLineNumbers
from panos_upgrade_assurance.check_firewall import CheckFirewall
```
+ ```mdx-code-block
+
+
+ ```
+
## Initializing objects
In the following code snippets, we assume the 3rd way of importing the classes.
@@ -51,7 +84,12 @@ In the following code snippets, we assume the 3rd way of importing th
This class inherits the constructor method from the [Pan-OS-Python Firewall](https://pandevice.readthedocs.io/en/latest/module-firewall.html) class. Therefore, objects for this class are initialized in the same way. For details, see documentation for this class. Here we will provide only the most basic way of initializing the [`FirewallProxy`](/panos/docs/panos-upgrade-assurance/api/firewall_proxy#class-firewallproxy) class that includes a username/password authentication.
-``` python
+```mdx-code-block
+
+
+```
+
+```python showLineNumbers
from panos_upgrade_assurance.firewall_proxy import FirewallProxy
firewall = FirewallProxy(
@@ -61,11 +99,21 @@ firewall = FirewallProxy(
)
```
+```mdx-code-block
+
+
+```
+
### `CheckFirewall` class
Since this is a *high level* class, it depends on the [`FirewallProxy`](/panos/docs/panos-upgrade-assurance/api/firewall_proxy#class-firewallproxy) class for device communication. Hence, the constructor for this class takes an object of the [`FirewallProxy`](/panos/docs/panos-upgrade-assurance/api/firewall_proxy#class-firewallproxy) class.
-``` python
+```mdx-code-block
+
+
+```
+
+```python showLineNumbers
from panos_upgrade_assurance.check_firewall import CheckFirewall
from panos_upgrade_assurance.firewall_proxy import FirewallProxy
@@ -73,6 +121,11 @@ firewall = FirewallProxy(hostname='1.2.3.4', api_username='ro_admin', api_passwo
checks = CheckFirewall(firewall)
```
+```mdx-code-block
+
+
+```
+
### `SnapshotCompare` class
This class provides methods of comparing two snapshots made with the
@@ -82,7 +135,12 @@ The idea around this class is that an object represents an entity storing two sn
In the example above, we implicitly take snapshots for all supported state areas. For more details, see [`ConfigParser`](/panos/docs/panos-upgrade-assurance/api/utils#class-configparser) [`dialect`](/panos/docs/panos-upgrade-assurance/dialect).
-``` python
+```mdx-code-block
+
+
+```
+
+```python showLineNumbers
from panos_upgrade_assurance.snapshot_compare import SnapshotCompare
diff_object = SnapshotCompare( # initialize object storing both snapshots
@@ -91,6 +149,11 @@ diff_object = SnapshotCompare( # initialize object storing both snapshots
)
```
+```mdx-code-block
+
+
+```
+
### `ConfigParser` class (internal)
Although this is an internally used class, probably not often used on a daily basis, we provide documentation on how to initialize it as it's heavily used in the other classes.
@@ -100,7 +163,12 @@ The constructor for this class takes two arguments:
- a valid set of configuration parameters,
- a configuration provided by a user (the one that will be verified and parsed).
-``` python
+```mdx-code-block
+
+
+```
+
+```python showLineNumbers
from panos_upgrade_assurance.utils import ConfigParser
parser = ConfigParser(
@@ -109,6 +177,11 @@ parser = ConfigParser(
)
```
+```mdx-code-block
+
+
+```
+
## The library in action - usage examples
Please note that the samples below assume the minimum knowledge on available tests and their configurations. Refer to the [Configuration Details document](/panos/docs/panos-upgrade-assurance/configuration-details) for complete documentation.
@@ -122,7 +195,12 @@ This is the sample code showing how to run readiness checks. In this example, we
If at least one of the tests fail, the script exits immediately.
-``` python
+```mdx-code-block
+
+
+```
+
+```python showLineNumbers
from panos_upgrade_assurance.check_firewall import CheckFirewall
from panos_upgrade_assurance.firewall_proxy import FirewallProxy
@@ -159,13 +237,28 @@ if not passed:
# ... continue script
```
+```mdx-code-block
+
+
+```
+
The sample output of this portion of the script (both tests fail):
-``` console
+```mdx-code-block
+
+
+```
+
+```console showLineNumbers
FAILED: session_exist - [FAIL] Session not found in the session table.
FAILED: arp_entry_exist - [FAIL] Entry not found in the ARP table.
```
+```mdx-code-block
+
+
+```
+
### Generating a report based on snapshots
In this example, we take two snapshots (one for each device in an HA pair) and we use the [`SnapshotCompare`](/panos/docs/panos-upgrade-assurance/api/snapshot_compare#class-snapshotcompare) class to compare licenses. Based on the comparison result, a decision is made whether to continue with the rest of the script.
@@ -177,7 +270,12 @@ The comparison itself is configured to:
- `authcodes` as two different authcodes were used for licensing devices.
- check only part of the comparison results that compares licenses existing in both snapshots. Licenses missing in each snapshot are not checked.
-``` python
+```mdx-code-block
+
+
+```
+
+```python showLineNumbers
from panos_upgrade_assurance.check_firewall import CheckFirewall
from panos_upgrade_assurance.firewall_proxy import FirewallProxy
from panos_upgrade_assurance.snapshot_compare import SnapshotCompare
@@ -205,9 +303,19 @@ if not license_diff['license']['changed']['passed']:
# ... code that handles failed check
```
+```mdx-code-block
+
+
+```
+
The sample output of the above script:
-``` console
+```mdx-code-block
+
+
+```
+
+```console showLineNumbers
GlobalProtect Gateway:
| passed: True
WildFire License:
@@ -235,3 +343,8 @@ PAN-DB URL Filtering:
Threat Prevention:
| passed: True
```
+
+```mdx-code-block
+
+
+```