The opnsense module configures OPNsense firewalls with custom types and providers.
It allows administrators to manage an OPNsense firewall directly via the sysutils/puppet-agent opnsense plugin and/or manage multiple firewalls from a bastion host running a puppet-agent with opn-cli installed.
You can automate the following with the module:
- plugins
- firewall aliases
more to come...
If you want to manage your firewall directly with a puppet-agent running on the device.
- OPNsense plugin: sysutils/puppet-agent
Menu->Firmware->Plugins
Install Plugin: sysutils/puppet-agent
If you want a bastion hosts running a puppet-agent which could manage multiple firewalls via https API calls.
- opn-cli
- puppetlabs/resource_api (puppet < 6.0)
$packages = [
'python3',
'python3-pip',
]
$pip_packages = [
'opn-cli',
]
package { $packages:
ensure => present,
}
-> package { $pip_packages:
ensure => latest,
provider => 'pip3',
}
If you want to manage an OPNsense Firewall, you need to supply credentials and connection information for the device.
For each device you want to mange create an opnsense_device type:
opnsense_device { 'opnsense.example.com':
url => 'https://opnsense.example.com/api',
api_key => 'your_api_key',
api_secret => Sensitive('your_api_secret'),
timeout => 60,
ssl_verify => true,
ca => '/path/to/ca.pem',
ensure => 'present',
}
To create an api_key and api_secret see: https://docs.opnsense.org/development/how-tos/api.html#creating-keys.
If you want to use ssl verification (recommended):
To download the default self-signed cert, open the OPNsense web gui and go to System->Trust->Certificates. Search for the name: "Web GUI SSL certificate" and press the "export user cert" button.
If you use a ca signed certificate, go to System->Trust->Authorities and press the "export CA cert" button to download the ca.
Save the cert or ca and make sure the puppet agent is able to read it.
If you have at least one configured opnsense_device, you could start to use other puppet types to manage the device.
In the following example we use the opnsense_plugin type to manage the installed plugins on the opnsense device "opnsense.example.com":
opnsense_plugin { 'os-helloworld':
device => 'opnsense.example.com',
ensure => 'present',
}
See Reference.md for all available puppet types to manage your OPNsense firewall.
Types and providers are documented in REFERENCE.md.
For an extensive list of supported operating systems, see metadata.json
CI/CD is done via Github Actions.
Install the you following requirements if you need alocal development environment:
scripts/create_test_env
Unit testing uses pdk
scripts/unit_tests
Acceptance testing uses puppet litmus.
scripts/acceptance_tests
scripts/remove_test_env
Please use the GitHub issues functionality to report any bugs or requests for new features. Feel free to fork and submit pull requests for potential contributions.
All contributions must pass all existing tests, new features should provide additional unit/acceptance tests.