# OPNsense Configuration Generator
This package takes a Python ConfigParser formatted INI file and generates a ready to use config.xml file for OPNsense. The intent is for the file to be used during the installation process by the OPNsense Importer. The end result is a minimal working configuraion with interfaces fully configured. Included in this package are a command line interface and a class which is importable into Python scripts and other applications.
More information about the OPNsense importer can be found [here](https://docs.opnsense.org/manual/install.html#opnsense-importer).
There are five potential output files:
| Filename | Content |
|--------- | ------- |
| config.xml | OPNsense configuration XML |
| config.iso | OPNsense configuration XML in a CD image |
| WGBootstrap.conf | WireGuard client configuration |
| WGBootstrap.url | macOS shortcut leading to OPNsense console |
| opnsense_config_example.ini | Example configuration INI |
## Optional Interfaces
Any number of optional network interfaces beyond the basic WAN and LAN can be included in the INI as `OPT` sections. Each may include a description that would result in the display name of the interface being `Servers` rather than `OPT2` for example.
## DHCP Configuration
If an `OPT` section of the INI contains a `dhcp_start` field, then a DHCP configuration section will be included that corresponds to that interface.
## WireGuard Bootstrap
An optional feature is the WireGuard bootstrap. If a `WGB` section is provided in the INI, then a working WireGuard VPN interface will be available for immediate connection. The interface occupies instance 1, therefore the device will be `wg1` rather than `wg0`. This is to allow the user or automation to create a permanent WireGuard VPN interface at `wg0` then delete the bootstrap. The goal with this process is to have the permanent WireGaurd private key generated on the OPNsense instance and never to have been transmitted at any time.
The WireGuard bootstrap has a number of options. If the INI contains a server private key, it will be used to derive a public key. That resulting key pair will be used to populate the configuration output. If the server private key is missing from the INI file, a new key pair will be generated using libsodium which will then be used to populate the configuration output. If a WireGuard client public key is present, it will be used to populate the endpoint section of the configuration output. If this public key is missing, a new key pair will be generated and used to populate the configuration output. A missing client public key will also trigger the output of a WireGuard client configuration file with the server public key and the client key pair populated and ready to be imported into the user's WireGuard client. Lastly, if a hostname and domain are included in the INI, they will be used to make an FQDN to populate the `Endpoint` field in the WireGuard client configuration file.
## API Key Bootstrap
Another optional feature is to add a root API key bootstrap. If a `API` section is provided in the INI, then the provided key and secret will be appended to the user section in the configuration for the root user. This API key can be used immediately after install is complete to make further configuration changes to the OPNsense instance.
## Web Console Shortcut
For convenience, an optional macOS shortcut file can be created that leads to the OPNsense console with one click.
## ISO Image
An alterative output format is an ISO image that contains the `config.xml` file in a directory named `conf` as expected by the OPNsense Importer. With OPNsense version 22.1.7, the importer is able to detect ISO9660 and grab the config. This mode of delivery can be used in a virtualization environment such as Proxmox which has shared ISO storage. One ISO can be used simultaneously in multiple OPNsense deployments.
## Installation
```
pip install opnsense-confgen
```
## Command Line Usage
##### Write example INI file then exit
```
oscg -e
```
##### Write XML OPNsense configuration file
```
oscg -f xml
```
##### Write ISO image containing OPNsense configuration file
```
oscg -f iso
```
##### Write both XML and ISO configuration files
```
oscg -f both
```
##### Write macOS shortcut file
```
oscg -s
```
##### Delete all existing output files
```
oscg -c
```
##### Print the OPNsense console URL
```
oscg -u
```
##### Print the XML config for debugging
```
oscg -d
```
## Class Usage
### Example Code
The following example will read a file `opnsense_config.ini` and instantiate the class with it. The OPNsense configuration result is an XML text string and the WireGuard result is a ConfigParser generated string. The config input used to instantiate the class can be a ConfigParser instance or it can be a dictionary object with the same section and field structure as what would result from reading the INI.
```
import configparser
import pathlib
import oscg.core
ini_config = configparser.ConfigParser()
ini_config.read('opnsense_config.ini')
gc = oscg.core.GenerateConfigs(ini_config)
opnsense_config = gc.os_config
wireguard_config = gc.wg_config
macos_shortcut = gc.mac_shortcut
config_path = pathlib.Path('config.xml')
config_path.write_text(opnsense_config)
wg_path = pathlib.Path('WGBootstrap.conf')
wg_path.write_text(wireguard_config)
sc_path = pathlib.Path('WGBootstrap.url')
sc_path.write_text(macos_shortcut)
```
### Example INI
```
[Host]
hostname = firewall
domain = example.com
dns = 198.51.100.100
[WAN]
if = vtnet0
ip = 192.0.2.10
subnet = 24
gateway = 192.0.2.1
[LAN]
if = vtnet1
ip = 172.16.0.1
subnet = 24
description = Workstations
dhcp_start = 172.16.0.10
dhcp_end = 172.16.0.250
[OPT1]
if = vtnet2
ip = 172.17.0.1
subnet = 24
description = Servers
dhcp_start = 172.17.0.10
dhcp_end = 172.17.0.250
[OPT2]
if = vtnet3
ip = 172.18.0.1
subnet = 24
description = DMZ
dhcp_start = 172.18.0.10
dhcp_end = 172.18.0.250
[WGB]
port = 51821
server_privkey = AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
server_ip = 172.19.0.1/24
client_ip = 172.19.0.2/32
client_pubkey = AgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIC
[API]
key = AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
secret = $6$$AgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIC
```
**Note:** The keys in the example above are deliberately malformed so that they are not accidentally used in a real deployment.
### Example INI Section for Optional Interface without DHCP
```
[OPT2]
if = vtnet3
ip = 172.18.0.1
subnet = 24
description = DMZ
```
### Example INI section for WireGuard Bootstrap which will generate a client configuration
```
[WGB]
port = 51821
server_privkey = AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
server_ip = 172.19.0.1/24
client_ip = 172.19.0.2/32
```
### Example INI section for WireGuard Bootstrap which will generate a new server key pair and a client configuration
```
[WGB]
port = 51821
server_ip = 172.19.0.1/24
client_ip = 172.19.0.2/32
```
## Dependencies
1. PyNaCl Python binding to libsodium https://pynacl.readthedocs.io/en/latest/
2. pycdlib https://clalancette.github.io/pycdlib/
## Known Issues
The automatically created `WireGuard (Group)` interface that is normally part of the WireGuard plugin is removed during the OPNsense install process.
To workaround this issue, login to the OPNsense console, navigate to the `Interfaces` menu and select `Assignments`. In the pane that appears on the right, click `Save`. This will recreate the `WireGuard (Group)` interface.
The Github issue for this bug is here: https://github.com/opnsense/core/issues/5768
Raw data
{
"_id": null,
"home_page": null,
"name": "opnsense-confgen",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12.3",
"maintainer_email": null,
"keywords": "opnsense, configuration, firewall, install",
"author": "Malwarology LLC",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a4/fe/57f8afc75ec8fa6134ac55afcbf63a61075f8830236f943b24e50bdef411/opnsense_confgen-2.3.2.tar.gz",
"platform": null,
"description": "# OPNsense Configuration Generator\n\nThis package takes a Python ConfigParser formatted INI file and generates a ready to use config.xml file for OPNsense. The intent is for the file to be used during the installation process by the OPNsense Importer. The end result is a minimal working configuraion with interfaces fully configured. Included in this package are a command line interface and a class which is importable into Python scripts and other applications.\n\nMore information about the OPNsense importer can be found [here](https://docs.opnsense.org/manual/install.html#opnsense-importer).\n\nThere are five potential output files:\n\n| Filename | Content |\n|--------- | ------- |\n| config.xml | OPNsense configuration XML |\n| config.iso | OPNsense configuration XML in a CD image |\n| WGBootstrap.conf | WireGuard client configuration |\n| WGBootstrap.url | macOS shortcut leading to OPNsense console |\n| opnsense_config_example.ini | Example configuration INI |\n\n## Optional Interfaces\n\nAny number of optional network interfaces beyond the basic WAN and LAN can be included in the INI as `OPT` sections. Each may include a description that would result in the display name of the interface being `Servers` rather than `OPT2` for example.\n\n## DHCP Configuration\n\nIf an `OPT` section of the INI contains a `dhcp_start` field, then a DHCP configuration section will be included that corresponds to that interface.\n\n## WireGuard Bootstrap\n\nAn optional feature is the WireGuard bootstrap. If a `WGB` section is provided in the INI, then a working WireGuard VPN interface will be available for immediate connection. The interface occupies instance 1, therefore the device will be `wg1` rather than `wg0`. This is to allow the user or automation to create a permanent WireGuard VPN interface at `wg0` then delete the bootstrap. The goal with this process is to have the permanent WireGaurd private key generated on the OPNsense instance and never to have been transmitted at any time.\n\nThe WireGuard bootstrap has a number of options. If the INI contains a server private key, it will be used to derive a public key. That resulting key pair will be used to populate the configuration output. If the server private key is missing from the INI file, a new key pair will be generated using libsodium which will then be used to populate the configuration output. If a WireGuard client public key is present, it will be used to populate the endpoint section of the configuration output. If this public key is missing, a new key pair will be generated and used to populate the configuration output. A missing client public key will also trigger the output of a WireGuard client configuration file with the server public key and the client key pair populated and ready to be imported into the user's WireGuard client. Lastly, if a hostname and domain are included in the INI, they will be used to make an FQDN to populate the `Endpoint` field in the WireGuard client configuration file.\n\n## API Key Bootstrap\n\nAnother optional feature is to add a root API key bootstrap. If a `API` section is provided in the INI, then the provided key and secret will be appended to the user section in the configuration for the root user. This API key can be used immediately after install is complete to make further configuration changes to the OPNsense instance.\n\n## Web Console Shortcut\n\nFor convenience, an optional macOS shortcut file can be created that leads to the OPNsense console with one click.\n\n## ISO Image\n\nAn alterative output format is an ISO image that contains the `config.xml` file in a directory named `conf` as expected by the OPNsense Importer. With OPNsense version 22.1.7, the importer is able to detect ISO9660 and grab the config. This mode of delivery can be used in a virtualization environment such as Proxmox which has shared ISO storage. One ISO can be used simultaneously in multiple OPNsense deployments.\n\n## Installation\n\n```\npip install opnsense-confgen\n```\n\n## Command Line Usage\n\n##### Write example INI file then exit\n\n```\noscg -e\n```\n\n##### Write XML OPNsense configuration file\n\n```\noscg -f xml\n```\n\n##### Write ISO image containing OPNsense configuration file\n\n```\noscg -f iso\n```\n\n##### Write both XML and ISO configuration files\n\n```\noscg -f both\n```\n\n##### Write macOS shortcut file\n\n```\noscg -s\n```\n\n##### Delete all existing output files\n\n```\noscg -c\n```\n\n##### Print the OPNsense console URL\n\n```\noscg -u\n```\n\n##### Print the XML config for debugging\n\n```\noscg -d\n```\n\n## Class Usage\n\n### Example Code\n\nThe following example will read a file `opnsense_config.ini` and instantiate the class with it. The OPNsense configuration result is an XML text string and the WireGuard result is a ConfigParser generated string. The config input used to instantiate the class can be a ConfigParser instance or it can be a dictionary object with the same section and field structure as what would result from reading the INI.\n\n```\nimport configparser\nimport pathlib\nimport oscg.core\n\nini_config = configparser.ConfigParser()\nini_config.read('opnsense_config.ini')\n\ngc = oscg.core.GenerateConfigs(ini_config)\nopnsense_config = gc.os_config\nwireguard_config = gc.wg_config\nmacos_shortcut = gc.mac_shortcut\n\nconfig_path = pathlib.Path('config.xml')\nconfig_path.write_text(opnsense_config)\n\nwg_path = pathlib.Path('WGBootstrap.conf')\nwg_path.write_text(wireguard_config)\n\nsc_path = pathlib.Path('WGBootstrap.url')\nsc_path.write_text(macos_shortcut)\n```\n\n### Example INI\n\n```\n[Host]\nhostname = firewall\ndomain = example.com\ndns = 198.51.100.100\n\n[WAN]\nif = vtnet0\nip = 192.0.2.10\nsubnet = 24\ngateway = 192.0.2.1\n\n[LAN]\nif = vtnet1\nip = 172.16.0.1\nsubnet = 24\ndescription = Workstations\ndhcp_start = 172.16.0.10\ndhcp_end = 172.16.0.250\n\n[OPT1]\nif = vtnet2\nip = 172.17.0.1\nsubnet = 24\ndescription = Servers\ndhcp_start = 172.17.0.10\ndhcp_end = 172.17.0.250\n\n[OPT2]\nif = vtnet3\nip = 172.18.0.1\nsubnet = 24\ndescription = DMZ\ndhcp_start = 172.18.0.10\ndhcp_end = 172.18.0.250\n\n[WGB]\nport = 51821\nserver_privkey = AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\nserver_ip = 172.19.0.1/24\nclient_ip = 172.19.0.2/32\nclient_pubkey = AgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIC\n\n[API]\nkey = AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\nsecret = $6$$AgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIC\n```\n\n**Note:** The keys in the example above are deliberately malformed so that they are not accidentally used in a real deployment.\n\n### Example INI Section for Optional Interface without DHCP\n\n```\n[OPT2]\nif = vtnet3\nip = 172.18.0.1\nsubnet = 24\ndescription = DMZ\n```\n\n### Example INI section for WireGuard Bootstrap which will generate a client configuration\n\n```\n[WGB]\nport = 51821\nserver_privkey = AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\nserver_ip = 172.19.0.1/24\nclient_ip = 172.19.0.2/32\n```\n\n### Example INI section for WireGuard Bootstrap which will generate a new server key pair and a client configuration\n\n```\n[WGB]\nport = 51821\nserver_ip = 172.19.0.1/24\nclient_ip = 172.19.0.2/32\n```\n\n## Dependencies\n\n1. PyNaCl Python binding to libsodium https://pynacl.readthedocs.io/en/latest/\n2. pycdlib https://clalancette.github.io/pycdlib/\n\n## Known Issues\n\nThe automatically created `WireGuard (Group)` interface that is normally part of the WireGuard plugin is removed during the OPNsense install process.\n\nTo workaround this issue, login to the OPNsense console, navigate to the `Interfaces` menu and select `Assignments`. In the pane that appears on the right, click `Save`. This will recreate the `WireGuard (Group)` interface.\n\nThe Github issue for this bug is here: https://github.com/opnsense/core/issues/5768\n",
"bugtrack_url": null,
"license": null,
"summary": "Generate OPNsense configuration XML",
"version": "2.3.2",
"project_urls": {
"Homepage": "https://github.com/malwarology/opnsense-confgen",
"Issues": "https://github.com/malwarology/opnsense-confgen/issues"
},
"split_keywords": [
"opnsense",
" configuration",
" firewall",
" install"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "541e6e51038319740c52e452f432c7c7e6325a5ecce573cbb312439d47995884",
"md5": "2d082c0e25a96bb0af93d417c53ba1a6",
"sha256": "7ed7f544e1f5192203998502212edf39d6877300190d961b4e71c4a8a38aeecc"
},
"downloads": -1,
"filename": "opnsense_confgen-2.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d082c0e25a96bb0af93d417c53ba1a6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12.3",
"size": 17807,
"upload_time": "2024-05-25T21:14:19",
"upload_time_iso_8601": "2024-05-25T21:14:19.778644Z",
"url": "https://files.pythonhosted.org/packages/54/1e/6e51038319740c52e452f432c7c7e6325a5ecce573cbb312439d47995884/opnsense_confgen-2.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a4fe57f8afc75ec8fa6134ac55afcbf63a61075f8830236f943b24e50bdef411",
"md5": "1d1140798567e9228e3f9e9f90cc5749",
"sha256": "6765a1d9057a2ba09f485add45c81ecf2d223836a444ca252178f42954a1ae7e"
},
"downloads": -1,
"filename": "opnsense_confgen-2.3.2.tar.gz",
"has_sig": false,
"md5_digest": "1d1140798567e9228e3f9e9f90cc5749",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12.3",
"size": 23899,
"upload_time": "2024-05-25T21:14:20",
"upload_time_iso_8601": "2024-05-25T21:14:20.933225Z",
"url": "https://files.pythonhosted.org/packages/a4/fe/57f8afc75ec8fa6134ac55afcbf63a61075f8830236f943b24e50bdef411/opnsense_confgen-2.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-25 21:14:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "malwarology",
"github_project": "opnsense-confgen",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "opnsense-confgen"
}
JSON
