mirror of
https://github.com/freedbygrace/PSOPNSenseAPI.git
synced 2026-07-26 11:58:18 +00:00
GraceSolutions
297 lines
7.5 KiB
Markdown
297 lines
7.5 KiB
Markdown
# 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.
|