-
Notifications
You must be signed in to change notification settings - Fork 50
pfsense_aggregate
Orion Poplawski edited this page Jan 1, 2024
·
12 revisions
Manage multiple pfSense firewall aliases, rules, and rule
separators, plus interfaces and VLANs
ADDED IN: version 0.1.0 of pfsensible.core
OPTIONS (= is mandatory):
- aggregated_aliases
Dict of aliases to apply on the target
default: null
elements: dict
type: list
SUBOPTIONS:
- address
The address of the alias. Use a space separator for
multiple values
default: null
type: str
- descr
The description of the alias
default: null
type: str
- detail
The descriptions of the items. Use || separator between
items
default: null
type: str
= name
The name of the alias
type: str
- state
State in which to leave the alias
choices: [present, absent]
default: present
type: str
- type
The type of the alias
choices: [host, network, port, urltable, urltable_ports]
default: null
type: str
- updatefreq
Update frequency in days for urltable
default: null
type: int
- aggregated_interfaces
Dict of interfaces to apply on the target
default: null
elements: dict
type: list
SUBOPTIONS:
- blockbogons
Blocks traffic from reserved IP addresses (but not RFC
1918) or not yet assigned by IANA.
default: null
type: bool
- blockpriv
Blocks traffic from IP addresses that are reserved for
private networks.
default: null
type: bool
= descr
Description (name) for the interface.
type: str
- enable
Enable interface.
default: false
type: bool
- interface
Network port to which assign the interface.
default: null
type: str
- interface_descr
Network port descr to which assign the interface.
default: null
type: str
- ipv4_address
IPv4 Address.
default: null
type: str
- ipv4_gateway
IPv4 gateway for this interface.
default: null
type: str
- ipv4_prefixlen
IPv4 subnet prefix length.
default: 24
type: int
- ipv4_type
IPv4 Configuration Type.
choices: [none, static, dhcp]
default: none
type: str
- ipv6_address
IPv6 Address.
default: null
type: str
- ipv6_gateway
IPv6 gateway for this interface.
default: null
type: str
- ipv6_prefixlen
IPv6 subnet prefix length.
default: 128
type: int
- ipv6_type
IPv4 Configuration Type.
choices: [none, static, slaac]
default: none
type: str
- mac
Used to modify ("spoof") the MAC address of this
interface.
default: null
type: str
- mss
MSS clamping for TCP connections.
default: null
type: int
- mtu
Maximum transmission unit
default: null
type: int
- speed_duplex
Set speed and duplex mode for this interface.
default: autoselect
type: str
- state
State in which to leave the interface.
choices: [present, absent]
default: present
type: str
- aggregated_nat_outbounds
Dict of nat_outbound rules to apply on the target
default: null
elements: dict
type: list
SUBOPTIONS:
- address
The translated to address, in {ALIAS,NETWORK}[:port]
format. Leave address part empty to use interface address.
default: null
type: str
- after
Rule to go after, or "top"
default: null
type: str
- before
Rule to go before, or "bottom"
default: null
type: str
= descr
The name of the nat rule
default: null
type: str
- destination
The matching destination address, in
{any,ALIAS,NETWORK}[:port] format.
default: null
type: str
- disabled
Is the rule disabled
default: false
type: bool
- interface
The interface for the rule
default: null
type: str
- invert
Invert the sense of the destination match.
default: false
type: bool
- ipprotocol
The Internet Protocol version this rule applies to.
choices: [inet, inet46, inet6]
default: inet46
type: str
- nonat
This option will disable NAT for traffic matching this
rule and stop processing Outbound NAT rules
default: false
type: bool
- nosync
Prevents the rule on Master from automatically syncing to
other CARP members. This does NOT prevent the rule from
being overwritten on Slave.
default: false
type: bool
- poolopts
When an address pool is used, there are several options
available that control how NAT translations happen on the
pool.
choices: ['', round-robin, round-robin sticky-address, random, random sticky-address, source-hash,
bitmask]
default: ''
type: str
- protocol
Which protocol this rule should match.
choices: [any, tcp, udp, tcp/udp, icmp, esp, ah, gre, ipv6, igmp, carp, pfsync]
default: any
type: str
- source
The matching source address, in
{any,(self),ALIAS,NETWORK}[:port] format.
default: null
type: str
- source_hash_key
The key that is fed to the hashing algorithm in hex
format, preceeded by "0x", or any string. A non-hex string
is hashed using md5 to a hexadecimal key. Defaults to a
randomly generated value.
default: ''
type: str
- state
State in which to leave the rule
choices: [present, absent]
default: present
type: str
- staticnatport
Do not randomize source port
default: false
type: bool
- aggregated_nat_port_forwards
Dict of nat_port_forward rules to apply on the target
default: null
elements: dict
type: list
SUBOPTIONS:
- after
Rule to go after, or "top"
default: null
type: str
- associated_rule
Choose one of Add an associated filter rule gets updated
when the port forward is updated, or Add an unassociated
filter rule, or pass which passes all traffic that matches
the entry without having a firewall rule at all.
choices: [associated, unassociated, pass, none]
default: associated
type: str
- before
Rule to go before, or "bottom"
default: null
type: str
= descr
The name of the nat rule
default: null
type: str
- destination
The destination address, in
[!]{IP,HOST,ALIAS,any,IP:INTERFACE,NET:INTERFACE}[:port]
format.
default: null
type: str
- disabled
Is the rule disabled
default: false
type: bool
- interface
The interface for the rule
default: null
type: str
- ipprotocol
The IP protocol
choices: [inet, inet6]
default: inet
type: str
- natreflection
Allows NAT reflection to be enabled or disabled on a per-
port forward basis.
choices: [system-default, enable, purenat, disable]
default: system-default
type: str
- nordr
Disable redirection for traffic matching this rule
default: false
type: bool
- nosync
Prevents the rule on Master from automatically syncing to
other CARP members. This does NOT prevent the rule from
being overwritten on Slave.
default: false
type: bool
- protocol
Which protocol this rule should match.
choices: [tcp, udp, tcp/udp, icmp, esp, ah, gre, ipv6, igmp, pim, ospf]
default: tcp
type: str
- source
The source address, in
[!]{IP,HOST,ALIAS,any,IP:INTERFACE,NET:INTERFACE}[:port]
format.
default: null
type: str
- state
State in which to leave the rule
choices: [present, absent]
default: present
type: str
- target
The translated to address, in {ALIAS,IP}[:port] format.
default: null
type: str
- aggregated_rule_separators
Dict of rule separators to apply on the target
default: null
elements: dict
type: list
SUBOPTIONS:
- after
Rule to go after, or "top"
default: null
type: str
- before
Rule to go before, or "bottom"
default: null
type: str
- color
The separator's color
choices: [info, warning, danger, success]
default: info
type: str
- floating
Is the rule on floating tab
default: null
type: bool
- interface
The interface for the separator
default: null
type: str
= name
The name of the separator
type: str
- state
State in which to leave the separator
choices: [present, absent]
default: present
type: str
- aggregated_rules
Dict of rules to apply on the target
default: null
elements: dict
type: list
SUBOPTIONS:
- ackqueue
QOS acknowledge queue
default: null
type: str
- action
The action of the rule
choices: [pass, block, match, reject]
default: pass
type: str
- after
Rule to go after, or `top'
default: null
type: str
- before
Rule to go before, or `bottom'
default: null
type: str
- destination
The destination address, in
[!]{IP,HOST,ALIAS,any,(self),IP:INTERFACE,NET:INTERFACE}
format.
default: null
type: str
- destination_port
Destination port or port range specification.
This can either be a alias or a port number.
An inclusive range can also be specified, using the format
`first-last'..
default: null
type: str
- direction
Direction floating rule applies to
choices: [any, in, out]
default: null
type: str
- disabled
Is the rule disabled
default: false
type: bool
- floating
Is the rule floating
default: null
type: bool
- gateway
Leave as `default' to use the system routing table or
choose a gateway to utilize policy based routing.
default: default
type: str
- icmptype
One or more of these ICMP subtypes may be specified,
separated by comma, or `any' for all of them.
The types must match ip protocol.
althost, dataconv, echorep, echoreq, fqdnrep, fqdnreq,
groupqry, grouprep, groupterm, inforep, inforeq,
ipv6-here,
ipv6-where, listendone, listenrep, listqry, maskrep,
maskreq, mobredir, mobregrep, mobregreq, mtrace,
mtraceresp,
neighbradv, neighbrsol, niqry, nirep, paramprob, photuris,
redir, routeradv, routersol, routrrenum, skip, squench,
timerep, timereq, timex, toobig, trace, unreach, wrurep,
wrureq
default: any
type: str
- in_queue
Limiter queue for traffic coming into the chosen interface
default: null
type: str
= interface
The interface for the rule
type: str
- ipprotocol
The IP protocol
choices: [inet, inet46, inet6]
default: inet
type: str
- log
Log packets matched by rule
default: null
type: bool
= name
The name the rule
default: null
type: str
- out_queue
Limiter queue for traffic leaving the chosen interface
default: null
type: str
- protocol
The protocol
choices: [any, tcp, udp, tcp/udp, icmp, igmp, ospf, esp, ah, gre, pim, sctp, pfsync, carp]
default: any
type: str
- queue
QOS default queue
default: null
type: str
- queue_error
Raise an error if a specified queue is missing
default: true
type: bool
- quick
Set this option to apply this action to traffic that
matches this rule immediately
default: false
type: bool
- sched
Schedule day/time when the rule must be active
default: null
type: str
- source
The source address, in
[!]{IP,HOST,ALIAS,any,(self),IP:INTERFACE,NET:INTERFACE}
format.
default: null
type: str
- source_port
Source port or port range specification.
This can either be a alias or a port number.
An inclusive range can also be specified, using the format
`first-last'..
default: null
type: str
- state
State in which to leave the rule
choices: [present, absent]
default: present
type: str
- statetype
State type
choices: [keep state, sloppy state, synproxy state, none]
default: keep state
type: str
- tcpflags_any
Allow TCP packets with any flags set.
default: null
type: bool
- tracker
Rule tracking ID. Defaults to timestamp of rule creation.
default: null
type: str
- aggregated_vlans
Dict of VLANs to apply on the target
default: null
elements: dict
type: list
SUBOPTIONS:
- descr
The description of the VLAN
default: ''
type: str
= interface
The interface on which to declare the VLAN. Friendly name
(assignments) can be used.
type: str
- priority
802.1Q VLAN Priority code point. Must be between 0 and 7.
default: null
type: int
- state
State in which to leave the VLAN
choices: [present, absent]
default: present
type: str
= vlan_id
The VLAN tag. Must be between 1 and 4094.
type: int
- ignored_aliases
aliases that will be ignored (won't be auto deleted)
default: []
elements: str
type: list
- ignored_rules
rules that will be ignored (won't be auto deleted)
default: []
elements: str
type: list
- interface_filter
only apply rules and rules separators on those interfaces
(separated by space)
default: null
type: str
- order_rules
rules will be generated following the playbook order
default: false
type: bool
- purge_aliases
delete all the aliases that are not defined into
aggregated_aliases
default: false
type: bool
- purge_interfaces
delete all the interfaces that are not defined into
aggregated_interfaces
default: false
type: bool
- purge_nat_outbounds
delete all the nat_outbound rules that are not defined into
aggregated_nat_outbounds
default: false
type: bool
- purge_nat_port_forwards
delete all the nat_port_forward rules that are not defined
into aggregated_nat_port_forwards
default: false
type: bool
- purge_rule_separators
delete all the rule separators that are not defined into
aggregated_rule_separators
default: false
type: bool
- purge_rules
delete all the rules that are not defined into
aggregated_rules
default: false
type: bool
- purge_vlans
delete all the VLANs that are not defined into
aggregated_vlans
default: false
type: bool
NOTES:
* aggregated_* use the same options definitions than
pfsense corresponding module
AUTHOR: Frederic Bor (@f-bor)
METADATA:
metadata_version: '1.1'
status:
- preview
supported_by: community
EXAMPLES:
- name: "Setup two VLANs, three aliases, six rules, four separators, and delete everything else"
pfsense_aggregate:
purge_aliases: true
purge_rules: true
purge_rule_separators: true
purge_vlans: true
aggregated_aliases:
- { name: port_ssh, type: port, address: 22, state: present }
- { name: port_http, type: port, address: 80, state: present }
- { name: port_https, type: port, address: 443, state: present }
aggregated_rules:
- { name: "allow_all_ssh", source: any, destination: "any:port_ssh", protocol: tcp, interface: lan, state: present }
- { name: "allow_all_http", source: any, destination: "any:port_http", protocol: tcp, interface: lan, state: present }
- { name: "allow_all_https", source: any, destination: "any:port_https", protocol: tcp, interface: lan, state: present }
- { name: "allow_all_ssh", source: any, destination: "any:port_ssh", protocol: tcp, interface: wan, state: present }
- { name: "allow_all_http", source: any, destination: "any:port_http", protocol: tcp, interface: wan, state: present }
- { name: "allow_all_https", source: any, destination: "any:port_https", protocol: tcp, interface: wan, state: present }
aggregated_rule_separators:
- { name: "SSH", interface: lan, state: present, before: allow_all_ssh }
- { name: "HTTP", interface: lan, state: present, before: allow_all_http }
- { name: "SSH", interface: wan, state: present, before: allow_all_ssh }
- { name: "HTTP", interface: wan, state: present, before: allow_all_http }
aggregated_vlans:
- { descr: voice, vlan_id: 100, interface: mvneta0, state: present }
- { descr: video, vlan_id: 200, interface: mvneta0, state: present }
RETURN VALUES:
- aggregated_rules
final set of rules
returned: success
sample: []
type: list
- result_aliases
the set of aliases commands that would be pushed to the remote
device (if pfSense had a CLI)
returned: success
sample: ['create alias ''adservers'', type=''host'', address=''10.0.0.1 10.0.0.2''', update
alias 'one_host' set address='10.9.8.7', delete alias 'one_alias']
type: list
- result_interfaces
the set of interfaces commands that would be pushed to the
remote device (if pfSense had a CLI)
returned: success
sample: ['create interface ''VOICE'', port=''mvneta1.100''', 'create interface ''VIDEO'',
port=''mvneta1.200''']
type: list
- result_separators
the set of separators commands that would be pushed to the
remote device (if pfSense had a CLI)
returned: success
sample: ['create rule_separator ''SSH'', interface=''lan'', color=''info''', update rule_separator
'SSH' set color='warning', delete rule_separator 'SSH']
type: list
- result_vlans
the set of commands that would be pushed to the remote device
(if pfSense had a CLI)
returned: success
sample: ['create vlan ''mvneta.100'', descr=''voice'', priority=''5''', 'update vlan ''mvneta.100'',
set priority=''6''', delete vlan 'mvneta.100']
type: list