mirror of
https://github.com/freedbygrace/PSOPNSenseAPI.git
synced 2026-07-26 20:08:30 +00:00
GraceSolutions
121 lines
4.1 KiB
Markdown
121 lines
4.1 KiB
Markdown
# 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
|
|
|
|
```powershell
|
|
# 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
|
|
|
|
```powershell
|
|
# 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
|
|
|
|
```powershell
|
|
# 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
|
|
|
|
```powershell
|
|
# 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:
|
|
|
|
```powershell
|
|
# Create a firewall rule using aliases
|
|
New-OPNSenseFirewallRule -Description "Allow Web Traffic" -Protocol TCP -SourceNet "InternalNetworks" -DestinationPort "WebPorts" -Action pass -Apply
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Use descriptive names**: Choose alias names that clearly indicate their purpose.
|
|
2. **Use aliases for groups of objects**: Aliases are most useful when they group related objects.
|
|
3. **Keep aliases organized**: Use a consistent naming convention for aliases.
|
|
4. **Document aliases**: Use the description field to document the purpose of the alias.
|
|
5. **Apply changes**: Always use the `-Apply` parameter to apply changes immediately, or apply them later using `Apply-OPNSenseFirewallChanges`.
|