opnsense

README

OPNsense DNS module for Caddy

This package contains a DNS provider module for Caddy. It is used to manage DNS records in OPNsense dnsmasq or unbound. You can combine it with Caddys DNS-01 ACME challenge to get valid TLS certs for internal domains.

Caddy module name

dns.providers.opnsense

Config examples

To use this module for the internal domain overwrite, together with mholt/caddy-dynamicdns, with the dynamic_domains option like so:

dns_service can be dnsmasq or unbound

{
	"apps": {
		"dynamic_dns": {
			"dns_provider": {
				"name": "opnsense",
				"host": "{env.OPNSENSE_HOSTNAME}",
				"api_key": "{env.OPNSENSE_API_KEY}",
				"api_secret_key": "{env.OPNSENSE_API_SECRET_KEY}",
				"dns_service": "dnsmasq",
				"insecure": true,
				"entry_description": "Managed by Caddy"
			},
			"domains": {
				"example.com": [""]
			},
			"ip_sources": [
				{
					"source": "interface",
					"name": "eth0"
				}
			],
			"check_interval": "5m",
			"versions": {
				"ipv4": true,
				"ipv6": true
			},
			"ttl": "1h",
			"dynamic_domains": true
		}
	}
}

or with the Caddyfile:

# globally
{
	dynamic_dns {
		provider opnsense {
			host {env.OPNSENSE_HOSTNAME}
			api_key {env.OPNSENSE_API_KEY}
			api_secret_key {env.OPNSENSE_API_SECRET_KEY}
			dns_service dnsmasq # or unbound
			insecure true # Optional: skip TLS verification for self-signed certs
			entry_description Managed by Caddy # Optional
		}
		domains {
			example.com
		}
		dynamic_domains
		ip_source interface eth0
		check_interval 5m
		ttl 1h
	}
}

Valid local TLS Certs

Here an example using porkbun, but you can use any of the available caddy-dns providers:

{
	dynamic_dns {
		provider opnsense {
			host {env.OPNSENSE_HOSTNAME}
			api_key {env.OPNSENSE_API_KEY}
			api_secret_key {env.OPNSENSE_API_SECRET_KEY}
			dns_service dnsmasq # or unbound
			insecure true # Optional: skip TLS verification for self-signed certs
		}
		domains {
			example.com
		}
		dynamic_domains
		ip_source interface eth0
		check_interval 5m
		ttl 1h
	}
	acme_dns porkbun {
		api_key {env.PORKBUN_API_KEY}
		api_secret_key {env.PORKBUN_API_SECRET_KEY}
	}
}
test_caddy.example.com {
	respond "Welcome to caddy!"
}

Docker usage

If you want to use this inside a docker container use the static ip_source module to set the IP of the docker Host

{
	dynamic_dns {
		provider opnsense {
			host {env.OPNSENSE_HOSTNAME}
			api_key {env.OPNSENSE_API_KEY}
			api_secret_key {env.OPNSENSE_API_SECRET_KEY}
			dns_service dnsmasq # or unbound
			insecure true # Optional: skip TLS verification for self-signed certs
		}
		domains {
			example.com
		}
		dynamic_domains
		ip_source static {env.DOCKER_HOST_IP}
		check_interval 5m
		ttl 1h
	}
	acme_dns porkbun {
		api_key {env.PORKBUN_API_KEY}
		api_secret_key {env.PORKBUN_API_SECRET_KEY}
	}
}
test_caddy.example.com {
	respond "Welcome to caddy!"
}

Docker service discovery

You can also combine this with caddy-docker-proxy. Use the Caddyfile from above and add lables to you docker containers:

    labels:
        caddy: mycontainer.example.com
        caddy.reverse_proxy: "{{upstreams 8080}}"

You will automatically get local DNS entries in OPNsense.

Building with xcaddy

Use xcaddy to build the module:

xcaddy build \
    --with github.com/mietzen/caddy-dns-opnsense \
    --with github.com/mietzen/libdns-opnsense-dnsmasq \
    --with github.com/mietzen/libdns-opnsense-unbound \
    --with github.com/mholt/caddy-dynamicdns

You don't have to buildin both providers you can just use the one you use, e.g. dnsmasq:

xcaddy build \
    --with github.com/mietzen/caddy-dns-opnsense \
    --with github.com/mietzen/libdns-opnsense-dnsmasq \
    --with github.com/mholt/caddy-dynamicdns

You also will most likely add your DNS Provider for ACME, here porkbun:

xcaddy build \
    --with github.com/mietzen/caddy-dns-opnsense \
    --with github.com/mietzen/libdns-opnsense-dnsmasq \
    --with github.com/mholt/caddy-dynamicdns \
    --with github.com/caddy-dns/porkbun

Setting up OPNsense API keys

1. Create a new API-User under System -> Access -> Users

   • Set Scrambled Password to True and make sure Login shell is None

     

   • Set the Permissions for Dnsmasq to: Services: Dnsmasq DNS/DHCP: Settings

     

   • Set the Permissions for Unbound to: Services: Unbound (MVC) & Services: Unbound DNS: Edit Host and Domain Override

     

   • Click Save

2. Click the API-Key Symbol (Postage Stamp?) to create a API Key and click yes.

   

3. Open the downloaded file and copy the API key and secret

Documentation

Index

• type Provider
  • func (p *Provider) AppendRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)
  • func (Provider) CaddyModule() caddy.ModuleInfo
  • func (p *Provider) DeleteRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)
  • func (p *Provider) GetRecords(ctx context.Context, zone string) ([]libdns.Record, error)
  • func (p *Provider) Provision(ctx caddy.Context) error
  • func (p *Provider) SetRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)
  • func (p *Provider) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Types

type Provider

type Provider struct {
	// Host is the OPNsense hostname or IP address (e.g., "opnsense.example.com" or "192.168.1.1")
	Host string `json:"host,omitempty"`
	// APIKey is the OPNsense API key
	APIKey string `json:"api_key,omitempty"`
	// APISecretKey is the OPNsense API secret key
	APISecretKey string `json:"api_secret_key,omitempty"`
	// DNSService specifies which DNS service to use: "dnsmasq" or "unbound"
	DNSService string `json:"dns_service,omitempty"`
	// Insecure skips TLS certificate verification (for self-signed certificates)
	Insecure bool `json:"insecure,omitempty"`
	// EntryDescription is set on created host entries (defaults to "Managed by Caddy")
	EntryDescription string `json:"entry_description,omitempty"`
	// contains filtered or unexported fields
}

Provider lets Caddy read and manipulate DNS records hosted by OPNsense.

func (*Provider) AppendRecords

func (p *Provider) AppendRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)

AppendRecords adds records to the zone. It returns the records that were added.

func (Provider) CaddyModule

func (Provider) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*Provider) DeleteRecords

func (p *Provider) DeleteRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)

DeleteRecords deletes the records from the zone.

func (*Provider) GetRecords

func (p *Provider) GetRecords(ctx context.Context, zone string) ([]libdns.Record, error)

GetRecords lists all the records in the zone.

func (*Provider) Provision

func (p *Provider) Provision(ctx caddy.Context) error

Provision sets up the module. Implements caddy.Provisioner.

func (*Provider) SetRecords

func (p *Provider) SetRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)

SetRecords sets the records in the zone, either by updating existing records or creating new ones.

func (*Provider) UnmarshalCaddyfile

func (p *Provider) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the DNS provider from Caddyfile tokens. Syntax:

opnsense {
    host <host>
    api_key <api_key>
    api_secret_key <api_secret_key>
    dns_service <dnsmasq|unbound>
    insecure <true|false>
    entry_description <description>
}