OPNsense Aliases Role

Overview

This role creates and manages firewall aliases on OPNsense via the REST API. Aliases are named groups of IP addresses, networks, or other objects that simplify firewall rule management. The role uses name-based idempotency to create new aliases or update existing ones, applies configuration changes to activate them, and provides a summary of configured aliases.

Note: This role does NOT support deletion to avoid accidentally removing system-created aliases. Delete aliases manually via OPNsense Web UI (Firewall → Aliases).

Purpose

Simplified Rule Management: Group related IPs/networks under descriptive names
Centralized Updates: Change alias membership instead of updating multiple rules
Code as Configuration: Define aliases in YAML instead of GUI
Idempotent: Safe to run multiple times using name-based idempotency
API-Based: Uses OPNsense REST API for reliable automation
Multi-Alias Support: Configure multiple aliases in one run
Safe: No automatic deletion to protect system aliases

Requirements

Ansible 2.9 or higher
OPNsense firewall with API access enabled
API key and secret stored in Ansible Vault
Network connectivity to OPNsense (VLAN10)
OPNsense user with firewall alias permissions

What are OPNsense Aliases?

Aliases are named groups that can contain:

IP addresses (single hosts)
Networks (CIDR notation)
Ports
URLs (for dynamic lists)

Benefits:

Use “Internal_Servers” instead of “192.168.x.x, 192.168.x.x, 192.168.x.x”
Update alias once, affects all firewall rules using it
Self-documenting rules (names describe purpose)
Reduce errors (change in one place)

Role Variables

Required Variables

Variable	Required	Description
`vault_opnsense_bjoffrey_user_api_key`	Yes	OPNsense API key (in vault)
`vault_opnsense_bjoffrey_user_api_secret`	Yes	OPNsense API secret (in vault)
`opnsense_aliases_definition`	Yes	List of aliases to create

Optional Variables

Variable	Default	Description
`opnsense_aliases_validate_certs`	`true`	Validate SSL certificates

Variable Details

opnsense_aliases_definition

List of firewall aliases to create.

Structure:

opnsense_aliases_definition:
  - name: alias_name
    type: host|network|port
    content:
      - item1
      - item2
    description: "Description"
    enabled: "1"
    counters: "0"

Example:

opnsense_aliases_definition:
  - name: Internal_Servers
    type: network
    description: "Internal server infrastructure"
    content:
      - "192.168.x.x/32"
      - "192.168.x.x/32"
      - "192.168.x.x/32"

  - name: Management_IPs
    type: host
    description: "Management workstation IPs"
    content:
      - "192.168.x.x"
      - "192.168.x.x"

  - name: Web_Ports
    type: port
    description: "Standard web service ports"
    content:
      - "80"
      - "443"
      - "8080"

Field descriptions:

Field	Required	Default	Description
`name`	Yes	-	Alias name (no spaces, use underscore)
`type`	Yes	-	Type: `host`, `network`, `port`, `url`
`content`	Yes	-	List of IPs/networks/ports
`description`	No	`""`	Human-readable description
`enabled`	No	`"1"`	Enable (`"1"`) or disable (`"0"`)
`counters`	No	`"0"`	Track statistics (`"1"`) or not (`"0"`)

Dependencies

This role has no dependencies on other Ansible roles, but requires:

OPNsense firewall with API enabled
API key with alias management permissions
Ansible Vault for storing API credentials

Example Playbook

Basic Usage

---
- name: Configure OPNsense Aliases
  hosts: mint-vm
  gather_facts: false

  vars:
    opnsense_aliases_definition:
      - name: Internal_Servers
        type: network
        description: "Server VLAN networks"
        content:
          - "192.168.x.x/24"

  roles:
    - opnsense_aliases

Multiple Aliases

---
- name: Configure Multiple OPNsense Aliases
  hosts: mint-vm
  gather_facts: false

  vars:
    opnsense_aliases_definition:
      - name: DMZ_Hosts
        type: host
        description: "DMZ server IPs"
        content:
          - "192.168.x.x"
          - "192.168.x.x"
          - "192.168.x.x"

      - name: Trusted_Networks
        type: network
        description: "Internal trusted networks"
        content:
          - "192.168.x.x/24"
          - "192.168.x.x/24"

      - name: Common_Ports
        type: port
        description: "Commonly used service ports"
        content:
          - "22"
          - "80"
          - "443"

  roles:
    - opnsense_aliases

With Counters Enabled

---
- name: Configure Aliases with Statistics
  hosts: mint-vm
  gather_facts: false

  vars:
    opnsense_aliases_definition:
      - name: Web_Servers
        type: host
        description: "Production web servers"
        content:
          - "192.168.x.x"
          - "192.168.x.x"
        counters: "1"  # Track usage statistics

  roles:
    - opnsense_aliases

What This Role Does

Fetches existing aliases via /api/firewall/alias/searchItem
Builds name → UUID mapping for idempotency
For each alias in opnsense_aliases_definition:
- Creates new aliases (name doesn’t exist) via /api/firewall/alias/addItem
- Updates existing aliases (name exists but fields differ) via /api/firewall/alias/setItem
If any aliases changed:
- Calls reconfigure endpoint (/api/firewall/alias/reconfigure)
- Applies changes to active firewall configuration
Displays summary:
- Lists all configured alias names

Note: Deletion is NOT supported. Delete aliases manually via OPNsense Web UI.

OPNsense API Endpoints

Add/Update Alias

POST /api/firewall/alias/addItem
Authorization: Basic (API key:secret)
Content-Type: application/json

Request body:

{
  "alias": {
    "enabled": "1",
    "name": "Internal_Servers",
    "type": "network",
    "counters": "0",
    "description": "Server infrastructure",
    "content": "192.168.x.x/32\n192.168.12.20/32"
  }
}

Response:

{
  "result": "saved",
  "uuid": "12345678-1234-1234-1234-123456789abc"
}

Apply Configuration

POST /api/firewall/alias/reconfigure

Activates pending alias changes.

Alias Types

host

Single IP addresses (no CIDR notation).

Example:

name: Web_Servers
type: host
content:
  - "192.168.x.x"
  - "192.168.x.x"

Use case: Specific servers

network

Networks in CIDR notation.

Example:

name: Internal_Networks
type: network
content:
  - "192.168.x.x/24"
  - "192.168.x.x/24"
  - "10.x.x.x/8"

Use case: Entire subnets

port

TCP/UDP ports.

Example:

name: Web_Ports
type: port
content:
  - "80"
  - "443"
  - "8080"
  - "8443"

Use case: Service ports

url

Dynamic lists from URLs (not commonly used with this role).

Alias Naming Conventions

Best practices:

Use descriptive names: Internal_Servers not Alias1
Use underscores instead of spaces: Web_Servers not Web Servers
Group related items: VLAN12_Servers, VLAN12_Printers
Indicate type: Ports_Web, Net_Trusted

Examples:

VLAN10_Management
Servers_Production
Hosts_Monitoring
Ports_Database
Net_DMZ

Using Aliases in Firewall Rules

After creating aliases, use them in firewall rules:

Without alias:

Source: 192.168.x.x, 192.168.x.x, 192.168.x.x
Destination: 192.168.x.x

With alias:

Source: Internal_Servers (alias)
Destination: Management_IPs (alias)

Benefits:

Change alias content → affects all rules automatically
Rules remain readable
Easier to audit

Counters (Statistics)

Enable counters to track alias usage:

counters: "1"

What it tracks:

Number of packets matching this alias
Number of bytes
Shown in OPNsense UI (Firewall → Diagnostics → Aliases)

When to enable:

Troubleshooting: See if traffic matches expected alias
Capacity planning: Measure traffic to specific servers
Security: Detect unexpected traffic patterns

Performance impact: Minimal

Idempotency

Role uses name-based idempotency (create and update only, no deletion):

Create: New alias name → creates alias
Update: Existing name with changed fields → updates alias
No Delete: Aliases are never deleted to protect system aliases
Only applies configuration if changes detected
Safe to run repeatedly

First run: Creates aliases, reports changed Subsequent runs: No changes, reports ok

Important: To remove an alias, delete it manually via OPNsense Web UI (Firewall → Aliases).

Security Considerations

API Credentials: Stored in Ansible Vault
HTTPS: Uses SSL/TLS for API calls
Basic Auth: API key/secret authentication
Certificate Validation: Enabled by default
No Automatic Deletion: Protects system-created aliases from accidental removal

Notes

become: false recommended (no root needed for API calls)
Alias changes require reconfigure call to activate
Role does NOT delete aliases (only creates/updates) to protect system aliases
Delete aliases manually via OPNsense Web UI (Firewall → Aliases)
Content items joined with newline for API
Uses failed_when and changed_when for proper result handling

Troubleshooting

”Authentication failed” errors

Cause: Invalid API key/secret

Solution:

# Verify credentials in vault
ansible-vault view group_vars/all/vault.yml

# Test API manually
curl -u "key:secret" https://opnsense-ip/api/firewall/alias/get

Alias not appearing in firewall

Cause: Reconfigure not called or failed

Solution:

# Manually trigger reconfigure via OPNsense UI
# Firewall → Aliases → Apply

# Check role output for reconfigure task

“Invalid alias name” error

Cause: Name contains spaces or special characters

Solution: Use underscores instead of spaces:

✗ Web Servers
✓ Web_Servers

SSL certificate errors

Cause: Self-signed certificate

Solution: Set opnsense_aliases_validate_certs: false

opnsense_aliases_validate_certs: false

Or install CA certificate on control node.

Testing the Role

Verify Aliases Created

Via OPNsense UI:

Log into OPNsense
Go to Firewall → Aliases
Should see configured aliases

Via API:

curl -u "key:secret" \
  https://opnsense-ip/api/firewall/alias/searchItem | jq

Verify Alias Content

Click on alias in UI to see members.

Use in Firewall Rule

Create test firewall rule using the alias to verify it works.

Best Practices

Descriptive names: Use meaningful alias names
Organize by purpose: Group related IPs/networks
Document with descriptions: Explain alias purpose
Use CIDR notation: For networks, include /32 for single hosts
Version control: Store alias definitions in git
Test before production: Verify aliases work as expected
Regular review: Audit aliases for unused/outdated entries
Consistent naming: Follow naming convention across team
Group related aliases: VLAN-based, service-based, etc.
Enable counters for monitoring: Track important aliases

This role is often used with:

opnsense_firewall: Create rules using aliases
opnsense_source_nat: Use aliases in SNAT rules
opnsense_destination_nat: Use aliases in DNAT rules

License

MIT

Author

Created for homelab infrastructure management.

OPNsense Aliases

OPNsense Aliases Role

Overview

Purpose

Requirements

What are OPNsense Aliases?

Role Variables

Required Variables

Optional Variables

Variable Details

opnsense_aliases_definition

Dependencies

Example Playbook

Basic Usage

Multiple Aliases

With Counters Enabled

What This Role Does

OPNsense API Endpoints

Add/Update Alias

Apply Configuration

Alias Types

host

network

port

url

Alias Naming Conventions

Using Aliases in Firewall Rules

Counters (Statistics)

Idempotency

Security Considerations

Tags

Notes

Troubleshooting

”Authentication failed” errors

Alias not appearing in firewall

“Invalid alias name” error

SSL certificate errors

Testing the Role

Verify Aliases Created

Verify Alias Content

Use in Firewall Rule

Best Practices

Related Roles

License

Author