.. _vyos.vyos.vyos_vpn_ipsec_s2s_module: **************************** vyos.vyos.vyos_vpn_ipsec_s2s **************************** **Manages IPsec site-to-site VPN peers on VyOS network devices.** Version added: 1.0.0 .. contents:: :local: :depth: 1 Synopsis -------- - This module manages VPN IPsec site-to-site peer configuration on VyOS devices -- policy-based tunnels and route-based (VTI) connections. IKE/ESP groups, PSK/PPK authentication, and IPsec profiles are managed by the separate vyos_vpn_ipsec module; peers here reference those by name. Parameters ---------- .. raw:: html

Parameter						Choices/Defaults	Comments
config dictionary							IPsec site-to-site configuration.
	peer list / elements=dictionary						List of site-to-site peers.
		authentication dictionary					Peer authentication settings.
			local_id string				Local ID for peer authentication.
			mode string			Choices: pre-shared-secret rsa x509	Authentication mode.
			ppk dictionary				Post-quantum preshared key reference for this peer.
				id string			Post-quantum preshared key ID for this connection.
				required boolean		Choices: no yes	Require a valid PPK for the connection to establish.
			remote_id string				ID for remote authentication.
			rsa dictionary				RSA key authentication.
				local_key string			Name of the PKI key-pair with the local private key.
				passphrase string			Local private key passphrase.
				remote_key string			Name of the PKI key-pair with the remote public key.
			use_x509_id boolean			Choices: no yes	Use certificate common name as ID.
			x509 dictionary				X.509 certificate authentication.
				ca_certificate list / elements=string			Certificate Authority chain in PKI configuration.
				certificate string			Certificate in PKI configuration.
				passphrase string			Private key passphrase.
		childless string				Choices: allow prefer force never	Childless IKE SA initiation support.
		connection_type string				Choices: initiate trap none	Connection type.
		default_esp_group string					Default ESP group name for tunnels under this peer that don't specify their own.
		description string					Description.
		dhcp_interface string					DHCP interface supplying the next-hop IP address.
		disable boolean				Choices: no yes	Disable this peer.
		force_udp_encapsulation boolean				Choices: no yes	Force UDP encapsulation.
		ike_group string					IKE group name.
		ikev2_reauth string				Choices: yes no inherit	Re-authentication of the remote peer during an IKE re-key (IKEv2 only).
		local_address string					IPv4 or IPv6 address of a local interface to use for the VPN, or "any".
		name string / required					Connection name of the peer.
		remote_address list / elements=string					IPv4 or IPv6 address(es) of the remote peer, or "any".
		replay_window integer					IPsec replay window to configure for this CHILD_SA.
		tunnel list / elements=dictionary					Policy-based tunnel definitions for this peer.
			disable boolean			Choices: no yes	Disable this tunnel.
			esp_group string				ESP group name for this tunnel (overrides the peer's default_esp_group).
			local dictionary				Local traffic selector for this tunnel.
				port integer			Local port to match.
				prefix list / elements=string			Local IPv4 or IPv6 prefix(es) to match.
			priority integer				Priority for this IPsec policy (lowest value is most preferred).
			protocol string				Protocol to match for this tunnel's traffic selector.
			remote dictionary				Remote traffic selector for this tunnel.
				port integer			Remote port to match.
				prefix list / elements=string			Remote IPv4 or IPv6 prefix(es) to match.
			tunnel_id integer / required				The tunnel identifier.
		virtual_address list / elements=string					Initiator-requested virtual address(es) from the peer.
		vti dictionary					Route-based (VTI) connection settings for this peer.
			bind string				VTI tunnel interface associated with this connection.
			esp_group string				ESP group name for this VTI connection.
			traffic_selector dictionary				Traffic selector for the VTI connection.
				local dictionary			Local traffic-selector parameters.
					prefix list / elements=string		Local IPv4 or IPv6 prefix(es).
				remote dictionary			Remote traffic-selector parameters.
					prefix list / elements=string		Remote IPv4 or IPv6 prefix(es).
running_config string							This option is used only with state parsed. The value of this option should be the output received from the VyOS device by executing the command show configuration commands \| match "vpn ipsec site-to-site". The state parsed reads the configuration from the `running_config` option and transforms it into Ansible structured data as per the resource module's argspec, returned in the parsed key within the result.
state string						Choices: merged ← replaced overridden deleted gathered rendered parsed	The state the configuration should be left in.

Notes ----- .. note:: - Tested against VyOS 1.4 and 1.5. - Source of truth: vyos-1x's interface-definitions/vpn_ipsec.xml.in, resolved and drafted via this collection's fetch_vyos_xml_definition.py / parse_xml_definitions.py helper scripts, then hand-reviewed. - The argspec only requires *name* on a peer, but VyOS itself enforces several more requirements at commit time -- confirmed via real device testing, not visible in the argspec: every peer needs ``authentication``, a real ``remote_address`` (not just omitted), a ``local_address`` or ``dhcp_interface``, and at least one of ``tunnel`` or ``vti``. A peer missing any of these will pass Ansible's own argument validation but fail the device commit with a specific error naming what's missing. - For more information on using Ansible to manage network devices see the :ref:`Ansible Network Guide ` Examples -------- .. code-block:: yaml - name: Merge a site-to-site peer vyos.vyos.vyos_vpn_ipsec_s2s: config: peer: - name: PEER-TEST ike_group: IKE-TEST default_esp_group: ESP-TEST remote_address: - 203.0.113.1 state: merged Return Values ------------- Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html

Key	Returned	Description
after dictionary	when changed	The resulting configuration after module execution. Sample: This output will always be in the same format as the module argspec.
before dictionary	when state is `merged`, `replaced`, `overridden` or `deleted`	The configuration prior to the module execution. Sample: This output will always be in the same format as the module argspec.
commands list	when state is `merged`, `replaced`, `overridden` or `deleted`	The set of commands pushed to the remote device. Sample: ["set vpn ipsec site-to-site peer PEER-TEST ike-group 'IKE-TEST'", "set vpn ipsec site-to-site peer PEER-TEST default-esp-group 'ESP-TEST'"]
gathered dictionary	when state is `gathered`	Facts about the network resource gathered from the remote device as structured data. Sample: This output will always be in the same format as the module argspec.
parsed dictionary	when state is `parsed`	The device native config provided in running_config option parsed into structured data as per module argspec. Sample: This output will always be in the same format as the module argspec.
rendered list	when state is `rendered`	The provided configuration in the task rendered in device-native format (offline). Sample: ["set vpn ipsec site-to-site peer PEER-TEST ike-group 'IKE-TEST'"]

Status ------ Authors ~~~~~~~ - Evgeny Molotkov (@omnom62)