Automating bulk OPNsense Unbound DNS host overrides

I recently deployed OPNsense in my homelab, which I will be using it to setup my VMware Cloud Foundation (VCF) environment. A critical part infrastructure service that is often miss-configured is DNS and OPNsense provides a simple way add your custom DNS entries (forward/reverse) called Host Overrides, which uses Unbound DNS behind the scenes.

Like most, I have a number of DNS entries that I would like to pre-create and the UI is not exactly the quickest for any type of "bulk" operation as each entry is added sequentially.

Luckily, OPNsense does have a REST API for Unbound functions, but the documentation was not very useful as it just direct users to use the browser to extract the JSON payload, while something I am comfortable with, I think that is not what I expected from something called an API Reference ...

In any case, this was a simple enough API, that I was able to create a quick PowerShell script to parse a CSV file that contains the list of FQDN, IP Address and Description and then perform a bulk create since the API itself was also sequential in nature 🙁

Step 1 - Under user management, click on the "ticket" icon to create and download an API key, which will be a file that contains both the key and secret.

Step 2 - Create a CSV file that contains the following columns (FQDN, IP and DESCRIPTION) which should all be self-explanatory which the script will parse

FQDN, IP, DESCRIPTION
bastion.vcf.lab, 172.30.0.4, Bastion
auth.vcf.lab., 172.30.0.5, Auth
inst01.vcb.lab, 172.30.0.6, VCF Installer 1
inst02.vcb.lab, 172.30.0.7, VCF Installer 2

Step 3 - Download the add_opnsense_host_overrides.ps1 script and update the following variables:

• opnsense_uri - The base URI of your OPNsense endpoint (e.g. https://172.30.0.1)
• key - The API key from Step 1
• secret - The API secret from Step 1
• csv_input - The name of the CSV file from Step 2

After saving your changes, you can then run the PowerShell script as shown in the screenshot below to create your desired DNS host override entries, which certainly beats doing this one at a time!