NAME
WebService::OPNsense - Perl client library for the OPNsense REST API
VERSION
version 0.001
SYNOPSIS
use WebService::OPNsense;
my $opn = WebService::OPNsense->new(
base_url => 'https://opnsense.example.com',
username => 'your-api-key',
password => 'your-api-secret',
);
# Search firewall rules
my $rules = $opn->firewall_filter->search_rule;
for my $rule (@{$rules->{rows}}) {
say $rule->{description};
}
# Get system information
my $info = $opn->system->status;
say $_->{name} for @{$info->{rows}};DESCRIPTION
WebService::OPNsense is a Moo-based client for the OPNsense REST API. It consumes the WebService::Client role and provides lazy accessors for each OPNsense API controller.
Authentication is handled via HTTP Basic Auth using an API key/secret pair.
ALPHA STATUS
This release should be considered an alpha release. Please adjust your expectations accordingly.
Your feedback is very welcomed. Patches are even more welcome.
ATTRIBUTES
base_url
Required. Base URL of the OPNsense instance (e.g. https://opnsense.example.com).
username
Required. API key for authentication.
password
Required. API secret for authentication.
firewall
Lazy accessor returning a WebService::OPNsense::Firewall instance.
firewall_filter
Lazy accessor returning a WebService::OPNsense::Firewall::Filter instance.
firewall_alias
Lazy accessor returning a WebService::OPNsense::Firewall::Alias instance.
firewall_category
Lazy accessor returning a WebService::OPNsense::Firewall::Category instance.
system
Lazy accessor returning a WebService::OPNsense::System instance.
diagnostics
Lazy accessor returning a WebService::OPNsense::Diagnostics instance.
routes
Lazy accessor returning a WebService::OPNsense::Routes instance.
backup
Lazy accessor returning a WebService::OPNsense::Backup instance.
captive_portal_settings
Lazy accessor returning a WebService::OPNsense::CaptivePortal::Settings instance.
captive_portal_session
Lazy accessor returning a WebService::OPNsense::CaptivePortal::Session instance.
captive_portal_access
Lazy accessor returning a WebService::OPNsense::CaptivePortal::Access instance.
captive_portal_voucher
Lazy accessor returning a WebService::OPNsense::CaptivePortal::Voucher instance.
captive_portal_service
Lazy accessor returning a WebService::OPNsense::CaptivePortal::Service instance.
cron_settings
Lazy accessor returning a WebService::OPNsense::Cron::Settings instance.
cron_service
Lazy accessor returning a WebService::OPNsense::Cron::Service instance.
dnsmasq_settings
Lazy accessor returning a WebService::OPNsense::Dnsmasq::Settings instance.
dnsmasq_leases
Lazy accessor returning a WebService::OPNsense::Dnsmasq::Leases instance.
dnsmasq_service
Lazy accessor returning a WebService::OPNsense::Dnsmasq::Service instance.
firewall_d_nat
Lazy accessor returning a WebService::OPNsense::Firewall::DNat instance.
firewall_npt
Lazy accessor returning a WebService::OPNsense::Firewall::Npt instance.
firewall_one_to_one
Lazy accessor returning a WebService::OPNsense::Firewall::OneToOne instance.
firewall_source_nat
Lazy accessor returning a WebService::OPNsense::Firewall::SourceNat instance.
hasync
Lazy accessor returning a WebService::OPNsense::HASync instance.
ids_settings
Lazy accessor returning a WebService::OPNsense::IDS::Settings instance.
ids_service
Lazy accessor returning a WebService::OPNsense::IDS::Service instance.
ipsec_connections
Lazy accessor returning a WebService::OPNsense::IPsec::Connections instance.
ipsec_key_pairs
Lazy accessor returning a WebService::OPNsense::IPsec::KeyPairs instance.
ipsec_leases
Lazy accessor returning a WebService::OPNsense::IPsec::Leases instance.
ipsec_manual_spd
Lazy accessor returning a WebService::OPNsense::IPsec::ManualSpd instance.
ipsec_pools
Lazy accessor returning a WebService::OPNsense::IPsec::Pools instance.
ipsec_pre_shared_keys
Lazy accessor returning a WebService::OPNsense::IPsec::PreSharedKeys instance.
ipsec_sad
Lazy accessor returning a WebService::OPNsense::IPsec::Sad instance.
ipsec_service
Lazy accessor returning a WebService::OPNsense::IPsec::Service instance.
ipsec_sessions
Lazy accessor returning a WebService::OPNsense::IPsec::Sessions instance.
ipsec_settings
Lazy accessor returning a WebService::OPNsense::IPsec::Settings instance.
ipsec_spd
Lazy accessor returning a WebService::OPNsense::IPsec::Spd instance.
ipsec_tunnel
Lazy accessor returning a WebService::OPNsense::IPsec::Tunnel instance.
ipsec_vti
Lazy accessor returning a WebService::OPNsense::IPsec::Vti instance.
kea_dhcpv4
Lazy accessor returning a WebService::OPNsense::Kea::Dhcpv4 instance.
kea_dhcpv6
Lazy accessor returning a WebService::OPNsense::Kea::Dhcpv6 instance.
kea_leases
Lazy accessor returning a WebService::OPNsense::Kea::Leases instance.
kea_ddns
Lazy accessor returning a WebService::OPNsense::Kea::Ddns instance.
kea_ctrl_agent
Lazy accessor returning a WebService::OPNsense::Kea::CtrlAgent instance.
kea_service
Lazy accessor returning a WebService::OPNsense::Kea::Service instance.
openvpn_instances
Lazy accessor returning a WebService::OPNsense::OpenVPN::Instances instance.
openvpn_client_overwrites
Lazy accessor returning a WebService::OPNsense::OpenVPN::ClientOverwrites instance.
openvpn_service
Lazy accessor returning a WebService::OPNsense::OpenVPN::Service instance.
openvpn_export
Lazy accessor returning a WebService::OPNsense::OpenVPN::Export instance.
trafficshaper_settings
Lazy accessor returning a WebService::OPNsense::TrafficShaper::Settings instance.
trafficshaper_service
Lazy accessor returning a WebService::OPNsense::TrafficShaper::Service instance.
unbound_settings
Lazy accessor returning a WebService::OPNsense::Unbound::Settings instance.
unbound_overview
Lazy accessor returning a WebService::OPNsense::Unbound::Overview instance.
unbound_diagnostics
Lazy accessor returning a WebService::OPNsense::Unbound::Diagnostics instance.
unbound_service
Lazy accessor returning a WebService::OPNsense::Unbound::Service instance.
interfaces
Lazy accessor returning a WebService::OPNsense::Interfaces instance.
METHODS
BUILD
Moo lifecycle hook. Validates and normalizes base_url, configures HTTP Basic Auth credentials, and sets a descriptive User-Agent string.
req
my $data = $opn->req($http_request, %args);around modifier wrapping "req" in WebService::Client. Unwraps the response object, returns undef for GET 404/410 responses, and throws a WebService::OPNsense::Exception on other non-2xx status codes.
get
my $data = $opn->get($path, \%params);around modifier wrapping "get" in WebService::Client. URL-encodes all query-parameter values before dispatch.
SEE ALSO
WebService::Client - role consumed by this class
WebService::OPNsense::Exception - exception objects thrown on errors
https://docs.opnsense.org/development/api.html - OPNsense API documentation
API COMPATIBILITY
The OPNsense REST API does not use versioned paths, headers, or content negotiation. Endpoints change between OPNsense releases without formal deprecation notices. This module follows the API spec as it appears and may require updates when the firewall is upgraded.
AUTHOR
Dean Hamstead <dean@fragfest.com.au>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2026 by Dean Hamstead.
This is free software, licensed under:
The MIT (X11) License