PSOPNSenseAPI/docs/Troubleshooting.md

Troubleshooting Guide

This document provides troubleshooting information for common issues with the PSOPNSenseAPI module.

Connection Issues

Unable to Connect to OPNSense Firewall

Symptoms:

• Connect-OPNSense fails with connection errors
• Error messages about unreachable hosts or connection timeouts

Possible Causes and Solutions:

1. Incorrect URL:

   • Ensure the URL is correct and includes the protocol (https://)
   • Verify there are no typos in the domain name or IP address

   # Correct format
   Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret"
   

2. Network Connectivity:

   • Verify that you can reach the OPNSense firewall from your computer
   • Try pinging the firewall or accessing the web interface in a browser

   # Test connectivity
   Test-NetConnection -ComputerName "firewall.example.com" -Port 443
   

3. Certificate Issues:

   • If the firewall uses a self-signed certificate, use the -SkipCertificateCheck parameter

   Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
   

4. Firewall Rules:

   • Check if there are any firewall rules blocking access to the OPNSense web interface
   • Ensure that port 443 (HTTPS) is open for your IP address

5. Proxy Settings:

   • If you're behind a proxy, configure PowerShell to use the proxy

   # Configure proxy
   [System.Net.WebRequest]::DefaultWebProxy = New-Object System.Net.WebProxy("http://proxy.example.com:8080")
   [System.Net.WebRequest]::DefaultWebProxy.Credentials = [System.Net.CredentialCache]::DefaultNetworkCredentials
   

Authentication Failures

Symptoms:

• Connect-OPNSense fails with authentication errors
• Error messages about invalid credentials or unauthorized access

Possible Causes and Solutions:

1. Incorrect API Key or Secret:

   • Verify that the API key and secret are correct
   • Regenerate the API key and secret if necessary

2. API Access Not Enabled:

   • Ensure that API access is enabled for the user
   • Check the user's privileges in the OPNSense web interface

3. User Permissions:

   • Verify that the user has the necessary privileges for the operations you're trying to perform
   • Consider using a user with administrative privileges for testing

4. API Key Expiration:

   • Some OPNSense configurations may have API key expiration
   • Generate a new API key if the current one has expired

Module Loading Issues

Module Not Found

Symptoms:

• Import-Module PSOPNSenseAPI fails with module not found errors
• Commands from the module are not recognized

Possible Causes and Solutions:

1. Module Not Installed:

   • Verify that the module is installed

   # Check if the module is installed
   Get-Module -Name PSOPNSenseAPI -ListAvailable
   

2. Module Not in PSModulePath:

   • Check if the module is installed in a valid module path

   # List module paths
   $env:PSModulePath -split ';'
   

3. Module Version Mismatch:

   • Check if you have multiple versions of the module installed

   # List all versions of the module
   Get-Module -Name PSOPNSenseAPI -ListAvailable | Select-Object Name, Version
   

4. PowerShell Version Compatibility:

   • Verify that you're using a compatible PowerShell version
   • The module requires PowerShell 5.1 or later

   # Check PowerShell version
   $PSVersionTable
   

Module Loading Errors

Symptoms:

• Import-Module PSOPNSenseAPI fails with loading errors
• Error messages about missing dependencies or assembly loading failures

Possible Causes and Solutions:

1. Missing Dependencies:

   • Ensure that all dependencies are installed
   • The module requires .NET Framework 4.7.2 or later for Windows PowerShell

2. Assembly Loading Issues:

   • Try loading the module with verbose output to identify the specific issue

   # Load module with verbose output
   Import-Module -Name PSOPNSenseAPI -Verbose
   

3. File Corruption:

   • Reinstall the module to ensure all files are intact

   # Uninstall and reinstall the module
   Uninstall-Module -Name PSOPNSenseAPI -Force
   Install-Module -Name PSOPNSenseAPI -Force
   

Command Execution Issues

Command Fails with Error

Symptoms:

• Commands fail with error messages
• Unexpected results or behavior

Possible Causes and Solutions:

1. Not Connected to Firewall:

   • Ensure that you're connected to the firewall before running commands

   # Check if connected
   if (-not $OPNSenseSessionState.Instance.ApiClient) {
       Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret"
   }
   

2. Insufficient Permissions:

   • Verify that the user has the necessary privileges for the operation
   • Check the error message for permission-related issues

3. Invalid Parameters:

   • Check that you're using the correct parameters and values
   • Use Get-Help to see the required and optional parameters

   # Get help for a command
   Get-Help -Name New-OPNSenseFirewallRule -Full
   

4. API Limitations:

   • Some operations may not be supported by the OPNSense API
   • Check the OPNSense API documentation for supported operations

5. Firewall Configuration:

   • The current state of the firewall may prevent certain operations
   • Check the OPNSense logs for more information

Changes Not Applied

Symptoms:

• Commands appear to succeed, but changes are not reflected on the firewall
• Configuration changes don't persist after a firewall reboot

Possible Causes and Solutions:

1. Apply Changes Not Called:

   • Many commands require an explicit call to apply the changes

   # Apply changes after making configuration changes
   Apply-OPNSenseFirewallChanges
   

2. Caching Issues:

   • The OPNSense web interface may be showing cached data
   • Refresh the web interface or wait a few moments

3. Conflicting Configurations:

   • Other configurations may be overriding your changes
   • Check for conflicting rules or settings

4. Firewall Reboot Required:

   • Some changes may require a firewall reboot to take effect

   # Reboot the firewall
   Invoke-OPNSenseReboot
   

Performance Issues

Slow Command Execution

Symptoms:

• Commands take a long time to execute
• Timeouts or performance degradation

Possible Causes and Solutions:

1. Network Latency:

   • High latency between your computer and the firewall can slow down commands
   • Consider running commands from a location with better connectivity

2. Firewall Load:

   • The firewall may be under heavy load
   • Try running commands during periods of lower activity

3. Large Data Sets:

   • Commands that retrieve large amounts of data may be slow
   • Use filtering parameters to limit the data returned

   # Filter results to reduce data
   Get-OPNSenseFirewallRule -Interface "lan"
   

4. Inefficient Scripts:

   • Scripts that make many individual API calls can be slow
   • Batch operations where possible and minimize the number of API calls

Logging and Debugging

Enabling Verbose Logging

To troubleshoot issues, you can enable verbose logging:

# Enable verbose output
$VerbosePreference = "Continue"

# Run commands with verbose output
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -Verbose

Capturing HTTP Traffic

For advanced troubleshooting, you can capture the HTTP traffic between the module and the OPNSense firewall:

# Enable Fiddler capture
[System.Net.WebRequest]::DefaultWebProxy = New-Object System.Net.WebProxy("http://localhost:8888")
[System.Net.WebRequest]::DefaultWebProxy.BypassProxyOnLocal = $false

Note: This requires Fiddler or a similar HTTP debugging proxy to be installed and running.

Checking OPNSense Logs

Check the OPNSense logs for additional information:

1. Log in to the OPNSense web interface
2. Navigate to System > Log Files > General
3. Look for entries related to the API or the operations you're performing

Common Error Messages

"Not connected to an OPNSense firewall"

Cause: You're trying to run a command without first connecting to the firewall.

Solution: Connect to the firewall before running commands:

Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret"

"The remote server returned an error: (401) Unauthorized"

Cause: The API key or secret is incorrect, or the user doesn't have the necessary privileges.

Solution: Verify the API key and secret, and check the user's privileges.

"The remote server returned an error: (404) Not Found"

Cause: The requested resource or API endpoint doesn't exist.

Solution: Check that you're using the correct command and parameters, and that the resource exists on the firewall.

"The remote server returned an error: (500) Internal Server Error"

Cause: An error occurred on the OPNSense firewall while processing the request.

Solution: Check the OPNSense logs for more information, and verify that the firewall is functioning correctly.

"Unable to find type [System.Net.IPNetwork.IPNetwork]"

Cause: The IPNetwork2 assembly is not loaded or is missing.

Solution: Reinstall the module to ensure all dependencies are properly installed.

Getting Help

If you're still experiencing issues after trying the troubleshooting steps above:

1. Check the GitHub repository for known issues and solutions
2. Open an issue on GitHub with detailed information about the problem
3. Include the following information in your issue:
   • PSOPNSenseAPI module version
   • PowerShell version
   • OPNSense version
   • Error messages (with sensitive information redacted)
   • Steps to reproduce the issue