diff --git a/docs/vyos.vyos.vyos_vpn_ipsec_module.rst b/docs/vyos.vyos.vyos_vpn_ipsec_module.rst new file mode 100644 index 00000000..68c3d384 --- /dev/null +++ b/docs/vyos.vyos.vyos_vpn_ipsec_module.rst @@ -0,0 +1,1779 @@ +.. _vyos.vyos.vyos_vpn_ipsec_module: + + +************************ +vyos.vyos.vyos_vpn_ipsec +************************ + +**Manages global IPsec (ike-group, esp-group, profile, authentication, options) attributes of VyOS network devices.** + + +Version added: 6.2.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- This module manages global VPN IPsec configuration on VyOS devices — IKE groups, ESP groups, PSK/PPK authentication, IPsec profiles, and global options. Site-to-site peers and IKEv2 remote-access connections are handled by separate modules. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ dictionary +
+ 		+ +
IPsec global configuration.
+
+
+ authentication + +
+ dictionary +
+ 		+ +
Global pre-shared-key and post-quantum pre-shared-key definitions.
+
+
+ ppk + +
+ list + / elements=dictionary +
+ 		+ +
List of post-quantum pre-shared keys.
+
+
+ id + +
+ list + / elements=string +
+ 		+ +
ID(s) for PPK.
+
+
+ name + +
+ string + / required +
+ 		+ +
Post-quantum pre-shared key name.
+
+
+ secret + +
+ string +
+ 		+ +
Post-quantum pre-shared secret key.
+
+
+ secret_type + +
+ string +
+ 		+
    Choices: +
  • base64
    • +
  • hex
    • +
  • plaintext
    • +
+ 		+
Secret encoding type.
+
+
+ psk + +
+ list + / elements=dictionary +
+ 		+ +
List of pre-shared keys.
+
+
+ dhcp_interface + +
+ list + / elements=string +
+ 		+ +
DHCP interface(s) supplying next-hop IP address.
+
+
+ id + +
+ list + / elements=string +
+ 		+ +
ID(s) for authentication.
+
+
+ name + +
+ string + / required +
+ 		+ +
Pre-shared key name.
+
+
+ secret + +
+ string +
+ 		+ +
IKE pre-shared secret key.
+
+
+ secret_type + +
+ string +
+ 		+
    Choices: +
  • base64
    • +
  • hex
    • +
  • plaintext
    • +
+ 		+
Secret encoding type.
+
+
+ disable_uniqreqids + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Disable requirement for unique IDs in the Security Database.
+
+
+ esp_group + +
+ list + / elements=dictionary +
+ 		+ +
List of ESP groups.
+
+
+ compression + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Enable ESP compression.
+
+
+ disable_rekey + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Do not locally initiate a re-key of the SA; remote peer must re-key before expiration.
+
+
+ life_bytes + +
+ integer +
+ 		+ +
Security Association byte count to expire.
+
+
+ life_packets + +
+ integer +
+ 		+ +
Security Association packet count to expire.
+
+
+ lifetime + +
+ integer +
+ 		+ +
Security Association time to expire, in seconds.
+
+
+ mode + +
+ string +
+ 		+
    Choices: +
  • tunnel
    • +
  • transport
    • +
+ 		+
ESP mode.
+
+
+ name + +
+ string + / required +
+ 		+ +
The name of the ESP group.
+
+
+ pfs + +
+ string +
+ 		+
    Choices: +
  • enable
    • +
  • disable
    • +
  • dh-group1
    • +
  • dh-group2
    • +
  • dh-group5
    • +
  • dh-group14
    • +
  • dh-group15
    • +
  • dh-group16
    • +
  • dh-group17
    • +
  • dh-group18
    • +
  • dh-group19
    • +
  • dh-group20
    • +
  • dh-group21
    • +
  • dh-group22
    • +
  • dh-group23
    • +
  • dh-group24
    • +
  • dh-group25
    • +
  • dh-group26
    • +
  • dh-group27
    • +
  • dh-group28
    • +
  • dh-group29
    • +
  • dh-group30
    • +
  • dh-group31
    • +
  • dh-group32
    • +
+ 		+
ESP Perfect Forward Secrecy.
+
+
+ proposal + +
+ list + / elements=dictionary +
+ 		+ +
List of ESP proposals.
+
+
+ encryption + +
+ string +
+ 		+
    Choices: +
  • null
    • +
  • aes128
    • +
  • aes192
    • +
  • aes256
    • +
  • aes128ctr
    • +
  • aes192ctr
    • +
  • aes256ctr
    • +
  • aes128ccm64
    • +
  • aes192ccm64
    • +
  • aes256ccm64
    • +
  • aes128ccm96
    • +
  • aes192ccm96
    • +
  • aes256ccm96
    • +
  • aes128ccm128
    • +
  • aes192ccm128
    • +
  • aes256ccm128
    • +
  • aes128gcm64
    • +
  • aes192gcm64
    • +
  • aes256gcm64
    • +
  • aes128gcm96
    • +
  • aes192gcm96
    • +
  • aes256gcm96
    • +
  • aes128gcm128
    • +
  • aes192gcm128
    • +
  • aes256gcm128
    • +
  • aes128gmac
    • +
  • aes192gmac
    • +
  • aes256gmac
    • +
  • 3des
    • +
  • blowfish128
    • +
  • blowfish192
    • +
  • blowfish256
    • +
  • camellia128
    • +
  • camellia192
    • +
  • camellia256
    • +
  • camellia128ctr
    • +
  • camellia192ctr
    • +
  • camellia256ctr
    • +
  • camellia128ccm64
    • +
  • camellia192ccm64
    • +
  • camellia256ccm64
    • +
  • camellia128ccm96
    • +
  • camellia192ccm96
    • +
  • camellia256ccm96
    • +
  • camellia128ccm128
    • +
  • camellia192ccm128
    • +
  • camellia256ccm128
    • +
  • serpent128
    • +
  • serpent192
    • +
  • serpent256
    • +
  • twofish128
    • +
  • twofish192
    • +
  • twofish256
    • +
  • cast128
    • +
  • chacha20poly1305
    • +
+ 		+
Encryption algorithm.
+
+
+ hash + +
+ string +
+ 		+
    Choices: +
  • md5
    • +
  • md5_128
    • +
  • sha1
    • +
  • sha1_160
    • +
  • sha256
    • +
  • sha256_96
    • +
  • sha384
    • +
  • sha512
    • +
  • aesxcbc
    • +
  • aescmac
    • +
  • aes128gmac
    • +
  • aes192gmac
    • +
  • aes256gmac
    • +
+ 		+
Hash algorithm.
+
+
+ proposal_id + +
+ integer +
+ 		+ +
The proposal identifier.
+
+
+ ike_group + +
+ list + / elements=dictionary +
+ 		+ +
List of IKE groups.
+
+
+ close_action + +
+ string +
+ 		+
    Choices: +
  • none
    • +
  • trap
    • +
  • start
    • +
+ 		+
Action to take if a child SA is unexpectedly closed.
+
+
+ dead_peer_detection + +
+ dictionary +
+ 		+ +
Dead Peer Detection (DPD).
+
+
+ action + +
+ string +
+ 		+
    Choices: +
  • trap
    • +
  • clear
    • +
  • restart
    • +
+ 		+
Keep-alive failure action.
+
+
+ interval + +
+ integer +
+ 		+ +
Keep-alive interval in seconds.
+
+
+ timeout + +
+ integer +
+ 		+ +
Dead Peer Detection keep-alive timeout (IKEv1 only), in seconds.
+
+
+ disable_mobike + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Disable MOBIKE support (IKEv2 only).
+
+
+ ikev2_reauth + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Re-authentication of the remote peer during an IKE re-key (IKEv2 only).
+
+
+ key_exchange + +
+ string +
+ 		+
    Choices: +
  • ikev1
    • +
  • ikev2
    • +
+ 		+
IKE version.
+
+
+ lifetime + +
+ integer +
+ 		+ +
IKE lifetime in seconds.
+
+
+ mode + +
+ string +
+ 		+
    Choices: +
  • main
    • +
  • aggressive
    • +
+ 		+
IKEv1 phase 1 mode.
+
+
+ name + +
+ string + / required +
+ 		+ +
The name of the IKE group.
+
+
+ proposal + +
+ list + / elements=dictionary +
+ 		+ +
List of IKE proposals.
+
+
+ dh_group + +
+ integer +
+ 		+
    Choices: +
  • 1
    • +
  • 2
    • +
  • 5
    • +
  • 14
    • +
  • 15
    • +
  • 16
    • +
  • 17
    • +
  • 18
    • +
  • 19
    • +
  • 20
    • +
  • 21
    • +
  • 22
    • +
  • 23
    • +
  • 24
    • +
  • 25
    • +
  • 26
    • +
  • 27
    • +
  • 28
    • +
  • 29
    • +
  • 30
    • +
  • 31
    • +
  • 32
    • +
+ 		+
Diffie-Hellman group.
+
+
+ encryption + +
+ string +
+ 		+
    Choices: +
  • null
    • +
  • aes128
    • +
  • aes192
    • +
  • aes256
    • +
  • aes128ctr
    • +
  • aes192ctr
    • +
  • aes256ctr
    • +
  • aes128ccm64
    • +
  • aes192ccm64
    • +
  • aes256ccm64
    • +
  • aes128ccm96
    • +
  • aes192ccm96
    • +
  • aes256ccm96
    • +
  • aes128ccm128
    • +
  • aes192ccm128
    • +
  • aes256ccm128
    • +
  • aes128gcm64
    • +
  • aes192gcm64
    • +
  • aes256gcm64
    • +
  • aes128gcm96
    • +
  • aes192gcm96
    • +
  • aes256gcm96
    • +
  • aes128gcm128
    • +
  • aes192gcm128
    • +
  • aes256gcm128
    • +
  • aes128gmac
    • +
  • aes192gmac
    • +
  • aes256gmac
    • +
  • 3des
    • +
  • blowfish128
    • +
  • blowfish192
    • +
  • blowfish256
    • +
  • camellia128
    • +
  • camellia192
    • +
  • camellia256
    • +
  • camellia128ctr
    • +
  • camellia192ctr
    • +
  • camellia256ctr
    • +
  • camellia128ccm64
    • +
  • camellia192ccm64
    • +
  • camellia256ccm64
    • +
  • camellia128ccm96
    • +
  • camellia192ccm96
    • +
  • camellia256ccm96
    • +
  • camellia128ccm128
    • +
  • camellia192ccm128
    • +
  • camellia256ccm128
    • +
  • serpent128
    • +
  • serpent192
    • +
  • serpent256
    • +
  • twofish128
    • +
  • twofish192
    • +
  • twofish256
    • +
  • cast128
    • +
  • chacha20poly1305
    • +
+ 		+
Encryption algorithm.
+
+
+ hash + +
+ string +
+ 		+
    Choices: +
  • md5
    • +
  • md5_128
    • +
  • sha1
    • +
  • sha1_160
    • +
  • sha256
    • +
  • sha256_96
    • +
  • sha384
    • +
  • sha512
    • +
  • aesxcbc
    • +
  • aescmac
    • +
  • aes128gmac
    • +
  • aes192gmac
    • +
  • aes256gmac
    • +
+ 		+
Hash algorithm.
+
+
+ prf + +
+ string +
+ 		+
    Choices: +
  • prfmd5
    • +
  • prfsha1
    • +
  • prfaesxcbc
    • +
  • prfaescmac
    • +
  • prfsha256
    • +
  • prfsha384
    • +
  • prfsha512
    • +
+ 		+
Pseudo-Random Function.
+
+
+ proposal_id + +
+ integer +
+ 		+ +
The proposal identifier.
+
+
+ interface + +
+ list + / elements=string +
+ 		+ +
Interface(s) IPsec listens on. If omitted, listens on all interfaces.
+
+
+ log + +
+ dictionary +
+ 		+ +
+
+ level + +
+ integer +
+ 		+
    Choices: +
  • 0
    • +
  • 1
    • +
  • 2
    • +
+ 		+
Global IPsec logging level.
+
+
+ subsystem + +
+ list + / elements=string +
+ 		+
    Choices: +
  • dmn
    • +
  • mgr
    • +
  • ike
    • +
  • chd
    • +
  • job
    • +
  • cfg
    • +
  • knl
    • +
  • net
    • +
  • asn
    • +
  • enc
    • +
  • lib
    • +
  • esp
    • +
  • tls
    • +
  • tnc
    • +
  • imc
    • +
  • imv
    • +
  • pts
    • +
  • any
    • +
+ 		+
Per-subsystem logging levels to enable.
+
+
+ options + +
+ dictionary +
+ 		+ +
+
+ disable_route_autoinstall + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Do not automatically install routes to remote networks.
+
+
+ flexvpn + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Allow FlexVPN vendor ID payload (IKEv2 only).
+
+
+ interface + +
+ string +
+ 		+ +
Single interface for IPsec options scope (distinct from top-level interface list).
+
+
+ retransmission + +
+ dictionary +
+ 		+ +
+
+ attempts + +
+ integer +
+ 		+ +
Maximum number of retransmissions.
+
+
+ base + +
+ float +
+ 		+ +
Base of exponential backoff.
+
+
+ timeout + +
+ integer +
+ 		+ +
Timeout in seconds before the first retransmission.
+
+
+ virtual_ip + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Allow install of virtual-ip addresses.
+
+
+ profile + +
+ list + / elements=dictionary +
+ 		+ +
List of VPN IPsec profiles (used for e.g. DMVPN/GRE tunnel binding).
+
+
+ authentication + +
+ dictionary +
+ 		+ +
+
+ mode + +
+ string +
+ 		+
    Choices: +
  • pre-shared-secret
    • +
+ 		+
Authentication mode.
+
+
+ pre_shared_secret + +
+ string +
+ 		+ +
Pre-shared secret key.
+
+
+ bind_tunnel + +
+ list + / elements=string +
+ 		+ +
Tunnel interface(s) associated with this profile.
+
+
+ disable + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Disable this profile.
+
+
+ esp_group + +
+ string +
+ 		+ +
ESP group name to use for this profile.
+
+
+ ike_group + +
+ string +
+ 		+ +
IKE group name to use for this profile.
+
+
+ name + +
+ string + / required +
+ 		+ +
Profile name.
+
+
+ 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 for field types/choices: device node.def templates under /opt/vyatta/share/vyatta-cfg/templates/vpn/ipsec/. + + + +Examples +-------- + +.. code-block:: yaml + + # ------------------- + # Using merged + # ------------------- + + # Before state: + # ------------- + # vyos@vyos:~$ show configuration commands | match "vpn ipsec" + # (empty) + + # Task + # ------------- + # - name: Merge provided configuration with device configuration + # vyos.vyos.vyos_vpn_ipsec: + # config: + # esp_group: + # - name: ESP-TEST + # proposal: + # - proposal_id: 1 + # encryption: aes256 + # hash: sha256 + # ike_group: + # - name: IKE-TEST + # key_exchange: ikev2 + # proposal: + # - proposal_id: 1 + # encryption: aes256 + # hash: sha256 + # dh_group: 14 + # state: merged + + # Task output: + # ------------- + # "commands": [ + # "set vpn ipsec esp-group ESP-TEST", + # "set vpn ipsec esp-group ESP-TEST proposal 1", + # "set vpn ipsec esp-group ESP-TEST proposal 1 encryption aes256", + # "set vpn ipsec esp-group ESP-TEST proposal 1 hash sha256", + # "set vpn ipsec ike-group IKE-TEST", + # "set vpn ipsec ike-group IKE-TEST key-exchange ikev2", + # "set vpn ipsec ike-group IKE-TEST proposal 1", + # "set vpn ipsec ike-group IKE-TEST proposal 1 encryption aes256", + # "set vpn ipsec ike-group IKE-TEST proposal 1 hash sha256", + # "set vpn ipsec ike-group IKE-TEST proposal 1 dh-group 14" + # ] + + # ------------------- + # Using gathered + # ------------------- + + # Task + # ------------- + # - name: Gather current vpn_ipsec configuration + # vyos.vyos.vyos_vpn_ipsec: + # state: gathered + + # ------------------- + # Using deleted + # ------------------- + + # Task + # ------------- + # - name: Remove all vpn_ipsec configuration + # vyos.vyos.vyos_vpn_ipsec: + # state: deleted + + # ------------------- + # Using rendered + # ------------------- + + # Task + # ------------- + # - name: Render configuration without touching the device + # vyos.vyos.vyos_vpn_ipsec: + # config: + # esp_group: + # - name: ESP-TEST + # proposal: + # - proposal_id: 1 + # encryption: aes256 + # hash: sha256 + # state: rendered + + # ------------------- + # Using parsed + # ------------------- + + # Task + # ------------- + # - name: Parse raw config text into structured facts + # vyos.vyos.vyos_vpn_ipsec: + # running_config: "{{ lookup('file', './vpn_ipsec.cfg') }}" + # state: parsed + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ 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 esp-group ESP-TEST proposal 1 encryption aes256', 'set vpn ipsec ike-group IKE-TEST key-exchange ikev2']
+
+
+ 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 esp-group ESP-TEST proposal 1 encryption aes256']
+
+

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