pfsense_aggregate

> PFSENSE_AGGREGATE    (/home/fbor/ansible/lib/ansible/modules/network/pfsense/pfsense_aggregate.py)

  Manage multiple pfSense aliases, rules, rule separators, interfaces and vlans

  * This module is maintained by The Ansible Community
OPTIONS (= is mandatory):

- aggregated_aliases
  Dict of aliases to apply on the target
  [Default: (null)]
  suboptions:
    address:
      default: null
      description: The address of the alias. Use a space separator for multiple values
      type: str
    descr:
      default: null
      description: The description of the alias
      type: str
    detail:
      default: null
      description: The descriptions of the items. Use || separator between items
      type: str
    name:
      description: The name of the alias
      required: true
      type: str
    state:
      choices:
      - present
      - absent
      default: present
      description: State in which to leave the alias
      type: str
    type:
      choices:
      - host
      - network
      - port
      - urltable
      - urltable_ports
      default: null
      description: The type of the alias
      type: str
    updatefreq:
      default: null
      description: Update frequency in days for urltable
      type: int
  
  type: list

- aggregated_interfaces
  Dict of interfaces to apply on the target
  [Default: (null)]
  suboptions:
    blockbogons:
      description: Blocks traffic from reserved IP addresses (but not RFC 1918) or not
        yet assigned by IANA.
      required: false
      type: bool
    blockpriv:
      description: Blocks traffic from IP addresses that are reserved for private networks.
      required: false
      type: bool
    descr:
      description: Description (name) for the interface.
      required: true
      type: str
    enable:
      description: Enable interface.
      type: bool
    interface:
      description: Network port to which assign the interface.
      type: str
    interface_descr:
      description: Network port descr to which assign the interface.
      type: str
    ipv4_address:
      description: IPv4 Address.
      required: false
      type: str
    ipv4_gateway:
      description: IPv4 gateway for this interface.
      required: false
      type: str
    ipv4_prefixlen:
      default: 24
      description: IPv4 subnet prefix length.
      required: false
      type: int
    ipv4_type:
      choices:
      - none
      - static
      - dhcp
      default: none
      description: IPv4 Configuration Type.
      type: str
    ipv6_address:
      description: IPv6 Address.
      required: false
      type: str
    ipv6_gateway:
      description: IPv6 gateway for this interface.
      required: false
      type: str
    ipv6_prefixlen:
      default: 128
      description: IPv6 subnet prefix length.
      required: false
      type: int
    ipv6_type:
      choices:
      - none
      - static
      - slaac
      default: none
      description: IPv4 Configuration Type.
      type: str
    mac:
      description: Used to modify ("spoof") the MAC address of this interface.
      required: false
      type: str
    mss:
      description: MSS clamping for TCP connections.
      required: false
      type: int
    mtu:
      description: Maximum transmission unit
      required: false
      type: int
    speed_duplex:
      default: autoselect
      description: Set speed and duplex mode for this interface.
      required: false
      type: str
    state:
      choices:
      - present
      - absent
      default: present
      description: State in which to leave the interface.
      type: str
  
  type: list

- aggregated_nat_outbounds
  Dict of nat_outbound rules to apply on the target
  [Default: (null)]
  suboptions:
    address:
      default: null
      description: The translated to address, in {ALIAS,NETWORK}[:port] format. Leave
        address part empty to use interface address.
      required: false
      type: str
    after:
      description: Rule to go after, or "top"
      type: str
    before:
      description: Rule to go before, or "bottom"
      type: str
    descr:
      default: null
      description: The name of the nat rule
      required: true
      type: str
    destination:
      default: null
      description: The matching destination address, in {any,ALIAS,NETWORK}[:port] format.
      required: false
      type: str
    disabled:
      default: false
      description: Is the rule disabled
      type: bool
    interface:
      description: The interface for the rule
      required: false
      type: str
    invert:
      default: false
      description: Invert the sense of the destination match.
      type: bool
    ipprotocol:
      choices:
      - inet
      - inet46
      - inet6
      default: inet46
      description: The Internet Protocol version this rule applies to.
      type: str
    nonat:
      default: false
      description: This option will disable NAT for traffic matching this rule and stop
        processing Outbound NAT rules
      type: bool
    nosync:
      default: false
      description: 'Prevents the rule on Master from automatically syncing to other
        CARP members. This does NOT prevent the rule from being overwritten on Slave.
  
        '
      type: bool
    poolopts:
      choices:
      - ''
      - round-robin
      - round-robin sticky-address
      - random
      - random sticky-address
      - source-hash
      - bitmask
      default: ''
      description: When an address pool is used, there are several options available
        that control how NAT translations happen on the pool.
      type: str
    protocol:
      choices:
      - any
      - tcp
      - udp
      - tcp/udp
      - icmp
      - esp
      - ah
      - gre
      - ipv6
      - igmp
      - carp
      - pfsync
      default: any
      description: Which protocol this rule should match.
      type: str
    source:
      default: null
      description: The matching source address, in {any,(self),ALIAS,NETWORK}[:port]
        format.
      required: false
      type: str
    source_hash_key:
      default: ''
      description: '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.
  
        '
      required: false
      type: str
    state:
      choices:
      - present
      - absent
      default: present
      description: State in which to leave the rule
      type: str
    staticnatport:
      default: false
      description: Do not randomize source port
      type: bool
  
  type: list

- aggregated_nat_port_forwards
  Dict of nat_port_forward rules to apply on the target
  [Default: (null)]
  suboptions:
    after:
      description: Rule to go after, or "top"
      type: str
    associated_rule:
      choices:
      - associated
      - unassociated
      - pass
      - none
      default: associated
      description: '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.
  
        '
      type: str
    before:
      description: Rule to go before, or "bottom"
      type: str
    descr:
      default: null
      description: The name of the nat rule
      required: true
      type: str
    destination:
      default: null
      description: The destination address, in [!]{IP,HOST,ALIAS,any,IP:INTERFACE,NET:INTERFACE}[:port]
        format.
      type: str
    disabled:
      default: false
      description: Is the rule disabled
      type: bool
    interface:
      description: The interface for the rule
      required: false
      type: str
    natreflection:
      choices:
      - system-default
      - enable
      - purenat
      - disable
      default: system-default
      description: Allows NAT reflection to be enabled or disabled on a per-port forward
        basis.
      type: str
    nordr:
      default: false
      description: Disable redirection for traffic matching this rule
      type: bool
    nosync:
      default: false
      description: 'Prevents the rule on Master from automatically syncing to other
        CARP members. This does NOT prevent the rule from being overwritten on Slave.
  
        '
      type: bool
    protocol:
      choices:
      - tcp
      - udp
      - tcp/udp
      - icmp
      - esp
      - ah
      - gre
      - ipv6
      - igmp
      - pim
      - ospf
      default: tcp
      description: Which protocol this rule should match.
      type: str
    source:
      default: null
      description: The source address, in [!]{IP,HOST,ALIAS,any,IP:INTERFACE,NET:INTERFACE}[:port]
        format.
      type: str
    state:
      choices:
      - present
      - absent
      default: present
      description: State in which to leave the rule
      type: str
    target:
      default: null
      description: The translated to address, in {ALIAS,IP}[:port] format.
      required: false
      type: str
  
  type: list

- aggregated_rule_separators
  Dict of rule separators to apply on the target
  [Default: (null)]
  suboptions:
    after:
      description: Rule to go after, or "top"
      type: str
    before:
      description: Rule to go before, or "bottom"
      type: str
    color:
      choices:
      - info
      - warning
      - danger
      - success
      default: info
      description: The separator's color
      type: str
    floating:
      description: Is the rule on floating tab
      type: bool
    interface:
      description: The interface for the separator
      type: str
    name:
      description: The name of the separator
      required: true
      type: str
    state:
      choices:
      - present
      - absent
      default: present
      description: State in which to leave the separator
      type: str
  
  type: list

- aggregated_rules
  Dict of rules to apply on the target
  [Default: (null)]
  suboptions:
    ackqueue:
      description: QOS acknowledge queue
      type: str
    action:
      choices:
      - pass
      - block
      - match
      - reject
      default: pass
      description: The action of the rule
      type: str
    after:
      description: Rule to go after, or `top'
      type: str
    before:
      description: Rule to go before, or `bottom'
      type: str
    destination:
      default: null
      description: The destination address, in [!]{IP,HOST,ALIAS,any,(self),IP:INTERFACE,NET:INTERFACE}
        format.
      type: str
    destination_port:
      default: null
      description:
      - 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'..
      type: str
    direction:
      choices:
      - any
      - in
      - out
      description: Direction floating rule applies to
      type: str
    disabled:
      default: false
      description: Is the rule disabled
      type: bool
    floating:
      description: Is the rule floating
      type: bool
    gateway:
      default: default
      description: Leave as `default' to use the system routing table or choose a gateway
        to utilize policy based routing.
      type: str
    icmptype:
      default: any
      description:
      - 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
      type: str
    in_queue:
      description: Limiter queue for traffic coming into the chosen interface
      type: str
    interface:
      description: The interface for the rule
      required: true
      type: str
    ipprotocol:
      choices:
      - inet
      - inet46
      - inet6
      default: inet
      description: The IP protocol
      type: str
    log:
      description: Log packets matched by rule
      type: bool
    name:
      default: null
      description: The name the rule
      required: true
      type: str
    out_queue:
      description: Limiter queue for traffic leaving the chosen interface
      type: str
    protocol:
      choices:
      - any
      - tcp
      - udp
      - tcp/udp
      - icmp
      - igmp
      - ospf
      - esp
      - ah
      - gre
      - pim
      - sctp
      - pfsync
      - carp
      default: any
      description: The protocol
      type: str
    queue:
      description: QOS default queue
      type: str
    quick:
      default: false
      description: Set this option to apply this action to traffic that matches this
        rule immediately
      type: bool
    sched:
      description: Schedule day/time when the rule must be active
      required: false
      type: str
    source:
      default: null
      description: The source address, in [!]{IP,HOST,ALIAS,any,(self),IP:INTERFACE,NET:INTERFACE}
        format.
      type: str
    source_port:
      default: null
      description:
      - 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'..
      type: str
    state:
      choices:
      - present
      - absent
      default: present
      description: State in which to leave the rule
      type: str
    statetype:
      choices:
      - keep state
      - sloppy state
      - synproxy state
      - none
      default: keep state
      description: State type
      type: str
    tcpflags_any:
      description: Allow TCP packets with any flags set.
      type: bool
    tracker:
      description: Rule tracking ID. Defaults to timestamp of rule creation.
      type: int
  
  type: list

- aggregated_vlans
  Dict of vlans to apply on the target
  [Default: (null)]
  suboptions:
    descr:
      default: null
      description: The description of the vlan
      type: str
    interface:
      description: The interface on which to declare the vlan. Friendly name (assignments)
        can be used.
      required: true
      type: str
    priority:
      description: 802.1Q VLAN Priority code point. Must be between 0 and 7.
      required: false
      type: int
    state:
      choices:
      - present
      - absent
      default: present
      description: State in which to leave the vlan
      type: str
    vlan_id:
      description: The vlan tag. Must be between 1 and 4094.
      required: true
      type: int
  
  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:
    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:

result_aliases:
    description: the set of aliases commands that would be pushed to the remote device (if pfSense had a CLI)
    returned: success
    type: list
    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'"]
result_interfaces:
    description: the set of interfaces commands that would be pushed to the remote device (if pfSense had a CLI)
    returned: success
    type: list
    sample: ["create interface 'VOICE', port='mvneta1.100'", "create interface 'VIDEO', port='mvneta1.200'"]
aggregated_rules:
    description: final set of rules
    returned: success
    type: list
    sample: []
result_separators:
    description: the set of separators commands that would be pushed to the remote device (if pfSense had a CLI)
    returned: success
    type: list
    sample: ["create rule_separator 'SSH', interface='lan', color='info'", "update rule_separator 'SSH' set color='warning'", "delete rule_separator 'SSH'"]
result_vlans:
    description: the set of commands that would be pushed to the remote device (if pfSense had a CLI)
    returned: success
    type: list
    sample: ["create vlan 'mvneta.100', descr='voice', priority='5'", "update vlan 'mvneta.100', set priority='6'", "delete vlan 'mvneta.100'"]