-
Notifications
You must be signed in to change notification settings - Fork 9
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update pan-os-upgrade documentation with latest configuration options
- Loading branch information
Showing
4 changed files
with
86 additions
and
155 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,89 +1,51 @@ | ||
| # Configuration Guide for pan-os-upgrade | ||
|
|
||
| Proper configuration is crucial for the effective use of the `pan-os-upgrade` package. There are two main methods to configure the tool: using a `.env` file or passing command-line arguments. Each method has its strengths and weaknesses, which we'll explore below. | ||
| 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. | ||
|
|
||
| ## Option 1: Using a `.env` File | ||
| ## Executing `pan-os-upgrade` | ||
|
|
||
| A `.env` file is a simple way to store configuration settings in key-value pairs. This method is advantageous for keeping your configuration organized and easily editable in one place. | ||
| ### Option 1: Execute Without Command-Line Arguments | ||
|
|
||
| **Creating a `.env` File:** | ||
| 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. | ||
|
|
||
| 1. Create a `.env` file in your project's root directory. | ||
| 2. Add your firewall's details to the file, as shown below: | ||
|
|
||
| ```env | ||
| # PAN-OS credentials - use either API key or username/password combination | ||
| PAN_USERNAME=admin | ||
| PAN_PASSWORD=paloalto123 | ||
| API_KEY= | ||
| # Hostname or IP address of the firewall | ||
| HOSTNAME=firewall1.example.com | ||
| # Target PAN-OS version for the upgrade | ||
| TARGET_VERSION=11.0.2-h3 | ||
| # Logging level (e.g., debug, info, warning, error, critical) | ||
| LOG_LEVEL=debug | ||
| # Set to true for a dry run | ||
| DRY_RUN=false | ||
| ```bash | ||
| $ pan-os-upgrade | ||
| IP address: 192.168.255.1 | ||
| Username: admin | ||
| Password: | ||
| Target PAN-OS version: 11.1.1 | ||
| ...output... | ||
| ``` | ||
|
|
||
| **Pros:** | ||
|
|
||
| - Centralized configuration management. | ||
| - Easy to update or modify settings. | ||
|
|
||
| **Cons:** | ||
| ### Option 2: Execute Using Command-Line Arguments | ||
|
|
||
| - Risk of committing sensitive information to a version control system if not properly ignored. | ||
| - Less flexibility for dynamic or per-run configurations. | ||
|
|
||
| ## Option 2: Using Command-Line Arguments | ||
|
|
||
| Command-line arguments offer a direct way to pass configuration settings each time you run the script. | ||
|
|
||
| **Passing Details via Command-Line:** | ||
|
|
||
| - Standard Usage: | ||
| Alternatively, you can pass these details as command-line arguments: | ||
|
|
||
| ```bash | ||
| pan-os-upgrade --hostname 192.168.1.1 --username admin --password secret --version 10.1.0 | ||
| $ pan-os-upgrade --ip-address 192.168.1.1 --username admin --password secret --version 10.1.0 | ||
| ``` | ||
|
|
||
| - For a Dry Run: | ||
| For a dry run: | ||
|
|
||
| ```bash | ||
| pan-os-upgrade --hostname 192.168.1.1 --username admin --password secret --version 10.1.0 --dry-run | ||
| $ pan-os-upgrade --ip-address 192.168.1.1 --username admin --password secret --version 10.1.0 --dry-run | ||
| ``` | ||
|
|
||
| **Pros:** | ||
|
|
||
| - Greater control and flexibility for each run. | ||
| - Avoids storing sensitive details in a file. | ||
|
|
||
| **Cons:** | ||
|
|
||
| - Risk of exposing sensitive information in console history. | ||
| - Less convenient for repeated use with the same settings. | ||
|
|
||
| ## CLI Arguments Description | ||
|
|
||
| When using command-line arguments, the following options are available: | ||
|
|
||
| | argument | description | required | | ||
| | ------------- | ------------------------------------------------------------------------- | --------- | | ||
| | `--api-key` | API Key for authentication | required* | | ||
| | `--dry-run` | Dry run of all tests and downloads without performing the actual upgrade. | optional | | ||
| | `--hostname` | Hostname or IP address of the PAN-OS firewall. | optional | | ||
| | `--log-level` | Set the logging output level (e.g., debug, info, warning). | optional | | ||
| | `--password` | Password for authentication. | required* | | ||
| | `--username` | Username for authentication. | required* | | ||
| | `--version` | Target PAN-OS version to upgrade to. | required | | ||
| | 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 | | ||
|
|
||
| <small>* if using a <code>--api-key</code> for authentication, omit the <code>--username</code> and <code>--password</code> arguments; opposite is also true.</small> | ||
| 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. To learn more about the execution steps and options, proceed to the [Execution Guide](execution.md). | ||
| 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). |
Oops, something went wrong.