Add port forwarding support, improve XML documentation, and add unit tests

docs/Installation-Setup.md

@@ -0,0 +1,217 @@
+# Installation and Setup
+
+This document provides instructions for installing and setting up the PSOPNSenseAPI PowerShell module.
+
+## Overview
+
+The PSOPNSenseAPI module is a PowerShell module that provides cmdlets for managing OPNSense firewalls through the OPNSense API. This document covers the installation of the module, setting up API access on the OPNSense firewall, and establishing a connection to the firewall.
+
+## Prerequisites
+
+Before installing the PSOPNSenseAPI module, ensure that you have the following:
+
+- PowerShell 5.1 or later (Windows PowerShell or PowerShell Core)
+- .NET Framework 4.7.2 or later (for Windows PowerShell)
+- .NET Core 3.1 or later (for PowerShell Core)
+- OPNSense 21.1 or later with API access configured
+
+## Installation Methods
+
+### Installing from PowerShell Gallery
+
+The recommended way to install the PSOPNSenseAPI module is from the PowerShell Gallery:
+
+```powershell
+# Install the module for the current user
+Install-Module -Name PSOPNSenseAPI -Scope CurrentUser
+
+# Install the module for all users (requires administrator privileges)
+Install-Module -Name PSOPNSenseAPI -Scope AllUsers
+```
+
+### Installing from GitHub
+
+You can also install the module directly from the GitHub repository:
+
+```powershell
+# Clone the repository
+git clone https://github.com/freedbygrace/PSOPNSenseAPI.git
+
+# Navigate to the repository directory
+cd PSOPNSenseAPI
+
+# Build the module
+.\build\build.ps1
+
+# Import the module
+Import-Module .\output\PSOPNSenseAPI
+```
+
+### Manual Installation
+
+To install the module manually:
+
+1. Download the latest release from the [GitHub releases page](https://github.com/freedbygrace/PSOPNSenseAPI/releases)
+2. Extract the archive to a module directory:
+   - For the current user: `$env:USERPROFILE\Documents\WindowsPowerShell\Modules\PSOPNSenseAPI`
+   - For all users: `$env:ProgramFiles\WindowsPowerShell\Modules\PSOPNSenseAPI`
+3. Import the module:
+
+```powershell
+Import-Module PSOPNSenseAPI
+```
+
+## Setting Up API Access on OPNSense
+
+Before you can use the PSOPNSenseAPI module, you need to set up API access on your OPNSense firewall:
+
+1. Log in to the OPNSense web interface
+2. Navigate to **System > Access > Users**
+3. Select the user you want to use for API access or create a new user
+4. Ensure the user has the necessary privileges for the operations you want to perform
+5. Click on the **API keys** tab
+6. Click **+** to add a new API key
+7. Note the **Key** and **Secret** values, as you will need them to connect to the firewall
+
+## Connecting to an OPNSense Firewall
+
+Once you have installed the module and set up API access, you can connect to an OPNSense firewall:
+
+```powershell
+# Connect to the OPNSense firewall
+Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret"
+
+# Connect to the OPNSense firewall with certificate validation disabled (for self-signed certificates)
+Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
+```
+
+## Verifying the Installation
+
+To verify that the module is installed and working correctly:
+
+```powershell
+# Check the module version
+Get-Module -Name PSOPNSenseAPI
+
+# List available cmdlets
+Get-Command -Module PSOPNSenseAPI
+
+# Get help for a specific cmdlet
+Get-Help -Name Connect-OPNSense -Full
+```
+
+## Updating the Module
+
+To update the module to the latest version:
+
+```powershell
+# Update the module from PowerShell Gallery
+Update-Module -Name PSOPNSenseAPI
+```
+
+## Uninstalling the Module
+
+To uninstall the module:
+
+```powershell
+# Uninstall the module
+Uninstall-Module -Name PSOPNSenseAPI
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+If you encounter connection issues:
+
+1. Verify that the OPNSense firewall is reachable from your computer
+2. Check that the API key and secret are correct
+3. Ensure that the user associated with the API key has the necessary privileges
+4. If using HTTPS with a self-signed certificate, use the `-SkipCertificateCheck` parameter
+5. Check if there are any firewall rules blocking access to the OPNSense web interface
+
+### Module Loading Issues
+
+If you encounter issues loading the module:
+
+1. Verify that you have the required PowerShell and .NET versions
+2. Check that the module is installed in a valid module path:
+
+```powershell
+# List module paths
+$env:PSModulePath -split ';'
+
+# Check if the module is in a valid path
+Get-Module -Name PSOPNSenseAPI -ListAvailable
+```
+
+3. Try importing the module with verbose output:
+
+```powershell
+Import-Module -Name PSOPNSenseAPI -Verbose
+```
+
+### API Access Issues
+
+If you encounter issues with API access:
+
+1. Verify that the API is enabled on the OPNSense firewall
+2. Check that the user has the necessary privileges
+3. Ensure that the API key and secret are valid
+4. Check if there are any firewall rules blocking access to the API
+
+## Common Configuration
+
+### Creating a Profile for Quick Connection
+
+You can create a profile to store your connection information for quick access:
+
+```powershell
+# Create a directory for profiles
+$profilesDir = "$env:USERPROFILE\Documents\PSOPNSenseAPI\Profiles"
+New-Item -Path $profilesDir -ItemType Directory -Force
+
+# Create a profile
+$profile = @{
+    Server = "https://firewall.example.com"
+    ApiKey = "your_api_key"
+    ApiSecret = "your_api_secret"
+    SkipCertificateCheck = $true
+}
+
+# Save the profile
+$profilePath = "$profilesDir\firewall.json"
+$profile | ConvertTo-Json | Set-Content -Path $profilePath
+
+# Load the profile and connect
+$profile = Get-Content -Path $profilePath | ConvertFrom-Json
+Connect-OPNSense -Server $profile.Server -ApiKey $profile.ApiKey -ApiSecret $profile.ApiSecret -SkipCertificateCheck:$profile.SkipCertificateCheck
+```
+
+### Setting Up a Module Import Profile
+
+You can create a PowerShell profile that automatically imports the module:
+
+```powershell
+# Add the following line to your PowerShell profile
+if (-not (Get-Module -Name PSOPNSenseAPI -ErrorAction SilentlyContinue)) {
+    Import-Module -Name PSOPNSenseAPI
+}
+
+# To edit your PowerShell profile
+notepad $PROFILE
+```
+
+## Notes
+
+- Store API keys and secrets securely, as they provide access to your OPNSense firewall.
+- Consider using a dedicated user with limited privileges for API access.
+- Always disconnect from the firewall when you're done:
+
+```powershell
+Disconnect-OPNSense
+```
+
+- For security reasons, avoid storing API keys and secrets in scripts or profiles that are shared or stored in unsecured locations.
+- When using the module in scripts, consider using secure string variables or environment variables for API keys and secrets.
+- The module uses HTTPS for all communication with the OPNSense firewall, ensuring that all data is encrypted in transit.