opnsense

Table of Contents

• Description
• Setup
  • OPNsense firewall
    • Requirements
    • Install requirements
  • Bastion host
    • Requirements
    • Install requirements
• Usage
  • Creating the device
  • Configure your OPNsense Firewall
• Reference
• Limitations
• CI/CD
• Development
  • Create the local development environment
  • Running unit tests
  • Running acceptance tests
  • Teardown
  • Contributing

Description

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.

Setup

OPNsense firewall

If you want to manage your firewall directly with a puppet-agent running on the device.

Requirements

• OPNsense plugin: sysutils/puppet-agent

Install requirements

Menu->Firmware->Plugins

Install Plugin: sysutils/puppet-agent

Bastion host

If you want a bastion hosts running a puppet-agent which could manage multiple firewalls via https API calls.

Requirements

• opn-cli
• puppetlabs/resource_api (puppet < 6.0)

Install requirements

$packages = [
    'python3',
    'python3-pip',
]
$pip_packages = [
    'opn-cli',
]
package { $packages:
    ensure => present,
}
-> package { $pip_packages:
    ensure   => latest,
    provider => 'pip3',
}

Usage

Creating the device

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.

Configure your OPNsense Firewall

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.

Reference

Types and providers are documented in REFERENCE.md.

Limitations

For an extensive list of supported operating systems, see metadata.json

CI/CD

CI/CD is done via Github Actions.

Development

Install the you following requirements if you need alocal development environment:

• vagrant
• docker
• git
• Puppet Development Kit (PDK)

Create the local development environment

scripts/create_test_env 

Running unit tests

Unit testing uses pdk

scripts/unit_tests

Running acceptance tests

Acceptance testing uses puppet litmus.

scripts/acceptance_tests

Teardown

scripts/remove_test_env

Contributing

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.

Reference

Table of Contents

Resource types

• opnsense_device: Manage an OPNsense device access.
• opnsense_plugin: Manage installed opnsense plugins

Resource types

opnsense_device

This type provides Puppet with the capabilities to manage OPNSense device access data.

• See also
  • https://docs.opnsense.org/development/how-tos/api.html#use-the-api

Examples

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',
}

Properties

The following properties are available in the opnsense_device type.

api_key

Data type: String

The api key from the generated key/secret pair.

api_secret

Data type: Sensitive[String]

The api secret from the generated key/secret pair.

ca

Data type: Optional[String]

The path to the ca bundle file for ssl verification.

ensure

Data type: Enum[present, absent]

Whether this resource should be present or absent on the target system.

Default value: present

ssl_verify

Data type: Boolean

The timeout for API calls in seconds.

Default value: true

timeout

Data type: Integer

The timeout for API calls in seconds.

Default value: 60

url

Data type: String

The api url of the OPNsense device.

Parameters

The following parameters are available in the opnsense_device type.

• name

name

namevar

Data type: Pattern[/\A[0-9A-Za-z.-]+/] *this data type contains a regex that may not be accurately reflected in generated documentation

The name of the OPNsense device you want to manage.

opnsense_plugin

This type provides Puppet with the capabilities to manage opnsense plugins.

• See also
  • https://docs.opnsense.org/plugins.html

Examples

opnsense_plugin { 'os-acme-client':
  device => 'opnsense.example.com'
  ensure => 'present',
}

Properties

The following properties are available in the opnsense_plugin type.

ensure

Data type: Enum[present, absent]

Whether this plugin should be present or absent on the opnsense device.

Default value: present

Parameters

The following parameters are available in the opnsense_plugin type.

• device
• name

device

namevar

Data type: String

The name of the opnsense_device type you want to manage.

name

namevar

Data type: String

The name of the plugin you want to manage.

Change log

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v1.0.0 (2021-06-17)

Full Changelog

Added

• Manage OPNsense plugins #1 (andeman)

* This Changelog was automatically generated by github_changelog_generator