Alias Management

This document describes how to use the alias management cmdlets in the PSOPNSenseAPI module.

Overview

Aliases in OPNSense are named lists of networks, hosts, ports, or URLs that can be used in firewall rules. Using aliases makes it easier to manage firewall rules, as you can update the alias content without having to modify the rules that use it.

The PSOPNSenseAPI module provides cmdlets for managing aliases:

Get-OPNSenseAlias: Retrieves aliases from an OPNSense firewall
New-OPNSenseAlias: Creates a new alias on an OPNSense firewall
Set-OPNSenseAlias: Updates an alias on an OPNSense firewall
Remove-OPNSenseAlias: Removes an alias from an OPNSense firewall

Alias Types

OPNSense supports several types of aliases:

host: A list of IP addresses
network: A list of networks in CIDR notation
port: A list of port numbers
url: A URL that points to a list of IPs or networks
urltable: A URL that points to a table of IPs or networks
geoip: A list of country codes for GeoIP filtering
networkgroup: A group of networks
mac: A list of MAC addresses
interface: A list of network interfaces
dynipv6host: A list of dynamic IPv6 hosts
internal: Special internal aliases
external: Special external aliases

Examples

Getting Aliases

# Get all aliases
Get-OPNSenseAlias

# Get a specific alias by UUID
Get-OPNSenseAlias -Uuid "9e4ec4f0-9dd1-4fa3-8c1d-8a8e9d772b0f"

# Get a specific alias by name
Get-OPNSenseAlias -Name "WebServers"

# Get all host aliases
Get-OPNSenseAlias -Type host

# Get all port aliases
Get-OPNSenseAlias -Type port

Creating Aliases

# Create a host alias
New-OPNSenseAlias -Name "WebServers" -Type host -Content "192.168.1.10,192.168.1.11" -Description "Web Servers" -Apply

# Create a network alias
New-OPNSenseAlias -Name "InternalNetworks" -Type network -Content "192.168.1.0/24,192.168.2.0/24" -Description "Internal Networks" -Apply

# Create a port alias
New-OPNSenseAlias -Name "WebPorts" -Type port -Content "80,443" -Protocol TCP -Description "Web Ports" -Apply

# Create a URL alias
New-OPNSenseAlias -Name "BlockList" -Type url -Content "https://example.com/blocklist.txt" -UpdateFrequency 1 -Description "Block List" -Apply

Updating Aliases

# Update an alias's content
Set-OPNSenseAlias -Uuid "9e4ec4f0-9dd1-4fa3-8c1d-8a8e9d772b0f" -Content "192.168.1.10,192.168.1.11,192.168.1.12" -Apply

# Update an alias's description
Set-OPNSenseAlias -Uuid "9e4ec4f0-9dd1-4fa3-8c1d-8a8e9d772b0f" -Description "Updated description" -Apply

# Disable an alias
Set-OPNSenseAlias -Uuid "9e4ec4f0-9dd1-4fa3-8c1d-8a8e9d772b0f" -Disabled -Apply

# Enable an alias
Set-OPNSenseAlias -Uuid "9e4ec4f0-9dd1-4fa3-8c1d-8a8e9d772b0f" -Enabled -Apply

# Enable counters for an alias
Set-OPNSenseAlias -Uuid "9e4ec4f0-9dd1-4fa3-8c1d-8a8e9d772b0f" -EnableCounters -Apply

Removing Aliases

# Remove an alias by UUID
Remove-OPNSenseAlias -Uuid "9e4ec4f0-9dd1-4fa3-8c1d-8a8e9d772b0f" -Apply

# Remove an alias with confirmation
Remove-OPNSenseAlias -Uuid "9e4ec4f0-9dd1-4fa3-8c1d-8a8e9d772b0f" -Confirm -Apply

# Remove an alias without confirmation
Remove-OPNSenseAlias -Uuid "9e4ec4f0-9dd1-4fa3-8c1d-8a8e9d772b0f" -Force -Apply

# Remove aliases by pipeline
Get-OPNSenseAlias -Type host | Remove-OPNSenseAlias -Force -Apply

Using Aliases in Firewall Rules

Once you have created aliases, you can use them in firewall rules:

# Create a firewall rule using aliases
New-OPNSenseFirewallRule -Description "Allow Web Traffic" -Protocol TCP -SourceNet "InternalNetworks" -DestinationPort "WebPorts" -Action pass -Apply

Best Practices

Use descriptive names: Choose alias names that clearly indicate their purpose.
Use aliases for groups of objects: Aliases are most useful when they group related objects.
Keep aliases organized: Use a consistent naming convention for aliases.
Document aliases: Use the description field to document the purpose of the alias.
Apply changes: Always use the -Apply parameter to apply changes immediately, or apply them later using Apply-OPNSenseFirewallChanges.

4.1 KiB Raw Blame History