From a6bfd14862ebd64913fe0a914e8f2163426aa1e9 Mon Sep 17 00:00:00 2001 From: Calvin Remsburg Date: Sun, 21 Jan 2024 13:54:23 -0600 Subject: [PATCH] Update pan-os-upgrade version to 0.2.2 and fix documentation links --- README.md | 123 +++++++- docker/Dockerfile | 2 +- docker/requirements.txt | 2 +- docs/about/contributing.md | 2 +- docs/about/release-notes.md | 18 ++ docs/css/custom.css | 186 ++++++++++++ docs/css/termynal.css | 113 +++++++ {images => docs/images}/logo.svg | 0 {images => docs/images}/screenshot.jpg | Bin docs/index.md | 59 ++-- docs/js/custom.js | 188 ++++++++++++ docs/js/termynal.js | 283 ++++++++++++++++++ docs/user-guide/configuration.md | 51 ---- docs/user-guide/docker/execution.md | 53 ++++ docs/user-guide/docker/getting-started.md | 27 ++ docs/user-guide/docker/troubleshooting.md | 59 ++++ docs/user-guide/execution.md | 105 ------- docs/user-guide/introduction.md | 31 +- docs/user-guide/python/execution.md | 170 +++++++++++ .../{ => python}/getting-started.md | 2 +- .../{ => python}/troubleshooting.md | 2 +- mkdocs.yml | 20 +- pyproject.toml | 2 +- 23 files changed, 1278 insertions(+), 220 deletions(-) create mode 100644 docs/css/custom.css create mode 100644 docs/css/termynal.css rename {images => docs/images}/logo.svg (100%) rename {images => docs/images}/screenshot.jpg (100%) create mode 100644 docs/js/custom.js create mode 100644 docs/js/termynal.js delete mode 100644 docs/user-guide/configuration.md create mode 100644 docs/user-guide/docker/execution.md create mode 100644 docs/user-guide/docker/getting-started.md create mode 100644 docs/user-guide/docker/troubleshooting.md delete mode 100644 docs/user-guide/execution.md create mode 100644 docs/user-guide/python/execution.md rename docs/user-guide/{ => python}/getting-started.md (92%) rename docs/user-guide/{ => python}/troubleshooting.md (96%) diff --git a/README.md b/README.md index 36721b5..50794bd 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@
- Logo + Logo

PAN-OS Automation Project

Streamlining Palo Alto Networks Firewall Upgrades with Python Automation @@ -52,28 +52,84 @@ Key Features: > Note: this script is targeted towards standalone and `active-passive` HA environments, no testing has been performed against `active-active` or clustered firewalls. -Example Screenshot +Example Execution -![Example Screenshot](https://github.com/cdot65/pan-os-upgrade/blob/main/images/screenshot.jpg?raw=true) +

+ +```console +pan-os-upgrade --ip-address 192.168.255.211 --username admin --password secret --version 10.2.0-h2 +INFO - βœ… Connection to firewall established +INFO - πŸ“ 007054000123456 houston 192.168.255.211 +INFO - πŸ“ Firewall HA mode: disabled +INFO - πŸ“ Current PAN-OS version: 10.2.0 +INFO - πŸ“ Target PAN-OS version: 10.2.0-h2 +INFO - βœ… Confirmed that moving from 10.2.0 to 10.2.0-h2 is an upgrade +INFO - βœ… Target PAN-OS version 10.2.0-h2 is available for download +INFO - βœ… Base image for 10.2.0-h2 is already downloaded +INFO - πŸš€ Performing test to see if 10.2.0-h2 is already downloaded... +INFO - πŸ” PAN-OS version 10.2.0-h2 is not on the firewall +INFO - πŸš€ PAN-OS version 10.2.0-h2 is beginning download +INFO - Device 007054000123456 downloading version: 10.2.0-h2 +INFO - βš™οΈ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 4 seconds +INFO - βš™οΈ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 36 seconds +INFO - βš™οΈ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 71 seconds +INFO - βœ… 10.2.0-h2 downloaded in 103 seconds +INFO - βœ… PAN-OS version 10.2.0-h2 has been downloaded. +INFO - πŸš€ Performing snapshot of network state information... +INFO - βœ… Network snapshot created successfully +INFO - πŸš€ Performing readiness checks to determine if firewall is ready for upgrade... +INFO - βœ… Passed Readiness Check: Check if there are pending changes on device +INFO - βœ… Passed Readiness Check: No Expired Licenses +INFO - βœ… Passed Readiness Check: Check if a there is enough space on the `/opt/panrepo` volume for downloading an PanOS image. +INFO - βœ… Passed Readiness Check: Check if NTP is synchronized +INFO - βœ… Passed Readiness Check: Check connectivity with the Panorama appliance +INFO - βœ… Readiness Checks completed +INFO - πŸš€ Performing backup of houston's configuration to local filesystem... +INFO - πŸš€ Not a dry run, continue with upgrade... +INFO - πŸš€ Performing upgrade on houston to version 10.2.0-h2... +INFO - πŸš€ Attempting upgrade houston to version 10.2.0-h2 (Attempt 1 of 3)... +INFO - Device 007054000123456 installing version: 10.2.0-h2 +INFO - βœ… houston upgrade completed successfully +INFO - πŸš€ Rebooting the firewall... +INFO - πŸ“ Command succeeded with no output +INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... +INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... +INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... +INFO - βœ… Firewall upgraded and rebooted in 542 seconds +``` + +

(back to top)

## Getting Started -This guide will help you set up the `pan-os-upgrade` library in your environment, especially focusing on users who are new to Python and virtual environments. +There are two primary methods to utilize the `pan-os-upgrade` tool: through a Python virtual environment or via a Docker container. Both methods are outlined below to cater to different preferences or requirements. + +### Running with Python Virtual Environment -### Prerequisites +This approach involves setting up a Python virtual environment on your local machine and running the `pan-os-upgrade` tool within this isolated environment. + +#### Python Prerequisites * Python 3.8 or newer. * Access to a Palo Alto Networks firewall. * An active internet connection to download the package from PyPI. -### Installation +#### Installation The `pan-os-upgrade` library is available on PyPI and can be installed within a Python virtual environment. A virtual environment is a self-contained directory that contains a Python installation for a particular version of Python, plus a number of additional packages. -#### Creating a Python Virtual Environment +##### Creating a Python Virtual Environment The steps below highlight the process for creating, activating, and installing `pan-os-upgrade` into a Python virtual environment. If you're new to Python, it may be beneficial to understand why this is such an important step, [here is a good writeup](https://realpython.com/python-virtual-environments-a-primer/) to prime yourself. @@ -109,11 +165,11 @@ The steps below highlight the process for creating, activating, and installing ` pip install pan-os-upgrade ``` -### Setting Up Your Environment +#### Setting Up Your Environment -After setting up the virtual environment and installing the package, you can configure your environment to use the library. This can be done using command-line arguments or an .env file. +After setting up the virtual environment and installing the package, you can configure your environment to use the library. This can be done using command-line arguments or using the interactive shell. -#### Option 1: Execute `pan-os-upgrade` without Command-Line Arguments +##### Option 1: Execute `pan-os-upgrade` without Command-Line Arguments You can simply get started by issuing `pan-os-upgrade` from your current working directory, you will be guided to input the missing requirement arguments through an interactive shell. @@ -132,7 +188,7 @@ INFO - βœ… Confirmed that moving from 11.0.2 to 11.1.1 is an upgrade ...continue until completed... ``` -#### Option 2: Execute `pan-os-upgrade` Using Command-Line Arguments +##### Option 2: Execute `pan-os-upgrade` Using Command-Line Arguments Alternatively, you can pass these details as command-line arguments when running the script: @@ -148,6 +204,50 @@ pan-os-upgrade --ip-address 192.168.1.1 --username admin --password secret --ver

(back to top)

+### Running with Docker + +Alternatively, you can run `pan-os-upgrade` as a Docker container. This method ensures that the tool runs in an isolated environment with all its dependencies packaged together. + +#### Docker Prerequisites + +* Docker installed on your system. You can download it from [Docker's official site](https://www.docker.com/products/docker-desktop). + +#### Pulling the Docker Image + +First, pull the `pan-os-upgrade` image from GitHub Packages: + +```bash +docker pull ghcr.io/cdot65/pan-os-upgrade:latest +``` + +#### Running the Container + +To run the container and mount local directories for `assurance` and `logs`, use the following commands: + +On macOS and Linux: + +```bash +docker run -v $(pwd)/assurance:/app/assurance -v $(pwd)/logs:/app/logs -it pan-os-upgrade +``` + +On Windows: + +```bash +docker run -v %CD%/assurance:/app/assurance -v %CD%/logs:/app/logs -it pan-os-upgrade +``` + +These commands mount the current directory's `assurance` and `logs` subdirectories to the corresponding directories in the container. If these directories don't exist on your host, Docker will create them. + +#### Interactive Mode + +The container will start in interactive mode, prompting you for the necessary input like IP address, username, password, and target PAN-OS version. + +#### Accessing Logs and Output + +After the container stops, you can find the logs and other output files in the `assurance` and `logs` directories of your current working directory on your host machine. + +

(back to top)

+ ## Usage @@ -255,4 +355,3 @@ Project Link: [https://github.com/cdot65/pan-os-upgrade](https://github.com/cdot [issues-url]: https://github.com/cdot65/pan-os-upgrade/issues [license-shield]: https://img.shields.io/github/license/cdot65/pan-os-upgrade.svg?style=for-the-badge [license-url]: https://github.com/cdot65/pan-os-upgrade/blob/main/LICENSE -[product-screenshot]: https://github.com/cdot65/pan-os-upgrade/blob/main/images/screenshot.jpg diff --git a/docker/Dockerfile b/docker/Dockerfile index 26511c8..0145262 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -14,7 +14,7 @@ WORKDIR /app COPY requirements.txt /app/ # Install any needed packages specified in requirements.txt -# Note: The requirements.txt should contain pan-os-upgrade==0.2.1 +# Note: The requirements.txt should contain pan-os-upgrade==0.2.2 RUN pip install --no-cache-dir -r requirements.txt # Set the locale to avoid issues with emoji rendering diff --git a/docker/requirements.txt b/docker/requirements.txt index cec1633..aa5dd6c 100644 --- a/docker/requirements.txt +++ b/docker/requirements.txt @@ -1 +1 @@ -pan-os-upgrade==0.2.1 \ No newline at end of file +pan-os-upgrade==0.2.2 \ No newline at end of file diff --git a/docs/about/contributing.md b/docs/about/contributing.md index 9aad98a..ec0b522 100644 --- a/docs/about/contributing.md +++ b/docs/about/contributing.md @@ -25,7 +25,7 @@ Before you begin, make sure you have a GitHub account and are familiar with Git git checkout -b feature/YourFeatureName ``` -4. **Set Up the Development Environment:** Follow the [Getting Started](../user-guide/getting-started.md) to set up your local development environment. +4. **Set Up the Development Environment:** Follow the [Getting Started](../user-guide/python/getting-started.md) to set up your local development environment. --- diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 1805613..7abd71b 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -2,6 +2,24 @@ Welcome to the release notes for the `pan-os-upgrade` tool. This document provides a detailed record of changes, enhancements, and fixes in each version of the tool. +## Version 0.2.2 + +**Release Date:** *<20240121>* + +### What's New + +- Optimized for Docker execution. +- Refreshed documentation to showcase both paths of execution (Python virtual environments and Docker) + +## Version 0.2.1 + +**Release Date:** *<20240121>* + +### What's New + +- Adjusting the execution of our script to instead reference the Typer app `app()` instead of `main()`. +- Updated the `pan-os-upgrade` alias within the pyproject.toml file to directly call `app()` instead of `main()` + ## Version 0.2.0 **Release Date:** *<20240121>* diff --git a/docs/css/custom.css b/docs/css/custom.css new file mode 100644 index 0000000..ac95bdd --- /dev/null +++ b/docs/css/custom.css @@ -0,0 +1,186 @@ +.termynal-comment { + color: #4a968f; + font-style: italic; + display: block; +} + +.termy { + /* For right to left languages */ + direction: ltr; +} + +.termy [data-termynal] { + white-space: pre-wrap; +} + +a.external-link { + /* For right to left languages */ + direction: ltr; + display: inline-block; +} + +a.external-link::after { + /* \00A0 is a non-breaking space + to make the mark be on the same line as the link + */ + content: "\00A0[β†ͺ]"; +} + +a.internal-link::after { + /* \00A0 is a non-breaking space + to make the mark be on the same line as the link + */ + content: "\00A0β†ͺ"; +} + +.shadow { + box-shadow: 5px 5px 10px #999; +} + +/* Give space to lower icons so Gitter chat doesn't get on top of them */ +.md-footer-meta { + padding-bottom: 2em; +} + +.user-list { + display: flex; + flex-wrap: wrap; + margin-bottom: 2rem; +} + +.user-list-center { + justify-content: space-evenly; +} + +.user { + margin: 1em; + min-width: 7em; +} + +.user .avatar-wrapper { + width: 80px; + height: 80px; + margin: 10px auto; + overflow: hidden; + border-radius: 50%; + position: relative; +} + +.user .avatar-wrapper img { + position: absolute; + top: 50%; + left: 50%; + transform: translate(-50%, -50%); +} + +.user .title { + text-align: center; +} + +.user .count { + font-size: 80%; + text-align: center; +} + +a.announce-link:link, +a.announce-link:visited { + color: #fff; +} + +a.announce-link:hover { + color: var(--md-accent-fg-color); +} + +.announce-wrapper { + display: flex; + justify-content: space-between; + flex-wrap: wrap; + align-items: center; +} + +.announce-wrapper div.item { + display: none; +} + +.announce-wrapper .sponsor-badge { + display: block; + position: absolute; + top: -10px; + right: 0; + font-size: 0.5rem; + color: #999; + background-color: #666; + border-radius: 10px; + padding: 0 10px; + z-index: 10; +} + +.announce-wrapper .sponsor-image { + display: block; + border-radius: 20px; +} + +.announce-wrapper > div { + min-height: 40px; + display: flex; + align-items: center; +} + +.twitter { + color: #00acee; +} + +/* Right to left languages */ +code { + direction: ltr; + display: inline-block; +} + +.md-content__inner h1 { + direction: ltr !important; +} + +.illustration { + margin-top: 2em; + margin-bottom: 2em; +} + +/* Screenshots */ +/* + Simulate a browser window frame. + Inspired by Termynal's CSS tricks with modifications + */ + +.screenshot { + display: block; + background-color: #d3e0de; + border-radius: 4px; + padding: 45px 5px 5px; + position: relative; + -webkit-box-sizing: border-box; + box-sizing: border-box; +} + +.screenshot img { + display: block; + border-radius: 2px; +} + +.screenshot:before { + content: ""; + position: absolute; + top: 15px; + left: 15px; + display: inline-block; + width: 15px; + height: 15px; + border-radius: 50%; + /* A little hack to display the window buttons in one pseudo element. */ + background: #d9515d; + -webkit-box-shadow: + 25px 0 0 #f4c025, + 50px 0 0 #3ec930; + box-shadow: + 25px 0 0 #f4c025, + 50px 0 0 #3ec930; +} diff --git a/docs/css/termynal.css b/docs/css/termynal.css new file mode 100644 index 0000000..50f81fb --- /dev/null +++ b/docs/css/termynal.css @@ -0,0 +1,113 @@ +/** + * termynal.js + * + * @author Ines Montani + * @version 0.0.1 + * @license MIT + */ + +:root { + --color-bg: #252a33; + --color-text: #eee; + --color-text-subtle: #a2a2a2; +} + +[data-termynal] { + width: 750px; + max-width: 100%; + background: var(--color-bg); + color: var(--color-text); + /* font-size: 18px; */ + font-size: 15px; + /* font-family: 'Fira Mono', Consolas, Menlo, Monaco, 'Courier New', Courier, monospace; */ + font-family: "Roboto Mono", "Fira Mono", Consolas, Menlo, Monaco, + "Courier New", Courier, monospace; + border-radius: 4px; + padding: 75px 45px 35px; + position: relative; + -webkit-box-sizing: border-box; + box-sizing: border-box; +} + +[data-termynal]:before { + content: ""; + position: absolute; + top: 15px; + left: 15px; + display: inline-block; + width: 15px; + height: 15px; + border-radius: 50%; + /* A little hack to display the window buttons in one pseudo element. */ + background: #d9515d; + -webkit-box-shadow: + 25px 0 0 #f4c025, + 50px 0 0 #3ec930; + box-shadow: + 25px 0 0 #f4c025, + 50px 0 0 #3ec930; +} + +[data-termynal]:after { + content: "bash"; + position: absolute; + color: var(--color-text-subtle); + top: 5px; + left: 0; + width: 100%; + text-align: center; +} + +a[data-terminal-control] { + text-align: right; + display: block; + color: #aebbff; +} + +[data-ty] { + display: block; + line-height: 2; +} + +[data-ty]:before { + /* Set up defaults and ensure empty lines are displayed. */ + content: ""; + display: inline-block; + vertical-align: middle; +} + +[data-ty="input"]:before, +[data-ty-prompt]:before { + margin-right: 0.75em; + color: var(--color-text-subtle); +} + +[data-ty="input"]:before { + content: "$"; +} + +[data-ty][data-ty-prompt]:before { + content: attr(data-ty-prompt); +} + +[data-ty-cursor]:after { + content: attr(data-ty-cursor); + font-family: monospace; + margin-left: 0.5em; + -webkit-animation: blink 1s infinite; + animation: blink 1s infinite; +} + +/* Cursor animation */ + +@-webkit-keyframes blink { + 50% { + opacity: 0; + } +} + +@keyframes blink { + 50% { + opacity: 0; + } +} diff --git a/images/logo.svg b/docs/images/logo.svg similarity index 100% rename from images/logo.svg rename to docs/images/logo.svg diff --git a/images/screenshot.jpg b/docs/images/screenshot.jpg similarity index 100% rename from images/screenshot.jpg rename to docs/images/screenshot.jpg diff --git a/docs/index.md b/docs/index.md index ba3c342..0885072 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ --- hide: - - navigation + - navigation ---

- PaloAltoNetworks + PaloAltoNetworks

pan-os-upgrade, a Python CLI tool to help automate the upgrade process for PAN-OS firewalls using Typer @@ -36,42 +36,41 @@ hide: --- -pan-os-upgrade is a modern Python CLI tool that provides a comprehensive automated workflow for PAN-OS firewalls. +pan-os-upgrade is a modern Python CLI tool that provides a comprehensive automated workflow for PAN-OS firewalls. It offers two primary methods of execution: through a Python virtual environment or via a Docker container, catering to various operational requirements and preferences. -The key features of the `pan-os-upgrade` library are: +## Python Virtual Environment Workflow -* **Easy to Use**: Designed with simplicity in mind, the `pan-os-upgrade` script offers an intuitive interface, minimizing the need for extensive documentation perusal. Users can quickly learn to use the tool, saving valuable time and effort. +This approach involves setting up a Python virtual environment and running `pan-os-upgrade` within this isolated environment, ensuring compatibility and preventing any conflicts with system-wide Python installations. -* **Resilient**: Built with robust error handling and recovery mechanisms, the script can gracefully manage various nuances and mechanical intricacies of firewall upgrades. This resilience ensures reliable operations even in complex network environments. +### Python Key Features -* **Robust Workflow Coverage**: Capable of handling a wide range of upgrade workflows, the script is adaptable to different network configurations and requirements. This flexibility makes it suitable for various scenarios, from standalone setups to complex HA environments. +- Easy and isolated Python environment setup. +- Full control over the Python version and dependencies. +- Ideal for users familiar with Python and virtual environments. -* **Strong Typing**: Employing Python’s strong typing features, the script enhances code clarity and reduces the likelihood of type-related bugs. This approach contributes to the overall stability and reliability of the upgrade process. +### Python Getting Started -* **Data Modeling with Pydantic**: Utilizing Pydantic for data validation, the `pan-os-upgrade` script ensures that input and output data are accurately modeled. This feature significantly reduces bugs and enhances the predictability of operations, leading to smoother upgrade experiences. +Install `pan-os-upgrade` via pip in a Python virtual environment and configure it using command-line arguments or an interactive shell. Detailed instructions can be found in the [User Guide](user-guide/python/getting-started.md). -## Requirements +## Docker Container Workflow -Python 3.8+ +Running `pan-os-upgrade` in a Docker container encapsulates the tool and its dependencies in an isolated environment, simplifying setup and ensuring consistency across different systems. -`pan-os-upgrade` stands on the shoulders of giants: +### Docker Key Features -* pan-os-python for handling all interactions with PAN-OS firewalls. -* panos-upgrade-assurance for performing Readiness Checks, Snapshots, Health Checks, and Reporting. -* Pydantic for handling the data modeling and validation. -* Typer for handling the data modeling and validation. +- Simplified setup process with Docker. +- Consistent runtime environment regardless of the host system. +- Suitable for users who prefer Docker or require containerized environments. -## Installation +### Docker Getting Started -

+Pull the `pan-os-upgrade` Docker image, run the container with mounted directories for outputs, and interact with the tool in an isolated environment. More information is available in the [User Guide](user-guide/docker/getting-started.md). -```console -$ pip install pan-os-upgrade +--- ----> 100% -``` +Visit the [User Guide](user-guide/introduction.md) for detailed insights into setting up and running `pan-os-upgrade` using either Python or Docker workflows. -
+--- ## Example @@ -129,20 +128,18 @@ INFO - βœ… Firewall upgraded and rebooted in 343 seconds
-## Next Steps +For more examples and usage scenarios, refer to the [Documentation](https://cdot65.github.io/pan-os-upgrade/). -### Getting Started - -Visit the [User Guide](user-guide/introduction.md) for detailed insights into getting up and running. +--- -### API Documentation +### Release Notes -Visit the [Developer Documentation](reference/pan_os_upgrade.md) reference page for detailed documentation on the library's code. +Updates with each release are tracked at [Release Notes](about/release-notes.md). ### Contributing -Visit the [Contributing](about/contributing.md) page to understand how you can contribute to the project. +Contributions are welcome and greatly appreciated. Visit the [Contributing](about/contributing.md) page for guidelines on how to contribute. ### License -Visit the [License](about/license.md) for information about the project's licensing. +This project is licensed under the Apache 2.0 License - see the [License](about/license.md) page for details. diff --git a/docs/js/custom.js b/docs/js/custom.js new file mode 100644 index 0000000..f6da9f0 --- /dev/null +++ b/docs/js/custom.js @@ -0,0 +1,188 @@ +const div = document.querySelector(".github-topic-projects"); + +async function getDataBatch(page) { + const response = await fetch( + `https://api.github.com/search/repositories?q=topic:pan-os-upgrade&per_page=100&page=${page}`, + { headers: { Accept: "application/vnd.github.mercy-preview+json" } }, + ); + const data = await response.json(); + return data; +} + +async function getData() { + let page = 1; + let data = []; + let dataBatch = await getDataBatch(page); + data = data.concat(dataBatch.items); + const totalCount = dataBatch.total_count; + while (data.length < totalCount) { + page += 1; + dataBatch = await getDataBatch(page); + data = data.concat(dataBatch.items); + } + return data; +} + +function setupTermynal() { + document.querySelectorAll(".use-termynal").forEach((node) => { + node.style.display = "block"; + new Termynal(node, { + lineDelay: 500, + }); + }); + const progressLiteralStart = "---> 100%"; + const promptLiteralStart = "$ "; + const customPromptLiteralStart = "# "; + const termynalActivateClass = "termy"; + let termynals = []; + + function createTermynals() { + document + .querySelectorAll(`.${termynalActivateClass} .highlight`) + .forEach((node) => { + const text = node.textContent; + const lines = text.split("\n"); + const useLines = []; + let buffer = []; + function saveBuffer() { + if (buffer.length) { + let isBlankSpace = true; + buffer.forEach((line) => { + if (line) { + isBlankSpace = false; + } + }); + dataValue = {}; + if (isBlankSpace) { + dataValue["delay"] = 0; + } + if (buffer[buffer.length - 1] === "") { + // A last single
won't have effect + // so put an additional one + buffer.push(""); + } + const bufferValue = buffer.join("
"); + dataValue["value"] = bufferValue; + useLines.push(dataValue); + buffer = []; + } + } + for (let line of lines) { + if (line === progressLiteralStart) { + saveBuffer(); + useLines.push({ + type: "progress", + }); + } else if (line.startsWith(promptLiteralStart)) { + saveBuffer(); + const value = line.replace(promptLiteralStart, "").trimEnd(); + useLines.push({ + type: "input", + value: value, + }); + } else if (line.startsWith("// ")) { + saveBuffer(); + const value = "πŸ’¬ " + line.replace("// ", "").trimEnd(); + useLines.push({ + value: value, + class: "termynal-comment", + delay: 0, + }); + } else if (line.startsWith(customPromptLiteralStart)) { + saveBuffer(); + const promptStart = line.indexOf(promptLiteralStart); + if (promptStart === -1) { + console.error("Custom prompt found but no end delimiter", line); + } + const prompt = line + .slice(0, promptStart) + .replace(customPromptLiteralStart, ""); + let value = line.slice(promptStart + promptLiteralStart.length); + useLines.push({ + type: "input", + value: value, + prompt: prompt, + }); + } else { + buffer.push(line); + } + } + saveBuffer(); + const div = document.createElement("div"); + node.replaceWith(div); + const termynal = new Termynal(div, { + lineData: useLines, + noInit: true, + lineDelay: 500, + }); + termynals.push(termynal); + }); + } + + function loadVisibleTermynals() { + termynals = termynals.filter((termynal) => { + if (termynal.container.getBoundingClientRect().top - innerHeight <= 0) { + termynal.init(); + return false; + } + return true; + }); + } + window.addEventListener("scroll", loadVisibleTermynals); + createTermynals(); + loadVisibleTermynals(); +} + +function shuffle(array) { + var currentIndex = array.length, + temporaryValue, + randomIndex; + while (0 !== currentIndex) { + randomIndex = Math.floor(Math.random() * currentIndex); + currentIndex -= 1; + temporaryValue = array[currentIndex]; + array[currentIndex] = array[randomIndex]; + array[randomIndex] = temporaryValue; + } + return array; +} + +async function showRandomAnnouncement(groupId, timeInterval) { + const announcePanOsUpgrade = document.getElementById(groupId); + if (announcePanOsUpgrade) { + let children = [].slice.call(announcePanOsUpgrade.children); + children = shuffle(children); + let index = 0; + const announceRandom = () => { + children.forEach((el, i) => { + el.style.display = "none"; + }); + children[index].style.display = "block"; + index = (index + 1) % children.length; + }; + announceRandom(); + setInterval(announceRandom, timeInterval); + } +} + +async function main() { + if (div) { + data = await getData(); + div.innerHTML = ""; + const ul = document.querySelector(".github-topic-projects ul"); + data.forEach((v) => { + if (v.full_name === "cdot65/pan-os-upgrade") { + return; + } + const li = document.createElement("li"); + li.innerHTML = `β˜… ${v.stargazers_count} - ${v.full_name} by @${v.owner.login}`; + ul.append(li); + }); + } + + setupTermynal(); + showRandomAnnouncement("announce-left", 5000); + showRandomAnnouncement("announce-right", 10000); +} + +main(); diff --git a/docs/js/termynal.js b/docs/js/termynal.js new file mode 100644 index 0000000..c74e6dd --- /dev/null +++ b/docs/js/termynal.js @@ -0,0 +1,283 @@ +/** + * termynal.js + * A lightweight, modern and extensible animated terminal window, using + * async/await. + * + * @author Ines Montani + * @version 0.0.1 + * @license MIT + */ + +"use strict"; + +/** Generate a terminal widget. */ +class Termynal { + /** + * Construct the widget's settings. + * @param {(string|Node)=} container - Query selector or container element. + * @param {Object=} options - Custom settings. + * @param {string} options.prefix - Prefix to use for data attributes. + * @param {number} options.startDelay - Delay before animation, in ms. + * @param {number} options.typeDelay - Delay between each typed character, in ms. + * @param {number} options.lineDelay - Delay between each line, in ms. + * @param {number} options.progressLength - Number of characters displayed as progress bar. + * @param {string} options.progressChar – Character to use for progress bar, defaults to β–ˆ. + * @param {number} options.progressPercent - Max percent of progress. + * @param {string} options.cursor – Character to use for cursor, defaults to β–‹. + * @param {Object[]} lineData - Dynamically loaded line data objects. + * @param {boolean} options.noInit - Don't initialise the animation. + */ + constructor(container = "#termynal", options = {}) { + this.container = + typeof container === "string" + ? document.querySelector(container) + : container; + this.pfx = `data-${options.prefix || "ty"}`; + this.originalStartDelay = this.startDelay = + options.startDelay || + parseFloat(this.container.getAttribute(`${this.pfx}-startDelay`)) || + 600; + this.originalTypeDelay = this.typeDelay = + options.typeDelay || + parseFloat(this.container.getAttribute(`${this.pfx}-typeDelay`)) || + 90; + this.originalLineDelay = this.lineDelay = + options.lineDelay || + parseFloat(this.container.getAttribute(`${this.pfx}-lineDelay`)) || + 1500; + this.progressLength = + options.progressLength || + parseFloat(this.container.getAttribute(`${this.pfx}-progressLength`)) || + 40; + this.progressChar = + options.progressChar || + this.container.getAttribute(`${this.pfx}-progressChar`) || + "β–ˆ"; + this.progressPercent = + options.progressPercent || + parseFloat(this.container.getAttribute(`${this.pfx}-progressPercent`)) || + 100; + this.cursor = + options.cursor || + this.container.getAttribute(`${this.pfx}-cursor`) || + "β–‹"; + this.lineData = this.lineDataToElements(options.lineData || []); + this.loadLines(); + if (!options.noInit) this.init(); + } + + loadLines() { + // Load all the lines and create the container so that the size is fixed + // Otherwise it would be changing and the user viewport would be constantly + // moving as she/he scrolls + const finish = this.generateFinish(); + finish.style.visibility = "hidden"; + this.container.appendChild(finish); + // Appends dynamically loaded lines to existing line elements. + this.lines = [...this.container.querySelectorAll(`[${this.pfx}]`)].concat( + this.lineData, + ); + for (let line of this.lines) { + line.style.visibility = "hidden"; + this.container.appendChild(line); + } + const restart = this.generateRestart(); + restart.style.visibility = "hidden"; + this.container.appendChild(restart); + this.container.setAttribute("data-termynal", ""); + } + + /** + * Initialise the widget, get lines, clear container and start animation. + */ + init() { + /** + * Calculates width and height of Termynal container. + * If container is empty and lines are dynamically loaded, defaults to browser `auto` or CSS. + */ + const containerStyle = getComputedStyle(this.container); + this.container.style.width = + containerStyle.width !== "0px" ? containerStyle.width : undefined; + this.container.style.minHeight = + containerStyle.height !== "0px" ? containerStyle.height : undefined; + + this.container.setAttribute("data-termynal", ""); + this.container.innerHTML = ""; + for (let line of this.lines) { + line.style.visibility = "visible"; + } + this.start(); + } + + /** + * Start the animation and rener the lines depending on their data attributes. + */ + async start() { + this.addFinish(); + await this._wait(this.startDelay); + + for (let line of this.lines) { + const type = line.getAttribute(this.pfx); + const delay = line.getAttribute(`${this.pfx}-delay`) || this.lineDelay; + + if (type == "input") { + line.setAttribute(`${this.pfx}-cursor`, this.cursor); + await this.type(line); + await this._wait(delay); + } else if (type == "progress") { + await this.progress(line); + await this._wait(delay); + } else { + this.container.appendChild(line); + await this._wait(delay); + } + + line.removeAttribute(`${this.pfx}-cursor`); + } + this.addRestart(); + this.finishElement.style.visibility = "hidden"; + this.lineDelay = this.originalLineDelay; + this.typeDelay = this.originalTypeDelay; + this.startDelay = this.originalStartDelay; + } + + generateRestart() { + const restart = document.createElement("a"); + restart.onclick = (e) => { + e.preventDefault(); + this.container.innerHTML = ""; + this.init(); + }; + restart.href = "#"; + restart.setAttribute("data-terminal-control", ""); + restart.innerHTML = "restart ↻"; + return restart; + } + + generateFinish() { + const finish = document.createElement("a"); + finish.onclick = (e) => { + e.preventDefault(); + this.lineDelay = 0; + this.typeDelay = 0; + this.startDelay = 0; + }; + finish.href = "#"; + finish.setAttribute("data-terminal-control", ""); + finish.innerHTML = "fast β†’"; + this.finishElement = finish; + return finish; + } + + addRestart() { + const restart = this.generateRestart(); + this.container.appendChild(restart); + } + + addFinish() { + const finish = this.generateFinish(); + this.container.appendChild(finish); + } + + /** + * Animate a typed line. + * @param {Node} line - The line element to render. + */ + async type(line) { + const chars = [...line.textContent]; + line.textContent = ""; + this.container.appendChild(line); + + for (let char of chars) { + const delay = + line.getAttribute(`${this.pfx}-typeDelay`) || this.typeDelay; + await this._wait(delay); + line.textContent += char; + } + } + + /** + * Animate a progress bar. + * @param {Node} line - The line element to render. + */ + async progress(line) { + const progressLength = + line.getAttribute(`${this.pfx}-progressLength`) || this.progressLength; + const progressChar = + line.getAttribute(`${this.pfx}-progressChar`) || this.progressChar; + const chars = progressChar.repeat(progressLength); + const progressPercent = + line.getAttribute(`${this.pfx}-progressPercent`) || this.progressPercent; + line.textContent = ""; + this.container.appendChild(line); + + for (let i = 1; i < chars.length + 1; i++) { + await this._wait(this.typeDelay); + const percent = Math.round((i / chars.length) * 100); + line.textContent = `${chars.slice(0, i)} ${percent}%`; + if (percent > progressPercent) { + break; + } + } + } + + /** + * Helper function for animation delays, called with `await`. + * @param {number} time - Timeout, in ms. + */ + _wait(time) { + return new Promise((resolve) => setTimeout(resolve, time)); + } + + /** + * Converts line data objects into line elements. + * + * @param {Object[]} lineData - Dynamically loaded lines. + * @param {Object} line - Line data object. + * @returns {Element[]} - Array of line elements. + */ + lineDataToElements(lineData) { + return lineData.map((line) => { + let div = document.createElement("div"); + div.innerHTML = `${ + line.value || "" + }`; + + return div.firstElementChild; + }); + } + + /** + * Helper function for generating attributes string. + * + * @param {Object} line - Line data object. + * @returns {string} - String of attributes. + */ + _attributes(line) { + let attrs = ""; + for (let prop in line) { + // Custom add class + if (prop === "class") { + attrs += ` class=${line[prop]} `; + continue; + } + if (prop === "type") { + attrs += `${this.pfx}="${line[prop]}" `; + } else if (prop !== "value") { + attrs += `${this.pfx}-${prop}="${line[prop]}" `; + } + } + + return attrs; + } +} + +/** + * HTML API: If current script has container(s) specified, initialise Termynal. + */ +if (document.currentScript.hasAttribute("data-termynal-container")) { + const containers = document.currentScript.getAttribute( + "data-termynal-container", + ); + containers.split("|").forEach((container) => new Termynal(container)); +} diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md deleted file mode 100644 index 64b9992..0000000 --- a/docs/user-guide/configuration.md +++ /dev/null @@ -1,51 +0,0 @@ -# Configuration Guide for pan-os-upgrade - -Proper configuration is vital for the effective use of the `pan-os-upgrade` package. As of the latest update, configuration can be done primarily through command-line arguments. - -## Executing `pan-os-upgrade` - -### Option 1: Execute Without Command-Line Arguments - -You can start the script by simply issuing `pan-os-upgrade` from your current working directory. The interactive shell will prompt you to input the required arguments. - -```bash -$ pan-os-upgrade -IP address: 192.168.255.1 -Username: admin -Password: -Target PAN-OS version: 11.1.1 -...output... -``` - -### Option 2: Execute Using Command-Line Arguments - -Alternatively, you can pass these details as command-line arguments: - -```bash -$ pan-os-upgrade --ip-address 192.168.1.1 --username admin --password secret --version 10.1.0 -``` - -For a dry run: - -```bash -$ pan-os-upgrade --ip-address 192.168.1.1 --username admin --password secret --version 10.1.0 --dry-run -``` - -## CLI Arguments Description - -When using command-line arguments, the following options are available: - -| Argument | Description | Required | -| -------------- | -------------------------------------------------------------------- | -------- | -| `--ip-address` | IP address of the target PAN-OS firewall. | Yes | -| `--username` | Username for authentication with the firewall. | Yes | -| `--password` | Password for authentication with the firewall. | Yes | -| `--version` | Target PAN-OS version to upgrade to. | Yes | -| `--dry-run` | Perform a dry run of all tests and downloads without actual upgrade. | No | -| `--log-level` | Set the logging output level (e.g., debug, info, warning). | No | - -Note: The use of an API key and `.env` file for configuration is no longer supported. - -## Next Steps - -After configuring `pan-os-upgrade`, you're ready to execute the upgrade process. For more details on execution steps and options, proceed to the [Execution Guide](execution.md). diff --git a/docs/user-guide/docker/execution.md b/docs/user-guide/docker/execution.md new file mode 100644 index 0000000..918f20f --- /dev/null +++ b/docs/user-guide/docker/execution.md @@ -0,0 +1,53 @@ +# Docker Execution for pan-os-upgrade + +The `pan-os-upgrade` tool can be conveniently run using Docker, offering a consistent and streamlined setup process across different systems. This guide will walk you through configuring and executing the tool within a Docker container. + +## Pulling the Docker Image + +If you haven't already done so, start off by pulling the `pan-os-upgrade` Docker image from GitHub Packages: + +```bash +docker pull ghcr.io/cdot65/pan-os-upgrade:latest +``` + +## Setting Up the Docker Environment + +Before executing the tool, ensure your Docker environment is correctly set up. + +### Directory Setup + +Create `assurance` and `logs` directories in your working directory to store outputs and logs: + +```bash +mkdir assurance logs +``` + +### Running the Docker Container + +Run `pan-os-upgrade` in Docker using the following commands: + +#### On macOS and Linux + +```bash +docker run -v $(pwd)/assurance:/app/assurance -v $(pwd)/logs:/app/logs -it ghcr.io/cdot65/pan-os-upgrade:latest +``` + +This mounts your host's `assurance` and `logs` directories to the container. + +#### On Windows + +```bash +docker run -v %CD%/assurance:/app/assurance -v %CD%/logs:/app/logs -it ghcr.io/cdot65/pan-os-upgrade:latest +``` + +## Interacting with the Docker Container + +The container runs interactively, prompting you for details like IP address, username, password, and target PAN-OS version. + +## Output and Logs + +After running the container, you'll find all necessary outputs and logs in the `assurance` and `logs` directories on your host machine. + +## Next Steps + +With `pan-os-upgrade` successfully executed using Docker, check the outputs and logs for insights into the upgrade process. For further assistance or troubleshooting, refer to the [Troubleshooting Guide](troubleshooting.md). diff --git a/docs/user-guide/docker/getting-started.md b/docs/user-guide/docker/getting-started.md new file mode 100644 index 0000000..430b8ba --- /dev/null +++ b/docs/user-guide/docker/getting-started.md @@ -0,0 +1,27 @@ +# Getting Started with pan-os-upgrade using Docker + +Welcome to the Docker-based workflow of the `pan-os-upgrade` library! This guide will help you set up and use the `pan-os-upgrade` tool within a Docker container. This approach is ideal for users who prefer a containerized environment or who are not as familiar with Python environments. + +## Prerequisites + +Before starting, make sure you have: + +- Docker installed on your system. Visit the [Docker installation guide](https://docs.docker.com/get-docker/) for instructions. +- Access to a Palo Alto Networks firewall. +- An active internet connection for pulling the Docker image. + +## Pulling the Docker Image + +The `pan-os-upgrade` Docker image is hosted on GitHub Packages. Pull the image using the following command: + +```bash +docker pull ghcr.io/cdot65/pan-os-upgrade:latest +``` + +## Building the Docker Image + +As an alternative, if you would like to build the container yourself then simply navigate to the `docker` directory in the root of the repository. From there you can modify the Dockerfile to your liking and build your own custom image. + +## Next Steps + +With the Docker container set up and ready, you can begin using the `pan-os-upgrade` tool to automate PAN-OS upgrades. For detailed configuration instructions, proceed to the [Docker Execution Guide](execution.md). diff --git a/docs/user-guide/docker/troubleshooting.md b/docs/user-guide/docker/troubleshooting.md new file mode 100644 index 0000000..91a2354 --- /dev/null +++ b/docs/user-guide/docker/troubleshooting.md @@ -0,0 +1,59 @@ +# Troubleshooting Guide for Docker Execution of pan-os-upgrade + +Encountering issues during the Docker execution of `pan-os-upgrade` can happen, especially when dealing with different system environments. This guide aims to address common problems and their solutions. + +## Common Issues and Solutions + +### 1. Docker Image Not Found + +**Problem:** Unable to find or pull the `pan-os-upgrade` Docker image. + +**Solution:** Ensure you have a stable internet connection and access to GitHub Packages. Verify the image name: `ghcr.io/cdot65/pan-os-upgrade:latest`. + +**Alternative:** You can build your own image by navigating to the `docker/` directory in the repository and running the standard `docker build` process. + +### 2. Volume Mount Issues + +**Problem:** Errors related to mounting volumes for `assurance` and `logs` directories. + +**Solution:** Ensure the directories exist on your host machine. Check your Docker run command for typos. For Windows, replace `$(pwd)` with `%CD%`. + +### 3. Interactive Shell Not Responding + +**Problem:** The interactive shell within the Docker container does not accept input. + +**Solution:** Ensure the container is running in interactive mode (`-it` flag). Try restarting the Docker service. + +### 4. No Output in Mounted Directories + +**Problem:** The `assurance` and `logs` directories on the host are empty after container execution. + +**Solution:** Verify the Docker run command for correct volume mounting syntax. Ensure the container has the necessary permissions to write to these directories. + +### 5. Docker Container Exits Unexpectedly + +**Problem:** The Docker container stops running prematurely. + +**Solution:** Check the Docker container logs for any error messages. Ensure the container has sufficient resources (memory, CPU). + +### 6. Network Connectivity Issues + +**Problem:** The script within the Docker container cannot connect to the PAN-OS device. + +**Solution:** Verify network settings and ensure the Docker container has network access. Check firewall settings and IP address. + +### 7. Docker Version Compatibility + +**Problem:** Issues running `pan-os-upgrade` due to Docker version incompatibility. + +**Solution:** Ensure you are using a compatible version of Docker. Update Docker to the latest version if necessary. + +## General Tips + +- Always verify your Docker setup and configurations before running `pan-os-upgrade`. +- For complex Docker setups, consider simplifying or breaking down the execution process to isolate issues. +- Regularly update your Docker images to get the latest version of `pan-os-upgrade`. + +## Reporting Issues + +If you encounter a problem not covered in this guide, please report it on the [GitHub issues page](https://github.com/cdot65/pan-os-upgrade/issues) of `pan-os-upgrade`. Include detailed information, such as the Docker version, system environment, and any relevant logs or error messages. diff --git a/docs/user-guide/execution.md b/docs/user-guide/execution.md deleted file mode 100644 index 13e1a96..0000000 --- a/docs/user-guide/execution.md +++ /dev/null @@ -1,105 +0,0 @@ -# Execution Guide for pan-os-upgrade - -The `pan-os-upgrade` tool automates the entire process of upgrading PAN-OS firewalls. This guide will walk you through the execution steps, detailing how to use the script with the latest configuration options, and what to expect in terms of output and logging. - -## Execution Options - -You can execute `pan-os-upgrade` using command-line arguments to provide configuration details directly. - -### Using Command-Line Arguments - -Execute the script by passing the configuration details as command-line arguments: - -
- -```console -$ pan-os-upgrade --ip-address 192.168.1.1 --username admin --password secret --version 10.1.0 -``` - -
- -Replace `192.168.1.1`, `admin`, `secret`, and `10.1.0` with your firewall's details and the desired PAN-OS version. - -For a dry run: - -```console -$ pan-os-upgrade --ip-address 192.168.1.1 --username admin --password secret --version 10.1.0 --dry-run -``` - -## Output - -
- -```console -pan-os-upgrade --ip-address 192.168.255.211 --username admin --password secret --version 10.2.0-h2 -INFO - βœ… Connection to firewall established -INFO - πŸ“ 007054000123456 houston 192.168.255.211 -INFO - πŸ“ Firewall HA mode: disabled -INFO - πŸ“ Current PAN-OS version: 10.2.0 -INFO - πŸ“ Target PAN-OS version: 10.2.0-h2 -INFO - βœ… Confirmed that moving from 10.2.0 to 10.2.0-h2 is an upgrade -INFO - βœ… Target PAN-OS version 10.2.0-h2 is available for download -INFO - βœ… Base image for 10.2.0-h2 is already downloaded -INFO - πŸš€ Performing test to see if 10.2.0-h2 is already downloaded... -INFO - πŸ” PAN-OS version 10.2.0-h2 is not on the firewall -INFO - πŸš€ PAN-OS version 10.2.0-h2 is beginning download -INFO - Device 007054000123456 downloading version: 10.2.0-h2 -INFO - βš™οΈ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 4 seconds -INFO - βš™οΈ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 36 seconds -INFO - βš™οΈ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 71 seconds -INFO - βœ… 10.2.0-h2 downloaded in 103 seconds -INFO - βœ… PAN-OS version 10.2.0-h2 has been downloaded. -INFO - πŸš€ Performing snapshot of network state information... -INFO - βœ… Network snapshot created successfully -INFO - πŸš€ Performing readiness checks to determine if firewall is ready for upgrade... -INFO - βœ… Passed Readiness Check: Check if there are pending changes on device -INFO - βœ… Passed Readiness Check: No Expired Licenses -INFO - βœ… Passed Readiness Check: Check if a there is enough space on the `/opt/panrepo` volume for downloading an PanOS image. -INFO - βœ… Passed Readiness Check: Check if NTP is synchronized -INFO - βœ… Passed Readiness Check: Check connectivity with the Panorama appliance -INFO - βœ… Readiness Checks completed -INFO - πŸš€ Performing backup of houston's configuration to local filesystem... -INFO - πŸš€ Not a dry run, continue with upgrade... -INFO - πŸš€ Performing upgrade on houston to version 10.2.0-h2... -INFO - πŸš€ Attempting upgrade houston to version 10.2.0-h2 (Attempt 1 of 3)... -INFO - Device 007054000123456 installing version: 10.2.0-h2 -INFO - βœ… houston upgrade completed successfully -INFO - πŸš€ Rebooting the firewall... -INFO - πŸ“ Command succeeded with no output -INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... -INFO - βš™οΈ Firewall is rebooting... -INFO - βš™οΈ Firewall is rebooting... -INFO - βš™οΈ Firewall is rebooting... -INFO - βš™οΈ Firewall is rebooting... -INFO - βš™οΈ Firewall is rebooting... -INFO - βš™οΈ Firewall is rebooting... -INFO - βš™οΈ Firewall is rebooting... -INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... -INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... -INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... -INFO - βœ… Firewall upgraded and rebooted in 542 seconds -``` - -
- -This output will include detailed logs of the process, such as establishing a connection, checking versions, performing upgrades, and rebooting the firewall. - -## Assurance Functions - -The script performs various assurance functions like readiness checks, snapshots, and configuration backups. These are stored in the `assurance/` directory, structured as follows: - -- `snapshots/`: Contains pre and post-upgrade network state snapshots in JSON format. -- `readiness_checks/`: Holds results of readiness checks in JSON format. -- `configurations/`: Stores backups of the firewall's configuration in XML format. - -## Log Files - -Log entries are recorded in the `logs/` directory. The script maintains a detailed log file that includes every step of the execution process. This is particularly useful for troubleshooting and review. - -### Log Levels - -You can control the verbosity of logs with the `--log-level` argument. Available options are `debug`, `info`, `warning`, `error`, and `critical`. The default level is `info`. - -## Next Steps - -After familiarizing yourself with the execution process and output, proceed to the [Troubleshooting Guide](troubleshooting.md) of the user guide for detailed insights into troubleshooting and advanced tips. diff --git a/docs/user-guide/introduction.md b/docs/user-guide/introduction.md index f97b53c..bdcab18 100644 --- a/docs/user-guide/introduction.md +++ b/docs/user-guide/introduction.md @@ -2,28 +2,39 @@ ## Purpose of the Project -The `pan-os-upgrade` CLI tool is designed to streamline and simplify the process of upgrading Palo Alto Networks firewalls. Upgrading firewalls is not only challenging but also a tedious task fraught with potential complications. This tool aims to assist firewall administrators through this complex process by automating several critical steps. +The `pan-os-upgrade` CLI tool is designed to streamline and simplify the process of upgrading Palo Alto Networks firewalls. This tool offers two distinct workflows to cater to different user preferences and environments: a Python-based workflow and a Docker-based workflow. ## Problem Statement -Firewall upgrades can be intricate and tedious, with numerous issues that might arise from a variety of situations. The `pan-os-upgrade` tool addresses these challenges by: +Upgrading firewalls can be intricate and tedious, posing numerous challenges. The `pan-os-upgrade` tool addresses these by: - Performing a series of readiness checks. - Taking snapshots of the current network state. - Creating backups of the configuration before initiating the upgrade process. -These steps ensure a smoother and more reliable upgrade process, mitigating the risks associated with manual upgrades. +## Two Distinct Workflows -## Key Features +### Python Workflow -The tool is built with several key features to enhance its efficiency and reliability: +This workflow is ideal for those who prefer working within a Python environment. It involves setting up a Python virtual environment, installing dependencies, and executing the tool via command-line interface. -- **Leveraging `panos-upgrade-assurance`**: `pan-os-upgrade` utilizes the `panos-upgrade-assurance` library to manage the more complex aspects of the upgrade process. This includes pre and post-validation of the firewall's state, ensuring the integrity of the network environment, such as routing tables, ARP tables, and network interface statuses. +- **Advantages**: Offers more control and flexibility, especially for users familiar with Python. +- **Details**: See the [Python Workflow Getting Started Guide](python/getting-started.md) for detailed instructions on setup and usage. -- **Data Validation with Pydantic**: To minimize bugs and ensure smooth workflow execution, `pan-os-upgrade` incorporates Pydantic for robust data structure validation. This feature plays a crucial role in handling the input and output of data within the automation scripts, reducing instances of errors and enhancing the script's reliability. +### Docker Workflow -## Next Steps +The Docker workflow simplifies the setup by encapsulating the tool and its dependencies within a Docker container. It's suitable for users seeking an easy-to-deploy solution without configuring a Python environment. + +- **Advantages**: Ensures consistent runtime environment, simplifies deployment, and is ideal for users not familiar with Python. +- **Details**: Refer to the [Docker Workflow Getting Started Guide](docker/getting-started.md) for comprehensive steps on using the Docker container. + +## Key Features + +`pan-os-upgrade` is equipped with several features for efficient and reliable upgrades: -Now that you have an overview of the `pan-os-upgrade` tool and its capabilities, the next step is to get started with setting up and using the tool. The following guide will walk you through the initial setup and basic usage. +- **Leveraging `panos-upgrade-assurance`**: It utilizes the `panos-upgrade-assurance` library to manage complex aspects of the upgrade process. +- **Data Validation with Pydantic**: Ensures robust data structure validation, minimizing bugs and streamlining workflow execution. + +## Next Steps -Continue to the [Getting Started](getting-started.md) guide to begin using `pan-os-upgrade`. +With an understanding of `pan-os-upgrade` and its dual workflows, you can choose the approach that best suits your needs. Follow the respective guides to set up and start using the tool for upgrading your Palo Alto Networks firewalls. diff --git a/docs/user-guide/python/execution.md b/docs/user-guide/python/execution.md new file mode 100644 index 0000000..dee6c35 --- /dev/null +++ b/docs/user-guide/python/execution.md @@ -0,0 +1,170 @@ +# Python Setup and Execution Guide for pan-os-upgrade + +This guide provides comprehensive steps for configuring and executing the `pan-os-upgrade` package within a Python environment. It details both command-line execution and interactive setup methods. + +## Configuring and Executing `pan-os-upgrade` + +### Executing Without Command-Line Arguments + +You can start the script by simply issuing `pan-os-upgrade` from your current working directory. The interactive shell will prompt you to input the required arguments: + +
+ +```console +$ pan-os-upgrade +IP address: 192.168.255.1 +Username: admin +Password: +Target PAN-OS version: 11.1.1 +INFO - βœ… Connection to firewall established +INFO - πŸ“ 007054000123456 houston 192.168.255.211 +INFO - πŸ“ Firewall HA mode: disabled +INFO - πŸ“ Current PAN-OS version: 10.2.0 +INFO - πŸ“ Target PAN-OS version: 10.2.0-h2 +INFO - βœ… Confirmed that moving from 10.2.0 to 10.2.0-h2 is an upgrade +INFO - βœ… Target PAN-OS version 10.2.0-h2 is available for download +INFO - βœ… Base image for 10.2.0-h2 is already downloaded +INFO - πŸš€ Performing test to see if 10.2.0-h2 is already downloaded... +INFO - πŸ” PAN-OS version 10.2.0-h2 is not on the firewall +INFO - πŸš€ PAN-OS version 10.2.0-h2 is beginning download +INFO - Device 007054000123456 downloading version: 10.2.0-h2 +INFO - βš™οΈ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 4 seconds +INFO - βš™οΈ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 36 seconds +INFO - βš™οΈ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 71 seconds +INFO - βœ… 10.2.0-h2 downloaded in 103 seconds +INFO - βœ… PAN-OS version 10.2.0-h2 has been downloaded. +INFO - πŸš€ Performing snapshot of network state information... +INFO - βœ… Network snapshot created successfully +INFO - πŸš€ Performing readiness checks to determine if firewall is ready for upgrade... +INFO - βœ… Passed Readiness Check: Check if there are pending changes on device +INFO - βœ… Passed Readiness Check: No Expired Licenses +INFO - βœ… Passed Readiness Check: Check if a there is enough space on the `/opt/panrepo` volume for downloading an PanOS image. +INFO - βœ… Passed Readiness Check: Check if NTP is synchronized +INFO - βœ… Passed Readiness Check: Check connectivity with the Panorama appliance +INFO - βœ… Readiness Checks completed +INFO - πŸš€ Performing backup of houston's configuration to local filesystem... +INFO - πŸš€ Not a dry run, continue with upgrade... +INFO - πŸš€ Performing upgrade on houston to version 10.2.0-h2... +INFO - πŸš€ Attempting upgrade houston to version 10.2.0-h2 (Attempt 1 of 3)... +INFO - Device 007054000123456 installing version: 10.2.0-h2 +INFO - βœ… houston upgrade completed successfully +INFO - πŸš€ Rebooting the firewall... +INFO - πŸ“ Command succeeded with no output +INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... +INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... +INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... +INFO - βœ… Firewall upgraded and rebooted in 542 seconds +``` + +
+ +### Executing Using Command-Line Arguments + +Alternatively, you can pass these details as command-line arguments: + +```bash +$ pan-os-upgrade --ip-address 192.168.1.1 --username admin --password secret --version 10.1.0 +``` + +
+ +```console +pan-os-upgrade --ip-address 192.168.255.211 --username admin --password secret --version 10.2.0-h2 +INFO - βœ… Connection to firewall established +INFO - πŸ“ 007054000123456 houston 192.168.255.211 +INFO - πŸ“ Firewall HA mode: disabled +INFO - πŸ“ Current PAN-OS version: 10.2.0 +INFO - πŸ“ Target PAN-OS version: 10.2.0-h2 +INFO - βœ… Confirmed that moving from 10.2.0 to 10.2.0-h2 is an upgrade +INFO - βœ… Target PAN-OS version 10.2.0-h2 is available for download +INFO - βœ… Base image for 10.2.0-h2 is already downloaded +INFO - πŸš€ Performing test to see if 10.2.0-h2 is already downloaded... +INFO - πŸ” PAN-OS version 10.2.0-h2 is not on the firewall +INFO - πŸš€ PAN-OS version 10.2.0-h2 is beginning download +INFO - Device 007054000123456 downloading version: 10.2.0-h2 +INFO - βš™οΈ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 4 seconds +INFO - βš™οΈ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 36 seconds +INFO - βš™οΈ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 71 seconds +INFO - βœ… 10.2.0-h2 downloaded in 103 seconds +INFO - βœ… PAN-OS version 10.2.0-h2 has been downloaded. +INFO - πŸš€ Performing snapshot of network state information... +INFO - βœ… Network snapshot created successfully +INFO - πŸš€ Performing readiness checks to determine if firewall is ready for upgrade... +INFO - βœ… Passed Readiness Check: Check if there are pending changes on device +INFO - βœ… Passed Readiness Check: No Expired Licenses +INFO - βœ… Passed Readiness Check: Check if a there is enough space on the `/opt/panrepo` volume for downloading an PanOS image. +INFO - βœ… Passed Readiness Check: Check if NTP is synchronized +INFO - βœ… Passed Readiness Check: Check connectivity with the Panorama appliance +INFO - βœ… Readiness Checks completed +INFO - πŸš€ Performing backup of houston's configuration to local filesystem... +INFO - πŸš€ Not a dry run, continue with upgrade... +INFO - πŸš€ Performing upgrade on houston to version 10.2.0-h2... +INFO - πŸš€ Attempting upgrade houston to version 10.2.0-h2 (Attempt 1 of 3)... +INFO - Device 007054000123456 installing version: 10.2.0-h2 +INFO - βœ… houston upgrade completed successfully +INFO - πŸš€ Rebooting the firewall... +INFO - πŸ“ Command succeeded with no output +INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is rebooting... +INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... +INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... +INFO - βš™οΈ Firewall is responding to requests but hasn't finished its reboot process... +INFO - βœ… Firewall upgraded and rebooted in 542 seconds +``` + +
+ +For a dry run: + +```bash +$ pan-os-upgrade --ip-address 192.168.1.1 --username admin --password secret --version 10.1.0 --dry-run +``` + +### CLI Arguments Description + +When using command-line arguments, the following options are available: + +| Argument | Description | Required | +| -------------- | -------------------------------------------------------------------- | -------- | +| `--ip-address` | IP address of the target PAN-OS firewall. | Yes | +| `--username` | Username for authentication with the firewall. | Yes | +| `--password` | Password for authentication with the firewall. | Yes | +| `--version` | Target PAN-OS version to upgrade to. | Yes | +| `--dry-run` | Perform a dry run of all tests and downloads without actual upgrade. | No | +| `--log-level` | Set the logging output level (e.g., debug, info, warning). | No | + +Note: The use of an API key and `.env` file for configuration is no longer supported. + +## Output and Assurance Functions + +This output will include detailed logs of the process, such as establishing a connection, checking versions, performing upgrades, and rebooting the firewall. + +## Assurance Functions + +The script performs various assurance functions like readiness checks, snapshots, and configuration backups. These are stored in the `assurance/` directory, structured as follows: + +- `snapshots/`: Contains pre and post-upgrade network state snapshots in JSON format. +- `readiness_checks/`: Holds results of readiness checks in JSON format. +- `configurations/`: Stores backups of the firewall's configuration in XML format. + +### Log Files and Levels + +Log entries are recorded in the `logs/` directory. The verbosity of logs can be controlled with the `--log-level` argument, with available options being `debug`, `info`, `warning`, `error`, and `critical`. + +## Next Steps + +With `pan-os-upgrade` configured, you're ready to execute the upgrade process. This guide should have provided you with all the necessary information to use the tool effectively within a Python environment. For further assistance or advanced tips, refer to the [Python Troubleshooting Guide](troubleshooting.md). diff --git a/docs/user-guide/getting-started.md b/docs/user-guide/python/getting-started.md similarity index 92% rename from docs/user-guide/getting-started.md rename to docs/user-guide/python/getting-started.md index b194bb1..c654c4b 100644 --- a/docs/user-guide/getting-started.md +++ b/docs/user-guide/python/getting-started.md @@ -72,4 +72,4 @@ $ pip install pan-os-upgrade ## Next Steps -With `pan-os-upgrade` successfully installed in your virtual environment, the next step is to configure the library for use with your firewall. Visit the [Configuration Guide](configuration.md) to learn how to set up and configure `pan-os-upgrade` for your specific needs. +With `pan-os-upgrade` successfully installed in your virtual environment, the next step is to configure the library for use with your firewall. Visit the [Python Execution Guide](execution.md) to learn how to set up and configure `pan-os-upgrade` for your specific needs. diff --git a/docs/user-guide/troubleshooting.md b/docs/user-guide/python/troubleshooting.md similarity index 96% rename from docs/user-guide/troubleshooting.md rename to docs/user-guide/python/troubleshooting.md index 62b29f3..5bf5b2b 100644 --- a/docs/user-guide/troubleshooting.md +++ b/docs/user-guide/python/troubleshooting.md @@ -26,7 +26,7 @@ Encountering issues while using the `pan-os-upgrade` tool is not uncommon, espec **Problem:** The wrong PAN-OS version is downloaded or installed. -**Solution:** Verify the target PAN-OS version specified in the `.env` file or command-line arguments. Ensure compatibility with your firewall model. +**Solution:** Verify the target PAN-OS version specified in the command-line arguments. Ensure compatibility with your firewall model. ### 5. Readiness Check Failures diff --git a/mkdocs.yml b/mkdocs.yml index 95d2866..6c24c44 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: PAN-OS Upgrade +site_name: pan-os-upgrade Documentation site_description: Automate upgrades of Palo Alto Networks firewalls with Python site_url: https://cdot65.github.io/pan-os-upgrade/ repo_name: cdot65/pan-os-upgrade @@ -20,13 +20,23 @@ nav: - Home: index.md - User Guide: - Introduction: user-guide/introduction.md - - Getting Started: user-guide/getting-started.md - - Configuration: user-guide/configuration.md - - Execution: user-guide/execution.md - - Troubleshooting: user-guide/troubleshooting.md + - Python Workflow: + - Getting Started: user-guide/python/getting-started.md + - Execution: user-guide/python/execution.md + - Troubleshooting: user-guide/python/troubleshooting.md + - Docker Workflow: + - Getting Started: user-guide/docker/getting-started.md + - Execution: user-guide/docker/execution.md + - Troubleshooting: user-guide/docker/troubleshooting.md - API Reference: - pan_os_upgrade: reference/pan_os_upgrade.md - About: - License: about/license.md - Contributing: about/contributing.md - Release Notes: about/release-notes.md +extra_css: + - css/termynal.css + - css/custom.css +extra_javascript: + - js/termynal.js + - js/custom.js diff --git a/pyproject.toml b/pyproject.toml index ebdbdd7..cadfb88 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "pan-os-upgrade" -version = "0.2.1" +version = "0.2.2" description = "Python script to automate the upgrade process of PAN-OS firewalls." authors = ["Calvin Remsburg "] license = "Apache 2.0"