Add incremental RST-to-MyST swap mechanism (#1857)

* feat: add swap_sources.py for incremental RST-to-MyST migration

Pre-build swap/restore script that renames md-{name}.md → {name}.md
before Sphinx builds and restores after. Includes state tracking,
exclude file generation, collision detection, and partial-failure
rollback. 10 tests cover all specified behaviors plus rollback path.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat: add import_myst.py for importing MyST files from myst/* branches

Adds scripts/import_myst.py with import_page, git_show, list_myst_files,
list_rst_files, and do_import. Imported files are written as md-{name}.md
alongside existing RST files; importing is decoupled from swap activation.

Adds tests/test_import_myst.py covering single-page write, identical-skip,
warn-on-different-without-force, force-overwrite, and nested-path creation.
All 5 tests pass on Python 3.9.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat: add MyST swap exclude patterns and directive config to conf.py

🤖 Generated by [robots](https://vyos.io)

* feat: add swap-wrapped rendering targets to Makefile

🤖 Generated by [robots](https://vyos.io)

* feat: add swap pre/post build hooks for ReadTheDocs

🤖 Generated by [robots](https://vyos.io)

* feat: add empty _swap.txt, remove atexit from swap script

The atexit handler in --swap mode caused immediate restore on process
exit, breaking standalone usage. Makefile trap and RTD post_build
handle restore reliably.

🤖 Generated by [robots](https://vyos.io)

* feat: activate quick-start as MyST canary via swap mechanism

Imports docs/md-quick-start.md from origin/myst/current and adds
quick-start to docs/_swap.txt. Validates the swap pipeline end-to-end
on one page: import_myst pulls the MD via git show, swap_sources
renames md-quick-start.md to quick-start.md, sphinx-build renders
quick-start.html with zero MD-specific warnings, and restore reverses
the rename cleanly.

🤖 Generated by [robots](https://vyos.io)

* feat: activate 106 visual-validated canaries via swap

Imports 105 MD files (plus quick-start already present) from
origin/myst/current and adds them to docs/_swap.txt. The selection
is the BackstopJS visual-passers cohort: pages with <5% rendered
diff vs the live RST docs at docs.vyos.io/en/latest/, filtered to
those with an RST counterpart on current and no cmdincludemd usage
(template-format reconciliation pending).

Local sphinx-build with all 106 swapped: succeeded with 100
warnings (vs 95 baseline). The 5 new warnings are all undefined
cross-reference labels, not build failures:
- contributing/development.md (missing 'coding-guidelines')
- operation/upgrade-recovery.md (3 missing 'how_it_works' /
  'cancelling_recovery')
- vpp/configuration/dataplane/{buffers,memory,unix}.md (missing
  'vpp_config_dataplane_*' labels)

Source list: ~/.claude/projects/-Users-vybot-GitHub-vyos-documentation/docs/2026-04-29-myst-conversion-audit/visual-passers-under-5pct.txt
BackstopJS report: claude/gifted-hertz-74b9f9 worktree
(visual-compare/), 2026-04-23 vs vyos--1838.org.readthedocs.build.

🤖 Generated by [robots](https://vyos.io)

* fix: re-import 4 canary md-*.md files with xref label fixes

Re-imports the dash-form-corrected versions of:
- contributing/md-development.md (added (coding-guidelines)= anchor)
- operation/md-upgrade-recovery.md (3 ref renames: how_it_works /
  cancelling_recovery -> dash form)
- vpp/configuration/dataplane/md-buffers.md (vpp_config_dataplane_physmem
  -> vpp-config-dataplane-physmem)
- vpp/configuration/dataplane/md-unix.md
  (vpp_config_dataplane_interface_rx_mode
  -> vpp-config-dataplane-interface-rx-mode)

Source: origin/myst/current commit 59fbe3ea. Verified locally: clean
swap-build no longer reports any of the 5 target labels (1 of 6 —
vpp-config-hugepages — remains because system.md isn't in the canary
swap list; that anchor lives there).

🤖 Generated by [robots](https://vyos.io)

* fix: re-add 4 canary md-*.md files deleted by 242b334a

Commit 242b334a accidentally staged deletions instead of modifications
because the working tree had unprefixed *.md files left over from an
incomplete swap-restore cycle. Re-imports the same 4 files from
origin/myst/current with the xref label fixes applied:

- contributing/md-development.md       — (coding-guidelines)= anchor
- operation/md-upgrade-recovery.md     — how_it_works → how-it-works,
                                         cancelling_recovery → cancelling-recovery
- vpp/configuration/dataplane/md-buffers.md — vpp_config_dataplane_physmem
                                              → vpp-config-dataplane-physmem
- vpp/configuration/dataplane/md-unix.md   — vpp_config_dataplane_interface_rx_mode
                                              → vpp-config-dataplane-interface-rx-mode

Source: origin/myst/current commit 59fbe3ea.

🤖 Generated by [robots](https://vyos.io)

* fix: resolve remaining xref label gaps in swap-active build

Three small additions clear the cross-reference warnings tied to
underscore-vs-dash label form mismatches and the vpp-config-hugepages
reference that previously needed system.md in the canary set.

- system.rst: add .. _vpp-config-hugepages: alongside the existing
  underscore label so memory.md references resolve regardless of
  whether system.md is swap-active.
- md-lcp.md: add (vpp_config_dataplane_lcp_ignore-kernel-routes)=
  alongside dash form (carries upstream from myst/current 079fa786).
- md-memory.md: add (vpp_config_dataplane_memory)= alongside dash
  form (also from myst/current 079fa786).

Local clean swap-build with 106 canaries:
  before: 305 warnings, 8 undefined-label entries in our scope
  after:  300 warnings, 0 undefined-label entries in our scope

Remaining undefined-label warnings (release-notes, prepare_commit)
are in documentation.rst and unrelated to the canary swap mechanism.

🤖 Generated by [robots](https://vyos.io)

* fix: re-add md-lcp.md and md-memory.md (deleted by 870c9e7e)

Same disaster pattern as 242b334a: a swap-restore cycle left
unprefixed *.md files in the working tree, and the subsequent
git add staged deletions instead of modifications. Restoring the
two affected md-*.md files from origin/myst/current 079fa786
(which has the dual underscore+dash anchors needed for the
swap-active build).

🤖 Generated by [robots](https://vyos.io)

* feat: expand canaries to 114; refresh 3 with cfgcmd body fix

Adds 8 new visual-validated canaries from the post-cfgcmd-fix
BackstopJS run (2026-04-29):

- configuration/policy/as-path-list
- configuration/policy/community-list
- configuration/policy/extcommunity-list
- configuration/policy/large-community-list
- configuration/policy/local-route
- configuration/policy/prefix-list
- configuration/service/salt-minion
- configuration/system/updates

Refreshes 3 existing canaries whose MD content changed via the
cfgcmd/opcmd single-line body fix on myst/current fc19ab5c:

- configuration/firewall/global-options
- configuration/firewall/groups
- configuration/policy/route

All 11 sourced from origin/myst/current. Net: 106 -> 114 canaries.

🤖 Generated by [robots](https://vyos.io)

* fix: re-import md-cloud-init.md (block 3 fix from myst/current)

🤖 Generated by [robots](https://vyos.io)

* feat(swap): import .md files and webp transition from myst/current

Selective import from origin/myst/current (cf9c9b34):
- Add/update 255 .md files (full MyST conversion plus webp ref updates)
- Delete 175 PNG/JPG from docs/_static/images (webp twins already present)
- Delete 5 autotest topology.png (webp twins already present)

Preserved on swap (untouched):
- All .rst files (incremental swap pattern)
- conf.py, _ext/, _include/*.txt, .gitignore
- 115 canary md-*.md files
- 7 superpowers/specs/*.md design docs
- Logos vyos-logo.png / vyos-logo-icon.png (referenced by conf.py)

🤖 Generated by [robots](https://vyos.io)

* chore(swap): remove canary md-*.md files and docs/superpowers

- Remove 115 canary md-*.md files (incremental swap helpers no longer needed)
- Remove 8 files under docs/superpowers (project planning/design docs that
  shouldn't ship in the documentation tree)

🤖 Generated by [robots](https://vyos.io)

* docs: address Copilot review feedback on imported MyST pages

Fix issues flagged by Copilot review on PR #1857 (the same content lives
in myst/current as the canonical source):

Real bugs:
- site-2-site-cisco.md: replace curly quote (U+2019) with ASCII apostrophe
- rsa-keys.md: fix typo "key-pair nam>>" → "key-pair name>"
- vmware.md: lowercase admonition directive (:::{NOTE} → :::{note})
- vpp/configuration/nat/index.md: remove blank line inside {include} fence

Grammar:
- vpp/configuration/interfaces/loopback.md: "bounded" → "bound"
- vpp/configuration/sflow.md: "VyOS support" → "VyOS supports"
- vpp/requirements.md: "bypass" → "bypasses"
- vpp/configuration/dataplane/interface.md: "configures" → "configure"

CI linter (IP addresses):
- nmp.md: wrap 8.8.8.8 example with stop/start_vyoslinter
- lac-lns.md: wrap LNS config block (contains 8.8.8.8)
- wan-load-balancing.md: wrap whole file (illustrative non-RFC IPs)
- policy/examples.md: replace 192.0.1.1 with RFC 5737 192.0.2.1

🤖 Generated by [robots](https://vyos.io)

* fix(swap): address Copilot review feedback on swap infrastructure

Category D — drop obsolete canary mechanism settings:
- conf.py: remove '**/md-*.md' from exclude_patterns (no canaries left)
- Makefile: replace malformed '*/_build/*' with '$(BUILDDIR)/**' and drop
  the '*/md-*' ignore (canary files no longer exist)

Category C — script robustness:
- import_myst.py:
  * list_myst_files() now raises SystemExit on git ls-tree failure instead
    of silently returning [] (would have masked typo'd --source refs)
  * list_rst_files() skips _build/ when scanning for .rst stems
  * import_page() rejects stems containing '..' or absolute paths and
    re-checks that the resolved destination stays under docs_dir
  * --dry-run uses a separate "would_import" counter; summary line now
    distinguishes dry-run from actual imports
- swap_sources.py:
  * parse_swap_list() reads with explicit encoding='utf-8'
  * do_restore() validates state file version + entry shape before
    renaming files; raises with actionable message on corruption
  * State file reads/writes use explicit encoding='utf-8' throughout

_swap.txt:
- Wrap long comment line to satisfy 80-character doc-linter limit

🤖 Generated by [robots](https://vyos.io)

* refactor(swap): rename imported .md files to md- prefix for swap mechanism

Restore the canary file naming convention that swap_sources.py expects:
the imported MyST pages now live as docs/<dir>/md-<name>.md alongside
the existing docs/<dir>/<name>.rst, so swap_sources.py --swap can rename
them into place at build time.

- 254 .md files renamed (every page with a matching .rst counterpart)
- 2 MyST-only pages left at their final names (no .rst exists, no swap
  needed): docs/copyright.md, docs/automation/terraform/terraformvyos.md

All 114 stems listed in docs/_swap.txt now have a corresponding
md-<name>.md source file ready to swap in.

🤖 Generated by [robots](https://vyos.io)

* docs: address CodeRabbit review feedback on imported MyST pages

Fix issues flagged by CodeRabbit on PR #1857. All issues are pre-existing
in the upstream RST docs and inherited by the MyST conversion.

Real bugs:
- inter-vrf-routing-vrf-lite.md: invalid IPv6 next-hop "2001:db8::*" →
  "2001:db8::1"
- ipsec-pa-route-based.md: vendor mislabel "Cisco" → "Palo Alto"
  (header on line 39 and "Monitoring on Cisco side" section heading)
- bgp-ipv6-unnumbered.md: AS number mismatch between configuration and
  verification output for both routers (Router A: 65020 → 64496;
  Router B: 65021 → 64499)
- qos.md: class 30 used "match ADDRESS20" instead of ADDRESS30 — broke
  the documented pattern (classes 10/20/30 → ADDRESS10/20/30)

Security:
- OpenVPN_with_LDAP.md: redact full PEM private key material from the
  three "set pki ... private key '...'" lines and from the embedded
  OpenVPN client <key> block; replace with <REDACTED> / ...REDACTED...
  placeholders. Public certificates retained.

🤖 Generated by [robots](https://vyos.io)

* feat(swap): default to serving MyST for all swapped pages

Replace the previously-curated 114-stem _swap.txt with the full set of
254 imported md-prefixed pages, so MD is served by default at build
time. To revert any specific page back to RST, remove its stem from
_swap.txt (or comment it out).

🤖 Generated by [robots](https://vyos.io)

* fix(ext): handle RST fallback in CmdInclude when _renderer absent

`cmdincludemd` is in `myst_fence_as_directive`, so MyST routes
fence blocks through `render_fence → render_restructuredtext →
MockRSTParser`. In that path `self.state` is a plain docutils Body
with no `_renderer`, crashing the build.

Fall back to `nested_parse` when `_renderer` is unavailable so the
directive works in both MyST and RST/MockRSTParser contexts.

🤖 Generated by [robots](https://vyos.io)

* feat(conf): copy .md sources into HTML output for plain-text serving

Adds a build-finished hook that mirrors every .md file from the Sphinx
source tree into the HTML output directory verbatim, making unrendered
MyST sources accessible alongside HTML renders at the same URL path.

🤖 Generated by [robots](https://vyos.io)

* docs: address review feedback from PR #1857

Fix conversion artifacts, typos, grammar errors, and technical
inaccuracies flagged by automated code review (Copilot + CodeRabbit).

Infrastructure: add root-level md-*.md exclusion to conf.py,
fix sphinx-autobuild ignore globs in Makefile.

Content: fix curly quotes, invalid Go panic() calls, shell quoting
in cURL examples, incorrect firewall command paths, typos across
22 documentation files, remove duplicate sections.

🤖 Generated by [robots](https://vyos.io)

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

5 files changed, 1697 insertions, 0 deletions

diff --git a/docs/configuration/vpn/ipsec/md-index.md b/docs/configuration/vpn/ipsec/md-index.md
new file mode 100644
index 00000000..cc40b6f8
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/md-index.md
@@ -0,0 +1,11 @@
+# IPsec
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+ipsec_general
+site2site_ipsec
+remoteaccess_ipsec
+troubleshooting_ipsec
+```
diff --git a/docs/configuration/vpn/ipsec/md-ipsec_general.md b/docs/configuration/vpn/ipsec/md-ipsec_general.md
new file mode 100644
index 00000000..6fc47386
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/md-ipsec_general.md
@@ -0,0 +1,407 @@
+(ipsec_general)=
+
+# IPsec General Information
+
+## Information about IPsec
+
+IPsec is the framework used to secure data.
+IPsec accomplishes these goals by providing authentication,
+encryption of IP network packets, key exchange, and key management.
+VyOS uses Strongswan package to implement IPsec.
+
+**Authentication Header (AH)** is defined in {rfc}`4302`. It creates
+a hash using the IP header and data payload, and prepends it to the
+packet. This hash is used to validate that the data has not been
+changed during transfer over the network.
+
+**Encapsulating Security Payload (ESP)** is defined in {rfc}`4303`.
+It provides encryption and authentication of the data.
+
+```{eval-rst}
+There are two IPsec modes:
+    **IPsec Transport Mode**:
+        In transport mode, an IPSec header (AH or ESP) is inserted
+        between the IP header and the upper layer protocol header.
+
+    **IPsec Tunnel Mode:**
+        In tunnel mode, the original IP packet is encapsulated in
+        another IP datagram, and an IPsec header (AH or ESP) is
+        inserted between the outer and inner headers.
+
+.. figure:: /_static/images/ESP_AH.webp
+   :scale: 80 %
+   :alt: AH and ESP in Transport Mode and Tunnel Mode
+```
+
+## IKE (Internet Key Exchange)
+
+The default IPsec method for secure key negotiation is the Internet Key
+Exchange (IKE) protocol. IKE is designed to provide mutual authentication
+of systems, as well as to establish a shared secret key to create IPsec
+security associations. A security association (SA) includes all relevant
+attributes of the connection, including the cryptographic algorithm used,
+the IPsec mode, the encryption key, and other parameters related to the
+transmission of data over the VPN connection.
+
+### IKEv1
+
+IKEv1 is the older version and is still used today. Nowadays, most
+manufacturers recommend using IKEv2 protocol.
+
+IKEv1 is described in the next RFCs: {rfc}`2409` (IKE), {rfc}`3407`
+(IPsec DOI), {rfc}`3947` (NAT-T), {rfc}`3948` (UDP Encapsulation
+of ESP Packets), {rfc}`3706` (DPD)
+
+```{eval-rst}
+IKEv1 operates in two phases to establish these IKE and IPsec SAs:
+    * **Phase 1** provides mutual authentication of the IKE peers and
+      establishment of the session key. This phase creates an IKE SA (a
+      security association for IKE) using a DH exchange, cookies, and an
+      ID exchange. Once an IKE SA is established, all IKE communication
+      between the initiator and responder is protected with encryption
+      and an integrity check that is authenticated. The purpose of IKE
+      phase 1 is to facilitate a secure channel between the peers so that
+      phase 2 negotiations can occur securely. IKE phase 1 offers two modes:
+      Main and Aggressive.
+
+        * **Main Mode** is used for site-to-site VPN connections.
+        
+        * **Aggressive Mode** is used for remote access VPN connections.
+
+    * **Phase 2** provides for the negotiation and establishment of the
+      IPsec SAs using ESP or AH to protect IP data traffic.
+```
+
+### IKEv2
+
+IKEv2 is described in {rfc}`7296`. The biggest difference between IKEv1 and
+IKEv2 is that IKEv2 is much simpler and more reliable than IKEv1 because
+fewer messages are exchanged during the establishment of the VPN and
+additional security capabilities are available.
+
+### IKE Authentication
+
+```{eval-rst}
+VyOS supports 3 authentication methods.
+    * **Pre-shared keys**: In this method, both peers of the IPsec
+      tunnel must have the same preshared keys.
+    * **Digital certificates**: PKI is used in this method.
+    * **RSA-keys**: If the RSA-keys method is used in your IKE policy,
+      you need to make sure each peer has the other peer’s public keys.
+```
+
+## DPD (Dead Peer Detection)
+
+This is a mechanism used to detect when a VPN peer is no longer active.
+This mechanism has different algorithms in IKEv1 and IKEv2 in VyOS.
+DPD Requests are sent as ISAKMP R-U-THERE messages and DPD Responses
+are sent as ISAKMP R-U-THERE-ACK messages. In IKEv1, DPD sends messages
+every configured interval. The remote peer is considered unreachable
+if no response to these packets is received within the DPD timeout.
+In IKEv2, DPD sends messages every configured interval. If one request
+is not responded, Strongswan execute its retransmission algorithm with
+its timers.  [IKEv2 Retransmission](#ikev2-retransmission)
+
+## Post-Quantum Preshared Keys (PPK)
+
+Post-Quantum Preshared Keys help provide some quantum resistance to IPSec
+tunnels when a post-quantum key exchange algorithm such as ML-KEM is not
+available. The use of PPKs in IKEv2 is described in {rfc}`8784`.
+
+```{eval-rst}
+.. cfgmod:: edit vpn authentication ppk <name>
+```
+
+PPKs can be configued within VyOS under the `vpn ipsec authentication ppk`
+config.
+
+```{eval-rst}
+.. cfgmod:: set vpn authentication ppk <name> secret-type <plaintext|hex|base64>
+```
+
+PPKs need an id and a secret value. The ID and the secret must match if PPKs are
+required for a successful IPsec connection. The secret can be plain text, a
+hex value, or a Base64 value. The default is plain text. If using another
+type of value, you must define the secret type.
+
+```{eval-rst}
+.. cfgmod:: set vpn ipsec site-to-site <name> ppk id <id>
+```
+
+To use a PPK within a site-to-site or remote access connection, define the PPK
+id under the connection.
+
+```{eval-rst}
+.. cfgmod:: set vpn ipsec site-to-site <name> ppk required
+```
+
+Optionally, you can require the use of PPK to have a successful connection.
+
+```{eval-rst}
+.. cfgmod:: show vpn ipsec connections
+```
+
+You can view the PPK column for information on if PPK is configured, and
+if it is in use. The output is in the format of `<configured> / <in use>`.
+The options for configured are none if not conifugred, opt if configured
+but optional, and req is configured and required. The in use will show yes
+Possible values of the `configured` field are `none` if not
+conifgured, `opt` if configured but optional, and `req` is
+configured and required. The in use will show yes
+
+## Configuration IKE
+
+```{eval-rst}
+IKE (Internet Key Exchange) Attributes
+======================================
+
+VyOS IKE group has the next options:
+
+.. cfgcmd:: set vpn ipsec ike-group <name> close-action <action>
+
+  Defines the action to take if the remote peer unexpectedly
+  closes a CHILD_SA:
+
+ * **none** - Set action to none (default),
+ * **trap** - Installs a trap policy (IPsec policy without Security
+   Association) for the CHILD_SA and traffic matching these policies
+   will trigger acquire events that cause the daemon to establish the
+   required IKE/IPsec SAs.
+ * **start** - Tries to immediately re-create the CHILD_SA.
+
+.. cfgcmd:: set vpn ipsec ike-group <name> ikev2-reauth
+
+  Whether rekeying of an IKE_SA should also reauthenticate
+  the peer. In IKEv1, reauthentication is always done.
+  Setting this parameter enables remote host re-authentication
+  during an IKE rekey.
+
+.. cfgcmd:: set vpn ipsec ike-group <name> key-exchange
+
+  Which protocol should be used to initialize the connection
+  If not set both protocols are handled and connections will
+  use IKEv2 when initiating, but accept any protocol version
+  when responding:
+
+ * **ikev1** - Use IKEv1 for Key Exchange.
+ * **ikev2** - Use IKEv2 for Key Exchange.
+
+.. cfgcmd:: set vpn ipsec ike-group <name> lifetime
+
+  IKE lifetime in seconds <0-86400> (default 28800).
+
+.. cfgcmd:: set vpn ipsec ike-group <name> mode
+
+  IKEv1 Phase 1 Mode Selection:
+
+ * **main** - Use Main mode for Key Exchanges in the IKEv1 Protocol
+   (Recommended Default).
+ * **aggressive** - Use Aggressive mode for Key Exchanges in the IKEv1
+   protocol aggressive mode is much more insecure compared to Main mode.
+
+.. stop_vyoslinter
+
+.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> dh-group <dh-group number>
+
+  Dh-group. Default value is **2**.
+
+.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> encryption <encryption>
+
+  Encryption algorithm. Default value is **aes128**.
+
+.. start_vyoslinter
+
+.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> hash <hash>
+
+  Hash algorithm. Default value is **sha1**.
+
+.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> prf <prf>
+
+  Pseudo-random function.
+
+
+DPD (Dead Peer Detection) Configuration
+=======================================
+
+.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection action <action>
+
+  Action to perform for this CHILD_SA on DPD timeout.
+
+  * **trap** - Installs a trap policy (IPsec policy without Security
+    Association), which will catch matching traffic and tries to
+    re-negotiate the tunnel on-demand.
+  * **clear** - Closes the CHILD_SA and does not take further action
+    (default).
+  * **restart** - Immediately tries to re-negotiate the CHILD_SA
+    under a fresh IKE_SA.
+
+.. stop_vyoslinter
+
+.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection interval <interval>
+
+  Keep-alive interval in seconds <2-86400> (default 30).
+
+.. start_vyoslinter
+
+.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection timeout <timeout>
+
+  Keep-alive timeout in seconds <2-86400> (default 120) **IKEv1 only**
+
+ESP (Encapsulating Security Payload) Attributes
+===============================================
+
+In VyOS, ESP attributes are specified through ESP groups.
+Multiple proposals can be specified in a single group.
+
+VyOS ESP group has the next options:
+
+.. cfgcmd:: set vpn ipsec esp-group <name> compression
+
+  Enables the  IPComp(IP Payload Compression) protocol which allows
+  compressing the content of IP packets.
+
+.. cfgcmd:: set vpn ipsec esp-group <name> disable-rekey
+
+  Do not locally initiate a re-key of the SA, remote peer must
+  re-key before expiration.
+
+.. cfgcmd:: set vpn ipsec esp-group <name> life-bytes <bytes>
+
+  ESP life in bytes <1024-26843545600000>. Number of bytes
+  transmitted over an IPsec SA before it expires.
+
+.. cfgcmd:: set vpn ipsec esp-group <name> life-packets <packets>
+
+  ESP life in packets <1000-26843545600000>.
+  Number of packets transmitted over an IPsec SA before it expires.
+
+.. cfgcmd:: set vpn ipsec esp-group <name> lifetime <timeout>
+
+  ESP lifetime in seconds <30-86400> (default 3600).
+  How long a particular instance of a connection (a set of
+  encryption/authentication keys for user packets) should last,
+  from successful negotiation to expiry.
+
+.. cfgcmd:: set vpn ipsec esp-group <name> mode <mode>
+
+  The type of the connection:
+
+  * **tunnel** - Tunnel mode (default).
+  * **transport** - Transport mode.
+
+.. cfgcmd:: set vpn ipsec esp-group <name> pfs < dh-group>
+
+  Whether Perfect Forward Secrecy of keys is desired on the
+  connection's keying channel and defines a Diffie-Hellman group for
+  PFS:
+
+ * **enable** - Inherit Diffie-Hellman group from IKE group (default).
+ * **disable** - Disable PFS.
+ * **<dh-group>** - Defines a Diffie-Hellman group for PFS.
+
+.. stop_vyoslinter
+
+.. cfgcmd:: set vpn ipsec esp-group <name> proposal <number> encryption <encryption>
+
+  Encryption algorithm. Default value is **aes128**.
+
+.. start_vyoslinter
+
+.. cfgcmd:: set vpn ipsec esp-group <name> proposal <number> hash <hash>
+
+  Hash algorithm. Default value is **sha1**.
+
+Global IPsec Settings
+=====================
+
+.. cfgcmd:: set vpn ipsec interface <name>
+
+  Interface name to restrict outbound IPsec policies. There is a possibility
+  to specify multiple interfaces. If an interfaces are not specified, IPsec
+  policies apply to all interfaces.
+
+
+.. cfgcmd:: set vpn ipsec log level <number>
+
+  Level of logging. Default value is **0**.
+
+.. cfgcmd:: set vpn ipsec log subsystem <name>
+
+  Subsystem of the daemon.
+
+Options
+=======
+
+.. cfgcmd:: set vpn ipsec options disable-route-autoinstall
+
+  Do not automatically install routes to remote
+  networks.
+
+.. cfgcmd:: set vpn ipsec options flexvpn
+
+  Allows FlexVPN vendor ID payload (IKEv2 only). Send the Cisco
+  FlexVPN vendor ID payload (IKEv2 only), which is required in order to make
+  Cisco brand devices allow negotiating a local traffic selector (from
+  strongSwan's point of view) that is not the assigned virtual IP address if
+  such an address is requested by strongSwan. Sending the Cisco FlexVPN
+  vendor ID prevents the peer from narrowing the initiator's local traffic
+  selector and allows it to e.g. negotiate a TS of 0.0.0.0/0 == 0.0.0.0/0
+  instead. This has been tested with a "tunnel mode ipsec ipv4" Cisco
+  template but should also work for GRE encapsulation.
+
+.. cfgcmd:: set vpn ipsec options interface <name>
+
+  Interface Name to use. The name of the interface on which
+  virtual IP addresses should be installed. If not specified the addresses
+  will be installed on the outbound interface.
+
+.. cfgcmd:: set vpn ipsec options virtual-ip
+
+  Allows the installation of virtual-ip addresses.
+```
+
+### IKEv2 Retransmission
+
+If the peer does not respond on DPD packet, the router starts retransmission procedure.
+
+The following formula is used to calculate the timeout:
+
+```none
+relative timeout = timeout * base ^ (attempts-1)
+```
+
+```{cfgcmd} set vpn ipsec options retransmission attempts
+
+Number of attempts before the peer is considered to be in the down state.
+Default value is **5**.
+```
+
+```{cfgcmd} set vpn ipsec options retransmission base
+
+Base number of exponential backoff. Default value is **1.8**.
+```
+
+```{cfgcmd} set vpn ipsec options retransmission timeout
+
+Timeout in seconds before the first retransmission. Default value is **4**.
+```
+
+Using the default values, packets are retransmitted as follows:
+
+```{eval-rst}
++-----------+-------------+------------------+------------------+
+| Attempts  | Formula     | Relative timeout | Absolute timeout |
++-----------+-------------+------------------+------------------+
+| 1         | 4 * 1.8 ^ 0 | 4s               | 4s               |
++-----------+-------------+------------------+------------------+
+| 2         | 4 * 1.8 ^ 1 | 7s               | 11s              |
++-----------+-------------+------------------+------------------+
+| 3         | 4 * 1.8 ^ 2 | 13s              | 24s              |
++-----------+-------------+------------------+------------------+
+| 4         | 4 * 1.8 ^ 3 | 23s              | 47s              |
++-----------+-------------+------------------+------------------+
+| 5         | 4 * 1.8 ^ 4 | 42s              | 89s              |
++-----------+-------------+------------------+------------------+
+| peer down | 4 * 1.8 ^ 5 | 76s              | 165s             |
++-----------+-------------+------------------+------------------+
+```
diff --git a/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md b/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md
new file mode 100644
index 00000000..6931e00b
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md
@@ -0,0 +1,186 @@
+(remoteaccess-ipsec)=
+
+# IPSec IKEv2 Remote Access VPN
+
+```{todo}
+Convert raw command blocks in this file to cfgcmd/opcmd
+directives for command coverage tracking.
+```
+
+Internet Key Exchange version 2 (IKEv2) is a tunneling protocol, based on IPsec,
+that establishes a secure VPN communication between VPN devices, and defines
+negotiation and authentication processes for IPsec security associations (SAs).
+It is often known as IKEv2/IPSec or IPSec IKEv2 remote-access — or road-warriors
+as others call it.
+
+Key exchange and payload encryption is done using IKE and ESP proposals as known
+from IKEv1 but the connections are faster to establish, more reliable, and also
+support roaming from IP to IP (called MOBIKE which makes sure your connection
+does not drop when changing networks from e.g. WIFI to LTE and back).
+Authentication can be achieved with X.509 certificates.
+
+## Setting up certificates:
+
+First of all, we need to create a CA root certificate and server certificate
+on the server side.
+
+```none
+vyos@vpn.vyos.net# run generate pki ca install ca_root
+Enter private key type: [rsa, dsa, ec] (Default: rsa)
+Enter private key bits: (Default: 2048)
+Enter country code: (Default: GB)
+Enter state: (Default: Some-State)
+Enter locality: (Default: Some-City)
+Enter organization name: (Default: VyOS)
+Enter common name: (Default: vyos.io)
+Enter how many days certificate will be valid: (Default: 1825)
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N] N
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+[edit]
+
+
+vyos@vpn.vyos.net# comp
+[pki ca]
++ ca_root {
++     certificate "MIIDnTCCAoWgAwI…."
++     private {
++         key "MIIEvAIBADANBgkqhkiG9….”
+
+vyos@vpn.vyos.net# run generate pki certificate sign ca_root install server_cert
+Do you already have a certificate request? [y/N] N
+Enter private key type: [rsa, dsa, ec] (Default: rsa)
+Enter private key bits: (Default: 2048)
+Enter country code: (Default: GB)
+Enter state: (Default: Some-State)
+Enter locality: (Default: Some-City)
+Enter organization name: (Default: VyOS)
+Enter common name: (Default: vyos.io) vpn.vyos.net
+Do you want to configure Subject Alternative Names? [y/N] N
+Enter how many days certificate will be valid: (Default: 365)
+Enter certificate type: (client, server) (Default: server)
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N] N
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+
+vyos@vpn.vyos.net# comp
+[pki certificate]
++ server_cert {
++     certificate "MIIDuzCCAqOgAwIBAgIUaSrCPWx………"
++     private {
++         key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBK….."
++     }
++ }
+```
+
+Once the command is completed, it will add the certificate to the configuration
+session, to the pki subtree. You can then review the proposed changes and
+commit them.
+
+## Setting up IPSec:
+
+After the PKI certs are all set up we can start configuring our IPSec/IKE
+proposals used for key-exchange end data encryption. The used encryption ciphers
+and integrity algorithms vary from operating system to operating system. The
+ones used in this example are validated to work on Windows 10.
+
+```none
+set vpn ipsec esp-group ESP-RW lifetime '3600'
+set vpn ipsec esp-group ESP-RW pfs 'disable'
+set vpn ipsec esp-group ESP-RW proposal 10 encryption 'aes128gcm128'
+set vpn ipsec esp-group ESP-RW proposal 10 hash 'sha256'
+
+set vpn ipsec ike-group IKE-RW key-exchange 'ikev2'
+set vpn ipsec ike-group IKE-RW lifetime '7200'
+set vpn ipsec ike-group IKE-RW proposal 10 dh-group '14'
+set vpn ipsec ike-group IKE-RW proposal 10 encryption 'aes128gcm128'
+set vpn ipsec ike-group IKE-RW proposal 10 hash 'sha256'
+```
+
+Every connection/remote-access pool we configure also needs a pool where we
+can draw our client IP addresses from. We provide one IPv4 and IPv6 pool.
+Authorized clients will receive an IPv4 address from the configured IPv4 prefix
+and an IPv6 address from the IPv6 prefix. We can also send some DNS nameservers
+down to our clients used on their connection.
+
+```none
+set vpn ipsec remote-access pool ra-rw-ipv4 name-server '192.0.2.1'
+set vpn ipsec remote-access pool ra-rw-ipv4 prefix '192.0.2.128/25'
+
+set vpn ipsec remote-access pool ra-rw-ipv6 name-server '2001:db8:1000::1'
+set vpn ipsec remote-access pool ra-rw-ipv6 prefix '2001:db8:2000::/64'
+```
+
+
+## Setting up tunnel:
+
+```none
+set vpn ipsec remote-access connection rw authentication local-id '192.0.2.1'
+set vpn ipsec remote-access connection rw authentication server-mode 'x509'
+set vpn ipsec remote-access connection rw authentication x509 ca-certificate 'ca_root'
+set vpn ipsec remote-access connection rw authentication x509 certificate 'server_cert'
+set vpn ipsec remote-access connection rw esp-group 'ESP-RW'
+set vpn ipsec remote-access connection rw ike-group 'IKE-RW'
+set vpn ipsec remote-access connection rw local-address '192.0.2.1'
+set vpn ipsec remote-access connection rw pool 'ra-rw-ipv4'
+set vpn ipsec remote-access connection rw pool 'ra-rw-ipv6'
+```
+
+VyOS also supports two different modes of authentication, local and RADIUS.
+To create a new local user named "vyos" with a password of "vyos" use the
+following commands.
+
+```none
+set vpn ipsec remote-access connection rw authentication client-mode 'eap-mschapv2'
+set vpn ipsec remote-access connection rw authentication local-users username vyos password 'vyos'
+```
+
+Some client operating systems like to see the servers certificate. The following
+option causes the server to voluntarily send its certificate, even if it wasn't
+requested.
+
+```none
+set vpn ipsec remote-access connection rw authentication always-send-cert
+```
+
+
+## Client Configuration
+
+Most operating systems include native client support for IPsec IKEv2 VPN
+connections, and others typically have an app or add-on package which adds the
+capability.
+This section covers IPsec IKEv2 client configuration for Windows 10.
+
+VyOS provides a command to generate a connection profile used by Windows clients
+that will connect to the "rw" connection on our VyOS server.
+
+:::{note}
+Windows expects the server name to be also used in the server's
+certificate common name, so it's best to use this DNS name for your VPN
+connection.
+:::
+
+```none
+vyos@vpn.vyos.net:~$ generate ipsec profile windows-remote-access rw remote vpn.vyos.net
+
+
+==== <snip> ====
+Add-VpnConnection -Name "VyOS IKEv2 VPN" -ServerAddress "vpn.vyos.net" -TunnelType "Ikev2"
+
+Set-VpnConnectionIPsecConfiguration -ConnectionName "VyOS IKEv2 VPN" -AuthenticationTransformConstants GCMAES128 -CipherTransformConstants
+GCMAES128 -EncryptionMethod GCMAES128 -IntegrityCheckMethod SHA256128 -PfsGroup None -DHGroup "Group14" -PassThru -Force
+==== </snip> ====
+```
+
+Add the commands from Snippet in the Windows side via PowerShell.
+Also import the root CA cert to the Windows “Trusted Root Certification
+Authorities” and establish the connection.
+
+## Verification:
+
+```none
+vyos@vpn.vyos.net:~$ show vpn ipsec remote-access summary
+  Connection ID  Username    Protocol    State    Uptime    Tunnel IP    Remote Host    Remote ID    IKE Proposal                                IPSec Proposal
+---------------  ----------  ----------  -------  --------  -----------  -------------  -----------  ------------------------------------------  ------------------
+              5  vyos        IKEv2       UP       37s       192.0.2.129  10.0.0.2       10.0.0.2     AES_GCM_16-128/PRF_HMAC_SHA2_256/MODP_2048  ESP:AES_GCM_16-128
+```
diff --git a/docs/configuration/vpn/ipsec/md-site2site_ipsec.md b/docs/configuration/vpn/ipsec/md-site2site_ipsec.md
new file mode 100644
index 00000000..d3b65ae1
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/md-site2site_ipsec.md
@@ -0,0 +1,780 @@
+(size2site-ipsec)=
+
+# IPsec Site-to-Site VPN
+
+## IPsec Site-to-Site VPN Types
+
+VyOS supports two types of IPsec VPN: Policy-based IPsec VPN and Route-based
+IPsec VPN.
+
+### Policy-based VPN
+
+Policy-based VPN is based on static configured policies. Each policy creates
+individual IPSec SA. Traffic matches these SAs encrypted and directed to the
+remote peer.
+
+### Route-Based VPN
+
+Route-based VPN is based on secure traffic passing over Virtual Tunnel
+Interfaces (VTIs). This type of IPsec VPNs allows using routing protocols.
+
+## Configuration Site-to-Site VPN
+
+### Requirements and Prerequisites for Site-to-Site VPN
+
+**Negotiated parameters that need to match**
+
+```{eval-rst}
+Phase 1
+ * IKE version
+ * Authentication
+ * Encryption
+ * Hashing
+ * PRF
+ * Lifetime
+
+ .. note:: Strongswan recommends to use the same lifetime value on both peers
+
+Phase 2
+ * Encryption
+ * Hashing
+ * PFS
+ * Mode (tunnel or transport)
+ * Lifetime
+
+ .. note:: Strongswan recommends to use the same lifetime value on both peers
+
+ * Remote and Local networks in SA must be compatible on both peers
+```
+
+### Configuration Steps for Site-to-Site VPN
+
+The next example shows the configuration one of the router participating in
+IPsec VPN.
+
+```{eval-rst}
+Tunnel information:
+    * Phase 1:
+        * encryption: AES256
+        * hash: SHA256
+        * PRF: SHA256
+        * DH: 14
+        * lifetime: 28800
+    * Phase 2:
+        * IPsec mode: tunnel
+        * encryption: AES256
+        * hash: SHA256
+        * PFS: inherited from DH Phase 1
+        * lifetime: 3600
+    * If Policy based VPN is used
+        * Remote network is 192.168.50.0/24. Local network is 192.168.10.0/24
+    * If Route based VPN is used
+        * IP of the VTI interface is 10.0.0.1/30
+```
+
+:::{note}
+We do not recommend using policy-based vpn and route-based vpn configurations to the same peer.
+:::
+
+**1. Configure ike-group (IKE Phase 1)**
+
+```none
+set vpn ipsec ike-group IKE close-action 'start'
+set vpn ipsec ike-group IKE key-exchange 'ikev1'
+set vpn ipsec ike-group IKE lifetime '28800'
+set vpn ipsec ike-group IKE proposal 10 dh-group '14'
+set vpn ipsec ike-group IKE proposal 10 encryption 'aes256'
+set vpn ipsec ike-group IKE proposal 10 hash 'sha256'
+set vpn ipsec ike-group IKE proposal 10 prf 'prfsha256'
+```
+
+**2. Configure ESP-group (IKE Phase 2)**
+
+```none
+set vpn ipsec esp-group ESP lifetime '3600'
+set vpn ipsec esp-group ESP mode 'tunnel'
+set vpn ipsec esp-group ESP pfs 'enable'
+set vpn ipsec esp-group ESP proposal 10 encryption 'aes256'
+set vpn ipsec esp-group ESP proposal 10 hash 'sha256'
+```
+
+**3. Specify interface facing to the protected destination.**
+
+```none
+set vpn ipsec interface eth0
+```
+
+**4. Configure PSK keys and authentication ids for this key if authentication type is PSK**
+
+```none
+set vpn ipsec authentication psk PSK-KEY id '192.168.0.2'
+set vpn ipsec authentication psk PSK-KEY id '192.168.5.2'
+set vpn ipsec authentication psk PSK-KEY secret 'vyos'
+```
+
+To set base64 secret encode plaintext password to base64 and set secret-type
+
+```none
+echo -n "vyos" | base64
+dnlvcw==
+```
+
+```none
+set vpn ipsec authentication psk PSK-KEY secret 'dnlvcw=='
+set vpn ipsec authentication psk PSK-KEY secret-type base64
+```
+
+**5. Configure peer and apply IKE-group and esp-group to peer.**
+
+```none
+set vpn ipsec site-to-site peer PEER1 authentication local-id '192.168.0.2'
+set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer PEER1 authentication remote-id '192.168.5.2'
+set vpn ipsec site-to-site peer PEER1 connection-type 'initiate'
+set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP'
+set vpn ipsec site-to-site peer PEER1 ike-group 'IKE'
+set vpn ipsec site-to-site peer PEER1 local-address '192.168.0.2'
+set vpn ipsec site-to-site peer PEER1 remote-address '192.168.5.2'
+
+Peer selects the key from step 4 according to local-id/remote-id pair.
+```
+
+**6. Depends to vpn type (route-based vpn or policy-based vpn).**
+
+> **6.1 For Policy-based VPN configure SAs using tunnel command specifying remote and local networks.**
+>
+> > ```none
+> > set vpn ipsec site-to-site peer PEER1 tunnel 1 local prefix '192.168.10.0/24'
+> > set vpn ipsec site-to-site peer PEER1 tunnel 1 remote prefix '192.168.50.0/24'
+> > ```
+>
+> **6.2 For Route-based VPN create VTI interface, set IP address to this interface and bind this interface to the vpn peer.**
+>
+> > ```none
+> > set interfaces vti vti1 address 10.0.0.1/30
+> > set vpn ipsec site-to-site peer PEER1 vti bind vti1
+> > set vpn ipsec options disable-route-autoinstall
+> > ```
+> >
+> > Create routing between local networks via VTI interface using dynamic or
+> > static routing.
+> >
+> > ```none
+> > set protocol static route 192.168.50.0/24 next-hop 10.0.0.2
+> > ```
+
+### Initiator and Responder Connection Types
+
+In Site-to-Site IPsec VPN it is recommended that one peer should be an
+initiator and the other - the responder. The initiator actively establishes
+the VPN tunnel. The responder passively waits for the remote peer to
+establish the VPN tunnel. Depends on selected role it is recommended
+select proper values for close-action and DPD action.
+
+The result of wrong value selection can be unstable work of the VPN.
+: - Duplicate CHILD SA creation.
+  - None of the VPN sides initiates the tunnel establishment.
+
+Below flow-chart could be a quick reference for the close-action
+combination depending on how the peer is configured.
+
+```{eval-rst}
+.. figure:: /_static/images/IPSec_close_action_settings.webp
+```
+
+Similar combinations are applicable for the dead-peer-detection.
+
+### Detailed Configuration Commands
+
+#### PSK Key Authentication
+
+```{cfgcmd} set vpn ipsec authentication psk \<name\> dhcp-interface
+
+ID for authentication generated from DHCP address
+dynamically.
+
+```
+
+```{cfgcmd} set vpn ipsec authentication psk id \<id\>
+
+static ID's for authentication. In general local and remote address
+``<x.x.x.x>``, ``<h:h:h:h:h:h:h:h>`` or ``%any``.
+```
+
+```{cfgcmd} set vpn ipsec authentication psk secret \<secret\>
+
+A predefined shared secret used in configured mode
+``pre-shared-secret``. Base64-encoded secrets are allowed if
+`secret-type base64` is configured.
+```
+
+```{cfgcmd} set vpn ipsec authentication psk secret-type \<type\>
+
+Specifies the secret type:
+
+* **plaintext** - Plain text type (default value).
+* **base64** - Base64 type.
+```
+
+#### Peer Configuration
+
+
+##### Peer Authentication Commands
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication mode \<mode\>
+
+Mode for authentication between VyOS and remote peer:
+
+* **pre-shared-secret** - Use predefined shared secret phrase.
+* **rsa** - Use simple shared RSA key.
+* **x509** - Use certificates infrastructure for authentication.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication local-id \<id\>
+
+ID for the local VyOS router. If defined, during the authentication
+it will be send to remote peer.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication remote-id \<id\>
+
+ID for remote peer, instead of using peer name or
+address. Useful in case if the remote peer is behind NAT
+or if ``mode x509`` is used.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication rsa local-key \<key\>
+
+Name of PKI key-pair with local private key.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication rsa remote-key \<key\>
+
+Name of PKI key-pair with remote public key.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication rsa passphrase \<passphrase\>
+
+Local private key passphrase.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication use-x509-id \<id\>
+
+Use local ID from x509 certificate. Cannot be used when
+``id`` is defined.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication x509 ca-certificate \<name\>
+
+Name of CA certificate in PKI configuration. Using for authenticating
+remote peer in x509 mode.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication x509 certificate \<name\>
+
+Name of certificate in PKI configuration, which will be used
+for authenticating local router on remote peer.
+```
+
+```{cfgcmd} set vpn ipsec authentication x509 passphrase \<passphrase\>
+
+Private key passphrase, if needed.
+```
+
+##### Global Peer Configuration Commands
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> connection-type \<type\>
+
+Operational mode defines how to handle this connection process.
+
+* **initiate** - does initial connection to remote peer immediately
+  after configuring and after boot. In this mode the connection will
+  not be restarted in case of disconnection, therefore should be used
+  only together with DPD or another session tracking methods.
+
+* **trap** - does not try to initiate a connection to a remote
+  peer immediately. Instead, it installs a trap policy that will
+  trigger IKE negotiation and establish the IPsec session when
+  matching traffic is sent from the local side. This can be useful
+  when there is no direct connectivity to the peer due to firewall
+  or NAT in the middle of the local and remote side.
+
+  :::{warning}
+  The ``trap`` mode is not needed in most environments
+  and can lead to connection confusion or unintended tunnel uptime
+  behavior if used incorrectly. Using this mode requires careful
+  coordination with parameters such as ``close-action`` and DPD.
+  For most deployments, use ``initiate`` and ``none`` as described below.
+  :::
+
+* **none** - loads the connection only, which then can be manually
+  initiated or used as a responder configuration.
+
+:::{note}
+For most site-to-site VPNs, configure one peer
+with ``connection-type initiate`` (active side) and the other peer
+with ``connection-type none`` (passive side) to
+ensure stable and predictable tunnel behavior.
+When using ``connection-type initiate``, you must also configure
+DPD or another session tracking method (such as ``close-action``)
+to automatically re-establish the tunnel after a disconnection.
+Otherwise, the tunnel will not reconnect automatically if it goes down.
+:::
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> default-esp-group \<name\>
+
+Name of ESP group to use by default for traffic encryption.
+Might be overwritten by individual settings for tunnel or VTI
+interface binding.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> description \<description\>
+
+Description for this peer.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> dhcp-interface \<interface\>
+
+Specify the interface which IP address, received from DHCP for IPSec
+connection with this peer, will be used as ``local-address``.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> force-udp-encapsulation
+
+Force encapsulation of ESP into UDP datagrams. Useful in case if
+between local and remote side is firewall or NAT, which not
+allows passing plain ESP packets between them.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> ike-group \<name\>
+
+Name of IKE group to use for key exchanges.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> local-address \<address\>
+
+Local IP address for IPsec connection with this peer.
+If defined ``any``, then an IP address which configured on interface with
+default route will be used.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> remote-address \<address\>
+
+Remote IP address or hostname for IPsec connection. IPv4 or IPv6
+address is used when a peer has a public static IP address. Hostname
+is a DNS name which could be used when a peer has a public IP
+address and DNS name, but an IP address could be changed from time
+to time.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> replay-window \<size\>
+
+IPsec replay window to configure for CHILD_SAs
+(default: 32), a value of 0 disables IPsec replay protection.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> virtual-address \<address\>
+
+Defines a virtual IP address which is requested by the initiator and
+one or several IPv4 and/or IPv6 addresses are assigned from multiple
+pools by the responder. The wildcard addresses 0.0.0.0 and ::
+request an arbitrary address, specific addresses may be defined.
+```
+
+##### CHILD SAs Configuration Commands
+
+###### Policy-Based CHILD SAs Configuration Commands
+
+Every configured tunnel under peer configuration is a new CHILD SA.
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> disable
+
+Disable this tunnel.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> esp-group \<name\>
+
+Specify ESP group for this CHILD SA.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> priority \<number\>
+
+Priority for policy-based IPsec VPN tunnels (lowest value more
+preferable).
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> protocol \<name\>
+
+Define the protocol for match traffic, which should be encrypted and
+send to this peer.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> local prefix \<network\>
+
+IP network at the local side.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> local port \<number\>
+
+Local port number. Have effect only when used together with
+``prefix``.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> remote prefix \<network\>
+
+IP network at the remote side.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> remote port \<number\>
+
+Remote port number. Have effect only when used together with
+``prefix``.
+```
+
+###### Route-Based CHILD SAs Configuration Commands
+
+To configure route-based VPN it is enough to create vti interface and
+bind it to the peer. Any traffic, which will be send to VTI interface
+will be encrypted and send to this peer. Using VTI makes IPsec
+configuration much flexible and easier in complex situation, and
+allows to dynamically add/delete remote networks, reachable via a
+peer, as in this mode router don't need to create additional SA/policy
+for each remote network.
+
+:::{warning}
+When using site-to-site IPsec with VTI interfaces,
+be sure to disable route autoinstall.
+:::
+```none
+set vpn ipsec options disable-route-autoinstall
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> vti bind \<interface\>
+
+VTI interface to bind to this peer.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> vti esp-group \<name\>
+
+ESP group for encrypt traffic, passed this VTI interface.
+```
+
+Traffic-selectors parameters for traffic that should pass via vti
+interface.
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> vti traffic-selector local prefix \<network\>
+
+Local prefix for interesting traffic.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> vti traffic-selector remote prefix \<network\>
+
+Remote prefix for interesting traffic.
+```
+
+### IPsec Op-mode Commands
+
+```{opcmd} show vpn ike sa
+
+Shows active IKE SAs information.
+```
+
+```{opcmd} show vpn ike secrets
+
+Shows configured authentication keys.
+```
+
+```{opcmd} show vpn ike status
+
+Shows Strongswan daemon status.
+```
+
+```{opcmd} show vpn ipsec connections
+
+Shows summary status of all configured IKE and IPsec SAs.
+```
+
+```{opcmd} show vpn ipsec sa [detail]
+
+Shows active IPsec SAs information.
+```
+
+```{opcmd} show vpn ipsec status
+
+Shows status of IPsec process.
+```
+
+```{opcmd} show vpn ipsec policy
+
+Shows the in-kernel crypto policies.
+```
+
+```{opcmd} show vpn ipsec state
+
+Shows the in-kernel crypto state.
+```
+
+```{opcmd} show log ipsec
+
+Shows IPsec logs.
+```
+
+```{opcmd} reset vpn ipsec site-to-site all
+
+Clear all ipsec connection and reinitiate them if VyOS is configured
+as initiator.
+```
+
+```{opcmd} reset vpn ipsec site-to-site peer \<name\>
+
+Clear all peer IKE SAs with IPsec SAs and reinitiate them if VyOS is
+configured as initiator.
+```
+
+```{opcmd} reset vpn ipsec site-to-site peer \<name\> tunnel \<number\>
+
+Clear scpecific IPsec SA and reinitiate it if VyOS is configured as
+initiator.
+```
+
+```{opcmd} reset vpn ipsec site-to-site peer \<name\> vti \<number\>
+
+Clear IPsec SA which is map to vti interface of this peer and
+reinitiate it if VyOS is configured as initiator.
+```
+
+```{opcmd} restart ipsec
+
+Restart Strongswan daemon.
+```
+
+## Examples:
+
+### Policy-Based VPN Example
+
+**PEER1:**
+- WAN interface on `eth0`
+- `eth0` interface IP: `10.0.1.2/30`
+- `dum0` interface IP: `192.168.0.1/24` (for testing purposes)
+- Initiator
+
+**PEER2:**
+- WAN interface on `eth0`
+- `eth0` interface IP: `10.0.2.2/30`
+- `dum0` interface IP: `192.168.1.0/24` (for testing purposes)
+- Responder
+
+```none
+# PEER1
+set interfaces dummy dum0 address '192.168.0.1/32'
+set interfaces ethernet eth0 address '10.0.1.2/30'
+set protocols static route 0.0.0.0/0 next-hop 10.0.1.1
+set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2'
+set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2'
+set vpn ipsec authentication psk AUTH-PSK secret 'test'
+set vpn ipsec esp-group ESP-GRPOUP lifetime '3600'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1'
+set vpn ipsec ike-group IKE-GROUP close-action 'start'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '120'
+set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1'
+set vpn ipsec ike-group IKE-GROUP lifetime '28800'
+set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14'
+set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256'
+set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1'
+set vpn ipsec interface 'eth0'
+set vpn ipsec site-to-site peer PEER2 authentication local-id '10.0.1.2'
+set vpn ipsec site-to-site peer PEER2 authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer PEER2 authentication remote-id '10.0.2.2'
+set vpn ipsec site-to-site peer PEER2 connection-type 'initiate'
+set vpn ipsec site-to-site peer PEER2 default-esp-group 'ESP-GRPOUP'
+set vpn ipsec site-to-site peer PEER2 ike-group 'IKE-GROUP'
+set vpn ipsec site-to-site peer PEER2 local-address '10.0.1.2'
+set vpn ipsec site-to-site peer PEER2 remote-address '10.0.2.2'
+set vpn ipsec site-to-site peer PEER2 tunnel 0 local prefix '192.168.0.0/24'
+set vpn ipsec site-to-site peer PEER2 tunnel 0 remote prefix '192.168.1.0/24'
+
+
+# PEER2
+set interfaces dummy dum0 address '192.168.1.1/32'
+set interfaces ethernet eth0 address '10.0.2.2/30'
+set protocols static route 0.0.0.0/0 next-hop 10.0.2.1
+set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2'
+set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2'
+set vpn ipsec authentication psk AUTH-PSK secret 'test'
+set vpn ipsec esp-group ESP-GRPOUP lifetime '3600'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1'
+set vpn ipsec ike-group IKE-GROUP close-action 'none'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'clear'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '120'
+set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1'
+set vpn ipsec ike-group IKE-GROUP lifetime '28800'
+set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14'
+set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256'
+set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1'
+set vpn ipsec interface 'eth0'
+set vpn ipsec site-to-site peer PEER1 authentication local-id '10.0.2.2'
+set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer PEER1 authentication remote-id '10.0.1.2'
+set vpn ipsec site-to-site peer PEER1 connection-type 'none'
+set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP-GRPOUP'
+set vpn ipsec site-to-site peer PEER1 ike-group 'IKE-GROUP'
+set vpn ipsec site-to-site peer PEER1 local-address '10.0.2.2'
+set vpn ipsec site-to-site peer PEER1 remote-address '10.0.1.2'
+set vpn ipsec site-to-site peer PEER1 tunnel 0 local prefix '192.168.1.0/24'
+set vpn ipsec site-to-site peer PEER1 tunnel 0 remote prefix '192.168.0.0/24'
+```
+
+Show status of policy-based IPsec VPN setup:
+
+```none
+vyos@PEER2:~$ show vpn ike sa
+Peer ID / IP                            Local ID / IP
+------------                            -------------
+10.0.1.2 10.0.1.2                       10.0.2.2 10.0.2.2
+
+    State  IKEVer  Encrypt      Hash          D-H Group      NAT-T  A-Time  L-Time
+    -----  ------  -------      ----          ---------      -----  ------  ------
+    up     IKEv1   AES_CBC_256  HMAC_SHA1_96  MODP_2048      no     1254    25633
+
+
+vyos@srv-gw0:~$ show vpn ipsec sa
+Connection      State    Uptime    Bytes In/Out    Packets In/Out    Remote address    Remote ID    Proposal
+--------------  -------  --------  --------------  ----------------  ----------------  -----------  ----------------------------------
+PEER1-tunnel-0  up       20m42s    0B/0B           0/0               10.0.1.2          10.0.1.2     AES_CBC_256/HMAC_SHA1_96/MODP_2048
+
+vyos@PEER2:~$ show vpn ipsec connections
+Connection      State    Type    Remote address    Local TS        Remote TS       Local id    Remote id    Proposal
+--------------  -------  ------  ----------------  --------------  --------------  ----------  -----------  ----------------------------------
+PEER1           up       IKEv1   10.0.1.2          -               -               10.0.2.2    10.0.1.2     AES_CBC/256/HMAC_SHA1_96/MODP_2048
+PEER1-tunnel-0  up       IPsec   10.0.1.2          192.168.1.0/24  192.168.0.0/24  10.0.2.2    10.0.1.2     AES_CBC/256/HMAC_SHA1_96/MODP_2048
+```
+
+If there is SNAT rules on eth0, need to add exclude rule
+
+```none
+# PEER1 side
+set nat source rule 10 destination address '192.168.1.0/24'
+set nat source rule 10 'exclude'
+set nat source rule 10 outbound-interface name 'eth0'
+set nat source rule 10 source address '192.168.0.0/24'
+
+# PEER2 side
+set nat source rule 10 destination address '192.168.0.0/24'
+set nat source rule 10 'exclude'
+set nat source rule 10 outbound-interface name 'eth0'
+set nat source rule 10 source address '192.168.1.0/24'
+```
+
+### Route-Based VPN Example
+
+**PEER1:**
+- WAN interface on `eth0`
+- `eth0` interface IP: `10.0.1.2/30`
+- 'vti0' interface IP: `10.100.100.1/30`
+- `dum0` interface IP: `192.168.0.1/24` (for testing purposes)
+- Role: Initiator
+
+**PEER2:**
+- WAN interface on `eth0`
+- `eth0` interface IP: `10.0.2.2/30`
+- 'vti0' interface IP: `10.100.100.2/30`
+- `dum0` interface IP: `192.168.1.0/24` (for testing purposes)
+- Role: Responder
+
+```none
+# PEER1
+set interfaces dummy dum0 address '192.168.0.1/32'
+set interfaces ethernet eth0 address '10.0.1.2/30'
+set interfaces vti vti0 address '10.100.100.1/30'
+set protocols static route 0.0.0.0/0 next-hop 10.0.1.1
+set protocols static route 192.168.1.0/24 next-hop 10.100.100.2
+set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2'
+set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2'
+set vpn ipsec authentication psk AUTH-PSK secret 'test'
+set vpn ipsec esp-group ESP-GRPOUP lifetime '3600'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1'
+set vpn ipsec ike-group IKE-GROUP close-action 'start'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30'
+set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2'
+set vpn ipsec ike-group IKE-GROUP lifetime  '28800'
+set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14'
+set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256'
+set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1'
+set vpn ipsec interface 'eth0'
+set vpn ipsec options disable-route-autoinstall
+set vpn ipsec site-to-site peer PEER2 authentication local-id '10.0.1.2'
+set vpn ipsec site-to-site peer PEER2 authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer PEER2 authentication remote-id '10.0.2.2'
+set vpn ipsec site-to-site peer PEER2 connection-type 'initiate'
+set vpn ipsec site-to-site peer PEER2 default-esp-group 'ESP-GRPOUP'
+set vpn ipsec site-to-site peer PEER2 ike-group 'IKE-GROUP'
+set vpn ipsec site-to-site peer PEER2 local-address '10.0.1.2'
+set vpn ipsec site-to-site peer PEER2 remote-address '10.0.2.2'
+set vpn ipsec site-to-site peer PEER2 vti bind 'vti0'
+
+
+# PEER2
+set interfaces dummy dum0 address '192.168.1.1/32'
+set interfaces ethernet eth0 address '10.0.2.2/30'
+set interfaces vti vti0 address '10.100.100.2/30'
+set protocols static route 0.0.0.0/0 next-hop 10.0.2.1
+set protocols static route 192.168.0.0/24 next-hop 10.100.100.1
+set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2'
+set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2'
+set vpn ipsec authentication psk AUTH-PSK secret 'test'
+set vpn ipsec esp-group ESP-GRPOUP lifetime '3600'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1'
+set vpn ipsec ike-group IKE-GROUP close-action 'none'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'clear'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30'
+set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2'
+set vpn ipsec ike-group IKE-GROUP lifetime '28800'
+set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14'
+set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256'
+set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1'
+set vpn ipsec interface 'eth0'
+set vpn ipsec options disable-route-autoinstall
+set vpn ipsec site-to-site peer PEER1 authentication local-id '10.0.2.2'
+set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer PEER1 authentication remote-id '10.0.1.2'
+set vpn ipsec site-to-site peer PEER1 connection-type 'none'
+set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP-GRPOUP'
+set vpn ipsec site-to-site peer PEER1 ike-group 'IKE-GROUP'
+set vpn ipsec site-to-site peer PEER1 local-address '10.0.2.2'
+set vpn ipsec site-to-site peer PEER1 remote-address '10.0.1.2'
+set vpn ipsec site-to-site peer PEER1 vti bind 'vti0'
+```
+
+Show status of route-based IPsec VPN setup:
+
+```none
+vyos@PEER2:~$ show vpn ike sa
+Peer ID / IP                            Local ID / IP
+------------                            -------------
+10.0.1.2 10.0.1.2                       10.0.2.2 10.0.2.2
+
+    State  IKEVer  Encrypt      Hash          D-H Group      NAT-T  A-Time  L-Time
+    -----  ------  -------      ----          ---------      -----  ------  ------
+    up     IKEv2   AES_CBC_256  HMAC_SHA1_96  MODP_2048      no     404     27650
+
+vyos@PEER2:~$ show vpn ipsec sa
+Connection    State    Uptime    Bytes In/Out    Packets In/Out    Remote address    Remote ID    Proposal
+------------  -------  --------  --------------  ----------------  ----------------  -----------  ----------------------------------
+PEER1-vti     up       3m28s     0B/0B           0/0               10.0.1.2          10.0.1.2     AES_CBC_256/HMAC_SHA1_96/MODP_2048
+
+vyos@PEER2:~$ show vpn ipsec connections
+Connection    State    Type    Remote address    Local TS    Remote TS    Local id    Remote id    Proposal
+------------  -------  ------  ----------------  ----------  -----------  ----------  -----------  ----------------------------------
+PEER1         up       IKEv2   10.0.1.2          -           -            10.0.2.2    10.0.1.2     AES_CBC/256/HMAC_SHA1_96/MODP_2048
+PEER1-vti     up       IPsec   10.0.1.2          0.0.0.0/0   0.0.0.0/0    10.0.2.2    10.0.1.2     AES_CBC/256/HMAC_SHA1_96/MODP_2048
+                                               ::/0        ::/0
+```
diff --git a/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md b/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md
new file mode 100644
index 00000000..2ca37bc2
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md
@@ -0,0 +1,313 @@
+(troubleshooting-ipsec)=
+
+# Troubleshooting Site-to-Site VPN IPsec
+
+```{todo}
+Convert raw command blocks in this file to cfgcmd/opcmd
+directives for command coverage tracking.
+```
+
+
+## Introduction
+
+This document describes the methodology to monitor and troubleshoot
+Site-to-Site VPN IPsec.
+
+Steps for troubleshooting problems with Site-to-Site VPN IPsec:
+: 1. Ping the remote site through the tunnel using the source and
+     destination IPs included in the policy.
+  2. Check connectivity between the routers using the ping command
+     (if ICMP traffic is allowed).
+  3. Check the IKE SAs' statuses.
+  4. Check the IPsec SAs' statuses.
+  5. Check logs to view debug messages.
+
+## Checking IKE SA Status
+
+The next command shows IKE SAs' statuses.
+
+```none
+vyos@vyos:~$ show vpn ike sa
+
+Peer ID / IP                            Local ID / IP
+------------                            -------------
+192.168.1.2 192.168.1.2                 192.168.0.1 192.168.0.1
+
+    State  IKEVer  Encrypt      Hash          D-H Group      NAT-T  A-Time  L-Time
+    -----  ------  -------      ----          ---------      -----  ------  ------
+    up     IKEv2   AES_CBC_128  HMAC_SHA1_96  MODP_2048      no     162     27023
+```
+
+This command shows the next information:
+: - IKE SA status.
+  - Selected IKE version.
+  - Selected Encryption, Hash and Diffie-Hellman Group.
+  - NAT-T.
+  - ID and IP of both peers.
+  - A-Time: established time, L-Time: time for next rekeying.
+
+## IPsec SA (CHILD SA) Status
+
+The next commands show IPsec SAs' statuses.
+
+```none
+vyos@vyos:~$ show vpn ipsec sa
+Connection     State    Uptime    Bytes In/Out    Packets In/Out    Remote address    Remote ID    Proposal
+-------------  -------  --------  --------------  ----------------  ----------------  -----------  ----------------------------------
+PEER-tunnel-1  up       16m30s    168B/168B       2/2               192.168.1.2       192.168.1.2  AES_CBC_128/HMAC_SHA1_96/MODP_2048
+```
+
+```none
+vyos@vyos:~$ show vpn ipsec sa detail
+PEER: #1, ESTABLISHED, IKEv2, 101275ac719d5a1b_i* 68ea4ec3bed3bf0c_r
+  local  '192.168.0.1' @ 192.168.0.1[4500]
+  remote '192.168.1.2' @ 192.168.1.2[4500]
+  AES_CBC-128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+  established 4054s ago, rekeying in 23131s
+  PEER-tunnel-1: #2, reqid 1, INSTALLED, TUNNEL, ESP:AES_CBC-128/HMAC_SHA1_96/MODP_2048
+    installed 1065s ago, rekeying in 1998s, expires in 2535s
+    in  c5821882,    168 bytes,     2 packets,    81s ago
+    out c433406a,    168 bytes,     2 packets,    81s ago
+    local  10.0.0.0/24
+    remote 10.0.1.0/24
+```
+
+These commands show the next information:
+: - IPsec SA status.
+  - Uptime and time for the next rekeing.
+  - Amount of transferred data.
+  - Remote and local ID and IP.
+  - Selected Encryption, Hash and Diffie-Hellman Group.
+  - Mode (tunnel or transport).
+  - Remote and local prefixes which are use for policy.
+
+There is a possibility to view the summarized information of SAs' status
+
+```none
+vyos@vyos:~$ show vpn ipsec connections
+Connection     State    Type    Remote address    Local TS     Remote TS    Local id     Remote id    Proposal
+-------------  -------  ------  ----------------  -----------  -----------  -----------  -----------  ----------------------------------
+PEER           up       IKEv2   192.168.1.2       -            -            192.168.0.1  192.168.1.2  AES_CBC/128/HMAC_SHA1_96/MODP_2048
+PEER-tunnel-1  up       IPsec   192.168.1.2       10.0.0.0/24  10.0.1.0/24  192.168.0.1  192.168.1.2  AES_CBC/128/HMAC_SHA1_96/MODP_2048
+```
+
+
+## Viewing Logs for Debugging
+
+If IKE SAs or IPsec SAs are down, need to debug IPsec connectivity
+using logs `show log ipsec`
+
+The next example of the successful IPsec connection initialization.
+
+```none
+vyos@vyos:~$ show log ipsec
+Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes)
+Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ]
+Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes)
+Jun 20 14:29:47 charon[2428]: 02[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ]
+Jun 20 14:29:47 charon-systemd[2428]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key
+Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.0.1' (myself) with pre-shared key
+Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1}
+Jun 20 14:29:47 charon-systemd[2428]: establishing CHILD_SA PEER-tunnel-1{1}
+Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ]
+Jun 20 14:29:47 charon-systemd[2428]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ]
+Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes)
+Jun 20 14:29:47 charon-systemd[2428]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes)
+Jun 20 14:29:47 charon[2428]: 13[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes)
+Jun 20 14:29:47 charon[2428]: 13[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ]
+Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes)
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful
+Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ]
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> peer supports MOBIKE
+Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.1.2' with pre-shared key successful
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2]
+Jun 20 14:29:47 charon-systemd[2428]: peer supports MOBIKE
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> scheduling rekeying in 27703s
+Jun 20 14:29:47 charon-systemd[2428]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2]
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> maximum IKE_SA lifetime 30583s
+Jun 20 14:29:47 charon-systemd[2428]: scheduling rekeying in 27703s
+Jun 20 14:29:47 charon[2428]: 13[CFG] <PEER|1> selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ
+Jun 20 14:29:47 charon-systemd[2428]: maximum IKE_SA lifetime 30583s
+Jun 20 14:29:47 charon-systemd[2428]: selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24
+Jun 20 14:29:47 charon-systemd[2428]: CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24
+```
+
+
+## Troubleshooting Examples
+
+### IKE PROPOSAL are Different
+
+In this situation, IKE SAs can be down or not active.
+
+```none
+vyos@vyos:~$ show vpn ike sa
+```
+
+The problem is in IKE phase (Phase 1). The next step is checking debug logs.
+
+Responder Side:
+
+```none
+Jun 23 07:36:33 charon[2440]: 01[CFG] <1> received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 07:36:33 charon-systemd[2440]: received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 07:36:33 charon[2440]: 01[CFG] <1> configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 07:36:33 charon-systemd[2440]: configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 07:36:33 charon[2440]: 01[IKE] <1> received proposals unacceptable
+Jun 23 07:36:33 charon-systemd[2440]: received proposals unacceptable
+Jun 23 07:36:33 charon[2440]: 01[ENC] <1> generating IKE_SA_INIT response 0 [ N(NO_PROP) ]
+```
+
+Initiator side:
+
+```none
+Jun 23 07:36:32 charon-systemd[2444]: parsed IKE_SA_INIT response 0 [ N(NO_PROP) ]
+Jun 23 07:36:32 charon[2444]: 14[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify error
+Jun 23 07:36:32 charon-systemd[2444]: received NO_PROPOSAL_CHOSEN notify error
+```
+
+The notification **NO_PROPOSAL_CHOSEN** means that the proposal mismatch.
+On the Responder side there is concrete information where is mismatch.
+Encryption **AES_CBC_128** is configured in IKE policy on the responder
+but **AES_CBC_256** is configured on the initiator side.
+
+### PSK Secret Mismatch
+
+In this situation, IKE SAs can be down or not active.
+
+```none
+vyos@vyos:~$ show vpn ike sa
+```
+
+The problem is in IKE phase (Phase 1). The next step is checking debug logs.
+
+Responder:
+
+```none
+Jun 23 08:07:26 charon-systemd[2440]: tried 1 shared key for '192.168.1.2' - '192.168.0.1', but MAC mismatched
+Jun 23 08:07:26 charon[2440]: 13[ENC] <PEER|3> generating IKE_AUTH response 1 [ N(AUTH_FAILED) ]
+```
+
+Initiator side:
+
+```none
+Jun 23 08:07:24 charon[2436]: 12[ENC] <PEER|1> parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ]
+Jun 23 08:07:24 charon-systemd[2436]: parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ]
+Jun 23 08:07:24 charon[2436]: 12[IKE] <PEER|1> received AUTHENTICATION_FAILED notify error
+Jun 23 08:07:24 charon-systemd[2436]: received AUTHENTICATION_FAILED notify error
+```
+
+The notification **AUTHENTICATION_FAILED** means that the authentication
+is failed. There is a reason to check PSK on both side.
+
+### ESP Proposal Mismatch
+
+The output of **show** commands shows us that IKE SA is established but
+IPSec SA is not.
+
+```none
+vyos@vyos:~$ show vpn ike sa
+Peer ID / IP                            Local ID / IP
+------------                            -------------
+192.168.1.2 192.168.1.2                 192.168.0.1 192.168.0.1
+
+    State  IKEVer  Encrypt      Hash          D-H Group      NAT-T  A-Time  L-Time
+    -----  ------  -------      ----          ---------      -----  ------  ------
+    up     IKEv2   AES_CBC_128  HMAC_SHA1_96  MODP_2048      no     158     26817
+```
+
+```none
+vyos@vyos:~$ show vpn ipsec sa
+Connection    State    Uptime    Bytes In/Out    Packets In/Out    Remote address    Remote ID    Proposal
+------------  -------  --------  --------------  ----------------  ----------------  -----------  ----------
+```
+
+The next step is checking debug logs.
+
+Initiator side:
+
+```none
+Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes)
+Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ]
+Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes)
+Jun 23 08:16:10 charon[3789]: 13[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ]
+Jun 23 08:16:10 charon-systemd[3789]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key
+Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.0.1' (myself) with pre-shared key
+Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1}
+Jun 23 08:16:10 charon-systemd[3789]: establishing CHILD_SA PEER-tunnel-1{1}
+Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ]
+Jun 23 08:16:10 charon-systemd[3789]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ]
+Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes)
+Jun 23 08:16:10 charon-systemd[3789]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes)
+Jun 23 08:16:10 charon[3789]: 09[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes)
+Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes)
+Jun 23 08:16:10 charon[3789]: 09[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ]
+Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ]
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful
+Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.1.2' with pre-shared key successful
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> peer supports MOBIKE
+Jun 23 08:16:10 charon-systemd[3789]: peer supports MOBIKE
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2]
+Jun 23 08:16:10 charon-systemd[3789]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2]
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> scheduling rekeying in 26975s
+Jun 23 08:16:10 charon-systemd[3789]: scheduling rekeying in 26975s
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> maximum IKE_SA lifetime 29855s
+Jun 23 08:16:10 charon-systemd[3789]: maximum IKE_SA lifetime 29855s
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built
+Jun 23 08:16:10 charon-systemd[3789]: received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA
+Jun 23 08:16:10 charon-systemd[3789]: failed to establish CHILD_SA, keeping IKE_SA
+```
+
+There are messages: **NO_PROPOSAL_CHOSEN** and
+**failed to establish CHILD_SA** which refers that the problem is in
+the IPsec(ESP) proposal mismatch.
+
+The reason of this problem is showed on the responder side.
+
+```none
+Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ
+Jun 23 08:16:12 charon-systemd[2440]: received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ
+Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ
+Jun 23 08:16:12 charon-systemd[2440]: configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ
+Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> no acceptable proposal found
+Jun 23 08:16:12 charon-systemd[2440]: no acceptable proposal found
+Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> failed to establish CHILD_SA, keeping IKE_SA
+```
+
+Encryption **AES_CBC_128** is configured in IKE policy on the responder but **AES_CBC_256**
+is configured on the initiator side.
+
+### Prefixes in Policies Mismatch
+
+As in previous situation, IKE SA is in up state but IPsec SA is not up.
+According to logs we can see **TS_UNACCEPTABLE** notification. It means
+that prefixes (traffic selectors) mismatch on both sides
+
+Initiator:
+
+```none
+Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> received TS_UNACCEPTABLE notify, no CHILD_SA built
+Jun 23 14:13:17 charon-systemd[4996]: maximum IKE_SA lifetime 29437s
+Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA
+Jun 23 14:13:17 charon-systemd[4996]: received TS_UNACCEPTABLE notify, no CHILD_SA built
+Jun 23 14:13:17 charon-systemd[4996]: failed to establish CHILD_SA, keeping IKE_SA
+```
+
+The reason of this problem is showed on the responder side.
+
+```none
+Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable
+Jun 23 14:13:19 charon-systemd[2440]: traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable
+Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> failed to establish CHILD_SA, keeping IKE_SA
+Jun 23 14:13:19 charon-systemd[2440]: failed to establish CHILD_SA, keeping IKE_SA
+Jun 23 14:13:19 charon[2440]: 01[ENC] <PEER|7> generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ]
+Jun 23 14:13:19 charon-systemd[2440]: generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ]
+```
+
+Traffic selectors **10.0.2.0/24 === 10.0.0.0/24** are unacceptable on the
+responder side.