Tip

Check out the repository on GitHub

Interface

STATE: stable

TESTS: vlan | vxlan | vip | lagg | loopback

API Docs: Core - Interfaces

Service Docs: VLAN Docs | VxLAN Docs | VIP Docs | LAGG Docs | Loopback Docs

Info

ansibleguy.opnsense.interface_vlan

This module manages VLAN configuration that can be found in the WEB-UI menu: ‘Interfaces - Other Types - VLAN’

ansibleguy.opnsense.interface_vxlan

This module manages VXLAN configuration that can be found in the WEB-UI menu: ‘Interfaces - Other Types - VXLAN’

ansibleguy.opnsense.interface_vip

This module manages VIP configuration that can be found in the WEB-UI menu: ‘Interfaces - Virtual IPs - Settings’

ansibleguy.opnsense.interface_lagg

This module manages LAGG configuration that can be found in the WEB-UI menu: ‘Interfaces - Other Types - LAGG’

ansibleguy.opnsense.interface_loopback

This module manages Loopback configuration that can be found in the WEB-UI menu: ‘Interfaces - Other Types - Loopback’

Contribution

Thanks to @jiuka for developing the interface_loopback module!

Definition

For basic parameters see: Basic

ansibleguy.opnsense.interface_vlan

Definition

Parameter	Type	Required	Default	Aliases	Comment
description	string	true	-	desc, name	The unique description used to match the configured entries to the existing ones
interface	string	false for state changes, else true	-	parent, port, int, if	The parent interface to add the vlan to. Existing VLAN capable interface - you must provide the network port as shown in ‘Interfaces - Assignments - Network port’
vlan	integer	false for state changes, else true	-	tag, id	802.1Q VLAN tag (between 1 and 4094)
priority	integer	false	0	prio	802.1Q VLAN PCP (between 0 and 7)
reload	boolean	false	true	-	If the running config should be reloaded on change - this may take some time. For mass-managing items you might want to reload it ‘manually’ after all changes are done => using the ansibleguy.opnsense.reload module.

ansibleguy.opnsense.interface_vxlan

Definition

Parameter	Type	Required	Default	Aliases	Comment
id	integer	true	-	vxlanid, vni	The unique ID of the VxLAN
interface	string	false for state changes, else true	-	vxlandev, device, int	Optionally set an interface to bind the VxLAN to. You must provide the network port as shown in ‘Interface - Assignments - Interface ID (in brackets)’
local	string	false for state changes, else true	-	source_address, source_ip, vxlanlocal, source, src	Source IP for the VxLAN tunnel. The source address used in the encapsulating IPv4/IPv6 header. The address should already be assigned to an existing interface. When the interface is configured in unicast mode, the listening socket is bound to this address.
remote	string	false	-	remote_address, remote_ip, destination, vxlanremote, dest	Remote IP for the VxLAN tunnel - if unicast is used. The interface can be configured in a unicast, or point-to-point, mode to create a tunnel between two hosts. This is the IP address of the remote end of the tunnel.
group	string	false	-	multicast_group, multicast_address, multicast_ip, vxlangroup	Remote IP for the VxLAN tunnel - if multicast is used. The interface can be configured in a multicast mode to create a virtual network of hosts. This is the IP multicast group address the interface will join.
reload	boolean	false	true	-	If the running config should be reloaded on change - this may take some time. For mass-managing items you might want to reload it ‘manually’ after all changes are done => using the ansibleguy.opnsense.reload module.

ansibleguy.opnsense.interface_vip

Definition

Parameter	Type	Required	Default	Aliases	Comment
match_fields	list	false	[‘address’, ‘interface’]	-	Fields that are used to match configured VIPs with the running config - if any of those fields are changed, the module will think it’s a new entry. At least one of: ‘address’, ‘interface’, ‘cidr’, ‘description’
address	string	true	-	addr, ip, network, net	Provide an address and subnet to use. (e.g 192.168.0.1/24)
interface	string	true	-	port, int, if	Existing interface - you must provide the network port as shown in ‘Interfaces - Assignments - Network port’
mode	string	false	ipalias	m	One of: ‘ipalias’, ‘carp’, ‘proxyarp’, ‘other’
expand	boolean	false	true	-	-
bind	boolean	false	true	-	Assigning services to the virtual IP’s interface will automatically include this address. Uncheck to prevent binding to this address instead
gateway	string	false	-	gw	For some interface types a gateway is required to configure an IP Alias (ppp/pppoe/tun), leave this field empty for all other interface types
password	string	false	-	pwd	VHID group password
vhid	integer	false	-	group, grp, id	VHID group that the machines will share
advertising_base	integer	false	1	adv_base, base	The frequency that this machine will advertise. 0 usually means master. Otherwise the lowest combination of both values in the cluster determines the master
advertising_skew	integer	false	0	adv_skew, skew	-
description	string	false	-	desc, name	Optional description
reload	boolean	false	true	-	If the running config should be reloaded on change - this may take some time. For mass-managing items you might want to reload it ‘manually’ after all changes are done => using the ansibleguy.opnsense.reload module.

ansibleguy.opnsense.interface_lagg

Warning

This feature is only available in OPNSense version >= 23.7

Definition

Parameter	Type	Required	Default	Aliases	Comment
match_fields	list	false	[‘members’]	-	Fields that are used to match configured LAGG with the running config - if any of those fields are changed, the module will think it’s a new entry. At least one of: ‘device’, ‘members’, ‘primary_member’, ‘proto’, ‘description’
device	string	false	-	laggif	Optional ‘device’ of the entry. Needs to start with ‘lagg’
members	list	false	-	port, int, if	Existing LAGG capable interface - you must provide the network port as shown in ‘Interfaces - Assignments - Network port’
primary_member	string	false	-	-	This interface will be added first in the lagg making it the primary one - you must provide the network port as shown in ‘Interfaces - Assignments - Network port’
proto	string	false	lacp	p	The protocol to use. One of: ‘none’, ‘lacp’, ‘failover’, ‘fec’, ‘loadbalance’, ‘roundrobin’
lacp_fast_timeout	boolean	false	false	-	Enable lacp fast-timeout on the interface.
use_flowid	string	false	-	-	Use the RSS hash from the network card if available, otherwise a hash is locally calculated. The default depends on the system tunable in net.link.lagg.default_use_flowid. One of: ‘default’, ‘yes’, ‘no’
lagghash	list	false	[‘l2’]	-	Set the packet layers to hash for aggregation protocols which load balance. At least one of: ‘l2’, ‘l3’, ‘l4’
lacp_strict	string	false	-	-	Enable lacp strict compliance on the interface. The default depends on the system tunable in net.link.lagg.lacp.default_strict_mode. One of: ‘default’, ‘yes’, ‘no’
mtu	integer	false	false	-	If you leave this field blank, the smallest mtu of this laggs children will be used.
description	string	true	-	desc, name	The description used to match the configured entries to the existing ones
reload	boolean	false	true	-	If the running config should be reloaded on change - this may take some time. For mass-managing items you might want to reload it ‘manually’ after all changes are done => using the ansibleguy.opnsense.reload module.

ansibleguy.opnsense.interface_loopback

Definition

Parameter	Type	Required	Default	Aliases	Comment
description	string	true	-	desc, name	The unique description used to match the configured entries to the existing ones
reload	boolean	false	true	-	If the running config should be reloaded on change - this may take some time. For mass-managing items you might want to reload it ‘manually’ after all changes are done => using the ansibleguy.opnsense.reload module.

Examples

ansibleguy.opnsense.interface_vlan

- hosts: localhost
  gather_facts: no
  module_defaults:
    group/ansibleguy.opnsense.all:
      firewall: 'opnsense.template.ansibleguy.net'
      api_credential_file: '/home/guy/.secret/opn.key'

    ansibleguy.opnsense.list:
      target: 'interface_vlan'

  tasks:
    - name: Example
      ansibleguy.opnsense.interface_vlan:
        description: 'example'
        interface: 'vtnet0'
        vlan: 100
        # priority: 0
        # debug: false
        # state: 'present'
        # reload: true

    - name: Adding VLAN
      ansibleguy.opnsense.interface_vlan:
        description: 'test1'
        interface: 'vtnet0'
        vlan: 100

    - name: Listing
      ansibleguy.opnsense.list:
      #  target: 'interface_vlan'
      register: existing_entries

    - name: Printing VLANs
      ansible.builtin.debug:
        var: existing_entries.data

    - name: Removing VLAN
      ansibleguy.opnsense.interface_vlan:
        description: 'test1'
        state: 'absent'

ansibleguy.opnsense.interface_vxlan

- hosts: localhost
  gather_facts: no
  module_defaults:
    group/ansibleguy.opnsense.all:
      firewall: 'opnsense.template.ansibleguy.net'
      api_credential_file: '/home/guy/.secret/opn.key'

    ansibleguy.opnsense.list:
      target: 'interface_vxlan'

  tasks:
    - name: Example
      ansibleguy.opnsense.interface_vxlan:
        id: 100
        local: '192.168.0.1'
        # remote: ''
        # group: ''
        # interface: 'lan'
        # debug: false
        # state: 'present'
        # reload: true

    - name: Adding VxLAN
      ansibleguy.opnsense.interface_vxlan:
        id: 100
        local: '192.168.0.1'
        interface: 'lan'

    - name: Listing
      ansibleguy.opnsense.list:
      #  target: 'interface_vxlan'
      register: existing_entries

    - name: Printing VxLANs
      ansible.builtin.debug:
        var: existing_entries.data

    - name: Removing VxLAN
      ansibleguy.opnsense.interface_vxlan:
        id: 100
        state: 'absent'

ansibleguy.opnsense.interface_vip

- hosts: localhost
  gather_facts: no
  module_defaults:
    group/ansibleguy.opnsense.all:
      firewall: 'opnsense.template.ansibleguy.net'
      api_credential_file: '/home/guy/.secret/opn.key'

    ansibleguy.opnsense.list:
      target: 'interface_vip'

  tasks:
    - name: Example
      ansibleguy.opnsense.interface_vip:
        interface: 'opt1'
        address: '192.168.0.100/24'
        # match_fields: ['address', 'interface]
        # mode: 'ipalias'
        # expand: true
        # bind: true
        # gateway: ''
        # password: ''
        # vhid: ''
        # advertising_base: 1
        # advertising_skew: 0
        # description: ''
        # debug: false
        # state: 'present'
        # reload: true

    - name: Adding VIP
      ansibleguy.opnsense.interface_vip:
        interface: 'opt1'
        address: '192.168.0.100/24'
        mode: 'carp'
        vhid: 10
        password: 'secret'

    - name: Listing
      ansibleguy.opnsense.list:
      #  target: 'interface_vip'
      register: existing_entries

    - name: Printing VIPs
      ansible.builtin.debug:
        var: existing_entries.data

    - name: Removing VIP
      ansibleguy.opnsense.interface_vip:
        interface: 'opt1'
        address: '192.168.0.100/24'
        state: 'absent'

ansibleguy.opnsense.interface_lagg

- hosts: localhost
  gather_facts: no
  module_defaults:
    group/ansibleguy.opnsense.all:
      firewall: 'opnsense.template.ansibleguy.net'
      api_credential_file: '/home/guy/.secret/opn.key'

    ansibleguy.opnsense.list:
      target: 'interface_lagg'

  tasks:
    - name: Example
      ansibleguy.opnsense.interface_lagg:
        # device: lagg0
        # description: LACP ax0/1
        members:
          - ax0
          - ax1
        # primary_member: ax0
        # proto: lacp
        # lacp_fast_timeout: 'default'
        # use_flowid: 'default'
        # lagghash: ['l2']
        # lacp_strict: 'default'
        # mtu: 9000
        # match_fields: ['members']

    - name: Adding LAGG
      ansibleguy.opnsense.interface_lagg:
        members:
          - ax0
          - ax1

    - name: Listing
      ansibleguy.opnsense.list:
      #  target: 'interface_lagg'
      register: existing_entries

    - name: Printing LAGGs
      ansible.builtin.debug:
        var: existing_entries.data

    - name: Removing LAGG
      ansibleguy.opnsense.interface_lagg:
        device: lagg0
        match_fields: ['device']
        state: 'absent'

ansibleguy.opnsense.interface_loopback

- hosts: localhost
  gather_facts: no
  module_defaults:
    group/ansibleguy.opnsense.all:
      firewall: 'opnsense.template.ansibleguy.net'
      api_credential_file: '/home/guy/.secret/opn.key'

    ansibleguy.opnsense.list:
      target: 'interface_loopback'

  tasks:
    - name: Example
      ansibleguy.opnsense.interface_loopback:
        description: 'MyLoopback'
        # debug: false
        # state: 'present'
        # reload: true

    - name: Adding Loopback
      ansibleguy.opnsense.interface_loopback:
        description: 'MyLoopback'

    - name: Listing
      ansibleguy.opnsense.list:
      #  target: 'interface_loopback'
      register: existing_entries

    - name: Printing Loopbacks
      ansible.builtin.debug:
        var: existing_entries.data

    - name: Removing Loopback
      ansibleguy.opnsense.interface_loopback:
        description: 'MyLoopback'
        state: 'absent'