OPNsense TypeScript SDK

A comprehensive TypeScript SDK for the OPNsense API, providing type-safe access to all core and plugin modules.

Documentation

This SDK includes comprehensive documentation across multiple files:

• OPNsense Documentation Crawler - Automated API documentation extraction
• OPNsense Core Modules API Documentation - Complete core modules reference
• OPNsense Plugin Modules API Documentation - Complete plugin modules reference
• WireGuard Key Generation - Comprehensive keygen utility documentation
• Generators - Code generation tools and scripts
• OPNsense TypeScript API Client - Intermediate Stage Modules - Intermediate development modules

Installation

yarn add opnsense-typescript-client

Quick Start

import { OPNsenseClient } from 'opnsense-typescript-client';

const client = new OPNsenseClient({
  baseUrl: 'https://your-opnsense.local',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  verifySsl: false, // Set to true in production
});

// Test connection
const result = await client.testConnection();
console.log(result);

// Use core modules
const interfaces = await client.interfaces.get();
const firewallRules = await client.firewall.filterGet();

// Use plugin modules
const caddyStatus = await client.plugins.caddy.serviceStatus();
const nginxConfig = await client.plugins.nginx.generalGet();

Features

• Type-safe: Full TypeScript support with detailed type definitions
• Tree-shakable: Import only the modules you need
• Secure: Built-in authentication and SSL handling
• Complete: Covers all 24 core and 64 plugin modules
• Modern: Built with async/await and modern JavaScript features

Configuration

Basic Configuration

import { OPNsenseClient } from 'opnsense-typescript-client';

const client = new OPNsenseClient({
  baseUrl: 'https://opnsense.local', // Do not include '/api' - it's added automatically
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  verifySsl: true, // Enable SSL verification in production
  timeout: 30000, // Request timeout in milliseconds
});

Important: The baseUrl should only include the protocol and hostname (e.g., https://opnsense.local). The /api segment is automatically appended by the SDK - do not include it in your base URL.

Advanced Configuration

const client = new OPNsenseClient({
  baseUrl: 'https://opnsense.local',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  verifySsl: true,
  timeout: 30000,
  // Additional axios configuration
  httpsAgent: new https.Agent({
    rejectUnauthorized: false, // Only for self-signed certificates
  }),
});

Authentication

The SDK uses HTTP Basic Authentication with API keys. To obtain API credentials:

1. Log into your OPNsense web interface
2. Navigate to System → Access → Users
3. Create or edit a user account
4. Under API keys, click the + button to generate a new key/secret pair
5. Use the generated key as apiKey and secret as apiSecret

Core Modules

The SDK provides access to 24 core OPNsense modules:

System & Configuration

• core - Core system functions and settings
• firmware - Firmware updates and package management
• auth - Authentication and authorization management
• trust - Certificate and trust store management

Networking

• interfaces - Network interface configuration
• routes - Static route configuration
• routing - Dynamic routing protocols configuration
• dhcpv4 - DHCPv4 server configuration
• dhcpv6 - DHCPv6 server configuration
• dhcrelay - DHCP relay service configuration
• kea - Kea DHCP server configuration

DNS Services

• dnsmasq - DNS forwarder configuration
• unbound - DNS resolver configuration

Security & Firewall

• firewall - Firewall rules, aliases, and NAT configuration
• ids - Intrusion Detection System (IDS) configuration
• captiveportal - Captive portal configuration and management

VPN

• ipsec - IPsec VPN configuration
• openvpn - OpenVPN server and client configuration
• wireguard - WireGuard VPN configuration

Monitoring & Logging

• diagnostics - System diagnostics and troubleshooting tools
• syslog - System logging configuration
• monit - Service monitoring configuration

Scheduling & Traffic

• cron - Cron job scheduling and management
• trafficshaper - Traffic shaping and QoS configuration

Plugin Modules

The SDK supports 64 plugin modules organized by category:

Web Services & Reverse Proxy

• caddy - Modern web server with automatic HTTPS
• nginx - Web server and reverse proxy
• haproxy - Load balancer with statistics

Security & Authentication

• acmeclient - ACME/Let's Encrypt certificate management
• clamav - Antivirus scanning
• crowdsec - Collaborative security engine
• freeradius - RADIUS authentication server

VPN & Networking

• tailscale - Mesh VPN networking
• zerotier - Virtual network management
• softether - SoftEther VPN server
• openconnect - OpenConnect VPN client

Monitoring & Metrics

• netdata - Real-time performance monitoring
• collectd - System statistics collection
• telegraf - Metrics collection with plugins
• zabbixagent - Zabbix monitoring agent

And many more...

For a complete list of all plugin modules, see the Plugin Modules Documentation.

Usage Examples

Firewall Management

// Get all firewall aliases
const aliases = await client.firewall.alias.searchItem();

// Add a new alias
const newAlias = await client.firewall.alias.addItem({
  name: 'web_servers',
  type: 'host',
  content: '192.168.1.100,192.168.1.101',
  description: 'Web server hosts',
});

// Apply firewall configuration
await client.firewall.alias.reconfigure();

Interface Configuration

// Get all interfaces
const interfaces = await client.interfaces.get();

// Get specific interface configuration
const lanConfig = await client.interfaces.getInterface('lan');

// Update interface settings
await client.interfaces.setInterface('lan', {
  enable: true,
  ipaddr: '192.168.1.1',
  subnet: '24',
  descr: 'LAN Interface',
});

VPN Management

// WireGuard configuration
const wgStatus = await client.wireguard.serviceStatus();
const wgConfig = await client.wireguard.generalGet();

// OpenVPN management
const ovpnInstances = await client.openvpn.instancesGet();
await client.openvpn.instanceStart('server1');

Plugin Management

// Caddy web server
const caddyStatus = await client.plugins.caddy.serviceStatus();
const caddyConfig = await client.plugins.caddy.generalGet();

// Nginx configuration
const nginxUpstreams = await client.plugins.nginx.upstreamGet();
const nginxLocations = await client.plugins.nginx.locationGet();

// HAProxy load balancer
const haproxyStats = await client.plugins.haproxy.statsGet();
const haproxyServers = await client.plugins.haproxy.serverGet();

Error Handling

try {
  const result = await client.firewall.alias.searchItem();
  console.log('Success:', result.data);
} catch (error) {
  if (error.response) {
    // API returned an error response
    console.error('API Error:', error.response.status, error.response.data);
  } else if (error.request) {
    // Network error
    console.error('Network Error:', error.message);
  } else {
    // Other error
    console.error('Error:', error.message);
  }
}

Working with UUIDs

Many OPNsense API endpoints work with UUIDs for resource identification:

// Get all items to find UUIDs
const items = await client.firewall.alias.searchItem();

// Work with specific item by UUID
const uuid = items.rows[0].uuid;
const item = await client.firewall.alias.getItem(uuid);

// Update item
await client.firewall.alias.setItem(uuid, {
  description: 'Updated description',
});

// Delete item
await client.firewall.alias.delItem(uuid);

Service Management

Most modules support standard service operations:

// Check service status
const status = await client.plugins.nginx.serviceStatus();

// Start/stop/restart services
await client.plugins.nginx.serviceStart();
await client.plugins.nginx.serviceStop();
await client.plugins.nginx.serviceRestart();

// Reload configuration
await client.plugins.nginx.serviceReload();

// Apply configuration changes
await client.plugins.nginx.reconfigure();

Postman Collections

Pre-built Postman collections are available for testing and exploring the API:

• Core Modules: postman/OPNsense_Core_Modules_API_Collection.postman_collection.json
• Plugin Modules: postman/OPNsense_Plugin_Modules_API_Collection.postman_collection.json

Usage

1. Import the collections into Postman
2. Set up environment variables:
   • opnsense_base_url - Your OPNsense instance URL
   • opnsense_api_key - Your API key
   • opnsense_secret_key - Your API secret
3. Start making requests

The collections include all available endpoints with proper authentication and parameter placeholders.

WireGuard Key Generation

The SDK includes a comprehensive WireGuard key generation utility. See the WireGuard Key Generation documentation for detailed usage examples and API reference.

TypeScript Support

The SDK is built with TypeScript and provides full type definitions:

import { OPNsenseClient, FirewallAlias, ApiResponse } from 'opnsense-typescript-client';

const client = new OPNsenseClient({
  baseUrl: 'https://opnsense.local',
  apiKey: 'key',
  apiSecret: 'secret',
});

// TypeScript will provide autocomplete and type checking
const aliases: ApiResponse<FirewallAlias[]> = await client.firewall.alias.searchItem();

Build Configuration

The SDK supports selective module inclusion through build configuration. See the Intermediate Stage Modules documentation for details on customizing builds.

Development

To contribute to the SDK or generate updated modules:

# Install dependencies
yarn install

# Build the SDK
yarn build

# Generate documentation
yarn generate:docs:core
yarn generate:docs:plugin

# Generate TypeScript modules
yarn generate:typescript:core
yarn generate:typescript:plugin

# Generate complete SDK
yarn generate:sdk

# Generate Postman collections
yarn generate:postman:core
yarn generate:postman:plugin

Requirements

• Node.js 16+ or compatible runtime
• OPNsense 20.1+ with API access enabled
• Valid API key and secret

License

MIT License - see LICENSE file for details.