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 or connecting to firewalls through Panorama as a proxy. 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, Hostname, 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.
8. Panorama Connection and Filter Challenges
Problem: Issues connecting to firewalls through Panorama using the --filter
option.
Solution: Ensure the filter syntax is correctly formatted and the specified criteria accurately reflect your firewall configuration in Panorama. Double-check network connectivity to Panorama and ensure the filters match the attributes of the firewalls you intend to upgrade.
9. ARP Table Comparison Failures
Problem: When capturing ARP tables for comparison, the script fails with WrongDataTypeException: Unknown value format for key ttl
.
Solution: This issue can arise when ARP table entries contain integer values for ttl
, which the current implementation may not handle properly. To address this, consider installing a custom fork of panos-upgrade-assurance
that includes a fix for this issue, available at https://github.com/cdot65/pan-os-upgrade-assurance/tree/main. Alternatively, you can configure the script to omit ARP snapshots from the tests if modifying the script is not feasible.
Steps to Install Custom Fork:
- Run this command:
pip install git+https://github.com/cdot65/pan-os-upgrade-assurance.git@main
Steps to Omit ARP Snapshots:
- If using a
settings.yaml
file, ensure ARP snapshots are disabled. - If running the script interactively, choose not to capture ARP snapshots when prompted.
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 of pan-os-upgrade
. Include detailed information, such as the Docker version, system environment, and any relevant logs or error messages.