mirror of
https://github.com/freedbygrace/PSOPNSenseAPI.git
synced 2026-07-26 11:58:18 +00:00
Add port forwarding support, improve XML documentation, and add unit tests
This commit is contained in:
GraceSolutions
@@ -0,0 +1,296 @@
|
||||
# Plugin Management
|
||||
|
||||
This component provides cmdlets for managing plugins on OPNSense firewalls.
|
||||
|
||||
## Overview
|
||||
|
||||
The Plugin Management component allows you to install, configure, and manage plugins on OPNSense firewalls. It provides cmdlets for listing available plugins, installing and uninstalling plugins, and managing plugin configurations.
|
||||
|
||||
## Cmdlets
|
||||
|
||||
### Get-OPNSensePlugin
|
||||
|
||||
Retrieves a list of available and installed plugins on an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Name** - The name of a specific plugin to retrieve. If not specified, all plugins are returned.
|
||||
- **Category** - Filter plugins by category.
|
||||
- **Installed** - Filter plugins by installation status.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Get all plugins
|
||||
Get-OPNSensePlugin
|
||||
|
||||
# Get a specific plugin by name
|
||||
Get-OPNSensePlugin -Name "os-tailscale"
|
||||
|
||||
# Get all installed plugins
|
||||
Get-OPNSensePlugin -Installed $true
|
||||
|
||||
# Get all plugins in a specific category
|
||||
Get-OPNSensePlugin -Category "security"
|
||||
```
|
||||
|
||||
### Install-OPNSensePlugin
|
||||
|
||||
Installs a plugin on an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Name** - The name of the plugin to install.
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Install a plugin
|
||||
Install-OPNSensePlugin -Name "os-tailscale"
|
||||
|
||||
# Install a plugin without confirmation
|
||||
Install-OPNSensePlugin -Name "os-wireguard" -Force
|
||||
```
|
||||
|
||||
### Uninstall-OPNSensePlugin
|
||||
|
||||
Uninstalls a plugin from an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Name** - The name of the plugin to uninstall.
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Uninstall a plugin
|
||||
Uninstall-OPNSensePlugin -Name "os-tailscale"
|
||||
|
||||
# Uninstall a plugin without confirmation
|
||||
Uninstall-OPNSensePlugin -Name "os-wireguard" -Force
|
||||
```
|
||||
|
||||
### Enable-OPNSensePlugin
|
||||
|
||||
Enables a plugin on an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Name** - The name of the plugin to enable.
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Enable a plugin
|
||||
Enable-OPNSensePlugin -Name "os-tailscale"
|
||||
|
||||
# Enable a plugin without confirmation
|
||||
Enable-OPNSensePlugin -Name "os-wireguard" -Force
|
||||
```
|
||||
|
||||
### Disable-OPNSensePlugin
|
||||
|
||||
Disables a plugin on an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Name** - The name of the plugin to disable.
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Disable a plugin
|
||||
Disable-OPNSensePlugin -Name "os-tailscale"
|
||||
|
||||
# Disable a plugin without confirmation
|
||||
Disable-OPNSensePlugin -Name "os-wireguard" -Force
|
||||
```
|
||||
|
||||
### Get-OPNSensePluginConfiguration
|
||||
|
||||
Retrieves the configuration of a plugin on an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Name** - The name of the plugin to get the configuration for.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Get the configuration of a plugin
|
||||
Get-OPNSensePluginConfiguration -Name "os-tailscale"
|
||||
```
|
||||
|
||||
### Set-OPNSensePluginConfiguration
|
||||
|
||||
Updates the configuration of a plugin on an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Name** - The name of the plugin to update the configuration for.
|
||||
- **Configuration** - The configuration to set.
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Update the configuration of a plugin
|
||||
$config = @{
|
||||
enabled = "1"
|
||||
settings = @{
|
||||
hostname = "opnsense-tailscale"
|
||||
acceptDns = "1"
|
||||
}
|
||||
}
|
||||
Set-OPNSensePluginConfiguration -Name "os-tailscale" -Configuration $config
|
||||
|
||||
# Update the configuration of a plugin without confirmation
|
||||
Set-OPNSensePluginConfiguration -Name "os-tailscale" -Configuration $config -Force
|
||||
```
|
||||
|
||||
### Apply-OPNSensePluginChanges
|
||||
|
||||
Applies pending plugin changes on an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Name** - The name of the plugin to apply changes for.
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Apply changes for a plugin
|
||||
Apply-OPNSensePluginChanges -Name "os-tailscale"
|
||||
|
||||
# Apply changes for a plugin without confirmation
|
||||
Apply-OPNSensePluginChanges -Name "os-tailscale" -Force
|
||||
```
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Installing and Configuring a Plugin
|
||||
|
||||
```powershell
|
||||
# Connect to the OPNSense firewall
|
||||
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
|
||||
|
||||
# Install the Tailscale plugin
|
||||
Install-OPNSensePlugin -Name "os-tailscale" -Force
|
||||
|
||||
# Configure the plugin
|
||||
$config = @{
|
||||
enabled = "1"
|
||||
settings = @{
|
||||
hostname = "opnsense-tailscale"
|
||||
acceptDns = "1"
|
||||
acceptRoutes = "1"
|
||||
advertiseRoutes = "192.168.1.0/24,10.0.0.0/8"
|
||||
}
|
||||
}
|
||||
Set-OPNSensePluginConfiguration -Name "os-tailscale" -Configuration $config -Force
|
||||
|
||||
# Apply the changes
|
||||
Apply-OPNSensePluginChanges -Name "os-tailscale" -Force
|
||||
|
||||
# Disconnect from the firewall
|
||||
Disconnect-OPNSense
|
||||
```
|
||||
|
||||
### Managing Multiple Plugins
|
||||
|
||||
```powershell
|
||||
# Connect to the OPNSense firewall
|
||||
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
|
||||
|
||||
# Define plugins to install
|
||||
$plugins = @(
|
||||
"os-tailscale",
|
||||
"os-wireguard",
|
||||
"os-acme-client",
|
||||
"os-theme-vicuna"
|
||||
)
|
||||
|
||||
# Install plugins
|
||||
foreach ($plugin in $plugins) {
|
||||
Install-OPNSensePlugin -Name $plugin -Force
|
||||
Write-Output "Installed plugin: $plugin"
|
||||
}
|
||||
|
||||
# Get all installed plugins
|
||||
$installedPlugins = Get-OPNSensePlugin -Installed $true
|
||||
Write-Output "Installed plugins:"
|
||||
$installedPlugins | Format-Table -Property Name, Version, Description
|
||||
|
||||
# Disconnect from the firewall
|
||||
Disconnect-OPNSense
|
||||
```
|
||||
|
||||
### Updating Plugin Configurations
|
||||
|
||||
```powershell
|
||||
# Connect to the OPNSense firewall
|
||||
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
|
||||
|
||||
# Get the current configuration of a plugin
|
||||
$currentConfig = Get-OPNSensePluginConfiguration -Name "os-wireguard"
|
||||
|
||||
# Update the configuration
|
||||
$currentConfig.server.enabled = "1"
|
||||
$currentConfig.server.port = "51820"
|
||||
$currentConfig.server.dns = "192.168.1.1"
|
||||
|
||||
# Set the updated configuration
|
||||
Set-OPNSensePluginConfiguration -Name "os-wireguard" -Configuration $currentConfig -Force
|
||||
|
||||
# Apply the changes
|
||||
Apply-OPNSensePluginChanges -Name "os-wireguard" -Force
|
||||
|
||||
# Disconnect from the firewall
|
||||
Disconnect-OPNSense
|
||||
```
|
||||
|
||||
### Cleaning Up Unused Plugins
|
||||
|
||||
```powershell
|
||||
# Connect to the OPNSense firewall
|
||||
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
|
||||
|
||||
# Get all installed plugins
|
||||
$installedPlugins = Get-OPNSensePlugin -Installed $true
|
||||
|
||||
# Define plugins to keep
|
||||
$pluginsToKeep = @(
|
||||
"os-tailscale",
|
||||
"os-wireguard",
|
||||
"os-acme-client"
|
||||
)
|
||||
|
||||
# Uninstall unused plugins
|
||||
foreach ($plugin in $installedPlugins) {
|
||||
if ($pluginsToKeep -notcontains $plugin.Name) {
|
||||
Uninstall-OPNSensePlugin -Name $plugin.Name -Force
|
||||
Write-Output "Uninstalled plugin: $($plugin.Name)"
|
||||
}
|
||||
}
|
||||
|
||||
# Disconnect from the firewall
|
||||
Disconnect-OPNSense
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Plugin installation and uninstallation may require a firewall reboot to take effect.
|
||||
- Some plugins may have dependencies that need to be installed first.
|
||||
- Plugin configurations vary widely depending on the plugin.
|
||||
- Always check the OPNSense documentation for specific plugin requirements and configuration options.
|
||||
- Plugin management requires administrative privileges.
|
||||
- Plugin installation and uninstallation can take some time, especially for larger plugins.
|
||||
- Some plugins may not be available for all OPNSense versions.
|
||||
- Plugin configurations are typically stored in XML format.
|
||||
- Changes to plugin configurations may not take effect until the plugin service is restarted or the firewall is rebooted.
|
||||
- Consider using the `-Force` parameter when installing or uninstalling plugins in scripts to avoid confirmation prompts.
|
||||
Reference in New Issue
Block a user