pfSense Commands

Overview

The netapi pfsense command group provides CLI access to pfSense firewalls via REST API.

Prerequisites

Load secrets before using pfSense commands:

eval "$(dsource d000 dev/network)"
export PFSENSE_HOST="10.50.1.1"
export PFSENSE_API_SECRET="$PFSENSE_HQ_01_API_SECRET"

Required environment variables:

Variable Description

Variable	Description
`PFSENSE_HOST`	pfSense hostname or IP (preferred)
`PFSENSE_IP`	pfSense IP (fallback, deprecated)
`PFSENSE_API_SECRET`	API secret key

PFSENSE_HOST

pfSense hostname or IP (preferred)

PFSENSE_IP

pfSense IP (fallback, deprecated)

PFSENSE_API_SECRET

API secret key

System Information

info

Show pfSense system information:

netapi pfsense info

interfaces

List network interfaces:

netapi pfsense interfaces

arp

Show ARP table:

netapi pfsense arp

leases

Show DHCP leases:

netapi pfsense leases

DNS Resolver Operations

The dns subcommand manages DNS host overrides in the Unbound resolver.

dns list

List all DNS host overrides:

netapi pfsense dns list

dns add

Add a DNS host override:

# Add with auto-apply
netapi pfsense dns add -h nas-01 -d inside.domusdigitalis.dev -i 10.50.1.50

# Add with description
netapi pfsense dns add -h printer-01 -d inside.domusdigitalis.dev -i 10.50.1.100 --descr "Office Printer"

# Add without auto-apply (batch changes)
netapi pfsense dns add -h test-01 -d lab.local -i 10.50.2.10 --no-apply

Options:

Option Required Description

Option	Required	Description
`-h, --host`	Yes	Hostname (e.g., nas-01)
`-d, --domain`	Yes	Domain (e.g., inside.domusdigitalis.dev)
`-i, --ip`	Yes	IP address
`--descr`	No	Description
`-a, --apply`	No	Apply immediately (default: true)

-h, --host

Yes

Hostname (e.g., nas-01)

-d, --domain

Yes

Domain (e.g., inside.domusdigitalis.dev)

-i, --ip

Yes

IP address

--descr

Description

-a, --apply

Apply immediately (default: true)

dns update

Update an existing DNS host override:

# Update IP address
netapi pfsense dns update --id 5 -h nas-01 -d inside.domusdigitalis.dev -i 10.50.1.51

# Update with new description
netapi pfsense dns update --id 5 -h nas-01 -d inside.domusdigitalis.dev -i 10.50.1.51 --descr "New NAS"

Options:

Option Required Description

Option	Required	Description
`--id`	Yes	Override ID to update
`-h, --host`	Yes	Hostname
`-d, --domain`	Yes	Domain
`-i, --ip`	Yes	New IP address
`--descr`	No	Description
`-a, --apply`	No	Apply immediately (default: true)

--id

Yes

Override ID to update

-h, --host

Yes

Hostname

-d, --domain

Yes

Domain

-i, --ip

Yes

New IP address

--descr

Description

-a, --apply

Apply immediately (default: true)

dns delete

Delete a DNS host override:

netapi pfsense dns delete --id 5

# Delete without auto-apply
netapi pfsense dns delete --id 5 --no-apply

dns apply

Apply pending DNS changes:

netapi pfsense dns apply

Use this after making multiple changes with --no-apply.

DNS Domain Overrides

Domain overrides forward entire domain queries to a specific DNS server. Unlike host overrides (individual A records), domain overrides delegate resolution of an entire zone.

dns domain list

List all DNS domain overrides:

netapi pfsense dns domain list

Example Output

                        DNS Domain Overrides
┏━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ ID ┃ Domain                    ┃ IP         ┃ Description        ┃
┡━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ 0  │ inside.domusdigitalis.dev │ 10.50.1.90 │ BIND DNS (bind-01) │
└────┴───────────────────────────┴────────────┴────────────────────┘

dns domain add

Add a DNS domain override:

# Forward internal domain to BIND server
netapi pfsense dns domain add -d inside.domusdigitalis.dev -i 10.50.1.90 --descr "BIND DNS (bind-01)"

# Forward lab domain to lab DNS
netapi pfsense dns domain add -d lab.local -i 192.168.100.10 --descr "Lab DNS"

Options:

Option Required Description

Option	Required	Description
`-d, --domain`	Yes	Domain to forward (e.g., inside.domusdigitalis.dev)
`-i, --ip`	Yes	DNS server IP to forward queries to
`--descr`	No	Description
`--tls-hostname`	No	TLS hostname for DNS-over-TLS
`--forward-tls`	No	Enable forward TLS upstream

-d, --domain

Yes

Domain to forward (e.g., inside.domusdigitalis.dev)

-i, --ip

Yes

DNS server IP to forward queries to

--descr

Description

--tls-hostname

TLS hostname for DNS-over-TLS

--forward-tls

Enable forward TLS upstream

dns domain delete

Delete a DNS domain override:

netapi pfsense dns domain delete --id 0

Options:

Option Required Description

Option	Required	Description
`--id`	Yes	Domain override ID to delete

--id

Yes

Domain override ID to delete

Use Case: BIND Authoritative DNS

Forward all queries for your internal domain to a BIND server:

# Load credentials
export PFSENSE_HOST="10.50.1.1"
export PFSENSE_API_SECRET="$PFSENSE_HQ_01_API_SECRET"

# Configure domain override
netapi pfsense dns domain add -d inside.domusdigitalis.dev -i 10.50.1.90 --descr "BIND DNS (bind-01)"

# Verify
dig @10.50.1.1 bind-01.inside.domusdigitalis.dev +short

This configures pfSense to forward all inside.domusdigitalis.dev queries to the BIND server at 10.50.1.90.

Certificate Operations

The cert subcommand manages SSL/TLS certificates.

cert list

List installed certificates:

netapi pfsense cert list

cert set-webgui

Set the WebGUI certificate via SSH:

# Set certificate by refid
netapi pfsense cert set-webgui -r 62a1b2c3d4e5f

# Use specific SSH alias
netapi pfsense cert set-webgui -r 62a1b2c3d4e5f -s pfsense-backup

# Skip webConfigurator restart
netapi pfsense cert set-webgui -r 62a1b2c3d4e5f --no-restart

The REST API doesn’t support setting the WebGUI certificate, so this uses SSH to run PHP directly on pfSense.

Options:

Option Required Description

Option	Required	Description
`-r, --refid`	Yes	Certificate refid
`-s, --ssh`	No	pfSense SSH host alias (default: pfsense)
`--restart`	No	Restart webConfigurator (default: true)

-r, --refid

Yes

Certificate refid

-s, --ssh

pfSense SSH host alias (default: pfsense)

--restart

Restart webConfigurator (default: true)

cert import-from-certmgr

Import certificate from vault-01 to pfSense:

# Import default domain certificate
netapi pfsense cert import-from-certmgr

# Import specific domain
netapi pfsense cert import-from-certmgr -D guest.domusdigitalis.dev

# Import without setting as WebGUI cert
netapi pfsense cert import-from-certmgr --no-webgui

# Custom certmgr host
netapi pfsense cert import-from-certmgr -c 10.50.1.60 --certmgr-user ansible

This command:

Fetches certificate from vault-01 via SSH
Imports via pfSense REST API
Sets as WebGUI certificate via SSH (if --webgui enabled)

Options:

Option Required Description

Option	Required	Description
`-c, --certmgr`	No	certmgr host (default: 10.50.1.60)
`--certmgr-user`	No	certmgr SSH user (default: ansible)
`-D, --domain`	No	Certificate domain (default: guest.domusdigitalis.dev)
`-d, --descr`	No	Certificate description (default: LetsEncrypt)
`-w, --webgui`	No	Set as WebGUI certificate (default: true)
`-s, --ssh`	No	pfSense SSH host alias (default: pfsense)

-c, --certmgr

certmgr host (default: 10.50.1.60)

--certmgr-user

certmgr SSH user (default: ansible)

-D, --domain

Certificate domain (default: guest.domusdigitalis.dev)

-d, --descr

Certificate description (default: LetsEncrypt)

-w, --webgui

Set as WebGUI certificate (default: true)

-s, --ssh

pfSense SSH host alias (default: pfsense)

Validation Loop

Quick validation of all pfSense commands:

for cmd in info interfaces arp leases; do
  echo "=== pfsense $cmd ==="
  uv run netapi pfsense $cmd 2>&1 | head -20
  echo
done

echo "=== pfsense dns list ==="
uv run netapi pfsense dns list 2>&1 | head -20
echo

echo "=== pfsense cert list ==="
uv run netapi pfsense cert list 2>&1 | head -20