docs(vpn): update README.vpn.md for easy-rsa 3.2 and openvpn3

.llm-wiki/wiki/sources/obs-2026-08-18-openvpn3-is-the-documented-cape-vpn-client-not-openvpn-2-x.md

@@ -0,0 +1,27 @@
+---
+type: source
+title: "Observation: openvpn3 is the documented CAPE VPN client, not openvpn 2.x"
+tags:
+  - vpn
+  - docs
+  - openvpn3
+  - easyrsa
+status: observation
+created: 2026-08-18
+updated: 2026-08-18
+slug: obs-2026-08-18-openvpn3-is-the-documented-cape-vpn-client-not-openvpn-2-x
+relevance: medium
+observed_at: 2026-08-18T17:35:02.076Z
+source_context: Updating README.vpn.md for easy-rsa 3.2 and openvpn3
+---
+
+# 🔍 Observation: openvpn3 is the documented CAPE VPN client, not openvpn 2.x
+
+The openvpn 2.x CLI path in extra-doc/README.vpn.md has not been tested in a long time (per repo maintainer). PR #378 (branch 377-docsvpn-update-readme-vpn-for-easyrsa-32-and-openvpn3, issue #377) makes openvpn3 the documented VPN client throughout the README and reduces openvpn 2.x to a passing "may work but not covered" mention. Connect flow is now openvpn3 config-import / session-start / sessions-list / session-manage --disconnect. Do not re-add the openvpn 2.x `openvpn --config` instructions as a primary path.
+
+*Relevance: medium*
+*Context: Updating README.vpn.md for easy-rsa 3.2 and openvpn3*
+*Tags: vpn docs openvpn3 easyrsa*
+
+---
+*Observed: 2026-08-18T17:35:02.076Z*

.llm-wiki/wiki/sources/vpn-add-demo-client-cert-openvpn3.md

@@ -0,0 +1,45 @@
+---
+type: source
+title: Adding a demo VPN client cert with easyrsa + openvpn3
+status: insight
+category: devops
+created: 2026-08-18
+updated: 2026-08-18
+slug: vpn-add-demo-client-cert-openvpn3
+---
+
+# Adding a demo VPN client cert with easyrsa + openvpn3
+
+Procedure for adding a throwaway client cert/key pair to the CAPE private-swimlane VPN without touching the server pair, CA, or existing client entries. Complements [[extra-doc/README.vpn.md]] which documents the `openvpn` CLI; this system only has `openvpn3`.
+
+## Environment
+- easyrsa env: `/home/lp76/easyrsa-envs/cape-cod` (run easyrsa from inside it so it uses `./pki`).
+- Installed easyrsa is `3.2.5` (README was tested against `3.2.0`). Signing a new client against the existing CA is unaffected.
+- CA is `CN=cape-cod.dev`; server is `CN=server`. Existing client pairs: `cape-dev.org`, `*.cape-dev.org`, `true.cape-dev.org`.
+- Both openvpn3 configs `cape-vpn` and `cape-split` authenticate with client `CN=cape-dev.org`. `cape-vpn` is the plain endpoint profile; `cape-split` is the split-DNS variant.
+
+## Build a new client pair
+- `easyrsa build-client-full <name> nopass` prompts for interactive `yes` confirmation and aborts (rolling back the req/key) if not answered. Use `easyrsa --batch build-client-full <name> nopass` to sign non-interactively.
+- Dots in the CN are fine (existing certs use them). Example name used: `demo-2026.08`, cert valid 825 days.
+- New files land beside the others: `pki/issued/<name>.crt`, `pki/private/<name>.key`, `pki/reqs/<name>.req`, plus one appended row in `pki/index.txt`. 3.2.5 writes these `0600` vs the older `0644`.
+
+## Build the .ovpn on an openvpn3-only host
+- Reuse the trusted endpoint profile instead of a fresh AWS console download: `openvpn3 config-dump --config cape-vpn > base.ovpn`, then swap only the `<cert>` and `<key>` blocks for the new pair, leaving `<ca>` and the `remote ...:443` line identical. Do NOT use `cape-split` as the base unless split-DNS is wanted.
+- Extract a clean cert PEM with `openssl x509 -in issued/<name>.crt` (strips easyrsa's extra text); the `nopass` key file is already a clean `BEGIN PRIVATE KEY` block.
+- Verify the key belongs to the cert by comparing `openssl pkey -pubout | openssl dgst -sha256` against `openssl x509 -noout -pubkey | openssl dgst -sha256`. Note MD5 is disabled on this OpenSSL 3.5 build, so an MD5 modulus check silently returns empty strings that falsely "match" - use sha256.
+- Keep profiles in `~/.openvpn3cfg/cape/`, named for the client pair. Remove any temp copies of key material from `/tmp` afterward.
+
+## Import / connect / revoke
+- Import under a distinct name so it doesn't collide: `openvpn3 config-import --config <file> --name cape-vpn-demo --persistent`.
+- Connect: `openvpn3 session-start --config cape-vpn-demo`; disconnect: `openvpn3 session-manage --config cape-vpn-demo --disconnect`.
+- A new cert authenticates immediately because it shares the CA the endpoint trusts and has no CRL entry. Endpoint-side authorization is a separate concern from cert validity.
+- Revoke when done: `easyrsa revoke <name>` then `easyrsa gen-crl`, then import the CRL `.pem` at the VPC Client VPN endpoint (Actions -> Import client certificate CRL). Keeping the openvpn3 config around lets you retest that revocation actually blocks the client.
+
+*Category: devops*
+
+---
+*Captured: 2026-08-18*
+
+## Related
+
+_Add links to related pages._

extra-doc/README.vpn.md

@@ -46,8 +46,9 @@ to see if there are changes not captured here.
 We use [easyrsa](https://github.com/OpenVPN/easy-rsa) (from `OpenVPN`) to
 generate the self-signed files. This can be done by other means (e.g. using
 `openssl` directly) if desired. We assume that `easyrsa` is already installed
-and on the system path. adjust for your setup as needed. We tested against
-`easyrsa` version `3.2.0`.
+and on the system path. adjust for your setup as needed. This procedure was
+originally written against `easyrsa` version `3.2.0` and has also been verified
+against `3.2.5`.
 
 **_NOTE:_** This procedure only has to be done once so long as the certs/keys do
 not expire and are not compromised. The cert rotation procedure is not covered
@@ -87,6 +88,15 @@ easyrsa --san=DNS:server build-server-full server nopass
 easyrsa build-client-full client1.domain.tld nopass
 ```
 
+On `easyrsa` `3.2.x`, `build-client-full` prints the certificate details and
+prompts for a `yes` confirmation before signing. If the prompt is not answered,
+it aborts and rolls back the generated request and key. To sign without the
+interactive prompt (for example in a script), use batch mode instead:
+
+```bash
+easyrsa --batch build-client-full client1.domain.tld nopass
+```
+
 - at this point, all files needed for the deployment and the vpn connection
   exist (as long as only one client cert/key pair is desired).
 
@@ -135,9 +145,9 @@ block).
 
 ## Set Up Connection to VPN
 
-At this time, all testing of connection to the VPN has been performed with
-`OpenVPN 2.4.12` (with `OpenSSL 1.1.1k`) via the command line. Other clients may
-work, but are not covered here.
+Connection to the VPN has been tested with `openvpn3` via the command line.
+Other clients (such as the older `openvpn` 2.x CLI) may work, but are not
+covered here.
 
 This section assumes a deployed `CAPE` instance and permissions to access the
 required resource consoles. If you do not have the required permissions to
@@ -204,15 +214,30 @@ added in a similar manner as follows:
 
 Once updated, save this file to a known location.
 
+If you already have a complete `ovpn` profile for the current endpoint (for
+example when adding an additional client while the endpoint is unchanged), you
+can skip the console download and instead copy that profile, replacing only the
+`<cert>` and `<key>` blocks with the new client's cert and key. The `<ca>` block
+and `remote` line stay the same.
+
 ### Connect to VPN
 
-Assuming the `ovpn` config file is in the current directory, with the name
-`aws-cvpn-endpoint.ovpn` and `openvpn` is on the system path, you can now
-connect to the VPN with:
+Assuming the `ovpn` config file is in the current directory with the name
+`aws-cvpn-endpoint.ovpn` and `openvpn3` is on the system path, import the
+profile once and then start a session from the imported config:
 
 ```bash
-# NOTE: depending on your setup, `sudo` may be required here
-openvpn --config aws-cvpn-endpoint.ovpn
+# import the profile under a name of your choosing
+openvpn3 config-import --config aws-cvpn-endpoint.ovpn --name cape-vpn --persistent
+
+# start the connection
+openvpn3 session-start --config cape-vpn
+
+# check active sessions
+openvpn3 sessions-list
+
+# disconnect when done
+openvpn3 session-manage --config cape-vpn --disconnect
 ```
 
 ## Routes
@@ -234,6 +259,13 @@ to that client. Be sure to replace `$CLIENT_NAME` with the actual client name
     easyrsa build-client-full $CLIENT_NAME nopass
     ```
 
+    On `easyrsa` `3.2.x` this prompts for a `yes` confirmation before signing.
+    To sign without the interactive prompt, use batch mode:
+
+    ```bash
+    easyrsa --batch build-client-full $CLIENT_NAME nopass
+    ```
+
 2. Use the generated files to create an OpenVPN configuration as described above
    and use to connect to the VPN as described above
 3. Revoke the client and generate the CRL using: