PSOPNSenseAPI/docs/Plugin-Management.md

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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.