This is a PowerShell module that uses the OPNsense REST api to manage OPNsense firewall appliances. The development of the OPNsense REST api and this PowerShell module is still ongoing, so additional functionality will be added in the future.
Currently there are basic api hooks for these OPNsense modules:
- Firmware
- CaptivePortal
- Cron
- Diagnostics
- IDS
- Packages
- Proxy
- Services
Not all functionality is implemented yet and this is an early development alpha release. All testing and feedback is appreciated.
All CRUD items are supported using Get-OPNsenseItem, Remove-OPNsenseItem and Switch-OPNsenseItem. Creating and updating CRUD items is being worked on and not yet fully supported.
Full support to install, re-install, remove, lock and unlock OPNsense Packages and Plugins.
You can get the Settings for all API modules. Changing the Settings is not supported yet.
Currently only Start, Stop, Update and Restart services are implemented for the other plugins. More work is needed to support all available REST api commands.
Updating firmware via PowerShell is implemented.
There is legacy WebUI support for these commands:
- Backup Config
- Restore Config
- Reset Factory Defaults
A minimal set of legacy commands are also available in this PowerShell module. Only crucial functionality that is not yet available via the REST api yet will be exposed using the WebUI. These cmdlets will be ported over to use the REST api functions when they are ported to the REST api when they are made available in future OPNsense firmware versions.
To find out the location of the Modules directory, check the PSModulePath environment variable:
$Env:PSModulePath -split ";" # On Windows
$Env:PSModulePath -split ":" # On LinuxChange into the PowerShell Module directory located in your profile folder.
You can download and unzip the module into the PowerShell Modules folder or clone the repository directly:
git clone https://github.com/fvanroie/PS_OPNsense.git
Depending on your ExecutionPolicy, you might need to unblock the downloaded module files:
Get-ChildItem PS_OPNsense -Recurse | Unblock-File -VerboseOn newer system you also might open PS with administrative access and run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserTo load this module in PowerShell type:
Import-Module -Name PS_OPNsense -PassThruGet all the commands in the PS_OPNsense module type:
Get-Command -Module PS_OPNsenseFrom the OPNsense GUI, create an API key for a user that will run PowerShell scripts:
- Open System > Access > Users.
- Click on a user that will be used for accessing the REST api.
- Under the section API keys, click on the Add [+] button to generate a key/secret pair.
- Download the txt file.
- Use the key and secret values to connect to OPNsense REST api using Connect-OPNsense cmdlet below.
Connecting to an OPNsense server:
Connect-OPNsense -Uri 'http://opnsense.local:8080' -Key <api_key> -Secret <api_secret>
Connect-OPNsense -Uri 'https://opnsense.local' -Key <api_key> -Secret <api_secret> -Verbose -Debug
Connect-OPNsense 'https://opnsense.local' <api_key> <api_secret> -SkipCertificateCheckRun some commands:
Get-OPNsenseItem -Cron Job
Get-OPNsensePackage -PluginDisconnect from the server:
Disconnect-OPNsenseUse the -Verbose and/or -Debug switches to see what is going on behind the scenes. You can use the output to learn more about the OPNsense REST api.
The project contains an Examples directory with more example scripts. For the full documentation of all the cmdlets and parameters, please visit the PS_OPNsense wiki.
This module is tested on:
| Platform | Edition | Version |
|---|---|---|
| Windows 10 | PowerShell Desktop | 5.1 |
| Windows 10 | PowerShell Core | 6.0 |
| Ubuntu 18.04 | PowerShell Core | 6.0 |
PS_OPNsense aims to be cross-platform on PowerShell Core 6.0 and up, however it has not been extensively tested on MacOS yet. Let me know what works and what doesn't. Feel free to use it on these platforms and report back any issues you encouter. The goal is to make PS_OPNsense crossplatform with PowerShell Core.
