pfSense API Complete Command Reference

Complete command reference for managing pfSense firewall via REST API using netapi.

Overview

pfSense REST API provides programmatic access to firewall configuration. Authentication uses API key + secret.

# Load credentials from dsec
DSEC_SECURITY_MODE=permissive eval $(dsec source d000 dev/network)

# Or set manually
export PFSENSE_HOST="10.50.1.1"
export PFSENSE_API_KEY="your_api_key"
export PFSENSE_API_SECRET="your_api_secret"

DNS Management

List DNS Entries

Retrieve all DNS host overrides and aliases.

netapi pfsense dns list

Output:

{
  "hosts": [
    {
      "host": "ise-01",
      "domain": "inside.domusdigitalis.dev",
      "ip": "10.50.1.21",
      "descr": "ISE Primary PAN"
    }
  ]
}

Add DNS Entry

Create a new DNS host override.

netapi pfsense dns add \
  --host <HOSTNAME> \
  --domain <DOMAIN> \
  --ip <IP_ADDRESS> \
  --descr "<DESCRIPTION>"

Example:

netapi pfsense dns add \
  --host "ise-02" \
  --domain "inside.domusdigitalis.dev" \
  --ip "10.50.1.22" \
  --descr "ISE Secondary PSN"

Update DNS Entry

Modify existing DNS entry.

netapi pfsense dns update \
  --host <HOSTNAME> \
  --domain <DOMAIN> \
  --new-ip <NEW_IP> \
  --new-descr "<NEW_DESCRIPTION>"

Delete DNS Entry

Remove DNS host override.

netapi pfsense dns delete \
  --host <HOSTNAME> \
  --domain <DOMAIN>

VLAN Management

List VLANs

Retrieve all configured VLANs.

netapi pfsense vlan list

Output:

{
  "vlans": [
    {
      "if": "igb0",
      "tag": "10",
      "descr": "MANAGEMENT",
      "vlanif": "igb0.10"
    },
    {
      "if": "igb0",
      "tag": "50",
      "descr": "RESEARCH",
      "vlanif": "igb0.50"
    }
  ]
}

Create VLAN

Add a new VLAN on physical interface.

netapi pfsense vlan create \
  --interface <PHYSICAL_IF> \
  --tag <VLAN_ID> \
  --descr "<DESCRIPTION>" \
  [--pcp <PRIORITY>]

Example:

netapi pfsense vlan create \
  --interface "igb0" \
  --tag "60" \
  --descr "GUEST-WIFI" \
  --pcp "2"

Parameters: - --interface: Physical interface (e.g., igb0, em0) - --tag: VLAN ID (1-4094) - --descr: Description - --pcp: Priority Code Point (0-7, optional)

Update VLAN

Modify existing VLAN configuration.

netapi pfsense vlan update \
  --vlanif <VLAN_INTERFACE> \
  [--descr "<NEW_DESCRIPTION>"] \
  [--pcp <NEW_PRIORITY>]

Delete VLAN

Remove VLAN configuration.

netapi pfsense vlan delete --vlanif <VLAN_INTERFACE>

Deleting a VLAN will break any interfaces, firewall rules, or DHCP servers using it!

Firewall Rules

List Firewall Rules

Retrieve firewall rules for a specific interface.

netapi pfsense firewall list --interface <INTERFACE_NAME>

Example:

# LAN rules
netapi pfsense firewall list --interface "lan"

# VLAN rules
netapi pfsense firewall list --interface "opt1"

Create Firewall Rule

Add a new firewall rule.

netapi pfsense firewall add \
  --interface <INTERFACE> \
  --action <pass|block|reject> \
  --protocol <tcp|udp|icmp|any> \
  --source <SOURCE> \
  --destination <DESTINATION> \
  [--port <PORT>] \
  [--descr "<DESCRIPTION>"]

Example (Allow SSH from Management):

netapi pfsense firewall add \
  --interface "lan" \
  --action "pass" \
  --protocol "tcp" \
  --source "10.50.1.0/24" \
  --destination "any" \
  --port "22" \
  --descr "Allow SSH from management network"

Example (Block RFC1918 to Internet):

netapi pfsense firewall add \
  --interface "wan" \
  --action "block" \
  --protocol "any" \
  --source "10.0.0.0/8" \
  --destination "any" \
  --descr "Block RFC1918 from WAN"

Update Firewall Rule

Modify existing firewall rule.

netapi pfsense firewall update \
  --interface <INTERFACE> \
  --id <RULE_ID> \
  [--action <pass|block|reject>] \
  [--descr "<NEW_DESCRIPTION>"]

Delete Firewall Rule

Remove firewall rule.

netapi pfsense firewall delete \
  --interface <INTERFACE> \
  --id <RULE_ID>

Apply Firewall Changes

Apply pending firewall rule changes (commit).

netapi pfsense firewall apply

Always apply changes after adding/updating/deleting rules!

DHCP Management

List DHCP Servers

Retrieve DHCP server configurations for all interfaces.

netapi pfsense dhcp list

Get DHCP Server

Retrieve DHCP configuration for specific interface.

netapi pfsense dhcp get --interface <INTERFACE>

Create DHCP Server

Configure DHCP server on an interface.

netapi pfsense dhcp create \
  --interface <INTERFACE> \
  --range-from <START_IP> \
  --range-to <END_IP> \
  --domain <DOMAIN> \
  --dns <DNS_SERVERS> \
  --gateway <GATEWAY_IP>

Example:

netapi pfsense dhcp create \
  --interface "opt2" \
  --range-from "10.60.1.100" \
  --range-to "10.60.1.200" \
  --domain "guest.domusdigitalis.dev" \
  --dns "10.50.1.1,8.8.8.8" \
  --gateway "10.60.1.1"

Add DHCP Static Mapping

Create a DHCP reservation (static mapping).

netapi pfsense dhcp add-static \
  --interface <INTERFACE> \
  --mac <MAC_ADDRESS> \
  --ip <IP_ADDRESS> \
  --hostname <HOSTNAME> \
  [--descr "<DESCRIPTION>"]

Example:

netapi pfsense dhcp add-static \
  --interface "lan" \
  --mac "b4:e9:b8:f6:c8:17" \
  --ip "10.50.1.50" \
  --hostname "chlxsbg" \
  --descr "Dr. Shahab workstation"

List DHCP Static Mappings

Retrieve all DHCP reservations for an interface.

netapi pfsense dhcp list-static --interface <INTERFACE>

Delete DHCP Static Mapping

Remove DHCP reservation.

netapi pfsense dhcp delete-static \
  --interface <INTERFACE> \
  --mac <MAC_ADDRESS>

Routing

List Static Routes

Retrieve all static routes.

netapi pfsense routes list

Add Static Route

Create a new static route.

netapi pfsense routes add \
  --network <NETWORK/PREFIX> \
  --gateway <GATEWAY_IP> \
  [--descr "<DESCRIPTION>"]

Example:

netapi pfsense routes add \
  --network "192.168.100.0/24" \
  --gateway "10.50.1.254" \
  --descr "Route to remote site"

Delete Static Route

Remove static route.

netapi pfsense routes delete --network <NETWORK/PREFIX>

System Management

Get System Information

Retrieve pfSense system details.

netapi pfsense system info

Output:

{
  "hostname": "fw-01",
  "domain": "inside.domusdigitalis.dev",
  "version": "2.7.2-RELEASE",
  "platform": "FreeBSD",
  "uptime": "15 days, 4 hours"
}

Backup Configuration

Download pfSense configuration backup (config.xml).

netapi pfsense backup --output <OUTPUT_FILE>

Example:

netapi pfsense backup --output "/backups/pfsense/config-$(date +%Y%m%d).xml"

Restore Configuration

Restore pfSense configuration from backup.

netapi pfsense restore --input <CONFIG_FILE>

Restoring configuration will reload pfSense. Active connections may be interrupted.

Reboot System

Reboot pfSense firewall.

netapi pfsense system reboot

This will cause downtime! Ensure you have console/IPMI access before rebooting.

Interface Management

List Interfaces

Retrieve all network interfaces.

netapi pfsense interfaces list

Get Interface

Retrieve specific interface configuration.

netapi pfsense interfaces get --name <INTERFACE_NAME>

Update Interface

Modify interface configuration.

netapi pfsense interfaces update \
  --name <INTERFACE_NAME> \
  [--descr "<DESCRIPTION>"] \
  [--ipaddr <IP_ADDRESS>] \
  [--subnet <PREFIX_LENGTH>]

Example:

netapi pfsense interfaces update \
  --name "opt3" \
  --descr "DMZ" \
  --ipaddr "10.70.1.1" \
  --subnet "24"

NAT / Port Forwarding

List NAT Rules

Retrieve all NAT/port forwarding rules.

netapi pfsense nat list

Add NAT Rule

Create a new port forward rule.

netapi pfsense nat add \
  --interface <INTERFACE> \
  --protocol <tcp|udp> \
  --external-port <PORT> \
  --target-ip <INTERNAL_IP> \
  --target-port <PORT> \
  [--descr "<DESCRIPTION>"]

Example (SSH Port Forward):

netapi pfsense nat add \
  --interface "wan" \
  --protocol "tcp" \
  --external-port "2222" \
  --target-ip "10.50.1.50" \
  --target-port "22" \
  --descr "SSH to chlxsbg workstation"

Delete NAT Rule

Remove NAT/port forward rule.

netapi pfsense nat delete --id <RULE_ID>

Common Workflows

Workflow 1: Add New VLAN with DHCP

# Step 1: Create VLAN
netapi pfsense vlan create \
  --interface "igb0" \
  --tag "80" \
  --descr "IOT-DEVICES"

# Step 2: Assign VLAN to interface (via web UI or manual config)

# Step 3: Configure DHCP on VLAN
netapi pfsense dhcp create \
  --interface "opt4" \
  --range-from "10.80.1.100" \
  --range-to "10.80.1.250" \
  --domain "iot.domusdigitalis.dev" \
  --dns "10.50.1.1" \
  --gateway "10.80.1.1"

# Step 4: Add firewall rules
netapi pfsense firewall add \
  --interface "opt4" \
  --action "pass" \
  --protocol "udp" \
  --source "10.80.1.0/24" \
  --destination "any" \
  --port "53" \
  --descr "Allow DNS from IOT"

netapi pfsense firewall add \
  --interface "opt4" \
  --action "block" \
  --protocol "any" \
  --source "10.80.1.0/24" \
  --destination "10.0.0.0/8" \
  --descr "Block IOT to internal networks"

# Step 5: Apply changes
netapi pfsense firewall apply

Workflow 2: DNS Failover Configuration

# Add primary DNS entries
netapi pfsense dns add \
  --host "ise-01" \
  --domain "inside.domusdigitalis.dev" \
  --ip "10.50.1.21" \
  --descr "ISE Primary - Main Site"

# Add secondary DNS entries (same hostname, different IP)
netapi pfsense dns add \
  --host "ise-01-dr" \
  --domain "inside.domusdigitalis.dev" \
  --ip "10.51.1.21" \
  --descr "ISE Primary - DR Site"

Workflow 3: Backup and Restore

# Daily backup script
#!/bin/bash
BACKUP_DIR="/backups/pfsense"
DATE=$(date +%Y%m%d)

# Create backup
netapi pfsense backup --output "${BACKUP_DIR}/config-${DATE}.xml"

# Compress and encrypt
gzip "${BACKUP_DIR}/config-${DATE}.xml"
age -r $(cat ~/.secrets/.metadata/keys/master.age.pub) \
  -o "${BACKUP_DIR}/config-${DATE}.xml.gz.age" \
  "${BACKUP_DIR}/config-${DATE}.xml.gz"

# Remove unencrypted
rm "${BACKUP_DIR}/config-${DATE}.xml.gz"

# Cleanup old backups (keep 30 days)
find "${BACKUP_DIR}" -name "*.age" -mtime +30 -delete

Error Handling

Common Errors

401 Unauthorized:

Check PFSENSE_API_KEY and PFSENSE_API_SECRET
Verify API user has correct privileges

404 Not Found:

Resource doesn't exist
Check interface/VLAN/rule names

422 Unprocessable Entity:

Invalid parameters
Check IP address formats, VLAN ranges

500 Internal Server Error:

pfSense configuration error
Check pfSense logs: /var/log/system.log

Best Practices

  1. Always backup before changes - Use netapi pfsense backup

  2. Test firewall rules - Verify before applying to production

  3. Apply changes immediately - Run firewall apply after rule changes

  4. Use descriptive names - Clear descriptions for rules/VLANs

  5. Monitor after changes - Check logs for unexpected blocks

  6. Version control configs - Git track backups

  7. Automate backups - Daily cron job with encryption

  8. Document network design - Maintain VLAN/subnet documentation

See Also

netapi Documentation