Tip

Check out the repository on GitHub

Report missing/incorrect information or broken links

IPSec

STATE: stable

TESTS: ipsec_cert | ipsec_psk | ipsec_connection | ipsec_pool | ipsec_vti

API Docs: Core - IPSec

Service Docs: IPSec | IPSec Examples | IPSec VTI

Limitations

Warning

The IPSec modules can only be used on OPNSense version >= 23.1

Definition

For basic parameters see: Basic

ansibleguy.opnsense.ipsec_connection

Module alias: ansibleguy.opnsense.ipsec_tunnel

Definition

Parameter	Type	Required	Default	Aliases	Comment
name	string	true	-	description, desc	Unique connection/tunnel name
local_addresses	list	false	-	local_addr, local	Local address[es] to use for IKE communication. Accepts single IPv4/IPv6 addresses, DNS names, CIDR subnets or IP address ranges. As an initiator, the first non-range/non-subnet is used to initiate the connection from. As a responder the local destination address must match at least to one of the specified addresses, subnets or ranges. If FQDNs are assigned, they are resolved every time a configuration lookup is done. If DNS resolution times out, the lookup is delayed for that time. When left empty %any is choosen as default
remote_addresses	list	false	-	remote_addr, remote	Remote address[es] to use for IKE communication. Accepts single IPv4/IPv6 addresses, DNS names, CIDR subnets or IP address ranges. As an initiator, the first non-range/non-subnet is used to initiate the connection to. As a responder the local destination address must match at least to one of the specified addresses, subnets or ranges. If FQDNs are assigned, they are resolved every time a configuration lookup is done. If DNS resolution times out, the lookup is delayed for that time. To initiate a connection, at least one specific address or DNS name must be specified
pools	list	false	-	networks	List of named IP pools to allocate virtual IP addresses and other configuration attributes from. Each name references a pool by name from either the pools section or an external pool. Note that the order in which they are queried primarily depends on the plugin order
proposals	list	false	[‘default’]	props	A proposal is a set of algorithms. For non-AEAD algorithms this includes IKE an encryption algorithm, an integrity algorithm, a pseudo random function (PRF) and a Diffie-Hellman key exchange group. For AEAD algorithms, instead of encryption and integrity algorithms a combined algorithm is used. With IKEv2 multiple algorithms of the same kind can be specified in a single proposal, from which one gets selected. For IKEv1 only one algorithm per kind is allowed per proposal, more algorithms get implicitly stripped. Use multiple proposals to offer different algorithm combinations with IKEv1. Algorithm keywords get separated using dashes. Multiple proposals may be separated by commas. The special value default adds a default proposal of supported algorithms considered safe and is usually a good choice for interoperability.
unique	string	false	no	-	One of: ‘no’, ‘never’, ‘keep’, ‘replace’; Connection uniqueness policy to enforce. To avoid multiple connections from the same user, a uniqueness policy can be enforced.
aggressive	boolean	false	false	aggr	Enables IKEv1 Aggressive Mode instead of IKEv1 Main Mode with Identity Protection. Aggressive Mode is considered less secure because the ID and HASH payloads are exchanged unprotected. This allows a passive attacker to snoop peer identities and even worse, start dictionary attacks on the Preshared Key
version	string	false	ike	vers, v	One of: ‘ike’, ‘ikev1’, ‘ikev2’; IKE major version to use for connection. 1 uses IKEv1 aka ISAKMP, 2 uses IKEv2. A connection using IKEv1+IKEv2 accepts both IKEv1 and IKEv2 as a responder and initiates the connection actively with IKEv2
mobike	boolean	false	true	mob	Enables MOBIKE on IKEv2 connections. MOBIKE is enabled by default on IKEv2 connections and allows mobility of clients and multi-homing on servers by migrating active IPsec tunnels. Usually keeping MOBIKE enabled is unproblematic, as it is not used if the peer does not indicate support for it. However, due to the design of MOBIKE, IKEv2 always floats to UDP port 4500 starting from the second exchange. Some implementations don’t like this behavior, hence it can be disabled
encapsulation	boolean	false	false	udp_encapsulation, encap	To enforce UDP encapsulation of ESP packets, the IKE daemon can manipulate the NAT detection payloads. This makes the peer believe that a NAT situation exist on the transmission path, forcing it to encapsulate ESP packets in UDP. Usually this is not required but it can help to work around connectivity issues with too restrictive intermediary firewalls that block ESP packets
reauth_seconds	integer	false	-	reauth, reauth_sec, reauth_time	Time to schedule IKE reauthentication. IKE reauthentication recreates the IKE/ISAKMP SA from scratch and re-evaluates the credentials. In asymmetric configurations (with EAP or configuration payloads) it might not be possible to actively reauthenticate as responder. The IKEv2 reauthentication lifetime negotiation can instruct the client to perform reauthentication. Reauthentication is disabled by default (0). Enabling it usually may lead to small connection interruptions as strongSwan uses a break-before-make policy with IKEv2 by default
rekey_seconds	integer	false	-	rekey, rekey_sec, rekey_time	IKE rekeying refreshes key material using a Diffie-Hellman key exchange, but does not re-check associated credentials. It is supported with IKEv2 only. IKEv1 performs a reauthentication procedure instead. With the default value, IKE rekeying is scheduled every 4 hours minus the configured rand_time. If a reauth_time is configured, rekey_time defaults to zero, disabling rekeying. In that case set rekey_time explicitly to both enforce rekeying and reauthentication
over_seconds	integer	false	-	over, over_sec, over_time	Hard IKE_SA lifetime if rekey/reauth does not complete, as time. To avoid having an IKE or ISAKMP connection kept alive if IKE reauthentication or rekeying fails perpetually, a maximum hard lifetime may be specified. If the IKE_SA fails to rekey or reauthenticate within the specified time, the IKE_SA gets closed. In contrast to CHILD_SA rekeying, over_time is relative in time to the rekey_time and reauth_time values, as it applies to both. The default is 10% of either rekey_time or reauth_time, whichever value is larger. [0.1 * max(rekey_time, reauth_time)]
dpd_delay_seconds	integer	false	-	dpd_delay, dpd_delay_sec, dpd_delay_time	Interval to check the liveness of a peer actively using IKEv2 INFORMATIONAL exchanges or IKEv1 R_U_THERE messages. Active DPD checking is only enforced if no IKE or ESP/AH packet has been received for the configured DPD delay. Defaults to 0s
dpd_timeout_seconds	integer	false	-	dpd_timeout, dpd_timeout_sec	Charon by default uses the normal retransmission mechanism and timeouts to check the liveness of a peer, as all messages are used for liveness checking. For compatibility reasons, with IKEv1 a custom interval may be specified. This option has no effect on IKEv2 connections
send_certificate_request	boolean	false	true	send_cert_req	Send certificate request payloads to offer trusted root CA certificates to the peer. Certificate requests help the peer to choose an appropriate certificate/private key for authentication and are enabled by default. Disabling certificate requests can be useful if too many trusted root CA certificates are installed, as each certificate request increases the size of the initial IKE packets
send_certificate	string	false	-	send_cert	One of: ‘’ (default), ‘ifasked’, ‘never’, ‘always’; Send certificate payloads when using certificate authentication. With the default of [ifasked] the daemon sends certificate payloads only if certificate requests have been received. [never] disables sending of certificate payloads altogether whereas [always] causes certificate payloads to be sent unconditionally whenever certificate-based authentication is used
keying_tries	integer	false	-	keyingtries	Number of retransmission sequences to perform during initial connect. Instead of giving up initiation after the first retransmission sequence with the default value of 1, additional sequences may be started according to the configured value. A value of 0 initiates a new sequence until the connection establishes or fails with a permanent error
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.ipsec_pool

Module alias: ansibleguy.opnsense.ipsec_network

Definition

Parameter	Type	Required	Default	Aliases	Comment
name	string	true	-	-	Unique pool/network name
network	string	false for state changes, else true	-	net, cidr	Pool network in CIDR format
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.ipsec_child

Definition

Parameter	Type	Required	Default	Aliases	Comment
name	string	true	-	description, desc	Unique name to identify the entry
connection	string	false for state changes, else true	-	tunnel, conn, tun	Connection to link this child to
mode	string	false	tunnel	-	One of: ‘tunnel’, ‘transport’, ‘pass’, ‘drop’; IPsec Mode to establish CHILD_SA with. tunnel negotiates the CHILD_SA in IPsec Tunnel Mode whereas transport uses IPsec Transport Mode. pass and drop are used to install shunt policies which explicitly bypass the defined traffic from IPsec processing or drop it, respectively
local_net	list	true	-	local_traffic_selectors, local_cidr, local_ts, local	List of local traffic selectors to include in CHILD_SA. Each selector is a CIDR subnet definition
remote_net	list	true	-	remote_traffic_selectors, remote_cidr, remote_ts, remote	List of remote traffic selectors to include in CHILD_SA. Each selector is a CIDR subnet definition
sha256_96	boolean	false	false	sha256	HMAC-SHA-256 is used with 128-bit truncation with IPsec. For compatibility with implementations that incorrectly use 96-bit truncation this option may be enabled to configure the shorter truncation length in the kernel. This is not negotiated, so this only works with peers that use the incorrect truncation length (or have this option enabled)
start_action	string	false	start	start	One of: ‘none’, ‘trap|start’, ‘route’, ‘start’, ‘trap’; Action to perform after loading the configuration. The default of none loads the connection only, which then can be manually initiated or used as a responder configuration. The value trap installs a trap policy which triggers the tunnel as soon as matching traffic has been detected. The value start initiates the connection actively. To immediately initiate a connection for which trap policies have been installed, user Trap|start
close_action	string	false	none	close	One of: ‘none’, ‘trap’, ‘start’; Action to perform after a CHILD_SA gets closed by the peer. The default of none does not take any action. trap installs a trap policy for the CHILD_SA (note that this is redundant if start_action includes trap). start tries to immediately re-create the CHILD_SA. close_action does not provide any guarantee that the CHILD_SA is kept alive. It acts on explicit close messages only but not on negotiation failures. Use trap policies to reliably re-create failed CHILD_SAs
dpd_action	string	false	clear	dpd	One of: ‘clear’, ‘trap’, ‘start’; Action to perform for this CHILD_SA on DPD timeout. The default clear closes the CHILD_SA and does not take further action. trap installs a trap policy, which will catch matching traffic and tries to re-negotiate the tunnel on-demand (note that this is redundant if start_action includes trap. restart immediately tries to re-negotiate the CHILD_SA under a fresh IKE_SA
policies	boolean	false	true	pols	Whether to install IPsec policies or not. Disabling this can be useful in some scenarios e.g. VTI where policies are not managed by the IKE daemon
request_id	integer	false	-	req_id, reqid	This might be helpful in some scenarios, like route based tunnels (VTI), but works only if each CHILD_SA configuration is instantiated not more than once. The default uses dynamic reqids, allocated incrementally
esp_proposals	list	false	[‘default’]	esp_props, esp	Choose ‘default’ or at least one of the options shown in the Web-UI
rekey_seconds	integer	false	3600	rekey_time, rekey	Time to schedule CHILD_SA rekeying. CHILD_SA rekeying refreshes key material, optionally using a Diffie-Hellman exchange if a group is specified in the proposal. To avoid rekey collisions initiated by both ends simultaneously, a value in the range of rand_time gets subtracted to form the effective soft lifetime. By default CHILD_SA rekeying is scheduled every hour, minus rand_time
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.ipsec_vti

Definition

Parameter	Type	Required	Default	Aliases	Comment
name	string	true	-	description, desc	Unique name to identify the entry
request_id	integer	false for state changes, else true	-	req_id, reqid	This might be helpful in some scenarios, like route based tunnels (VTI), but works only if each CHILD_SA configuration is instantiated not more than once. The default uses dynamic reqids, allocated incrementally
local_address	string	false	-	local_addr, local	-
remote_address	string	false	-	remote_addr, remote	-
local_tunnel_address	string	false	-	local_tun_addr, tunnel_local, local_tun	-
remote_tunnel_address	string	false	-	remote_tun_addr, tunnel_remote, remote_tun	-
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.ipsec_auth_local

ansibleguy.opnsense.ipsec_auth_remote

See: ansibleguy.opnsense.ipsec_auth_local

ansibleguy.opnsense.ipsec_cert

Definition

Parameter	Type	Required	Default	Aliases	Comment
name	string	true	-	-	Name of the key-pair - used to identify the entry.
public_key	string	false for state changes, else true	-	pub_key, pub	-
private_key	string	false for state changes, else true	-	priv_key, priv	-
type	string	false	rsa	-	Type of the key. Currently the only option is ‘rsa’
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.ipsec_psk

Definition

Parameter	Type	Required	Default	Aliases	Comment
identity_local	string	true	-	identity, ident	This can be either an IP address, fully qualified domain name or an email address.
identity_remote	string	false	-	remote_ident	(optional) This can be either an IP address, fully qualified domain name or an email address to identify the remote host.
psk	string	true	-	key, secret	-
type	string	false	-	kind	One of: ‘PSK’, ‘EAP’

Usage

To apply changes to the keys, you need to set ‘reload: true’ on each call or use the ansibleguy.opnsense.reload module to apply it once you finished modifying all entries!

As far as I can tell - the IPSec service gets restarted one you do so - be aware of that.

Vault

You may want to use ‘ansible-vault’ to encrypt your ‘private_key’ content!

ansible-vault encrypt_string '-----BEGIN RSA PRIVATE KEY-----\n...-----END RSA PRIVATE KEY-----\n'

# or encrypt the private_key file beforehand (might be easier)
ansible-vault encrypt /path/to/private/key/file.pem

Examples

ansibleguy.opnsense.ipsec_cert

- 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: 'ipsec_cert'

  tasks:
    - name: Example
      ansibleguy.opnsense.ipsec_cert:
        name: 'example'
        public_key: |
          -----BEGIN PUBLIC KEY-----
          ...
          -----END PUBLIC KEY-----
        private_key: |
          -----BEGIN RSA PRIVATE KEY-----
          ...
          -----END RSA PRIVATE KEY-----

        # reload: false

    - name: Adding key-pair and applying it
      ansibleguy.opnsense.ipsec_cert:
        name: 'test1'
        public_key: |
          -----BEGIN PUBLIC KEY-----
          ...
          -----END PUBLIC KEY-----
        private_key: !vault ...
        reload: true

    - name: Listing
      ansibleguy.opnsense.list:
      #  target: 'ipsec_cert'
      no_log: true  # could log private keys
      register: existing_entries

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

    - name: Manually reloading/applying config
      ansibleguy.opnsense.reload:
        target: 'ipsec'

---

ansibleguy.opnsense.ipsec_psk

- 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: 'ipsec_psk'

  tasks:
    - name: Example
      ansibleguy.opnsense.ipsec_psk:
        identity: 'example'
        psk: 'secret'
        # type: 'PSK'
        # identity_remote: ''

    - name: Adding
      ansibleguy.opnsense.ipsec_psk:
        identity: 'test1'
        psk: 'my-super-secret'

    - name: Removing
      ansibleguy.opnsense.ipsec_psk:
        identity: 'test1'
        state: 'absent'