### Service API Usage Examples

Source: https://context7.com/opnsense/plugins/llms.txt

Demonstrates how to check service status, start, stop, and restart services using curl.

```bash
# Check service status
curl -k -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/haproxy/service/status"
# Response: {"status":"running"}

# Start service
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/haproxy/service/start"
# Response: {"response":"OK"}

# Stop service
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/haproxy/service/stop"
# Response: {"response":"OK"}

# Restart service
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/haproxy/service/restart"
# Response: {"response":"OK"}

```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/opnsense/plugins/blob/master/www/nginx/README.md

Navigate to the specified directory and run `npm install` to install the build tools for the frontend code.

```bash
npm install
```

--------------------------------

### API Usage Examples for Settings Controller

Source: https://context7.com/opnsense/plugins/llms.txt

Demonstrates how to interact with the Settings API controller using curl for various CRUD operations.

```bash
# Authenticate and get API credentials from System > Access > Users
API_KEY="your_api_key"
API_SECRET="your_api_secret"
BASE_URL="https://192.168.1.1"

# Search/list items with pagination
curl -k -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/gridexample/settings/searchItem" \
  -d '{"current":1,"rowCount":25}'
# Response: {"rows":[{"uuid":"abc-123","enabled":"1","email":"test@example.com"}],"rowCount":25,"total":1,"current":1}

# Get a single item
curl -k -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/gridexample/settings/getItem/abc-123"
# Response: {"address":{"enabled":"1","email":"test@example.com","description":"Test entry"}}

# Add new item
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/gridexample/settings/addItem" \
  -d '{"address":{"enabled":"1","email":"new@example.com","description":"New entry"}}'
# Response: {"uuid":"def-456","result":"saved"}

# Update item
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/gridexample/settings/setItem/def-456" \
  -d '{"address":{"email":"updated@example.com"}}'
# Response: {"result":"saved"}

# Toggle item enabled/disabled
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/gridexample/settings/toggleItem/def-456"
# Response: {"result":"toggled","enabled":"0"}

# Delete item
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/gridexample/settings/delItem/def-456"
# Response: {"result":"deleted"}
```

--------------------------------

### HAProxy API Usage Examples

Source: https://context7.com/opnsense/plugins/llms.txt

These bash commands demonstrate how to interact with the HAProxy settings API to create new frontends and backends. Ensure you have your API key, secret, and base URL configured.

```bash
# Create a frontend
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/haproxy/settings/addFrontend" \
  -d '{"frontend":{"enabled":"1","name":"web_frontend","bind":"0.0.0.0:80","defaultBackend":"web_backend"}}'

# Create a backend
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/haproxy/settings/addBackend" \
  -d '{"backend":{"enabled":"1","name":"web_backend","mode":"http","balance":"roundrobin"}}'

```

--------------------------------

### OPNsense Plugin Build and Management Commands

Source: https://context7.com/opnsense/plugins/llms.txt

Common commands for managing OPNsense plugins, including listing, building, installing, and performing lint checks or style fixes.

```bash
# List all available plugins
make list

```

```bash
# Build a specific plugin package
cd net/haproxy && make package

```

```bash
# Install the plugin directly
cd net/haproxy && make upgrade

```

```bash
# Run lint checks
cd net/haproxy && make lint

```

```bash
# Apply style fixes
cd net/haproxy && make sweep

```

--------------------------------

### Configure ETPRO Telemetry

Source: https://github.com/opnsense/plugins/blob/master/security/etpro-telemetry/README.md

Example of the autogenerated configuration file containing the device registration token.

```ini
# autogenerated, do not edit.
[__properties__]
et_telemetry.token=eeyahsei1nootu6aeJ5Eeghoohahxu4rahkiewu2bayeiv2eif
```

--------------------------------

### QFeeds Configuration File Format

Source: https://github.com/opnsense/plugins/blob/master/security/q-feeds-connector/README.md

Configuration settings for the QFeeds plugin are stored in `/usr/local/etc/qfeeds.conf`. This example shows the basic API key setup.

```ini
[api]
key=tip_xxxxxxxx
```

--------------------------------

### sslh Log Entry Example

Source: https://github.com/opnsense/plugins/blob/master/net/sslh/DEVELOPMENT.md

Sample log output format observed on OPNsense 22.1.

```text
2021-12-29T23:41:07+00:00 OPNsense.localdomain sslh-fork[62839] 62839 - [meta sequenceId="43"] sslh-fork 1.21c started
```

--------------------------------

### QFeeds CLI Update Action Example

Source: https://github.com/opnsense/plugins/blob/master/security/q-feeds-connector/README.md

This command executes the `update` action using the `qfeedsctl.py` script. The `update` action typically involves fetching the index, then downloading the threat lists, and finally loading them into firewall tables.

```bash
/usr/local/opnsense/scripts/qfeeds/qfeedsctl.py update
```

--------------------------------

### Install Telemetry Dependencies

Source: https://github.com/opnsense/plugins/blob/master/security/etpro-telemetry/README.md

Command to install required Python packages for the telemetry scripts.

```bash
pip install -r requires.txt
```

--------------------------------

### GET /api/haproxy/service/configtest

Source: https://context7.com/opnsense/plugins/llms.txt

Tests the syntax of the current HAProxy configuration file.

```APIDOC
## GET /api/haproxy/service/configtest

### Description
Validates the syntax of the generated HAProxy configuration file.

### Method
GET

### Endpoint
/api/haproxy/service/configtest

### Response
#### Success Response (200)
- **result** (string) - A message indicating the validation result.

#### Response Example
{
  "result": "Configuration file is valid"
}
```

--------------------------------

### Sample sslh Configuration File

Source: https://github.com/opnsense/plugins/blob/master/net/sslh/DEVELOPMENT.md

This is a basic configuration file for sslh, providing sensible default values for a standard setup. It includes options for verbosity, running in the foreground, inetd mode, numeric output, transparency, timeout, user, pidfile, and chroot.

```config
# This is a basic configuration file that should provide
# sensible values for "standard" setup.

verbose:         0;
foreground:      false;
inetd:           false;
numeric:         false;
transparent:     false;
timeout:         2;
user:            "nobody";
pidfile:         "/var/run/sslh.pid";
chroot:          "/var/empty";



```

--------------------------------

### Protocol Configuration with SNI Hostnames

Source: https://github.com/opnsense/plugins/blob/master/net/sslh/DEVELOPMENT.md

Example of configuring TLS protocols with specific Server Name Indication (SNI) hostnames for different ports. This allows for multiple TLS certificates on the same IP address.

```yaml
protocols: (
    {   name: "tls";
        host: "localhost";
        port: "993";
        sni_hostnames: [ "mail.rutschle.net" ];
    },
    {
        name: "tls";
        host: "localhost";
        port: "xmpp-client";
        sni_hostnames: [ "im.rutschle.net" ];
    },
    {
        name: "tls";
        host: "localhost";
        port: "4443";
        sni_hostnames: [ "www.rutschle.net" ];
    }
);
```

--------------------------------

### Manage ACME Client Service

Source: https://context7.com/opnsense/plugins/llms.txt

API endpoints for checking status, starting challenges, signing certificates, and resetting or reconfiguring the ACME client.

```bash
curl -k -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/acmeclient/service/status"
```

```bash
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/acmeclient/service/start"
```

```bash
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/acmeclient/service/signallcerts"
```

```bash
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/acmeclient/service/reset"
```

```bash
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/acmeclient/service/reconfigure"
```

--------------------------------

### OPNsense Model Definition - Array Field for CRUD

Source: https://context7.com/opnsense/plugins/llms.txt

Defines an array-based data structure for OPNsense plugins, suitable for CRUD operations. This example includes an 'addresses' array with fields for email, enabled status, and description.

```xml
<!-- src/opnsense/mvc/app/models/OPNsense/GridExample/GridExample.xml -->
<model>
    <mount>//OPNsense/GridExample</mount>
    <description>the OPNsense "GridExample" application</description>
    <items>
        <addresses>
            <address type="ArrayField">
                <enabled type="BooleanField">
                    <Default>1</Default>
                    <Required>Y</Required>
                </enabled>
                <email type="EmailField">
                    <Required>Y</Required>
                </email>
                <description type="DescriptionField"/>
            </address>
        </addresses>
    </items>
</model>

```

--------------------------------

### Create Configuration Templates

Source: https://context7.com/opnsense/plugins/llms.txt

Use Jinja2 templates to generate service configuration files based on OPNsense model data.

```jinja2
{# src/opnsense/service/templates/OPNsense/HelloWorld/helloworld.conf #}
{% if not helpers.empty('OPNsense.helloworld.general.Enabled') %}
[general]
SMTPHost={{ OPNsense.helloworld.general.SMTPHost|default("") }}
FromEmail={{ OPNsense.helloworld.general.FromEmail|default("") }}
ToEmail={{ OPNsense.helloworld.general.ToEmail|default("") }}
Subject={{ OPNsense.helloworld.general.Description|default("") }}
{% endif %}
```

--------------------------------

### Configure Menu and ACL

Source: https://context7.com/opnsense/plugins/llms.txt

Define GUI menu entries and access control permissions using XML files.

```xml
<!-- src/opnsense/mvc/app/models/OPNsense/HelloWorld/Menu/Menu.xml -->
<menu>
    <Lobby>
        <HelloWorld VisibleName="Hello World!" cssClass="fa fa-comment-o fa-fw" url="/ui/helloworld"/>
    </Lobby>
</menu>
```

```xml
<!-- src/opnsense/mvc/app/models/OPNsense/HelloWorld/ACL/ACL.xml -->
<acl>
    <page-user-helloworld>
        <name>Lobby: Hello World!</name>
        <patterns>
            <pattern>ui/helloworld/*</pattern>
            <pattern>api/helloworld/*</pattern>
        </patterns>
    </page-user-helloworld>
</acl>
```

--------------------------------

### sslh Command Line Options

Source: https://github.com/opnsense/plugins/blob/master/net/sslh/DEVELOPMENT.md

Reference for available command line arguments for the sslh binary.

```text
sslh
	[-Fconfig file]
	[-t num]
	[--transparent]
	[-p listening address [-p listening address ...]
	[--ssl target address for SSL]
	[--tls target address for TLS]
	[--ssh target address for SSH]
	[--openvpn target address for OpenVPN]
	[--http target address for HTTP]
	[--xmpp target address for XMPP]
	[--tinc target address for TINC]
	[--anyprot default target address] (use this for SSLv2 connections)
	[--on-timeout protocol name]
	[-u username]
	[-C chroot] [-P pidfile] [-v] [-i] [-V] [-f] [-n]
```

--------------------------------

### QFeeds CLI Usage and Arguments

Source: https://github.com/opnsense/plugins/blob/master/security/q-feeds-connector/README.md

This is the usage string for the `qfeedsctl.py` command-line tool. It outlines the available positional arguments (actions) and optional flags.

```text
usage: qfeedsctl.py [-h] [--target_dir TARGET_DIR] [-f] [-v] [{fetch_index,fetch,show_index,firewall_load,update,stats} ...]

positional arguments:
  {fetch_index,fetch,show_index,firewall_load,update,stats}

options:
  -h, --help            show this help message and exit
  --target_dir TARGET_DIR
  -f                    forced (auto index)
  -v                    verbose output
```

--------------------------------

### Configure Hostname and Protocols

Source: https://github.com/opnsense/plugins/blob/master/net/sslh/DEVELOPMENT.md

Defines the hostname and lists the network protocols to be listened on. Ensure the hostname matches your external address name.

```yaml
listen:
(
    { host: "thelonious"; port: "443"; }
);

protocols:
(
     { name: "ssh";     service: "ssh"; host: "localhost"; port: "22";        fork: true; },
     { name: "openvpn";                 host: "localhost"; port: "1194"; },
     { name: "xmpp";                    host: "localhost"; port: "5222"; },
     { name: "http";                    host: "localhost"; port: "80"; },
     { name: "tls";                     host: "localhost"; port: "443";       log_level: 0; },
     { name: "anyprot";                 host: "localhost"; port: "443"; }
);
```

--------------------------------

### Generate DNSCrypt-Proxy Forwarder Configuration

Source: https://github.com/opnsense/plugins/blob/master/dns/dnscrypt-proxy/src/opnsense/service/templates/OPNsense/Dnscryptproxy/forwarding-rules.txt

Iterates through the OPNsense configuration to output enabled domain and DNS server pairs. Requires the DNSCrypt-Proxy plugin to be enabled.

```jinja2
{% if helpers.exists('OPNsense.dnscryptproxy.general.enabled') and OPNsense.dnscryptproxy.general.enabled == '1' %}

{% if helpers.exists('OPNsense.dnscryptproxy.forward.forwards.forward') %}
{%   for forward_list in helpers.toList('OPNsense.dnscryptproxy.forward.forwards.forward') %}
{%     if forward_list.enabled == '1' %}
{{ forward_list.domain }} {{ forward_list.dnsserver }}
{%     endif %}
{%   endfor %}
{% endif %}

{% endif %}
```

--------------------------------

### Implement Backend Script

Source: https://context7.com/opnsense/plugins/llms.txt

A Python script that reads configuration files and performs network operations, returning results as JSON.

```python
#!/usr/local/bin/python3
# src/opnsense/scripts/helloworld/testConnection.py
import os
import socket
import smtplib
import json
from configparser import ConfigParser

socket.setdefaulttimeout(2)
hello_world_config = '/usr/local/etc/helloworld/helloworld.conf'

result = {}
if os.path.exists(hello_world_config):
    cnf = ConfigParser()
    cnf.read(hello_world_config)
    if cnf.has_section('general'):
        try:
            smtpObj = smtplib.SMTP(cnf.get('general', 'SMTPHost'))
            msg_header = "From: " + cnf.get('general', 'FromEmail') + "\n" + \
                         "To: " + cnf.get('general', 'ToEmail') + "\n" + \
                         "Subject: " + cnf.get('general', 'Subject') + "\n" + \
                         "Test message!"
            smtpObj.sendmail(cnf.get('general', 'FromEmail'),
                           [cnf.get('general', 'ToEmail')], msg_header)
            smtpObj.quit()
            result['message'] = 'test ok!'
        except smtplib.SMTPException as error:
            result['message'] = '%s' % error
        except socket.error as error:
            result['message'] = error.strerror or 'time out!'
    else:
        result['message'] = 'empty configuration'
else:
    result['message'] = 'no configuration file found'

print(json.dumps(result))
```

--------------------------------

### Plugin Makefile Configuration

Source: https://context7.com/opnsense/plugins/llms.txt

Defines metadata for an OPNsense plugin, including name, version, dependencies, and maintainer information. This Makefile is used by the build system to create FreeBSD packages.

```makefile
# Example: net/haproxy/Makefile
PLUGIN_NAME=        haproxy
PLUGIN_VERSION=     5.1
PLUGIN_REVISION=    0
PLUGIN_COMMENT=     Reliable, high performance TCP/HTTP load balancer
PLUGIN_DEPENDS=     haproxy32
PLUGIN_MAINTAINER=  frank@example.com

.include "../../Mk/plugins.mk"

```

--------------------------------

### Usage of dump_data.py

Source: https://github.com/opnsense/plugins/blob/master/security/etpro-telemetry/README.md

Command-line interface documentation for dumping Suricata eve.log data.

```bash
usage: dump_data.py [-h] [-l LOG] [-t TIME] [-p] [-L LIMIT]

optional arguments:
  -h, --help            show this help message and exit
  -l LOG, --log LOG     log directory containing eve.json files
  -t TIME, --time TIME  max seconds to read from now()
  -p, --parsed          show data as shipped using send_telemetry
  -L LIMIT, --limit LIMIT
                        limit number of rows
```

--------------------------------

### Manage HAProxy Backend and Frontend

Source: https://context7.com/opnsense/plugins/llms.txt

Operations for adding backend servers and searching existing frontends via the HAProxy API.

```bash
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/haproxy/settings/addServer" \
  -d '{"server":{"enabled":"1","name":"web1","address":"192.168.1.10","port":"8080"}}'
```

```bash
curl -k -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/haproxy/settings/searchFrontends" \
  -d '{"current":1,"rowCount":25,"searchPhrase":"web"}'
```

--------------------------------

### Build JavaScript Files with Webpack

Source: https://github.com/opnsense/plugins/blob/master/www/nginx/README.md

Execute the webpack-cli command to build the JavaScript files. Ensure you are in the correct directory. Files ending with `.html` are converted to JavaScript functions.

```bash
node_modules/.bin/webpack-cli --config webpack.conf.js
```

--------------------------------

### Usage of send_heartbeat.py

Source: https://github.com/opnsense/plugins/blob/master/security/etpro-telemetry/README.md

Command-line interface documentation for sending device activity heartbeats.

```bash
usage: send_heartbeat.py [-h] [-e ENDPOINT] [-i] [-c CONFIG]

optional arguments:
  -h, --help            show this help message and exit
  -e ENDPOINT, --endpoint ENDPOINT
                        Endpoint url to reach
  -i, --insecure        Insecure, skip certificate validation
  -c CONFIG, --config CONFIG
                        rule downloader configuration
  -D, --direct          do not sleep before send (disable traffic spread)
  -t, --test            test mode, output request/response to stdout
```

--------------------------------

### Define Backend Actions

Source: https://context7.com/opnsense/plugins/llms.txt

Configure backend actions in an INI file to map commands to scripts executed by the configd service.

```ini
# src/opnsense/service/conf/actions.d/actions_helloworld.conf
[test]
command:/usr/local/opnsense/scripts/helloworld/testConnection.py
parameters:
type:script_output
message:hello world module test
```

--------------------------------

### Configure Nginx Include Pattern

Source: https://github.com/opnsense/plugins/blob/master/www/nginx/README.md

The include pattern for nginx vhosts is `opnsense_<TYPE>_vhost_plugins/*.conf`. Files in `/usr/local/etc/nginx/opnsense_<TYPE>_vhost_plugins` ending with `.conf` are automatically included. Type can be http or stream.

```nginx
opnsense_<TYPE>_vhost_plugins/*.conf
```

--------------------------------

### Service API Controller (Start/Stop/Status)

Source: https://context7.com/opnsense/plugins/llms.txt

Manages service lifecycle by extending ApiMutableServiceControllerBase. Use for controlling service status and configuration.

```php
<?php
// src/opnsense/mvc/app/controllers/OPNsense/HAProxy/Api/ServiceController.php
namespace OPNsense\HAProxy\Api;

use OPNsense\Base\ApiMutableServiceControllerBase;
use OPNsense\Core\Backend;

class ServiceController extends ApiMutableServiceControllerBase
{
    protected static $internalServiceClass = '\OPNsense\HAProxy\HAProxy';
    protected static $internalServiceTemplate = 'OPNsense/HAProxy';
    protected static $internalServiceEnabled = 'general.enabled';
    protected static $internalServiceName = 'haproxy';

    // Custom action: Test configuration syntax
    public function configtestAction()
    {
        $backend = new Backend();
        $backend->configdRun('template reload OPNsense/HAProxy');
        $response = $backend->configdRun("haproxy configtest");
        return array("result" => $response);
    }

    // Override: Use soft-reload instead of restart
    protected function reconfigureForceRestart()
    {
        return 0;
    }
}
```

--------------------------------

### OPNsense Model Definition - Basic Fields

Source: https://context7.com/opnsense/plugins/llms.txt

Defines the data structure for a simple OPNsense plugin using XML. It includes fields for enabling the application, SMTP host, sender and recipient email addresses, and a description.

```xml
<!-- src/opnsense/mvc/app/models/OPNsense/HelloWorld/HelloWorld.xml -->
<model>
    <mount>//OPNsense/helloworld</mount>
    <description>the OPNsense "Hello World" application</description>
    <items>
        <general>
            <Enabled type="BooleanField">
                <Default>1</Default>
                <Required>Y</Required>
            </Enabled>
            <SMTPHost type="NetworkField">
                <Required>Y</Required>
            </SMTPHost>
            <FromEmail type="EmailField">
                <Default>sample@example.com</Default>
                <Required>Y</Required>
            </FromEmail>
            <ToEmail type="EmailField">
                <Required>Y</Required>
                <ValidationMessage>please specify a valid email address</ValidationMessage>
            </ToEmail>
            <Description type="TextField">
                <Required>Y</Required>
            </Description>
        </general>
    </items>
</model>

```

--------------------------------

### Settings API Controller

Source: https://context7.com/opnsense/plugins/llms.txt

Endpoints for managing configuration items including search, retrieval, creation, updates, toggling, and deletion.

```APIDOC
## GET /api/gridexample/settings/searchItem

### Description
List configuration items with pagination.

### Method
GET

### Endpoint
/api/gridexample/settings/searchItem

### Query Parameters
- **current** (integer) - Optional - Current page number
- **rowCount** (integer) - Optional - Number of rows per page

### Response
#### Success Response (200)
- **rows** (array) - List of items
- **rowCount** (integer) - Number of rows returned
- **total** (integer) - Total items
- **current** (integer) - Current page

## GET /api/gridexample/settings/getItem/{uuid}

### Description
Retrieve a single configuration item by its UUID.

### Method
GET

### Endpoint
/api/gridexample/settings/getItem/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier of the item

## POST /api/gridexample/settings/addItem

### Description
Create a new configuration item.

### Method
POST

### Endpoint
/api/gridexample/settings/addItem

### Request Body
- **address** (object) - Required - The configuration data object

## POST /api/gridexample/settings/setItem/{uuid}

### Description
Update an existing configuration item.

### Method
POST

### Endpoint
/api/gridexample/settings/setItem/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier of the item

### Request Body
- **address** (object) - Required - The updated configuration data

## POST /api/gridexample/settings/toggleItem/{uuid}

### Description
Toggle the enabled state of a configuration item.

### Method
POST

### Endpoint
/api/gridexample/settings/toggleItem/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier of the item

## POST /api/gridexample/settings/delItem/{uuid}

### Description
Delete a configuration item.

### Method
POST

### Endpoint
/api/gridexample/settings/delItem/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier of the item
```

--------------------------------

### Control HAProxy Service

Source: https://context7.com/opnsense/plugins/llms.txt

Commands to validate the configuration and trigger a service reconfigure.

```bash
curl -k -u "$API_KEY:$API_SECRET" "$BASE_URL/api/haproxy/service/configtest"
```

```bash
curl -k -X POST -u "$API_KEY:$API_SECRET" "$BASE_URL/api/haproxy/service/reconfigure"
```

--------------------------------

### Define GUI Forms

Source: https://context7.com/opnsense/plugins/llms.txt

Specify form fields for the GUI using XML definitions.

```xml
<!-- src/opnsense/mvc/app/controllers/OPNsense/HelloWorld/forms/general.xml -->
<form>
    <field>
        <id>helloworld.general.Enabled</id>
        <label>enabled</label>
        <type>checkbox</type>
        <help>Enable this feature</help>
    </field>
    <field>
        <id>helloworld.general.SMTPHost</id>
        <label>SMTPHost</label>
        <type>text</type>
        <help><![CDATA[ip address of the mail host]]></help>
        <hint>choose a valid IPv4/v6 address</hint>
    </field>
    <field>
        <id>helloworld.general.FromEmail</id>
        <label>Email (from)</label>
        <type>text</type>
    </field>
    <field>
        <id>helloworld.general.ToEmail</id>
        <label>Email (to)</label>
        <type>text</type>
    </field>
    <field>
        <id>helloworld.general.Description</id>
        <label>Description</label>
        <type>text</type>
    </field>
</form>
```

--------------------------------

### POST /api/haproxy/service/reconfigure

Source: https://context7.com/opnsense/plugins/llms.txt

Triggers a reconfiguration of the HAProxy service, regenerating the configuration and reloading the service.

```APIDOC
## POST /api/haproxy/service/reconfigure

### Description
Regenerates the HAProxy configuration and reloads the service.

### Method
POST

### Endpoint
/api/haproxy/service/reconfigure

### Response
#### Success Response (200)
- **status** (string) - The status of the operation, typically 'ok'.

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### Manage HAProxy Service via API

Source: https://context7.com/opnsense/plugins/llms.txt

Use these cURL commands to reconfigure the HAProxy service or validate its configuration syntax.

```bash
curl -k -X POST -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/haproxy/service/reconfigure"
# Response: {"status":"ok"}
```

```bash
curl -k -u "$API_KEY:$API_SECRET" \
  "$BASE_URL/api/haproxy/service/configtest"
# Response: {"result":"Configuration file is valid"}
```

--------------------------------

### Hooking a HTTP Server Block

Source: https://github.com/opnsense/plugins/blob/master/www/nginx/README.md

To hook a HTTP server block, create a directory named `UUID_pre` or `UUID_post` in the nginx configuration directory and place a `.conf` file within it. UUID refers to the server object's UUID.

```nginx
UUID_pre
```

```nginx
UUID_post
```

--------------------------------

### Render View and Form in IndexController

Source: https://context7.com/opnsense/plugins/llms.txt

This PHP controller action is used to render the main view for a plugin and load a form definition. It sets the view template and assigns a form object to the view.

```php
<?php
// src/opnsense/mvc/app/controllers/OPNsense/HelloWorld/IndexController.php
namespace OPNsense\HelloWorld;

class IndexController extends \OPNsense\Base\IndexController
{
    public function indexAction()
    {
        $this->view->pick('OPNsense/HelloWorld/index');
        $this->view->generalForm = $this->getForm("general");
    }
}

```

--------------------------------

### Settings API Controller (CRUD Operations)

Source: https://context7.com/opnsense/plugins/llms.txt

Provides REST API endpoints for configuration management using automatic CRUD operations. Use for managing settings items.

```php
<?php
// src/opnsense/mvc/app/controllers/OPNsense/GridExample/Api/SettingsController.php
namespace OPNsense\GridExample\Api;

use OPNsense\Base\ApiMutableModelControllerBase;

class SettingsController extends ApiMutableModelControllerBase
{
    protected static $internalModelName = 'gridexample';
    protected static $internalModelClass = 'OPNsense\GridExample\GridExample';

    // GET /api/gridexample/settings/searchItem - List items with pagination
    public function searchItemAction()
    {
        return $this->searchBase("addresses.address", null, "email");
    }

    // POST /api/gridexample/settings/setItem/{uuid} - Update existing item
    public function setItemAction($uuid)
    {
        return $this->setBase("address", "addresses.address", $uuid);
    }

    // POST /api/gridexample/settings/addItem - Create new item
    public function addItemAction()
    {
        return $this->addBase("address", "addresses.address");
    }

    // GET /api/gridexample/settings/getItem/{uuid} - Get single item
    public function getItemAction($uuid = null)
    {
        return $this->getBase("address", "addresses.address", $uuid);
    }

    // POST /api/gridexample/settings/delItem/{uuid} - Delete item
    public function delItemAction($uuid)
    {
        return $this->delBase("addresses.address", $uuid);
    }

    // POST /api/gridexample/settings/toggleItem/{uuid} - Toggle enabled state
    public function toggleItemAction($uuid, $enabled = null)
    {
        return $this->toggleBase("addresses.address", $uuid, $enabled);
    }
}
```

--------------------------------

### HAProxy API Settings Controller

Source: https://context7.com/opnsense/plugins/llms.txt

This PHP controller provides API endpoints for managing HAProxy configurations, including frontends, backends, and servers. It extends a base controller for common CRUD operations.

```php
<?php
// src/opnsense/mvc/app/controllers/OPNsense/HAProxy/Api/SettingsController.php (excerpt)
namespace OPNsense\HAProxy\Api;

use OPNsense\Base\ApiMutableModelControllerBase;

class SettingsController extends ApiMutableModelControllerBase
{
    protected static $internalModelName = 'haproxy';
    protected static $internalModelClass = '\OPNsense\HAProxy\HAProxy';
    protected static $internalModelUseSafeDelete = true;

    // Frontend management
    public function getFrontendAction($uuid = null) { return $this->getBase('frontend', 'frontends.frontend', $uuid); }
    public function setFrontendAction($uuid) { return $this->setBase('frontend', 'frontends.frontend', $uuid); }
    public function addFrontendAction() { return $this->addBase('frontend', 'frontends.frontend'); }
    public function delFrontendAction($uuid) { return $this->delBase('frontends.frontend', $uuid); }
    public function toggleFrontendAction($uuid) { return $this->toggleBase('frontends.frontend', $uuid); }
    public function searchFrontendsAction() { return $this->searchBase('frontends.frontend', array('enabled', 'name', 'description'), 'name'); }

    // Backend management
    public function getBackendAction($uuid = null) { return $this->getBase('backend', 'backends.backend', $uuid); }
    public function setBackendAction($uuid) { return $this->setBase('backend', 'backends.backend', $uuid); }
    public function addBackendAction() { return $this->addBase('backend', 'backends.backend'); }
    public function delBackendAction($uuid) { return $this->delBase('backends.backend', $uuid); }
    public function searchBackendsAction() { return $this->searchBase('backends.backend', array('enabled', 'name', 'description'), 'name'); }

    // Server management
    public function getServerAction($uuid = null) { return $this->getBase('server', 'servers.server', $uuid); }
    public function setServerAction($uuid) { return $this->setBase('server', 'servers.server', $uuid); }
    public function addServerAction() { return $this->addBase('server', 'servers.server'); }
    public function delServerAction($uuid) { return $this->delBase('servers.server', $uuid); }
    public function searchServersAction() { return $this->searchBase('servers.server', array('enabled', 'name', 'type', 'mode', 'address', 'port', 'description'), 'name'); }
}

```

--------------------------------

### Volt View Template for Plugin UI

Source: https://context7.com/opnsense/plugins/llms.txt

This Volt template defines the structure and behavior of a plugin's web interface. It includes JavaScript for API interactions, form handling, and displaying messages, along with HTML for the form and buttons.

```volt
{# src/opnsense/mvc/app/views/OPNsense/HelloWorld/index.volt #}
<script>
    $( document ).ready(function() {
        // Load settings from API
        mapDataToFormUI({'frm_GeneralSettings':"/api/helloworld/settings/get"}).done(function(data){
            // Actions after load
        });

        // Save button handler
        $("#saveAct").click(function(){
            saveFormToEndpoint("/api/helloworld/settings/set",'frm_GeneralSettings',function(){
                // Reload service after save
                ajaxCall(url="/api/helloworld/service/reload", sendData={},callback=function(data,status) {
                    // Action after reload
                });
            });
        });

        // Test button using SimpleActionButton
        $("#testAct").SimpleActionButton({
            onAction: function(data) {
                $("#responseMsg").removeClass("hidden").html(data['message']);
            }
        });
    });
</script>

<div class="alert alert-info hidden" role="alert" id="responseMsg"></div>

<div class="col-md-12">
    {{ partial("layout_partials/base_form",['fields':generalForm,'id':'frm_GeneralSettings'])}}
</div>

<div class="col-md-12">
    <button class="btn btn-primary" id="saveAct" type="button"><b>{{ lang._('Save') }}</b></button>
    <button class="btn btn-primary" id="testAct" data-endpoint="/api/helloworld/service/test" data-label="{{ lang._('Test') }}"></button>
</div>

```

--------------------------------

### Usage of send_telemetry.py

Source: https://github.com/opnsense/plugins/blob/master/security/etpro-telemetry/README.md

Command-line interface documentation and testing command for sending anonymized telemetry data.

```bash
usage: send_telemetry.py [-h] [-e ENDPOINT] [-i] [-c CONFIG] [-l LOG]
                         [-s STATE]

optional arguments:
  -h, --help            show this help message and exit
  -e ENDPOINT, --endpoint ENDPOINT
                        Endpoint url to reach
  -i, --insecure        Insecure, skip certificate validation
  -c CONFIG, --config CONFIG
                        rule downloader configuration
  -l LOG, --log LOG     log directory containing eve.json files
  -s STATE, --state STATE
                        persistent state (and lock) filename
  -d DAYS, --days DAYS  Maximum number of days to look back on initial run
  -D, --direct          do not sleep before send (disable traffic spread)
```

```bash
python send_telemetry.py -i -d 9999 -e https://endpoint -c testdata/rule-updater.config -l testdata/log/
```

--------------------------------

### Regex Protocol Configuration

Source: https://github.com/opnsense/plugins/blob/master/net/sslh/DEVELOPMENT.md

Defines 'regex' protocols with specific host, port, and regex patterns for matching incoming requests. This is useful for advanced traffic routing based on request content.

```yaml
protocols: (
    {
        name: "regex";
        host: "192.168.0.2";
        port: "80";
        regex_patterns:
                ["^(GET|POST|PUT|OPTIONS|DELETE|HEADER) [^ ]* HTTP/[0-9.]*[
]*Host: host_A.acme"]
    },
    {
        name: "regex";
        host: "192.168.0.3";
        port: "80";
        regex_patterns:
                ["^(GET|POST|PUT|OPTIONS|DELETE|HEADER) [^ ]* HTTP/[0-9.]*[
]*Host: host_B.acme"]
    }
);
```

--------------------------------

### Generate Maltrail User Whitelist

Source: https://github.com/opnsense/plugins/blob/master/security/maltrail/src/opnsense/service/templates/OPNsense/Maltrail/user_whitelist.txt

This Jinja2 template snippet generates a user whitelist for Maltrail. It iterates over a comma-separated list of items, trimming whitespace from each, provided the whitelist setting is configured and not empty.

```Jinja2
{% if helpers.exists('OPNsense.maltrail.general.whitelist') and OPNsense.maltrail.general.whitelist != '' %}
{%   for item in OPNsense.maltrail.general.whitelist.split(',') %}
{{     item|trim }}
{%   endfor %}
{% endif %}
```

--------------------------------

### Service API Controller

Source: https://context7.com/opnsense/plugins/llms.txt

Endpoints for managing the lifecycle of services, including status checks and control commands.

```APIDOC
## GET /api/haproxy/service/status

### Description
Check the current status of the service.

### Method
GET

### Endpoint
/api/haproxy/service/status

### Response
#### Success Response (200)
- **status** (string) - Current service status

## POST /api/haproxy/service/start

### Description
Start the service.

### Method
POST

### Endpoint
/api/haproxy/service/start

## POST /api/haproxy/service/stop

### Description
Stop the service.

### Method
POST

### Endpoint
/api/haproxy/service/stop

## POST /api/haproxy/service/restart

### Description
Restart the service.

### Method
POST

### Endpoint
/api/haproxy/service/restart
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.