- »
- Firewall »
- Aliases
Aliases are named lists of networks, hosts or ports that can be used as one entityby selecting the alias name in the various supported sections of the firewall.These aliases are particularly useful to condense firewall rules and minimizechanges.
Aliases can be added, modified and removed via Firewall ‣ Aliases.
Overview¶
The page opens with an overview of the aliases available, including some internal ones available from installed software.At the top of the page you can search for aliases or preselect various types or categories to which they belong.
In order to gain some insights into the current status of the plugins, two additional (meta) fields are being displayed, being:
Loaded#
Shows the amount of entries planned to install into the table, in case there’s not enough memory available to load theitem in question, one can easily find the alias causing the overflow in table entries (bar at the right top of the page)
Last updated
Shows the last timestamp from the entries saved to disk.
Note
The fields above are only used for aliases that contain either networks or hosts, port type aliases are part of therule and thus not visible in any table.
Alias Types¶
OPNsense offers the following alias types:
Type | Description |
---|---|
Hosts | Single hosts by IP or Fully Qualified Domain Name orhost exclusions (starts with “!” sign) |
Networks | Entire network p.e. 192.168.1.1/24 or networkexclusion eg !192.168.1.0/24 |
Ports | Port numbers or a port range like 20:30 |
MAC addresses | MAC address or partial mac addresses like |
URL (IPs) | A table of IP addresses that are fetched once |
URL Tables (IPs) | A table of IP addresses that are fetched on regularintervals. |
GeoIP | Select countries or whole regions |
Network group | Combine different network type aliases into one |
Dynamic IPv6 Host | A Host entry that will auto update on a prefixchange |
BGP ASN | Maps autonomous system (AS) numbers to networkswhere they are responsible for. |
OpenVPN group | Map user groups to logged in OpenVPN users |
Internal(automatic) | Internal aliases which are managed by the product |
External(advanced) | Externally managed alias, this only handles theplaceholder. Content is set from another source(plugin, api call, etc) |
Hosts¶
Hosts can be entered as a single IP address, a range (separated with a minus sign, e.g. 10.0.0.1-10.0.0.10
)or a fully qualified domain name.
When using a fully qualified domain name, the name will be resolved periodically(default is each 300 seconds).
- Sample
Let’s say we want to create an alias table for www.youtube.com
Apply changes and look at the content of our newly created pf table.
Go to Firewall ‣ Diagnostics ‣ Aliases and select our newly created youtube table.
As you can see there are multiple IP addresses for this domain.
To change the alias domain resolve interval, go to Firewall ‣ Settings ‣ Advanced andset Aliases Resolve Interval to the number of seconds to refresh.
Hosts type Aliases can contain exclusion hosts.Exclusion addresses starts with “!” sign (eg !192.168.0.1) and can be used to exclude hosts from Network Group Aliases.
Warning
Please note thet the Flush action is not persistent!
“flush” means flush the current contents of the alias, which will be repopulated when it’s not an external type,so flush in most cases isn’t very useful.
Same behaviour applies to the API call alias_util flush
Networks¶
Networks are specified in Classless Inter-Domain Routing format (CIDR). Use thethe correct CIDR mask for each entry. For instance a /32 specifies a single IPv4 host,or /128 specifies a single IPv6 host, whereas /24 specifies 255.255.255.0 and/64 specifies a normal IPv6 network.Network type Aliases can contain exclusion hosts or networks.Exclusion addresses starts with “!” sign (eg !192.168.0.0/24) and can be used toexclude hosts or networks from current Alias or Network Group Alias
Apart from the CIDR notation, one could also use a wildcard maskto match ranges of hosts or networks.
Tip
To match all servers ending at .1 in the 192.168.X.1 networks, use a wildcard definition like 192.168.0.1/0.0.255.0
Ports¶
Ports can be specified as a single number or a range using a colon :.For instance to add a range of 20 to 25 one would enter 20:25 in the Port(s)section.
MAC addresses¶
Hardware mac addresses can be specified as a (partial) hex value, such as F4:90:EA
to match all addresses fromDeciso or f4:90:ea:00:00:01
to match a single item (the input is case insensitive).
The way these aliases function is approximately the same as hostnames in host type aliases, they are resolved on periodicintervals from the arp
and ndp
tables.
Warning
Please be aware that hardware addresses can be spoofed (https://en.wikipedia.org/wiki/MAC_spoofing), which doesn’t makefilters on them more secure than ip addresses in any way.
Note
Since mappings between addresses and mac addresses are resolved periodically the actual situation can differ, you canalways check Firewall -> Diagnostics -> Aliases to inspect the current contents of the alias.
URL Tables¶
URL tables can be used to fetch a list of IP addresses from a remote server.There are several IP lists available for free, most notably are the “Don’t RouteOr Peer” lists from Spamhaus.
Note
The content of the file being fetched should contain one IPv[4|6] address per line, lines that start with a whitespace
, colon (,
), semicolon (;
), pipe (|
) or hash (#
) will be ignored.
GeoIP¶
With GeoIP alias you can select one or more countries or whole continents to blockor allow. Use the toggle all checkbox to select all countries within the givenregion.
To use GeoIP, you need to configure a source in the Firewall ‣ Aliases -> GeoIP settings tab, the most commonlyused source is MaxMind, for which we have a how-to available : MaxMind GeoIP’s Setup
Note
When using the Business Edition, you can leave the Url`
field empty so the firewall will download the database providedby us.
The configured url should point to a zip file containing the following csv files:
Filename | Purpose | Format | Example |
---|---|---|---|
%prefix%-locations-en.csv | maps geo locations to iso countries | geoname_id,,,,country_iso_code | 1,,,,NL |
%prefix%-IPv4.csv | IPv4 networks | network,geoname_id | 2.21.241.0/28,1 |
%prefix%-IPv6.csv | IPv6 networks | network,geoname_id | 2001:470:1f15:210::/64,1 |
The %prefix%
can be used to identify the product and/or vendor, in MaxMind’s case these files are namedGeoLite2-Country-Locations-en.csv
, GeoLite2-Country-Blocks-IPv4.csv
, GeoLite2-Country-Blocks-IPv6.csv
for example.
Tip
Geo ip lists can be rather large, especially when using IPv6. When creating rules, always try to minimize the number ofaddresses needed in your selection. A selection of all countries in the world not being the Netherlands can usually berewritten as only addresses from the Netherlands for example.
Tip
If the number of items is larger than the allocated alias size, you can assign more memory to aliases.Firewall ‣ Settings ‣ Advanced : Firewall Maximum Table Entries
Network group¶
Combine different network type aliases into one, this type of alias accepts other host type aliases (networks, hosts, …).Although nesting is possible with other alias types as well, this type only displays valid aliases easing administration, functionallya Networks
type alias can do the same but uses a different presentation.
Dynamic IPv6 Host¶
An IPv6 Dynamic Host is used where the system is using a dynamic prefix on the LAN, a tracking interface. When the prefixchanges, either due to the ISP changing the prefix at will or the prefix changes when the WAN connection is reset, any aliascontaining an address of a client such as a server on the LAN would no longer be valid.
For example, you obtain a prefix 2001:db8:2222:2800::/56. You have a /56 prefix and if the tracking id was set to 0 for yourLAN, you would have an address range on your LAN of 2001:db8:2222:2800:: to 2001:db8:2222:2800:FFFF:FFFF:FFFF:FFFF.
You want to run a server on your LAN that is accessable from the WAN so you give it a static address of2001:db8:2222:2800:1000:1000::1 and create a rule allowing traffic to access the server.
When your prefix changes, that static address is no longer valid, so you must use the Dynamic IPv6 Host to create an aliasaddress for the firewall entry that automatically tracks the prefix and changes the rule.
The Dynamic Host Alias will always split on the /64 boundary, it will take the upper 64 bits from the interface you selectand the lower 64 bits from the address you enter. It does not matter what size your prefix delegation is.
Create a new IPv6 Dynamic Host alias and enter only the suffix of the address, in this example, we will enter the lower 64bits of the address, you would enter ::1000:1000:0000:1, note the ‘::’ at the start of the address, you MUST always startthe address with a ‘::’. You do not need to enter a size after the address i.e. /128 as that is automatically assumed.
Select the interface you wish to use for the source of the uppper 64 bits, in this case we will select the LAN interface.
When the prefix changes, the alias address will then be updated in the firewall rules, let’s say your prefix changes to2001:db8:2222:3200::/56 the rule updates and the entry for your server in the firewall would update automatically to be2001:db8:2222:3200:1000:1000::1
Let’s take another example, you have a /48 prefix delegation, you have two LAN interfaces and a server on each. You would needto create two separate Dynamic IPv6 Host entries, one for each LAN. For simplicities sake we will use the same address for eachserver on each interface, you would enter ::aaaa:bbbb:cccc:0001 as the address.
Upper 64 bits, taken from LAN 1 Interface | Lower 64 bits - Your server address |
---|---|
Server 1: 2a02:1234:5678:0000 | aaaa:bbbb:cccc:0001 |
Server 1 GUA address is: 2a02:1234:5678:0000:aaaa:bbbb:cccc:0001 |
Upper 64 bits, taken from LAN 2 Interface | Lower 64 bits - Your server address |
---|---|
Server 2: 2a02:1234:5678:0001 | aaaa:bbbb:cccc:0001 |
Server 2 GUA address is: 2a02:1234:5678:0001:aaaa:bbbb:cccc:0001 |
The prefix changes, in this case we have a /48 prefix, so the new prefix is 2a02:1234:5679/48 our aliases would update to giveus the following addresses:
LAN 1: Server 1 GUA address is: | 2a02:1234:5679:0000:aaaa:bbbb:cccc:0001 |
LAN 2: Server 2 GUA address is: | 2a02:1234:5679:0001:aaaa:bbbb:cccc:0001 |
You may enter multiple addresses, for example if you have several servers on the same LAN segment, just add the suffix for each one.In the example below we have three servers.
BGP ASN¶
With this alias type you are able to select networks by their responsible parties.Using BGP parties announce the addresses they are responsible for to eachother.For example Cloudflare uses AS number 13335
, Microsoft is known to use 8075
.
More background and how addresses are assigned is explained on wikipedia
External¶
The contents for external alias types is not administered via our normal alias service and can be practicalin scenarios where you want to push new entries from external programs. Such as specific lockout features orexternal tools feeding access control to your firewall.
In Firewall ‣ Diagnostics ‣ Aliases you can always inspect the current contents of the externalalias and add or remove entries immediately.
Tip
When changing alias contents which are used on firewall rules with state tracking enabled, you might need toremove the specific state before the new rule turns active. (see Firewall ‣ Diagnostics ‣ States Dump )
Tip
Since external alias types won’t be touched by OPNsense, you can use pfctl
directly in scripts to manageits contents. (e.g. pfctl -t MyAlias -T add 10.0.0.3
to add 10.0.0.3 to MyAlias)
OpenVPN group¶
This alias type offers the possibility to build firewall policies for logged in OpenVPN users by the group they belong toas configured in System ‣ Access ‣ Groups.
The current users that are logged into OpenVPN can be inspected via VPN ‣ OpenVPN ‣ Connection Status, the aliasjust follows this information and flushes the attached addresses to the item in question.
For example, when a user named fred which is a member of group remote_users logs into OpenVPN and received a tunnel addressof 10.10.10.2
, the alias containing “remote_users” would include this address as well.
Note
For this mechanism to work, the common-name of the user certificate must match the username exactly, which is the case bydefault if the certificate has been created from the user manager.
Tip
When using LDAP (Active directory), you can synchronise group membership to avoid double administration in OPNsense.
Internal (automatic)¶
Internal aliases are prefixed with __
so they are easy to identify and can’t overlap with any user defined ones.These aliases help you to determine what the content is for some internal concepts such as “LAN network”. Usingthe Firewall->Diagnostics->Aliases menu item you can inspect their contents at any time.
Using Aliases in Firewall Rules¶
Aliases can be used in firewall rules to ease administration of large lists.For instance we might need a list of remote IP addresses that should have access tocertain services, when anything changes we only need to update the list.
Let’s create a simple alias to allow 3 remote IP addresses access to an ipsec server for a site to site tunnel connection:
192.168.100.1
192.168.200.2
192.168.202.2
We call our list remote_ipsec and update our firewall rules accordingly.
Note
The list icon identifies a rule with an alias.
Export / Import¶
The alias admin page (Firewall ‣ Aliases) contains a download and an upload button in the footer of the table, with this feature you canmerge aliases into the configuration and download a json
formatted list of all aliases in the system.
Since data is validated before insertion, it shouldn’t be possible to import defective data (if the import fails, a list of errors is presented).
Tip
When performing migrations, sometimes its easier to change multiple items at once in a text editor. This feature can easilybe used to facilitate that, with limiting risk of a broken configuration (since items are validated equally as single item input would do).
Add new entries using our API¶
The endpoints from the alias_util can easily be used to push new entries into an alias (or remove existing ones). In case of an external aliasthese items won’t be persistent over reboots, which can be practical in some use-cases (large frequent changing lists for example).
The document “Use the API” contains the steps needed to create an api key and secret, next you can just callthe same endpoint the user interface would.
Below you see how to add 10.0.0.2 to an alias named MyAlias using an insecure connection (self-signed cert) onthe host opnsense.firewall with curl
. The verbose option provides more details about the data exchanged between thetwo machines.
curl \ --header "Content-Type: application/json" \ --basic \ --user "key:secret" \ --request POST \ --insecure \ --verbose \ --data '{"address":"10.0.0.2"}' \ https://opnsense.firewall/api/firewall/alias_util/add/MyAlias
Note
Adding aliases using /api/firewall/alias_util/add/
is only supported for Host, Network and External type aliases
Exclusions¶
Pf firewall tables support exceptions (or exclusion) of addresses. This feature can be used in one Alias or in combined (Networkgroup type) Aliases. See (https://www.freebsd.org/doc/handbook/firewalls-pf.html 30.3.2.4).
Nesting¶
For host and network alias types nesting is possibility, this can simplify management a lot since single items canbe named properly and grouped into sections for administration.
For example, we define 4 servers among 2 critical using different rulesets:
server_a {10.0.1.1}
server_b {10.0.1.2}
server_c {10.0.1.100}
server_d {10.0.1.200}
critical_servers {server_a , server_b}
other_servers {server_c , server_d}
servers { critical_servers , other_servers}.
The alias servers
will contain all 4 addresses after configuration.
There is also a possibility to combine different Aliases with Aliases, consisting of exclusions.For example, there is Alias “FireHOL” that use extensive externl drop-list and two Aliases that containssubnet and hosts exclusions. It is possible to create Network group (combined) Alias (“FireHOL_with_exclusions”):
FireHOL {https://raw.githubusercontent.com/firehol/blocklist-ipsets/master/firehol_level1.netset}
subnets_exclusions {!127.0.0.0/8, !0.0.0.0/8}
hosts_exclusions {!8.8.8.8}
FireHOL_with_exclusions {FireHOL, subnets_exclusions, hosts_exclusions}
FireHOL_with_exclusions
Alias will contain all records from FireHOL Alias excluding addresses from exclusions Aliases.
It’s always good to check if an address is included in the Alias via Firewall ‣ Diagnostics ‣ pfTable
Spamhaus¶
The Spamhaus Don’t Route Or Peer Lists DROP (Don’t Route Or Peer) and EDROP are advisory “drop all traffic” lists,consisting of netblocks that are “hijacked” or leased by professional spam orcyber-crime operations (used for dissemination of malware, trojan downloaders,botnet controllers). The DROP and EDROP lists are a tiny subset of the SBL,designed for use by firewalls and routing equipment to filter out the malicioustraffic from these netblocks.
Source : https://www.spamhaus.org/drop/
- Downloads
To setup the DROP and EDROP lists in combination with the firewall rules, read:Configure Spamhaus (E)DROP