OPNsense MCP Server by lucamarien

Create a new firewall alias (IP list, network group, port group, etc.).

Use this when you need to create a reusable alias for use in firewall rules. Aliases group IPs, networks, or ports under a single name.

This does NOT require savepoint protection — aliases are metadata definitions that only affect traffic when referenced by a firewall rule.

Parameters:

• name: alias name (alphanumeric and underscores only, no spaces)
• alias_type: 'host' (IPs), 'network' (CIDRs), 'port' (ports/ranges), 'urltable' (URL-based IP list), 'geoip' (country codes)
• content: alias entries separated by newlines. For GeoIP, use country codes (one per line, e.g. 'DE\nFR\nNL'). For host/network, use IPs/CIDRs.
• description: human-readable description

Returns: dict with 'result' (str) and 'uuid' (str) of the new alias.

Create a new Dynamic DNS account and apply the configuration.

Use this to register a hostname with a DDNS provider so the firewall automatically updates the DNS record when the public IP changes.

Add an Unbound DNS host override (A/AAAA record) and apply immediately.

Use this when you need to create a local DNS record that resolves a hostname to a specific IP address. Useful for split-horizon DNS, internal services, or overriding external DNS for specific hosts.

Changes are applied immediately (Unbound is reconfigured automatically). DNS overrides cannot be auto-reverted — verify settings before calling. Use opn_list_dns_overrides to check existing overrides first.

Parameters:

• hostname: the hostname part (e.g. 'myserver')
• domain: the domain part (e.g. 'local.lan')
• server: the IP address to resolve to (IPv4 or IPv6)
• description: optional description

Returns: dict with 'result', 'uuid', 'hostname', 'server', and 'applied' status.

Add domains to a DNSBL allowlist (whitelist) without overwriting existing entries.

Use this when a domain is blocked by DNSBL and you need to allowlist it (e.g. googleads.g.doubleclick.net blocking YouTube). Existing allowlist entries are preserved. Changes are applied immediately.

Get the UUID from opn_list_dnsbl first.

Parameters:

• uuid: blocklist UUID from opn_list_dnsbl
• domains: domains to add, comma or newline-separated

Returns: dict with 'added' (list), 'already_present' (list), 'dnsbl_status', and 'service_status'.

Create a new dnsmasq DHCP range and apply the configuration.

Use this to add DHCPv4 or DHCPv6 address ranges with optional Router Advertisement (RA) configuration.

Create a new firewall rule category.

Use this when you need to create a category for organizing firewall rules. Categories are metadata — creating one does not affect traffic or rules.

Parameters:

• name: category name (1-255 chars, no commas)
• color: hex color code without '#' (e.g. 'ff0000' for red, default '000000')

Returns: dict with 'result' (str), 'uuid' (str), and 'name' (str).

Create a new MVC firewall filter rule with savepoint protection where supported.

Use this when you need to add a firewall rule.

Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out.

IMPORTANT: This creates MVC rules (Settings > Firewall > Automation), not legacy GUI rules.

Parameters:

• action: 'pass', 'block', or 'reject'
• direction: 'in' or 'out'
• interface: interface name (e.g. 'lan', 'wan', 'opt1')
• ip_protocol: 'inet' (IPv4), 'inet6' (IPv6), or 'inet46' (dual-stack)
• protocol: 'any', 'TCP', 'UDP', 'TCP/UDP', 'ICMP', etc.
• source_net: source address/network or 'any'
• source_not: invert source match (True = NOT source_net)
• source_port: source port number or range, or empty for any
• destination_net: destination address/network or 'any'
• destination_not: invert destination match (True = NOT destination_net, e.g. !Private_Networks)
• destination_port: port number or range (e.g. '80', '1000-2000'), or empty for any
• gateway: force traffic via specific gateway (e.g. 'WAN_GW') for policy routing, or empty for default
• log: enable logging for this rule (default: off)
• quick: first-match wins (default: True). Set False for last-match-wins logic
• sequence: rule ordering within priority group (default: 1, higher = later)
• categories: comma-separated category UUIDs to assign to this rule
• description: human-readable rule description

Returns: dict with 'revision' (str), 'uuid' (str), and 'result' (str).

Create essential ICMPv6 firewall rules required for IPv6 operation.

Use this when setting up IPv6 on an interface. ICMPv6 is MANDATORY for IPv6 — without it, Neighbor Discovery (NDP), Router Advertisements (RA), and Path MTU Discovery (PMTUD) all break.

Creates 5 rules per RFC 4890:

1. NDP Neighbor Solicitation (link-local -> multicast)
2. NDP Neighbor Advertisement (link-local -> any)
3. NDP Router Solicitation (link-local -> all-routers multicast)
4. NDP Router Advertisement (link-local -> all-nodes multicast)
5. ICMPv6 Echo (ping6) inbound

Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out.

Parameters:

• interface: target interface (e.g. 'lan', 'opt1', 'opt2')

Returns: dict with 'revision' (str), 'rules' (list of created UUIDs), and instructions to confirm.

Create a NAT port forwarding rule with savepoint protection where supported.

Use this when you need to forward an external port to an internal host. Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out.

Parameters:

• destination_port: external port to forward (e.g. '8080', '3000-3010') — required
• target_ip: internal IP address to forward to (e.g. '192.168.1.100') — required
• interface: source interface (default 'wan')
• protocol: 'TCP', 'UDP', or 'TCP/UDP' (default 'TCP')
• target_port: internal port (default: same as destination_port)
• description: human-readable description

Returns: dict with 'revision' (str), 'uuid' (str), and 'result' (str).

Get the ARP table showing IP-to-MAC address mappings.

Use this when you need to find which MAC address is associated with an IP, identify devices on a network segment, or troubleshoot connectivity. Returns: dict with ARP entries including ip, mac, intf, and hostname fields.

Enable and configure the mDNS Repeater to relay multicast DNS between interfaces.

Use this to set up cross-VLAN mDNS discovery. The repeater relays mDNS packets (224.0.0.251:5353) between selected interfaces, enabling HomeKit, Chromecast, AirPlay, and other mDNS-based device discovery across VLANs.

Confirm pending firewall changes, cancelling the 60-second auto-rollback.

Use this AFTER applying firewall changes (rule add/edit/delete) to make them permanent. If not called within 60 seconds of applying, OPNsense automatically reverts all changes for safety.

Only relevant on OPNsense < 26.7. Newer versions have no savepoint API; there the write tools return an empty revision and this call is a no-op. Returns: dict with confirmation status, or status 'not_applicable'.

List CrowdSec security alerts (detected threats and attacks).

Use this when you need to review security events detected by CrowdSec, including brute-force attempts, port scans, and other threats. Note: Requires the CrowdSec plugin (os-crowdsec). Returns: dict with 'rows' (list of alerts) and 'rowCount' (total).

Get CrowdSec security engine status and active decisions summary.

Use this when you need to check if CrowdSec is running, see how many active security decisions (bans/captchas) are in effect, and get a quick overview of the threat protection state. Note: Requires the CrowdSec plugin (os-crowdsec). Returns: dict with 'service_status', 'decisions_count', and 'alerts_count'.

Delete a firewall alias by UUID.

IMPORTANT: Check if any firewall rules reference this alias BEFORE deleting. Deleting an alias that is referenced by rules may cause those rules to stop matching traffic. Use opn_list_firewall_rules to check for references first.

This does NOT use savepoint protection — aliases are metadata definitions. The deletion takes effect immediately.

Use opn_list_firewall_aliases first to find the UUID. Returns: dict with 'result' (str) and 'uuid' (str).

Delete a Dynamic DNS account by UUID and apply the configuration.

The deletion is applied immediately (ddclient is reconfigured automatically). Use opn_list_ddns_accounts first to find the UUID. Returns: dict with 'result' (str), 'uuid' (str), and 'reconfigure_status'.

Delete an Unbound DNS host override by UUID and apply immediately.

The deletion is applied immediately (Unbound is reconfigured automatically). DNS changes cannot be auto-reverted — verify the UUID before calling. Use opn_list_dns_overrides first to find the UUID. Returns: dict with 'result' (str), 'uuid' (str), and 'applied' status.

Delete a dnsmasq DHCP range by UUID and apply the configuration.

The deletion is applied immediately (dnsmasq is reconfigured automatically). Use opn_list_dnsmasq_ranges first to find the UUID. Returns: dict with 'result' (str), 'uuid' (str), and 'reconfigure_status'.

Delete a firewall rule category by UUID with savepoint protection where supported.

IMPORTANT: Reassign rules to other categories BEFORE deleting to avoid orphaned category references. Use opn_list_firewall_categories to find categories and opn_set_rule_categories to reassign rules first.

System default categories (auto=1) cannot be deleted. Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Returns: dict with 'revision' (str) for confirming and 'result' (str).

Delete a firewall filter rule by UUID with savepoint protection where supported.

Use this when you need to remove an existing MVC firewall rule.

Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_firewall_rules first to find the UUID of the rule to delete. Returns: dict with 'revision' (str) for confirming and 'result' (str).

Delete a NAT port forwarding rule by UUID with savepoint protection where supported.

Use this when you need to remove an existing NAT rule.

Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_nat_rules first to find the UUID of the rule to delete. Returns: dict with 'revision' (str) for confirming and 'result' (str).

Perform a DNS lookup from the OPNsense firewall.

Use this when you need to test DNS resolution from the firewall's perspective, verify Unbound is resolving correctly, or check if a specific DNS server returns expected results. Returns: dict with 'result' (str) and 'response' (DNS query results).

Get Unbound DNS resolver statistics (queries, cache hits, uptime).

Use this when you need to check DNS resolver performance, cache hit rates, or troubleshoot DNS resolution issues. Returns: dict with resolver statistics fields.

Download OPNsense config.xml backup as raw XML.

Use this ONLY when you need a full XML backup for archival purposes. For analyzing specific config sections, use opn_scan_config to build a cached inventory, then opn_get_config_section to query individual sections.

By default, sensitive data (passwords, keys, secrets) is redacted. Returns: dict with 'config_xml' (str), 'stripped' (bool), 'size_bytes' (int).

Get recent firewall log entries (blocked and passed packets).

Use this when you need to check what traffic has been blocked or passed, troubleshoot connectivity issues, or audit firewall activity. All filter parameters are optional substring matches applied client-side. Returns: dict with 'entries' (list of log rows) and 'total' (count after filtering).

Get gateway status including dpinger health checks.

Use this when you need to check if WAN gateways are up, their latency, packet loss, or failover state. Returns: dict with gateway items including status, loss, and delay fields.

Get a specific configuration section as structured JSON.

Use this after opn_scan_config to drill into a specific area of the OPNsense configuration. If the config hasn't been scanned yet, it will be loaded automatically.

Available sections vary by OPNsense installation. Common sections include: system, interfaces, vlans, filter (legacy firewall rules), nat, OPNsense (MVC plugin config), unbound, dnsmasq, dhcpd, staticroutes, syslog.

The 'filter' section is particularly useful — it contains legacy GUI firewall rules that are NOT visible via opn_list_firewall_rules.

Returns: dict with 'section' name and 'data' (structured config data).

Get full DNSBL configuration for a specific blocklist by UUID.

Use this when you need to see all available providers and their selection state, current allowlist/blocklist entries, and other DNSBL settings. Get the UUID from opn_list_dnsbl first.

Returns: dict with 'selected_providers', 'available_providers', 'allowlists', 'blocklists', 'wildcards', and config fields.

Create a new HAProxy resource.

Use this to add frontends, backends, servers, actions, ACLs, health checks, error files, resolvers, or mailers.

The config dict contains field name-value pairs. Only specify fields you want to set — the API fills in defaults for omitted fields.

Health check example:

• config={"name": "hc_web", "type": "http", "interval": "5000", "checkport": "8080", "http_method": "get", "http_uri": "/", "http_version": "http11"}
• For apps returning non-2xx (e.g. 401 behind auth), add: "http_expressionEnabled": "1", "http_expression": "rstatus", "http_value": "^[2-4][0-9]{2}$"
• After creating, link to a backend with opn_haproxy_update: config={"healthCheck": "<health-check-uuid>"}

IPv6 examples:

• Frontend bind: config={"name": "web-v6", "bind": "[::]:443,0.0.0.0:443", "mode": "http", "ssl_enabled": "1", "defaultBackend": "<backend-uuid>"}
• Server address: config={"name": "srv1", "address": "2001:db8::1", "port": "8080"}
• Backend resolvePrefer: config={"name": "pool1", "mode": "http", "algorithm": "roundrobin", "resolvePrefer": "ipv6"}

NOTE: Changes are NOT applied until you call opn_reconfigure_haproxy. Call opn_haproxy_configtest first to validate the configuration.

Returns: dict with 'result' (str) and 'uuid' (str) of the new resource.

Validate HAProxy configuration syntax before applying.

Use this BEFORE calling opn_reconfigure_haproxy to verify the configuration is valid. This runs 'haproxy -c' internally and reports any syntax errors.

Returns: dict with validation result (typically 'status' key).

Delete a HAProxy resource by UUID.

IMPORTANT: Check for dependencies before deleting:

• Delete servers before deleting backends that reference them
• Delete actions/ACLs before deleting frontends/backends that link them
• Delete backends before deleting frontends that use them as defaultBackend

Resource types: frontends, backends, servers, actions, acls, healthchecks, errorfiles, resolvers, mailers.

NOTE: Changes are NOT applied until you call opn_reconfigure_haproxy.

Returns: dict with 'result' indicating success.

Get detailed configuration for a specific HAProxy resource.

Use this to inspect all fields of a single resource before modifying it. Returns the full field set including SSL, tuning, persistence, and linked resources.

Resource types: frontends, backends, servers, actions, acls, healthchecks, errorfiles, resolvers, mailers.

Returns: dict with the resource type as key containing all field values.

Search HAProxy resources by type.

Use this to list and search any HAProxy resource. All resource types use the same paginated search pattern.

Resource types and their key fields:

• frontends: name, bind (IPv6: [::]:443), mode (http/ssl/tcp), ssl_enabled, defaultBackend
• backends: name, mode, algorithm (roundrobin/leastconn/source), linkedServers, healthCheck
• servers: name, address (IPv4/IPv6), port, mode (active/backup/disabled), weight, ssl
• actions: name, testType, operator (AND/OR), linkedAcls, useBackend
• acls: name, expression, negate
• healthchecks: name, type (http/tcp/agent/ldap/mysql/pgsql/redis/smtp), interval
• errorfiles: name, code (HTTP status), content
• resolvers: name, nameserver, timeout
• mailers: name, mailserver, port

Returns: dict with 'rows' (list of resources) and 'rowCount' (total).

Get HAProxy load balancer status and backend health.

Use this when you need to check HAProxy server status, backend availability, or connection statistics. Note: Requires the HAProxy plugin (os-haproxy). Returns: dict with HAProxy status including servers and backends.

Update an existing HAProxy resource.

Use this to modify any field on a HAProxy resource. Only provide the fields you want to change — omitted fields keep their current values.

To enable/disable a resource, set config={"enabled": "1"} or {"enabled": "0"}.

Resource types: frontends, backends, servers, actions, acls, healthchecks, errorfiles, resolvers, mailers.

NOTE: Changes are NOT applied until you call opn_reconfigure_haproxy. Call opn_haproxy_configtest first to validate the configuration.

Returns: dict with 'result' indicating success.

Get per-interface traffic statistics (bytes in/out, packets, errors).

Use this when you need to see network utilization, check for interface errors, or compare traffic across interfaces. Returns: dict keyed by interface name with statistics fields.

Get IPsec VPN tunnel status (IKE and ESP phases).

Use this when you need to check IPsec site-to-site tunnel health, see connected peers, or troubleshoot VPN connectivity. Shows both Phase 1 (IKE negotiation) and Phase 2 (ESP/AH tunnels). Note: Requires IPsec to be configured. Based on strongSwan (OPNsense 23.1+). Returns: dict with 'service_status', 'phase1' (IKE sessions), and 'phase2' (tunnels).

Get IPv6 configuration and address status for all interfaces.

Use this when you need a quick overview of which interfaces have IPv6 configured, what addresses are assigned, and the IPv6 method (DHCPv6-PD, Track Interface, SLAAC, static).

Returns: dict with 'interfaces' (list of per-interface IPv6 info) and 'summary' (counts of configured/unconfigured interfaces).

List ACME (Let's Encrypt) certificates and their status.

Use this when you need to check certificate expiry dates, renewal status, or which domains have ACME certificates configured. Note: Requires the ACME client plugin (os-acme-client). Returns: dict with 'rows' (list of certificates) and 'rowCount' (total).

List scheduled cron jobs configured in OPNsense.

Use this when you need to check what scheduled tasks are configured, their frequency, or which commands they run. Returns: dict with 'rows' (list of cron jobs) and 'rowCount' (total).

List Dynamic DNS (DDNS) accounts and their update status.

Use this to check which hostnames have DDNS configured, their current IP addresses, last update time, and which service provider is used.

Key fields: service (provider), hostname, checkip (method), current_ip, current_mtime (last update), interface, enabled.

For IPv6 DDNS: the global setting 'allowipv6' must be enabled AND an IPv6-capable checkip method must be used (e.g. 'cloudflare-ipv6'). Both must be set or IPv6 updates silently fail.

Note: Requires the Dynamic DNS plugin (os-ddclient). Returns: dict with 'rows' (list of accounts) and 'rowCount' (total).

List current DHCPv4 leases from the ISC DHCP server (legacy).

Use this when the OPNsense instance uses the ISC DHCP plugin (os-isc-dhcp). ISC DHCP is legacy and being phased out — most 26.x instances use dnsmasq or Kea. Use opn_scan_config first to check which DHCP backend is active. Returns: dict with DHCP lease entries including address, mac, and hostname fields.

List Unbound DNS forward zones (domain-specific DNS servers).

Use this when you need to check which domains are forwarded to specific upstream DNS servers or DNS-over-TLS resolvers. Returns: dict with 'rows' (list of forward zones) and 'rowCount' (total).

List Unbound DNS host overrides (local DNS records).

Use this when you need to see which hostnames are overridden to specific IP addresses in the local DNS resolver. Returns: dict with 'rows' (list of overrides) and 'rowCount' (total).

List DNSBL (DNS Blocklist) configurations with providers and status.

Use this when you need to see which DNS blocklists are configured, which providers are active, and what allowlist/blocklist entries exist. Use opn_get_dnsbl with a UUID from the results for full details. Returns: dict with 'rows' (list of blocklist configs) and 'rowCount' (total).

List current DHCPv4 and DHCPv6 leases from the dnsmasq DNS/DHCP server.

Use this when the OPNsense instance uses dnsmasq for DHCP (default in 26.x). dnsmasq is a lightweight combined DNS/DHCP server that handles both DHCPv4 and DHCPv6. IPv6 leases appear alongside IPv4 leases in the results. Use opn_scan_config first to check which DHCP backend is active. Returns: dict with 'rows' (list of leases) and 'rowCount' (total).

List dnsmasq DHCP ranges (both DHCPv4 and DHCPv6 with RA config).

Use this to see configured DHCP address pools and Router Advertisement settings for each interface. Both IPv4 and IPv6 ranges appear in the same list.

Key fields: interface, start_addr, end_addr, prefix_len (IPv6) or subnet_mask (IPv4), ra_mode (slaac/ra-stateless/ra-only), ra_priority, lease_time, enabled.

Note: Requires the dnsmasq DNS/DHCP server (os-dnsmasq-dns or built-in). Returns: dict with 'rows' (list of ranges) and 'rowCount' (total).

List firewall alias definitions (IP lists, port groups, GeoIP, URLs).

Use this when you need to see which aliases are defined, their types, or what IP addresses/networks they resolve to. Returns: dict with 'rows' (list of aliases) and 'rowCount' (total).

List firewall rule categories.

Use this when you need to see which categories exist, check their names and colors, or find category UUIDs for assigning to rules. Returns: dict with 'rows' (list of categories) and 'rowCount' (total).

List firewall filter rules configured via the MVC API.

IMPORTANT: This only returns rules created through the OPNsense MVC filter API (Settings > Firewall > Automation). Legacy rules configured via the traditional GUI (Firewall > Rules) are NOT visible through this endpoint. Most users have legacy rules — a result of 0 rules does not mean no rules exist.

Use this when you need to inspect MVC-managed firewall filter rules. Returns: dict with 'rows' (list of rules) and 'rowCount' (total).

List current DHCPv4 leases from the Kea DHCP server.

Use this when the OPNsense instance uses Kea for DHCP (available since 24.7). Kea is the modern replacement for ISC DHCP, recommended for HA setups. Use opn_scan_config first to check which DHCP backend is active. Returns: dict with 'rows' (list of leases) and 'rowCount' (total).

List NAT port forwarding (DNAT) rules.

Use this when you need to see which ports are forwarded to internal hosts, check NAT rule configuration, or troubleshoot port forwarding issues.

Like firewall filter rules, this only returns MVC-managed NAT rules. Legacy NAT rules from the traditional GUI may not appear here — use opn_get_config_section('nat') to see all NAT configuration.

Returns: dict with 'rows' (list of NAT rules) and 'rowCount' (total).

List system services and their running status.

Use this when you need to check which services are running, stopped, or available on the OPNsense instance. Returns: dict with 'rows' (list of services) and 'rowCount' (total).

List configured static routes.

Use this when you need to see custom routing table entries, check which networks are routed through which gateways, or troubleshoot routing issues. Note: This shows configured static routes, not the full kernel routing table. Returns: dict with 'rows' (list of static routes) and 'rowCount' (total).

Get MCP server version and runtime configuration.

Use this to check the MCP server version, whether write mode is enabled, the detected OPNsense API version, and whether firewall writes still get savepoint/rollback protection. Returns: dict with 'mcp_version', 'write_mode', 'opnsense_version', 'api_style' and 'savepoint_support'. 'savepoint_support' is true when the 60-second auto-revert is available, false when OPNsense no longer offers it (26.7+ removed it upstream, so firewall changes are immediate and permanent), and null when no firewall write has probed for it yet.

Get mDNS Repeater service status and configuration.

Use this to check if the mDNS Repeater is installed, enabled, running, and which interfaces it is configured to relay multicast DNS between.

The mDNS Repeater relays mDNS (224.0.0.251:5353) packets between selected interfaces, enabling device discovery (HomeKit, Chromecast, AirPlay, etc.) across VLANs.

Note: Requires the mDNS Repeater plugin (os-mdns-repeater). Returns: dict with 'service_running', 'enabled', 'interfaces', 'blocklist'.

Get the NDP table showing IPv6-to-MAC address mappings.

Use this when you need to find which MAC address is associated with an IPv6 address, identify IPv6-enabled devices on a network segment, or troubleshoot IPv6 neighbor reachability. This is the IPv6 equivalent of the ARP table. Returns: dict with NDP entries including ip, mac, intf, and manufacturer fields.

Get OpenVPN connection status (instances, sessions, routes).

Use this when you need to check OpenVPN server/client status, see connected clients, active VPN routes, or troubleshoot OpenVPN tunnels. Note: OpenVPN is built-in (no plugin needed) but must be configured. Returns: dict with 'instances', 'sessions' (connected clients), and 'routes'.

Query the active PF (packet filter) state table.

Use this when you need to see active connections through the firewall, debug NAT issues, or identify which hosts are communicating. Returns: dict with 'rows' (list of state entries) and 'rowCount' (total).

Ping a host from the OPNsense firewall to test connectivity.

Use this when you need to check if a host is reachable from the firewall, measure round-trip latency, or diagnose network connectivity issues. The ping runs on the firewall itself, not locally. Returns: dict with ping results including loss percentage and RTT stats.

Apply pending Dynamic DNS configuration changes.

Use this after manually editing DDNS account settings to apply the changes to the running ddclient service.

Note: opn_add_ddns_account auto-reconfigures, so this is only needed for manual edits or troubleshooting.

Note: Requires the Dynamic DNS plugin (os-ddclient). Returns: dict with 'status' indicating success or failure.

Apply pending dnsmasq DNS/DHCP configuration changes.

Use this after manually editing dnsmasq settings to apply the changes to the running dnsmasq service.

Note: opn_add_dnsmasq_range auto-reconfigures, so this is only needed for manual edits or troubleshooting.

Note: Requires the dnsmasq DNS/DHCP server. Returns: dict with 'status' indicating success or failure.

Apply pending HAProxy load balancer configuration changes.

Use this after making HAProxy configuration changes to apply them to the running HAProxy service. This reconfigures HAProxy with the new settings.

NOTE: This does not use savepoint protection. HAProxy changes take effect immediately. Requires the HAProxy plugin (os-haproxy). IMPORTANT: Do NOT call haproxy/service/start after reconfigure — reconfigure already starts the service, and start will error if already running. IMPORTANT: Always call opn_haproxy_configtest before reconfiguring to validate the configuration syntax. Returns: dict with 'status' indicating success or failure.

Apply pending Unbound DNS resolver configuration changes.

Use this after making DNS configuration changes (adding overrides, forward zones, etc.) to apply them to the running Unbound service. This restarts Unbound with the new configuration.

NOTE: This does not use savepoint protection. DNS changes take effect immediately and cannot be auto-reverted. Verify settings before calling. Returns: dict with 'status' indicating success or failure.

Remove domains from a DNSBL allowlist.

Use this when you no longer need a domain allowlisted and want to re-enable DNSBL blocking for it. Changes are applied immediately.

Get the UUID from opn_list_dnsbl first.

Parameters:

• uuid: blocklist UUID from opn_list_dnsbl
• domains: domains to remove, comma or newline-separated

Returns: dict with 'removed' (list), 'not_found' (list), 'dnsbl_status', and 'service_status'.

Scan the OPNsense configuration and build a cached inventory.

Use this FIRST when starting a new session. Downloads the full config, parses it into queryable sections, and detects runtime state (services, DHCP backend, DNS servers). Results are cached for the session — subsequent calls return the cached version unless force=True.

Call with force=True to rescan after manual config changes on the firewall. Use opn_get_config_section(section) to drill into specific sections.

Returns: dict with 'firmware', 'plugins', 'dhcp', 'dns', 'interfaces', 'services', and 'config_sections' (list of available sections with sizes).

Run a comprehensive security audit of the OPNsense firewall.

Checks 11 security areas: firmware, firewall rules (MVC + legacy), NAT/port forwarding, DNS resolver security, system hardening (SSH, HTTPS, syslog), services, certificates, VPN status (incl. WireGuard config audit), HAProxy reverse proxy security, and gateway health.

Findings are tagged with applicable compliance frameworks: PCI DSS v4.0, BSI IT-Grundschutz, NIST SP 800-41, CIS Benchmarks.

Returns a structured audit report with findings categorized by severity (critical, warning, info). Each finding includes a recommendation and applicable compliance framework references.

Use this when you need to assess the security posture of the firewall, identify misconfigurations, or perform a routine health check.

Update a DNSBL blocklist configuration (read-modify-write).

Use this when you need to change DNSBL settings — providers, allowlists, blocklists, etc. Only the parameters you provide are changed; all other settings are preserved. Changes are applied immediately.

Get the UUID from opn_list_dnsbl first.

Parameters:

• uuid: blocklist UUID from opn_list_dnsbl
• enabled: enable/disable this blocklist
• providers: comma-separated provider shortcodes (e.g. 'hgz002,hgz011,ag')
• custom_urls: newline-separated custom blocklist URLs
• allowlists: newline-separated allowlist entries (domains or regex patterns)
• blocklists: newline-separated custom block domains
• wildcards: newline-separated wildcard block domains
• source_nets: comma-separated source networks (empty = all)
• nxdomain: return NXDOMAIN instead of 0.0.0.0 for blocked domains
• cache_ttl: cache TTL in seconds for DNSBL responses
• description: human-readable description

Returns: dict with 'result', 'dnsbl_status', and 'service_status'.

Assign categories to a firewall rule by UUID with savepoint protection where supported.

Use this when you need to categorize or re-categorize a firewall rule. Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out.

Parameters:

• uuid: the firewall rule UUID (from opn_list_firewall_rules)
• categories: comma-separated category UUIDs (from opn_list_firewall_categories), or empty string to clear all categories

Returns: dict with 'revision' (str) for confirming and 'uuid' (str).

Get OPNsense system status including firmware version and product info.

Use this when you need to check the current firmware version, system name, or verify the OPNsense appliance is reachable and responding. Returns: dict with firmware/product info. On OPNsense 26.x+, product fields are nested under a 'product' key; earlier versions have them at the top level.

Toggle a firewall alias's enabled/disabled state.

Use this when you need to temporarily disable an alias without deleting it, or re-enable a previously disabled alias. The toggle flips the current state.

This does NOT use savepoint protection — aliases are metadata definitions. Use opn_list_firewall_aliases first to find the UUID. Returns: dict with 'result' (str) and 'uuid' (str).

Toggle a firewall filter rule's enabled/disabled state with savepoint protection where supported.

Use this when you need to temporarily disable a rule for testing or re-enable a previously disabled rule. The toggle flips the current state.

Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_firewall_rules first to find the UUID of the rule. Returns: dict with 'revision' (str) for confirming and 'uuid' (str).

Trace the network path from OPNsense to a destination host.

Use this when you need to diagnose routing issues, identify where packets are being dropped, or visualize the network hops to a destination. Returns: dict with 'result' (str) and 'response' (list of hops).

Update an existing firewall alias by UUID (read-modify-write).

Use this when you need to rename an alias, change its content (IPs, networks, ports), modify its description, or change its type. Only the parameters you provide are changed; all other settings are preserved.

This does NOT require savepoint protection — aliases are metadata definitions that only affect traffic when referenced by a firewall rule.

Use opn_list_firewall_aliases first to find the UUID.

Parameters:

• uuid: alias UUID (from opn_list_firewall_aliases)
• name: new alias name (alphanumeric and underscores only)
• content: new alias entries separated by newlines
• description: new description
• alias_type: new type ('host', 'network', 'port', 'urltable', 'geoip')
• enabled: enable/disable the alias

Returns: dict with 'result' (str) and 'uuid' (str).

Update a Dynamic DNS account by UUID and apply the configuration.

Use this when you need to change the hostname, provider, credentials, or other properties of a DDNS account. Only the parameters you provide are changed; all other settings are preserved.

After update, the ddclient service is automatically reconfigured. Changes take effect immediately. Use opn_list_ddns_accounts first to find the UUID.

Parameters:

• uuid: account UUID (from opn_list_ddns_accounts)
• service: DDNS provider name (e.g. 'cloudflare', 'dyndns', 'noip')
• hostname: fully qualified domain name to update
• username: provider username or API key
• password: provider password or API token
• checkip: IP check method (e.g. 'web_dyndns', 'if')
• interface: network interface name (e.g. 'wan')
• description: human-readable description
• enabled: enable/disable the account

Returns: dict with 'result' (str), 'uuid' (str), and 'reconfigure_status'.

Update an Unbound DNS host override by UUID and apply immediately.

Use this when you need to change the hostname, domain, IP address, or other properties of a DNS override. Only the parameters you provide are changed; all other settings are preserved.

Changes are applied immediately (Unbound is reconfigured automatically). DNS overrides cannot be auto-reverted — verify settings before calling. Use opn_list_dns_overrides first to find the UUID.

Parameters:

• uuid: override UUID (from opn_list_dns_overrides)
• hostname: new hostname part (e.g. 'myserver')
• domain: new domain part (e.g. 'local.lan')
• server: new IP address (IPv4 or IPv6)
• description: new description
• enabled: enable/disable the override

Returns: dict with 'result' (str), 'uuid' (str), and 'applied' status.

Reload DNSBL blocklist files and restart Unbound to apply them.

Use this when DNSBL lists need to be refreshed without changing the configuration — for example after a service restart that lost loaded lists, or to force Unbound to pick up previously generated blocklist files. This flushes the DNS cache, so previously cached blocked (or unblocked) domains will be re-evaluated.

NOTE: This does not use savepoint protection. DNS changes take effect immediately and cannot be auto-reverted. Returns: dict with 'dnsbl_status' and 'service_status'.

Update a dnsmasq DHCP range by UUID and apply the configuration.

Use this when you need to change the address range, lease time, RA settings, or other properties. Only the parameters you provide are changed; all other settings are preserved.

After update, the dnsmasq service is automatically reconfigured. Changes take effect immediately. Use opn_list_dnsmasq_ranges first to find the UUID.

Parameters:

• uuid: range UUID (from opn_list_dnsmasq_ranges)
• interface: network interface name (e.g. 'lan', 'opt1')
• start_addr: start of address range
• end_addr: end of address range
• prefix_len: IPv6 prefix length (e.g. '64')
• ra_mode: Router Advertisement mode ('slaac', 'ra-stateless', 'ra-only')
• lease_time: lease duration (e.g. '24h', '1h')
• description: human-readable description
• enabled: enable/disable the range

Returns: dict with 'result' (str), 'uuid' (str), and 'reconfigure_status'.

Update an existing MVC firewall rule by UUID with savepoint protection where supported.

Use this when you need to modify a firewall rule's action, source/destination, protocol, ports, or other properties. Only the parameters you provide are changed; all other settings are preserved.

Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_firewall_rules first to find the UUID.

Parameters:

• uuid: rule UUID (from opn_list_firewall_rules)
• action: 'pass', 'block', or 'reject'
• direction: 'in' or 'out'
• interface: interface name (e.g. 'lan', 'wan', 'opt1')
• ip_protocol: 'inet' (IPv4), 'inet6' (IPv6), or 'inet46' (dual-stack)
• protocol: 'any', 'TCP', 'UDP', 'TCP/UDP', 'ICMP', etc.
• source_net: source address/network or 'any'
• source_not: invert source match
• source_port: source port number or range
• destination_net: destination address/network or 'any'
• destination_not: invert destination match
• destination_port: port number or range
• gateway: force traffic via specific gateway, or empty to clear
• log: enable/disable logging
• quick: first-match wins (True) or last-match-wins (False)
• sequence: rule ordering within priority group
• categories: comma-separated category UUIDs
• description: human-readable rule description
• enabled: enable/disable the rule

Returns: dict with 'revision' (str), 'uuid' (str), and 'result' (str).

Update an existing NAT port forwarding rule by UUID with savepoint protection where supported.

Use this when you need to change the target IP, port, or other properties of a NAT rule. Only the parameters you provide are changed; all other settings are preserved.

Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_nat_rules first to find the UUID.

Parameters:

• uuid: NAT rule UUID (from opn_list_nat_rules)
• interface: source interface (e.g. 'wan', 'opt1')
• protocol: 'TCP', 'UDP', or 'TCP/UDP'
• destination_port: external port to forward (e.g. '8080', '3000-3010')
• target_ip: internal IP address to forward to
• target_port: internal port
• description: human-readable description
• enabled: enable/disable the rule

Returns: dict with 'revision' (str), 'uuid' (str), and 'result' (str).

Get WireGuard VPN tunnel and peer status.

Use this when you need to check WireGuard tunnel health, peer handshake times, transferred bytes, or endpoint information. Note: Requires the WireGuard plugin (os-wireguard). Returns: dict with tunnel and peer details including endpoints and transfer stats.