From 70babf15c86b3b0f5a0fdfa84840dec16ba51184 Mon Sep 17 00:00:00 2001
From: Kenneth Bingham <kenneth.bingham@netfoundry.io>
Date: Mon, 16 Dec 2024 14:00:32 -0500
Subject: [PATCH 01/10] fix default mountpoint in Docker share examples

---
 CHANGELOG.md                       |  4 ++++
 docs/guides/docker-share/index.mdx | 14 +++++++-------
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2dd8ff2f..0320d0dd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## v0.4.46
+
+FIX: Docker share examples had incorrect default path for zrok environment mountpoint
+
 ## v0.4.45
 
 FEATURE: Minimal support for "organizations". Site admin API endpoints provided to create, list, and delete "organizations". Site admin API endpoints provided to add, list, and remove "organization members" (zrok accounts) with the ability to mark accounts as a "organization admin". API endpoints provided for organization admins to list the members of their organizations, and to also see the overview (environments, shares, and accesses) for any account in their organization. API endpoint for end users to see which organizations their account is a member of (https://github.com/openziti/zrok/issues/537) 
diff --git a/docs/guides/docker-share/index.mdx b/docs/guides/docker-share/index.mdx
index a8da4037..31d0e7e6 100644
--- a/docs/guides/docker-share/index.mdx
+++ b/docs/guides/docker-share/index.mdx
@@ -26,7 +26,7 @@ Let's say you have a `compose.yml` file that defines a web app known within the
         restart: unless-stopped
         user: "${UID}"
         volumes:
-          - ${HOME}/.zrok:/.zrok
+          - ${HOME}/.zrok:/home/ziggy/.zrok
         environment:
           PFXLOG_NO_JSON: "true"
         command: share reserved "myapp" --headless
@@ -42,8 +42,8 @@ Let's say you have a web server running on the host's private network at `https:
 docker run \
     --rm \
     --network=host \
-    --volume ~/.zrok:/.zrok \
-    --user "${UID}" \
+    --volume ~/.zrok:/home/ziggy/.zrok \
+    --user "${UID:-1000}:${GID:-1000}" \
     openziti/zrok share public \
         --headless \
         https://10.11.12.13:8080
@@ -89,8 +89,8 @@ docker.exe run ^
 docker run \
     --rm \
     --network "host" \
-    --volume "/mnt/c/Users/$(powershell.exe -Command 'Write-Output $env:USERNAME' | tr -d '\r')/.zrok:/.zrok" \
-    --user "$UID" \
+    --volume "/mnt/c/Users/$(powershell.exe -Command 'Write-Output $env:USERNAME' | tr -d '\r')/.zrok:/home/ziggy/.zrok" \
+    --user "${UID:-1000}:${GID:-1000}" \
     openziti/zrok share public \
         --headless \
         https://10.11.12.13:8080
@@ -104,8 +104,8 @@ Let's break down those options and arguments.
 
 1. `--rm` don't save this container because it's providing a temporary public share that's destroyed when the container stops
 1. `--network=host` shares the host's network with the container so that the container can reach the web server directly. This is always necessary when the web server is listening only on the host's loopback interface, e.g., `https://::1:8080`, and may not be strictly necessary if the target is routeable from the default Docker bridge.
-1. `--volume ~/.zrok:/.zrok` mounts the `zrok` configuration from the Docker host into the container.
-1. `--user "${UID}:${GID}"` sets the container's user to the current user on the Docker host to avoid permission issues with reading the mounted `zrok` configuration.
+1. `--volume ~/.zrok:/home/ziggy/.zrok` mounts the `zrok` configuration from the Docker host into the container.
+1. `--user "${UID:-1000}:${GID:-1000}"` sets the container's user to the current user on the Docker host to avoid permission issues with reading the mounted `zrok` configuration (defaults to `1000:1000`).
 1. `openziti/zrok` is the `zrok` Docker image.
 1. `share public` is the `zrok` command to share the target publicly until zrok exits.
 1. `--headless` runs the `zrok` command without the interactive terminal UI.

From c3523e34fb4b6a17963427df629556df3d8fe01d Mon Sep 17 00:00:00 2001
From: Kenneth Bingham <kenneth.bingham@netfoundry.io>
Date: Wed, 13 Nov 2024 16:18:10 -0500
Subject: [PATCH 02/10] use 80/tcp instead of 1280/tcp to increase
 compatibility with restrictive egress firewalls

---
 CHANGELOG.md                                  |  2 ++
 docker/compose/zrok-instance/Caddyfile        |  8 ++++----
 docker/compose/zrok-instance/README.md        | 20 +++++++++++++------
 .../compose/zrok-instance/compose.caddy.yml   |  4 ++--
 docker/compose/zrok-instance/compose.yml      | 10 +++++-----
 5 files changed, 27 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0320d0dd..1fc3f373 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,8 @@ FIX: Docker reserved private share startup error (https://github.com/openziti/zr
 FIX: Correct the download URL for the armv7 Linux release (https://github.com/openziti/zrok/issues/782)
 
 
+CHANGE: Let the zrok instance for Docker use port 80 as an edge listener instead of HTTP redirect (https://github.com/openziti/zrok/issues/793)
+
 ## v0.4.44
 
 FIX: Fix for goreleaser build action to align with changed ARM64 build path.
diff --git a/docker/compose/zrok-instance/Caddyfile b/docker/compose/zrok-instance/Caddyfile
index 0e9a913f..6c6cc43e 100644
--- a/docker/compose/zrok-instance/Caddyfile
+++ b/docker/compose/zrok-instance/Caddyfile
@@ -4,9 +4,9 @@
 	admin 0.0.0.0:2019
 }
 
-http:// {
-	redir https://{host}{uri} permanent
-}
+# http:// {
+# 	redir https://{host}{uri} permanent
+# }
 
 *.{$ZROK_DNS_ZONE} {
 	tls {
@@ -22,7 +22,7 @@ http:// {
 
 	# ziti administration console uses :443 for the benefit of a web UI cert and accesses the ziti edge-management API
 	@ziti host ziti.{$ZROK_DNS_ZONE}
-	reverse_proxy @ziti ziti-quickstart:{$ZITI_CTRL_ADVERTISED_PORT:1280} {
+	reverse_proxy @ziti ziti-quickstart:{$ZITI_CTRL_ADVERTISED_PORT:80} {
 		transport http {
 			tls_insecure_skip_verify
 		}
diff --git a/docker/compose/zrok-instance/README.md b/docker/compose/zrok-instance/README.md
index 8975e2be..f42a6d58 100644
--- a/docker/compose/zrok-instance/README.md
+++ b/docker/compose/zrok-instance/README.md
@@ -79,7 +79,7 @@ ZROK_FRONTEND_PORT=8080
 ZROK_OAUTH_PORT=8081
 
 # ziti ports must be published to the internet and allowed by firewall
-ZITI_CTRL_ADVERTISED_PORT=1280
+ZITI_CTRL_ADVERTISED_PORT=80
 ZITI_ROUTER_PORT=3022
 
 # configure oauth for public shares
@@ -157,14 +157,13 @@ The `ziti-quickstart` and `caddy` containers publish ports to all devices that u
 #### Required
 
 1. `443/tcp` - reverse proxy handles HTTPS requests for zrok API, OAuth, and public shares (published by container `caddy`)
-1. `1280/tcp` - ziti ctrl plane (published by container `ziti-quickstart`)
+1. `80/tcp` - ziti ctrl plane (published by container `ziti-quickstart`)
 1. `3022/tcp` - ziti data plane (published by container `ziti-quickstart`)
 
-#### Optional
-
-1. `80/tcp` - reverse proxy redirects non-HTTPS requests to `443/tcp` (published by container `caddy`)
 <!-- 1. 443/udp used by Caddy for HTTP/3 QUIC protocol (published by container `caddy`) -->
 
+See "My internet connection can only send traffic to common ports" below about changing the required ports.
+
 ### Troubleshooting
 
 1. Check the ziti and zrok logs.
@@ -222,7 +221,7 @@ The `ziti-quickstart` and `caddy` containers publish ports to all devices that u
     docker compose exec caddy curl http://localhost:2019/config/ | jq
     ```
 
-1. My provider, e.g., Route53 doesn't give me a single API token.
+1. My DNS provider credential is composed of several values, not a single API token.
 
     As long as your DNS provider is supported by Caddy then it will work. You can modify the Caddyfile to use a different set of properties than the example. Here's how the `tls` section should look for Route53. You must declare any environment variables introduced in the `.env` file in `docker.compose.override` on the `caddy` service to ensure they are passed through to the Caddy container.
 
@@ -240,3 +239,12 @@ The `ziti-quickstart` and `caddy` containers publish ports to all devices that u
     AWS_ACCESS_KEY_ID=abcd1234
     AWS_SECRET_ACCESS_KEY=abcd1234
     ```
+
+1. My internet connection can only send traffic to common ports like 80, 443, and 3389.
+
+    You can change the required ports in the `.env` file. Caddy will still use port 443 for zrok shares and API if you renamed `compose.caddy.yml` as `compose.override.yml` to enable Caddy.
+
+    ```bash title=".env"
+    ZITI_CTRL_ADVERTISED_PORT=80
+    ZITI_ROUTER_PORT=3389
+    ```
diff --git a/docker/compose/zrok-instance/compose.caddy.yml b/docker/compose/zrok-instance/compose.caddy.yml
index 9423485a..8a0531a5 100644
--- a/docker/compose/zrok-instance/compose.caddy.yml
+++ b/docker/compose/zrok-instance/compose.caddy.yml
@@ -17,12 +17,12 @@ services:
       ZROK_FRONTEND_PORT: ${ZROK_FRONTEND_PORT:-8080}
       ZROK_OAUTH_PORT: ${ZROK_OAUTH_PORT:-8081}
     expose:
-      - 80/tcp
+      # - 80/tcp
       - 443/tcp
       - 443/udp   # Caddy's HTTP/3 (QUIC) (not published)
       - 2019/tcp  # Caddy's admin API     (not published)
     ports:
-      - ${CADDY_INTERFACE:-0.0.0.0}:80:80
+      # - ${CADDY_INTERFACE:-0.0.0.0}:80:80
       - ${CADDY_INTERFACE:-0.0.0.0}:443:443
       # - ${CADDY_INTERFACE:-0.0.0.0}:443:443/udp"  # future: HTTP/3 (QUIC)
     volumes:
diff --git a/docker/compose/zrok-instance/compose.yml b/docker/compose/zrok-instance/compose.yml
index 251b60ac..80b9b143 100644
--- a/docker/compose/zrok-instance/compose.yml
+++ b/docker/compose/zrok-instance/compose.yml
@@ -14,7 +14,7 @@ services:
       - -euc
       - |
         ZITI_CMD+=" --ctrl-address ziti.${ZROK_DNS_ZONE}"\
-        " --ctrl-port ${ZITI_CTRL_ADVERTISED_PORT:-1280}"\
+        " --ctrl-port ${ZITI_CTRL_ADVERTISED_PORT:-80}"\
         " --router-address ziti.${ZROK_DNS_ZONE}"\
         " --router-port ${ZITI_ROUTER_PORT:-3022}"\
         " --password ${ZITI_PWD:-admin}"
@@ -31,10 +31,10 @@ services:
       # directory, ZITI_HOME 
       - ${ZITI_HOME:-ziti_home}:/home/ziggy
     ports:
-      - ${ZITI_INTERFACE:-0.0.0.0}:${ZITI_CTRL_ADVERTISED_PORT:-1280}:${ZITI_CTRL_ADVERTISED_PORT:-1280}
+      - ${ZITI_INTERFACE:-0.0.0.0}:${ZITI_CTRL_ADVERTISED_PORT:-80}:${ZITI_CTRL_ADVERTISED_PORT:-80}
       - ${ZITI_INTERFACE:-0.0.0.0}:${ZITI_ROUTER_PORT:-3022}:${ZITI_ROUTER_PORT:-3022}
     expose:
-      - ${ZITI_CTRL_ADVERTISED_PORT:-1280}
+      - ${ZITI_CTRL_ADVERTISED_PORT:-80}
       - ${ZITI_ROUTER_PORT:-3022}
     depends_on:
       ziti-quickstart-init:
@@ -94,7 +94,7 @@ services:
         ZROK_CLI_IMAGE: ${ZROK_CLI_IMAGE:-openziti/zrok}
         ZROK_CLI_TAG: ${ZROK_CLI_TAG:-latest}
         ZROK_DNS_ZONE: ${ZROK_DNS_ZONE}  # e.g., "example.com" or "127.0.0.1.sslip.io"
-        ZITI_CTRL_ADVERTISED_PORT: ${ZITI_CTRL_ADVERTISED_PORT:-1280}
+        ZITI_CTRL_ADVERTISED_PORT: ${ZITI_CTRL_ADVERTISED_PORT:-80}
         ZROK_ADMIN_TOKEN: ${ZROK_ADMIN_TOKEN} # zrok controller admin password
         ZROK_CTRL_PORT: ${ZROK_CTRL_PORT:-18080}
         ZITI_PWD: ${ZITI_PWD} # ziti controller admin password
@@ -155,7 +155,7 @@ services:
       ZROK_API_ENDPOINT: http://zrok-controller:${ZROK_CTRL_PORT:-18080} # bridge address of the zrok controller
       ZROK_FRONTEND_SCHEME: http
       ZROK_FRONTEND_PORT: ${ZROK_FRONTEND_PORT:-8080}
-      ZITI_CTRL_ADVERTISED_PORT: ${ZITI_CTRL_ADVERTISED_PORT:-1280}
+      ZITI_CTRL_ADVERTISED_PORT: ${ZITI_CTRL_ADVERTISED_PORT:-80}
       ZITI_PWD: ${ZITI_PWD} # ziti controller admin password
 
 volumes:

From fd8a203494fe53d08431c41f18417a43c44afc4d Mon Sep 17 00:00:00 2001
From: Kenneth Bingham <kenneth.bingham@netfoundry.io>
Date: Thu, 12 Dec 2024 14:46:52 -0500
Subject: [PATCH 03/10] clarify how to use a DNS provider like Route53

---
 CHANGELOG.md                                  |  9 ++--
 docker/compose/zrok-instance/README.md        | 53 ++++++++++---------
 .../compose/zrok-instance/compose.caddy.yml   | 13 +++++
 .../compose/zrok-instance/route53.Caddyfile   | 51 ++++++++++++++++++
 4 files changed, 98 insertions(+), 28 deletions(-)
 create mode 100644 docker/compose/zrok-instance/route53.Caddyfile

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1fc3f373..74ff2044 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,9 +4,13 @@
 
 FIX: Docker share examples had incorrect default path for zrok environment mountpoint
 
+CHANGE: Use port 80 for the default Ziti API endpoint in the zrok Docker instance sample (https://github.com/openziti/zrok/issues/793).
+
+FIX: Clarify how to use DNS providers like Route53 with the zrok Docker instance sample.
+
 ## v0.4.45
 
-FEATURE: Minimal support for "organizations". Site admin API endpoints provided to create, list, and delete "organizations". Site admin API endpoints provided to add, list, and remove "organization members" (zrok accounts) with the ability to mark accounts as a "organization admin". API endpoints provided for organization admins to list the members of their organizations, and to also see the overview (environments, shares, and accesses) for any account in their organization. API endpoint for end users to see which organizations their account is a member of (https://github.com/openziti/zrok/issues/537) 
+FEATURE: Minimal support for "organizations". Site admin API endpoints provided to create, list, and delete "organizations". Site admin API endpoints provided to add, list, and remove "organization members" (zrok accounts) with the ability to mark accounts as a "organization admin". API endpoints provided for organization admins to list the members of their organizations, and to also see the overview (environments, shares, and accesses) for any account in their organization. API endpoint for end users to see which organizations their account is a member of (https://github.com/openziti/zrok/issues/537)
 
 CHANGE: briefly mention the backend modes that apply to public and private share concepts
 
@@ -20,9 +24,6 @@ FIX: Docker reserved private share startup error (https://github.com/openziti/zr
 
 FIX: Correct the download URL for the armv7 Linux release (https://github.com/openziti/zrok/issues/782)
 
-
-CHANGE: Let the zrok instance for Docker use port 80 as an edge listener instead of HTTP redirect (https://github.com/openziti/zrok/issues/793)
-
 ## v0.4.44
 
 FIX: Fix for goreleaser build action to align with changed ARM64 build path.
diff --git a/docker/compose/zrok-instance/README.md b/docker/compose/zrok-instance/README.md
index f42a6d58..ba68d0d7 100644
--- a/docker/compose/zrok-instance/README.md
+++ b/docker/compose/zrok-instance/README.md
@@ -65,6 +65,10 @@ ZROK_ADMIN_TOKEN=zroktoken
 
 ```bash title=".env options"
 # Caddy TLS option: rename compose.caddy.yml to compose.override.yml and set these vars; allow 80,443 in firewall
+
+#
+## set these in .env for providers other than Route53
+#
 # plugin name for your DNS provider
 CADDY_DNS_PLUGIN=cloudflare
 # API token from your DNS provider
@@ -72,22 +76,34 @@ CADDY_DNS_PLUGIN_TOKEN=abcd1234
 # use the staging API until you're sure everything is working to avoid hitting the rate limit
 CADDY_ACME_API=https://acme-staging-v02.api.letsencrypt.org/directory
 
-# no TLS option: publish the insecure ports to the internet and allow them in the firewall 
-ZROK_INSECURE_INTERFACE=0.0.0.0
+#
+## set these in .env for Route53
+#
+# AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
+# AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
+# AWS_REGION: ${AWS_REGION}
+# AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}  # if temporary credential, e.g., from STS
+
+#
+## if not using Caddy for TLS, uncomment to publish the insecure ports to the internet
+#
+#ZROK_INSECURE_INTERFACE=0.0.0.0
+
+# these insecure ports must be proxied with TLS for security
 ZROK_CTRL_PORT=18080
 ZROK_FRONTEND_PORT=8080
 ZROK_OAUTH_PORT=8081
 
-# ziti ports must be published to the internet and allowed by firewall
+# these secure ziti ports must be published to the internet
 ZITI_CTRL_ADVERTISED_PORT=80
 ZITI_ROUTER_PORT=3022
 
-# configure oauth for public shares
-ZROK_OAUTH_HASH_KEY=oauthhashkeysecret
-ZROK_OAUTH_GITHUB_CLIENT_ID=abcd1234
-ZROK_OAUTH_GITHUB_CLIENT_SECRET=abcd1234
-ZROK_OAUTH_GOOGLE_CLIENT_ID=abcd1234
-ZROK_OAUTH_GOOGLE_CLIENT_SECRET=abcd1234
+# optionally configure oauth for public shares
+#ZROK_OAUTH_HASH_KEY=oauthhashkeysecret
+#ZROK_OAUTH_GITHUB_CLIENT_ID=abcd1234
+#ZROK_OAUTH_GITHUB_CLIENT_SECRET=abcd1234
+#ZROK_OAUTH_GOOGLE_CLIENT_ID=abcd1234
+#ZROK_OAUTH_GOOGLE_CLIENT_SECRET=abcd1234
 
 # zrok version, e.g., 1.0.0
 ZROK_CLI_TAG=latest
@@ -223,22 +239,11 @@ See "My internet connection can only send traffic to common ports" below about c
 
 1. My DNS provider credential is composed of several values, not a single API token.
 
-    As long as your DNS provider is supported by Caddy then it will work. You can modify the Caddyfile to use a different set of properties than the example. Here's how the `tls` section should look for Route53. You must declare any environment variables introduced in the `.env` file in `docker.compose.override` on the `caddy` service to ensure they are passed through to the Caddy container.
+    As long as your DNS provider is supported by Caddy then it will work. Here's a checklist for DNS providers like Route53 with credentials expressed as multiple values, e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`.
 
-    ```json
-    tls {
-      dns {$CADDY_DNS_PLUGIN} {
-        access_key_id {$AWS_ACCESS_KEY_ID}
-        secret_access_key {$AWS_SECRET_ACCESS_KEY}
-      }
-    }
-    ```
-
-    ```bash title=".env"
-    CADDY_DNS_PLUGIN=route53
-    AWS_ACCESS_KEY_ID=abcd1234
-    AWS_SECRET_ACCESS_KEY=abcd1234
-    ```
+    1. Define env vars in `.env` file.
+    1. Declare env vars in `compose.override.yml` file on `caddy`'s `environment`.
+    1. Modify `Caddyfile` according to the DNS plugin author's instructions ([link to Route53 README](https://github.com/caddy-dns/route53)). This means modifying the `Caddyfile` to reference the env vars. The provided file `route53.Caddyfile` serves as an example.
 
 1. My internet connection can only send traffic to common ports like 80, 443, and 3389.
 
diff --git a/docker/compose/zrok-instance/compose.caddy.yml b/docker/compose/zrok-instance/compose.caddy.yml
index 8a0531a5..96d912e9 100644
--- a/docker/compose/zrok-instance/compose.caddy.yml
+++ b/docker/compose/zrok-instance/compose.caddy.yml
@@ -8,8 +8,21 @@ services:
         CADDY_DNS_PLUGIN: ${CADDY_DNS_PLUGIN} # e.g., "digitalocean" (see github.com/caddy-dns)
     restart: unless-stopped
     environment:
+      #
+      ## set these in .env for providers other than Route53
+      #
       CADDY_DNS_PLUGIN: ${CADDY_DNS_PLUGIN}  # e.g., "digitalocean" (see github.com/caddy-dns)
       CADDY_DNS_PLUGIN_TOKEN: ${CADDY_DNS_PLUGIN_TOKEN}  # API token from DNS provider used by plugin to solve the ACME challenge
+
+      #
+      ## for DNS providers like Route53 with multiple credential variables, you must define in .env and declare
+      ## here before referencing them in the Caddyfile
+      #
+      # AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
+      # AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
+      # AWS_REGION: ${AWS_REGION}
+      # AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}  # if temporary credential, e.g., from STS
+
       ZROK_USER_EMAIL: ${ZROK_USER_EMAIL}  # email address sent to CA for ACME account and renewal notifications
       CADDY_ACME_API: ${CADDY_ACME_API:-https://acme-v02.api.letsencrypt.org/directory}  # ACME API endpoint
       ZROK_DNS_ZONE: ${ZROK_DNS_ZONE}  # e.g., "example.com" or "127.0.0.1.sslip.io"
diff --git a/docker/compose/zrok-instance/route53.Caddyfile b/docker/compose/zrok-instance/route53.Caddyfile
new file mode 100644
index 00000000..ab846626
--- /dev/null
+++ b/docker/compose/zrok-instance/route53.Caddyfile
@@ -0,0 +1,51 @@
+{
+	email {$ZROK_USER_EMAIL}
+	acme_ca {$CADDY_ACME_API}
+	admin 0.0.0.0:2019
+}
+
+# http:// {
+# 	redir https://{host}{uri} permanent
+# }
+
+*.{$ZROK_DNS_ZONE} {
+	tls {
+		dns route53 {
+			access_key_id {$AWS_ACCESS_KEY_ID}
+			secret_access_key {$AWS_SECRET_ACCESS_KEY}
+			session_token {$AWS_SESSION_TOKEN}
+			region {$AWS_REGION}
+			# profile {$AWS_PROFILE}
+			# max_retries 10
+			# max_wait_dur 60
+			# wait_for_propagation false
+			# hosted_zone_id {$AWS_HOSTED_ZONE_ID}
+
+		}
+		propagation_timeout 60m
+	}
+
+	log {
+		output stdout
+		format console
+		level INFO
+	}
+
+	# ziti administration console uses :443 for the benefit of a web UI cert and accesses the ziti edge-management API
+	@ziti host ziti.{$ZROK_DNS_ZONE}
+	reverse_proxy @ziti ziti-quickstart:{$ZITI_CTRL_ADVERTISED_PORT:80} {
+		transport http {
+			tls_insecure_skip_verify
+		}
+	}
+
+	@oauth host oauth.{$ZROK_DNS_ZONE}
+	reverse_proxy @oauth zrok-frontend:{$ZROK_OAUTH_PORT}
+
+	@ctrl host zrok.{$ZROK_DNS_ZONE}
+	reverse_proxy @ctrl zrok-controller:{$ZROK_CTRL_PORT}
+
+	reverse_proxy zrok-frontend:{$ZROK_FRONTEND_PORT} {
+		header_up Host {http.request.host}
+	}
+}

From c9c94e726bc3f3445e584f1cfa6a06dc23dd2d1b Mon Sep 17 00:00:00 2001
From: Kenneth Bingham <kenneth.bingham@netfoundry.io>
Date: Thu, 19 Dec 2024 10:58:17 -0500
Subject: [PATCH 04/10] fix typo

---
 docs/guides/docker-share/docker_private_share_guide.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/guides/docker-share/docker_private_share_guide.md b/docs/guides/docker-share/docker_private_share_guide.md
index e9102f4a..160ef62a 100644
--- a/docs/guides/docker-share/docker_private_share_guide.md
+++ b/docs/guides/docker-share/docker_private_share_guide.md
@@ -94,7 +94,7 @@ Now that we have a private share we can access it with the zrok command or by ru
 1. Run your Compose project to start accessing the private share:
 
     ```bash
-    docker compose up zrok-private-access
+    docker compose up zrok-access
     ```
 
 1. Now your zrok private access proxy is ready on http://127.0.0.1:9191. You can visit the demo web server in your browser.

From b44f690ab2e67cbd7efb41b25429af4599274426 Mon Sep 17 00:00:00 2001
From: Kenneth Bingham <kenneth.bingham@netfoundry.io>
Date: Thu, 2 Jan 2025 00:45:01 -0500
Subject: [PATCH 05/10] add systemd user unit instance template

---
 .goreleaser-linux-amd64.yml           |  3 ++
 .goreleaser-linux-arm64.yml           |  3 ++
 .goreleaser-linux-armel.yml           |  6 +++
 .goreleaser-linux-armhf.yml           |  3 ++
 docs/guides/frontdoor.mdx             | 20 ++++++++-
 nfpm/zrok-share.bash                  | 58 ++++++++++++---------------
 nfpm/zrok-share.env                   |  6 ++-
 nfpm/zrok-share.service               |  7 ++--
 nfpm/zrok-share.service.override.conf |  2 -
 nfpm/zrok-share@.service              | 17 ++++++++
 10 files changed, 84 insertions(+), 41 deletions(-)
 create mode 100644 nfpm/zrok-share@.service

diff --git a/.goreleaser-linux-amd64.yml b/.goreleaser-linux-amd64.yml
index aeaf8074..9c3766d0 100644
--- a/.goreleaser-linux-amd64.yml
+++ b/.goreleaser-linux-amd64.yml
@@ -109,6 +109,9 @@ nfpms:
       - dst: /lib/systemd/system/
         src: ./nfpm/zrok-share.service
 
+      - dst: /usr/lib/systemd/user/
+        src: ./nfpm/zrok-share@.service
+
       - dst: /etc/systemd/system/zrok-share.service.d/override.conf
         src: ./nfpm/zrok-share.service.override.conf
 
diff --git a/.goreleaser-linux-arm64.yml b/.goreleaser-linux-arm64.yml
index d63b87fa..e4c5454f 100644
--- a/.goreleaser-linux-arm64.yml
+++ b/.goreleaser-linux-arm64.yml
@@ -113,6 +113,9 @@ nfpms:
       - dst: /lib/systemd/system/
         src: ./nfpm/zrok-share.service
 
+      - dst: /usr/lib/systemd/user/
+        src: ./nfpm/zrok-share@.service
+
       - dst: /etc/systemd/system/zrok-share.service.d/override.conf
         src: ./nfpm/zrok-share.service.override.conf
 
diff --git a/.goreleaser-linux-armel.yml b/.goreleaser-linux-armel.yml
index 80bdbc26..748360dd 100644
--- a/.goreleaser-linux-armel.yml
+++ b/.goreleaser-linux-armel.yml
@@ -117,6 +117,12 @@ nfpms:
       - dst: /lib/systemd/system/
         src: ./nfpm/zrok-share.service
 
+      - dst: /usr/lib/systemd/user/
+        src: ./nfpm/zrok-share@.service
+
+      - dst: /usr/lib/systemd/user/
+        src: ./nfpm/zrok-share@.service
+
       - dst: /etc/systemd/system/zrok-share.service.d/override.conf
         src: ./nfpm/zrok-share.service.override.conf
 
diff --git a/.goreleaser-linux-armhf.yml b/.goreleaser-linux-armhf.yml
index c7275d81..67518309 100644
--- a/.goreleaser-linux-armhf.yml
+++ b/.goreleaser-linux-armhf.yml
@@ -115,6 +115,9 @@ nfpms:
       - dst: /lib/systemd/system/
         src: ./nfpm/zrok-share.service
 
+      - dst: /usr/lib/systemd/user/
+        src: ./nfpm/zrok-share@.service
+
       - dst: /etc/systemd/system/zrok-share.service.d/override.conf
         src: ./nfpm/zrok-share.service.override.conf
 
diff --git a/docs/guides/frontdoor.mdx b/docs/guides/frontdoor.mdx
index 5e19aa43..dec7bd5f 100644
--- a/docs/guides/frontdoor.mdx
+++ b/docs/guides/frontdoor.mdx
@@ -46,7 +46,25 @@ the detected OS of the visitor's browser */}
 
 On Linux, zrok frontdoor is implemented natively as a system service provided by the `zrok-share` DEB or RPM package.
 
-    <LinuxService/>
+## Goal
+
+Proxy a reserved public subdomain to a backend target with an always-on Linux system service.
+
+## How it Works
+
+The `zrok-share` package creates a `zrok-share.service` unit in systemd. The administrator edits the service's configuration file to specify the:
+
+1. zrok account token
+1. target URL or files to be shared and backend mode, e.g. `proxy`
+1. authentication options, if wanted
+
+When the service starts it will:
+
+1. enable the zrok environment unless `/var/lib/zrok-share/.zrok/environment.json` exists
+1. reserve a public subdomain for the service unless `/var/lib/zrok-share/.zrok/reserved.json` exists
+1. start sharing the target specified as `ZROK_TARGET` in the environment file
+
+  <LinuxService/>
 
   </TabItem>
 
diff --git a/nfpm/zrok-share.bash b/nfpm/zrok-share.bash
index d46edb8f..6f5bd9a3 100644
--- a/nfpm/zrok-share.bash
+++ b/nfpm/zrok-share.bash
@@ -36,28 +36,20 @@ fi
 echo "DEBUG: zrok state directory is ${HOME}/.zrok"
 
 : "${ZROK_SHARE_RESERVED:=true}"
-
 echo "DEBUG: ZROK_SHARE_RESERVED=${ZROK_SHARE_RESERVED}"
 
-if (( $# )); then
-  if [[ -s "$1" ]]; then
+while (( $# )); do
+  if [[ "${1:0:1}" == @ ]]; then
+    ZROK_INSTANCE="${1:1}"
+    shift
+  elif [[ -s "$1" ]]; then
     echo "INFO: reading share configuration from $1"
     source "$1"
     shift
-  else
-    echo "ERROR: '$1' is empty or not readable" >&2
-    exit 1
   fi
-else
-  # TODO: consider defining a default environment file
-  # if [[ -s /opt/openziti/etc/zrok.env ]]; then
-  #   source /opt/openziti/etc/zrok.env
-  # else
-  #   echo "ERROR: need /opt/openziti/etc/zrok.env or filename argument to read share configuration" >&2
-  #   exit 1
-  # fi
-  echo "INFO: reading share configuration from environment variables"
-fi
+done
+
+ZROK_RESERVATION_FILE="${HOME}/.zrok/reserved${ZROK_INSTANCE:+@${ZROK_INSTANCE}}.json"
 
 [[ -n "${ZROK_TARGET:-}" ]] || {
   echo "ERROR: ZROK_TARGET is not defined." >&2
@@ -70,14 +62,14 @@ if [[ "${ZROK_FRONTEND_MODE:-}" == temp-public ]]; then
   ZROK_CMD="share public"
 elif [[ "${ZROK_FRONTEND_MODE:-}" == temp-private ]]; then
   ZROK_CMD="share private"
-elif [[ -s ~/.zrok/reserved.json ]]; then
-  ZROK_RESERVED_TOKEN="$(jq -r '.token' ~/.zrok/reserved.json 2>/dev/null)"
-  if [[ -z "${ZROK_RESERVED_TOKEN}" || "${ZROK_RESERVED_TOKEN}" == null ]]; then
-    echo "ERROR: invalid reserved.json: '$(jq -c . ~/.zrok/reserved.json)'" >&2
+elif [[ -s "${ZROK_RESERVATION_FILE}" ]]; then
+  ZROK_RESERVATION_TOKEN="$(jq -r '.token' "${ZROK_RESERVATION_FILE}" 2>/dev/null)"
+  if [[ -z "${ZROK_RESERVATION_TOKEN}" || "${ZROK_RESERVATION_TOKEN}" == null ]]; then
+    echo "ERROR: invalid reservation file: '$(jq -c . "${ZROK_RESERVATION_FILE}")'" >&2
     exit 1
   else
-    echo "INFO: zrok backend is already reserved: ${ZROK_RESERVED_TOKEN}"
-    ZROK_CMD="${ZROK_RESERVED_TOKEN} ${ZROK_TARGET}"
+    echo "INFO: zrok backend is already reserved: ${ZROK_RESERVATION_TOKEN}"
+    ZROK_CMD="${ZROK_RESERVATION_TOKEN} ${ZROK_TARGET}"
     if [[ "${ZROK_SHARE_RESERVED}" == true ]]; then
       exec_share_reserved ${ZROK_CMD}
     else
@@ -208,30 +200,30 @@ if [[ "${ZROK_FRONTEND_MODE:-}" =~ ^temp- ]]; then
   exec_with_common_opts ${ZROK_CMD}
 else
   # reserve and continue
-  zrok ${ZROK_CMD} > ~/.zrok/reserved.json
+  zrok ${ZROK_CMD} > "${ZROK_RESERVATION_FILE}"
   # share the reserved backend target until exit
-  if ! [[ -s ~/.zrok/reserved.json ]]; then
-    echo "ERROR: empty or missing $(realpath ~/.zrok)/reserved.json" >&2
+  if ! [[ -s "${ZROK_RESERVATION_FILE}" ]]; then
+    echo "ERROR: empty or missing $(realpath "${ZROK_RESERVATION_FILE}")" >&2
     exit 1
-  elif ! jq . < ~/.zrok/reserved.json &>/dev/null; then
-    echo "ERROR: invalid JSON in $(realpath ~/.zrok)/reserved.json" >&2
+  elif ! jq . < "${ZROK_RESERVATION_FILE}" &>/dev/null; then
+    echo "ERROR: invalid JSON in $(realpath "${ZROK_RESERVATION_FILE}")" >&2
     exit 1
   else
     if [[ "${ZROK_FRONTEND_MODE:-}" == reserved-public ]]; then
-      ZROK_PUBLIC_URLS=$(jq -cr '.frontend_endpoints' ~/.zrok/reserved.json 2>/dev/null)
+      ZROK_PUBLIC_URLS=$(jq -cr '.frontend_endpoints' "${ZROK_RESERVATION_FILE}" 2>/dev/null)
       if [[ -z "${ZROK_PUBLIC_URLS}" || "${ZROK_PUBLIC_URLS}" == null ]]; then
-        echo "ERROR: frontend endpoints not defined in $(realpath ~/.zrok)/reserved.json" >&2
+        echo "ERROR: frontend endpoints not defined in $(realpath "${ZROK_RESERVATION_FILE}")" >&2
         exit 1
       else
         echo "INFO: zrok public URLs: ${ZROK_PUBLIC_URLS}"
       fi
     fi
-    ZROK_RESERVED_TOKEN=$(jq -r '.token' ~/.zrok/reserved.json 2>/dev/null)
-    if [[ -z "${ZROK_RESERVED_TOKEN}" || "${ZROK_RESERVED_TOKEN}" == null ]]; then
-      echo "ERROR: zrok reservation token not defined in $(realpath ~/.zrok)/reserved.json" >&2
+    ZROK_RESERVATION_TOKEN=$(jq -r '.token' "${ZROK_RESERVATION_FILE}" 2>/dev/null)
+    if [[ -z "${ZROK_RESERVATION_TOKEN}" || "${ZROK_RESERVATION_TOKEN}" == null ]]; then
+      echo "ERROR: zrok reservation token not defined in $(realpath "${ZROK_RESERVATION_FILE}")" >&2
       exit 1
     fi
-    ZROK_CMD="${ZROK_RESERVED_TOKEN} ${ZROK_TARGET}"
+    ZROK_CMD="${ZROK_RESERVATION_TOKEN} ${ZROK_TARGET}"
     if [[ "${ZROK_SHARE_RESERVED}" == true ]]; then
       exec_share_reserved ${ZROK_CMD}
     else
diff --git a/nfpm/zrok-share.env b/nfpm/zrok-share.env
index c1b0b8f4..c2c67ac3 100644
--- a/nfpm/zrok-share.env
+++ b/nfpm/zrok-share.env
@@ -3,8 +3,10 @@
 #
 ## ZROK ENVIRONMENT
 #
-# You MUST enable a zrok environment by setting the environment enable token here. This file must be readable by
-# 'other'.  Obtain the enable token from the zrok console after accepting your invitation and creating a password.
+# The variables in this section are not used by user units, i.e., systemctl --user, because it is assumed the user's
+# environment in ~/.zrok is already enabled. The variables in this section are required by system-wide service units.
+# For system services, you MUST enable a zrok environment by setting the account token here.  This file must
+# be readable by 'other'. Obtain the account token from the zrok console.
 #
 # WARNING: changing these values has no effect if /var/lib/zrok-share/.zrok/environment.json exists. Remove that file to
 # enable a new environment and /var/lib/zrok-share/.zrok/reserved.json to provision a new frontend URL for the specified
diff --git a/nfpm/zrok-share.service b/nfpm/zrok-share.service
index f8fb4072..fdb528f3 100644
--- a/nfpm/zrok-share.service
+++ b/nfpm/zrok-share.service
@@ -1,5 +1,5 @@
 [Unit]
-Description=zrok reserved public share service
+Description=zrok share service 
 After=network-online.target
 
 [Service]
@@ -7,8 +7,9 @@ Type=simple
 DynamicUser=yes
 StateDirectory=zrok-share
 UMask=0007
-ExecStartPre=/opt/openziti/bin/zrok-enable.bash /opt/openziti/etc/zrok/zrok-share.env
-ExecStart=/opt/openziti/bin/zrok-share.bash /opt/openziti/etc/zrok/zrok-share.env
+EnvironmentFile=/opt/openziti/etc/zrok/zrok-share.env
+ExecStartPre=/opt/openziti/bin/zrok-enable.bash
+ExecStart=/opt/openziti/bin/zrok-share.bash
 Restart=always
 RestartSec=3
 
diff --git a/nfpm/zrok-share.service.override.conf b/nfpm/zrok-share.service.override.conf
index 57f4a796..9cf870a9 100644
--- a/nfpm/zrok-share.service.override.conf
+++ b/nfpm/zrok-share.service.override.conf
@@ -6,5 +6,3 @@
 
 # allow adding tun device and IP routes and iptables rules; required when ZROK_BACKEND_MODE=vpn
 # AmbientCapabilities=CAP_NET_ADMIN
-
-# you must run 'systemctl daemon-reload' after modifying this file
diff --git a/nfpm/zrok-share@.service b/nfpm/zrok-share@.service
new file mode 100644
index 00000000..ad242bf6
--- /dev/null
+++ b/nfpm/zrok-share@.service
@@ -0,0 +1,17 @@
+
+# /usr/lib/systemd/user/zrok-share@.service
+
+[Unit]
+Description=zrok share user service unit @%i
+After=network-online.target
+
+[Service]
+Type=simple
+UMask=0007
+EnvironmentFile=%h/.zrok/zrok-share@%i.env
+ExecStart=/opt/openziti/bin/zrok-share.bash @%i
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target

From af0367e36b584660cfe0e89cd33338b8110d16a4 Mon Sep 17 00:00:00 2001
From: Kenneth Bingham <kenneth.bingham@netfoundry.io>
Date: Thu, 2 Jan 2025 01:52:50 -0500
Subject: [PATCH 06/10] document and announce Linux user shares

---
 .goreleaser-linux-armel.yml                  |  3 --
 CHANGELOG.md                                 |  4 +-
 docs/guides/_frontdoor-linux.mdx             | 36 +---------------
 docs/guides/_linux-share-install.mdx         | 17 ++++++++
 docs/guides/linux-user-share/_category_.json |  8 ++++
 docs/guides/linux-user-share/index.mdx       | 44 ++++++++++++++++++++
 6 files changed, 74 insertions(+), 38 deletions(-)
 create mode 100644 docs/guides/_linux-share-install.mdx
 create mode 100644 docs/guides/linux-user-share/_category_.json
 create mode 100644 docs/guides/linux-user-share/index.mdx

diff --git a/.goreleaser-linux-armel.yml b/.goreleaser-linux-armel.yml
index 748360dd..86526dec 100644
--- a/.goreleaser-linux-armel.yml
+++ b/.goreleaser-linux-armel.yml
@@ -120,9 +120,6 @@ nfpms:
       - dst: /usr/lib/systemd/user/
         src: ./nfpm/zrok-share@.service
 
-      - dst: /usr/lib/systemd/user/
-        src: ./nfpm/zrok-share@.service
-
       - dst: /etc/systemd/system/zrok-share.service.d/override.conf
         src: ./nfpm/zrok-share.service.override.conf
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 74ff2044..3f997524 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,9 +4,11 @@
 
 FIX: Docker share examples had incorrect default path for zrok environment mountpoint
 
+FIX: Clarify how to use DNS providers like Route53 with the zrok Docker instance sample.
+
 CHANGE: Use port 80 for the default Ziti API endpoint in the zrok Docker instance sample (https://github.com/openziti/zrok/issues/793).
 
-FIX: Clarify how to use DNS providers like Route53 with the zrok Docker instance sample.
+FEATURE: Linux service template for systemd user units (https://github.com/openziti/zrok/pull/818)
 
 ## v0.4.45
 
diff --git a/docs/guides/_frontdoor-linux.mdx b/docs/guides/_frontdoor-linux.mdx
index 23977db9..ac3b6fe7 100644
--- a/docs/guides/_frontdoor-linux.mdx
+++ b/docs/guides/_frontdoor-linux.mdx
@@ -1,42 +1,10 @@
+import LinuxShareInstall from './_linux-share-install.mdx'
 import AnsibleRepoSetup from './install/_ansible_repo_setup.yaml'
 import ConcatenateYamlSnippets from '@site/src/components/cat-yaml.jsx'
 
-## Goal
-
-Proxy a reserved public subdomain to a backend target with an always-on Linux system service.
-
-## How it Works
-
-The `zrok-share` package creates a `zrok-share.service` unit in systemd. The administrator edits the service's configuration file to specify the:
-
-1. zrok environment enable token
-1. target URL or files to be shared and backend mode, e.g. `proxy`
-1. authentication options, if wanted
-
-When the service starts it will:
-
-1. enable the zrok environment unless `/var/lib/zrok-share/.zrok/environment.json` exists
-1. reserve a public subdomain for the service unless `/var/lib/zrok-share/.zrok/reserved.json` exists
-1. start sharing the target specified as `ZROK_TARGET` in the environment file
-
 ## Installation
 
-1. Set up `zrok`'s Linux package repository by following [the Linux install guide](/guides/install/linux.mdx#install-zrok-from-the-repository), or run this one-liner to complete the repo setup and install packages.
-
-    ```bash
-    curl -sSLf https://get.openziti.io/install.bash \
-    | sudo bash -s zrok-share
-    ```
-
-1. If you set up the repository by following the guide, then also install the `zrok-share` package. This package provides the systemd service.
-
-    ```bash title="Ubuntu, Debian"
-    sudo apt install zrok-share
-    ```
-
-    ```bash title="Fedora, Rocky"
-    sudo dnf install zrok-share
-    ```
+<LinuxShareInstall />
 
 <Details>
 <summary>Ansible Playbook</summary>
diff --git a/docs/guides/_linux-share-install.mdx b/docs/guides/_linux-share-install.mdx
new file mode 100644
index 00000000..acea45b2
--- /dev/null
+++ b/docs/guides/_linux-share-install.mdx
@@ -0,0 +1,17 @@
+
+1. Set up `zrok`'s Linux package repository by following [the Linux install guide](/guides/install/linux.mdx#install-zrok-from-the-repository), or run this one-liner to complete the repo setup and install packages.
+
+    ```bash
+    curl -sSLf https://get.openziti.io/install.bash \
+    | sudo bash -s zrok-share
+    ```
+
+1. If you set up the repository by following the guide, then also install the `zrok-share` package. This package provides the systemd service.
+
+    ```bash title="Ubuntu, Debian"
+    sudo apt install zrok-share
+    ```
+
+    ```bash title="Fedora, Rocky"
+    sudo dnf install zrok-share
+    ```
diff --git a/docs/guides/linux-user-share/_category_.json b/docs/guides/linux-user-share/_category_.json
new file mode 100644
index 00000000..16892730
--- /dev/null
+++ b/docs/guides/linux-user-share/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Linux User Share",
+  "position": 40,
+  "link": {
+    "type": "doc",
+    "id": "guides/linux-user-share/index"
+  }
+}
diff --git a/docs/guides/linux-user-share/index.mdx b/docs/guides/linux-user-share/index.mdx
new file mode 100644
index 00000000..6b9679e2
--- /dev/null
+++ b/docs/guides/linux-user-share/index.mdx
@@ -0,0 +1,44 @@
+---
+title: Linux User Share
+---
+
+import LinuxShareInstall from '/../docs/guides/_linux-share-install.mdx'
+
+## Overview
+
+You can run any number of zrok share services as `systemd --user` units with your Linux user's zrok environment in `~/.zrok`. This is like [zrok frontdoor](/guides/frontdoor.mdx) except that frontdoor is a system service managed by root separately from your user's login. Linux user shares, Linux system services, and Docker shares all use the same configuration environment variables.
+
+## Install the Linux Package
+
+The package provides the `zrok` executable and service unit template.
+
+<LinuxShareInstall />
+
+## Create a User Share Configuration File
+
+Substitute a name for your instance in place of `my-instance` in the following example. To avoid character escaping problems, use only letters, numbers, hyphens, and underscores in the instance name, not spaces or other special characters.
+
+```bash
+ZROK_INSTANCE="my-instance"
+cp /opt/openziti/etc/zrok/zrok-share.env ~/.zrok/zrok-share@${ZROK_INSTANCE}.env
+```
+
+## Edit the User Share Configuration File
+
+Edit the configuration file in `~/.zrok/zrok-share@${ZROK_INSTANCE}.env` as you would for [zrok frontdoor](/guides/frontdoor.mdx), except ignore the first section "ZROK ENVIRONMENT" because user shares re-use `~/.zrok` and do not need a separate zrok environment.
+
+## Start the User Share Service
+
+```bash
+systemctl --user enable --now zrok-share@${ZROK_INSTANCE}.service
+```
+
+## Check the User Share Journal
+
+```bash
+journalctl --user -lfu zrok-share@${ZROK_INSTANCE}.service
+```
+
+## Add Another User Share
+
+To create another user share, choose another instance name, copy the `zrok-share.env` file, edit the configuration file, and start the service.

From e30fbb6878c2639deed955fdef7eaeb1c9676de5 Mon Sep 17 00:00:00 2001
From: Kenneth Bingham <kenneth.bingham@netfoundry.io>
Date: Fri, 27 Dec 2024 15:50:54 -0500
Subject: [PATCH 07/10] simplify and clarify zrok vpn guidance

---
 CHANGELOG.md           |  2 ++
 docs/guides/vpn/vpn.md | 73 ++++++++++++++++++++++++------------------
 nfpm/zrok-share.bash   |  7 ++--
 nfpm/zrok-share.env    |  8 ++---
 4 files changed, 51 insertions(+), 39 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3f997524..39d7d1e5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,8 @@ FIX: Clarify how to use DNS providers like Route53 with the zrok Docker instance
 
 CHANGE: Use port 80 for the default Ziti API endpoint in the zrok Docker instance sample (https://github.com/openziti/zrok/issues/793).
 
+CHANGE: Clarify OS requirements for zrok VPN
+
 FEATURE: Linux service template for systemd user units (https://github.com/openziti/zrok/pull/818)
 
 ## v0.4.45
diff --git a/docs/guides/vpn/vpn.md b/docs/guides/vpn/vpn.md
index a2d718e0..3d0755ab 100644
--- a/docs/guides/vpn/vpn.md
+++ b/docs/guides/vpn/vpn.md
@@ -6,11 +6,27 @@ sidebar_label: VPN
 
 zrok VPN backend allows for simple host-to-host VPN setup.
 
-## Starting VPN server
+## Operating System Requirements
+
+zrok VPN requires elevated privileges to manage network devices.
+
+### Windows
+
+On Windows, you must run zrok VPN commands as an administrator and install Wintun by placing `wintun.dll` ([download link](https://www.wintun.net/)) in the same directory as the `zrok.exe` executable.
+
+### Linux
+
+On Linux, the simplest way to grant the necessary privileges is to run zrok VPN commands as root. You can enable a separate environment for root by also running `zrok enable` as the root user, or you can prefix the commands like `sudo -E` to allow zrok running as root to use the zrok environment owned by the current user. The minimum privilege is runing zrok VPN commands and the `ip` command with the `NET_ADMIN` kernel capability. The `zrok-share.service` unit has a commented example to grant `NET_ADMIN` as an Ambient Capability.
+
+### macOS
+
+On macOS, you must run zrok VPN commands as root. You can prefix the zrok command with `sudo -E` to allow zrok running as root to use the zrok environment owned by the current user.
+
+## Start the VPN Server
 
 VPN is shared through the `vpn` backend of `zrok` command.
 
-```
+```bash
 eugene@hermes $ sudo -E zrok share private --headless --backend-mode vpn
 [   0.542]    INFO sdk-golang/ziti.(*listenerManager).createSessionWithBackoff: {session token=[589d443c-f59d-4fc8-8c48-76609b7fb402]} new service session
 [   0.705]    INFO main.(*sharePrivateCommand).run: allow other to access your share with the following command:
@@ -25,8 +41,9 @@ zrok access private 3rq7torslq3n
 
 By default `vpn` backend uses subnet `10.122.0.0/16` and assigns `10.122.0.1` to the host that stared VPN share.
 
-```
-$ ifconfig
+Example output from `ifconfig`:
+
+```text
 tun0: flags=4305<UP,POINTOPOINT,RUNNING,NOARP,MULTICAST>  mtu 16384
         inet 10.122.0.1  netmask 255.255.0.0  destination 10.122.0.1
         inet6 fe80::705f:24e4:dcfc:a6b2  prefixlen 64  scopeid 0x20<link>
@@ -39,16 +56,17 @@ tun0: flags=4305<UP,POINTOPOINT,RUNNING,NOARP,MULTICAST>  mtu 16384
 ```
 
 Default IP/subnet setting can be overridden by adding `<target>` parameter:
-```
-$ sudo -E zrok share private --headless --backend-mode vpn 192.168.42.12/24
+
+```bash
+sudo -E zrok share private --headless --backend-mode vpn 192.168.42.12/24
 ```
 
-## VPN share reservation
+## Reserve a VPN Share Token
 
-Share reservation works the same as with other backend types:
+As with all backend modes, you can reserve a share token for a VPN share.
 
-```
-eugene@hermes $ zrok reserve private -b vpn
+```bash
+eugene@hermes $ zrok reserve private --backend-mode vpn
 [   0.297]    INFO main.(*reserveCommand).run: your reserved share token is 'k77y2cl7jmjl'
 
 eugene@hermes $ sudo -E zrok share reserved k77y2cl7jmjl --headless
@@ -57,14 +75,11 @@ eugene@hermes $ sudo -E zrok share reserved k77y2cl7jmjl --headless
 [   0.463]    INFO sdk-golang/ziti.(*listenerManager).createSessionWithBackoff: {session token=[22c5708d-e2f2-41aa-a507-454055f8bfcc]} new service session
 [   0.641]    INFO main.(*shareReservedCommand).run: use this command to access your zrok share: 'zrok access private k77y2cl7jmjl'
 [
-
 ```
 
-## Accessing VPN share
+## Access the VPN Share
 
-Accessing a VPN share works similar to other backends.
-
-```
+```bash
 eugene@calculon % sudo -E zrok access private --headless k77y2cl7jmjl
 [   0.201]    INFO main.(*accessPrivateCommand).run: allocated frontend '50B5hloP1s1X'
 [   0.662]    INFO main.(*accessPrivateCommand).run: access the zrok share at the following endpoint: VPN:
@@ -72,23 +87,22 @@ eugene@calculon % sudo -E zrok access private --headless k77y2cl7jmjl
 [   0.662]    INFO zrok/endpoints/vpn.(*Frontend).Run: connected:Welcome to zrok VPN
 ```
 
-Starting `zrok access` to a VPN share creates virtual network device/interface: 
+zrok creates a virtual network device, i.e., a "tun" interface, when you run `zrok access`.
 
-```
-eugene@calculon ~ % ifconfig 
-...
+Example output from `ifconfig` run on a VPN client device:
+
+```bash
 utun5: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
         inet 10.122.0.3 --> 10.122.0.1 netmask 0xff000000
         inet6 fe80::ce08:faff:fe8a:7b25%utun5 prefixlen 64 scopeid 0x14
         nd6 options=201<PERFORMNUD,DAD>
-...
 ```
 
-At this point a VPN tunnel is active between your server and client. 
-In the example above server is `hermes(10.122.0.1)` and client is `calculon(10.122.0.3)`. 
-You can access server from client by using assigned IP address.
+At this point a VPN tunnel is active between your server and client.
+In the example above server is `hermes(10.122.0.1)` and client is `calculon(10.122.0.3)`.
+All devices in the VPN can access one another by IP address.
 
-```
+```bash
 eugene@calculon ~ % ssh eugene@10.122.0.1
 Welcome to Ubuntu 23.10 (GNU/Linux 6.5.0-27-generic x86_64)
 
@@ -107,14 +121,11 @@ eugene@hermes:~$
 ```
 
 You can also make a reverse(server-to-client) connection:
-```
+
+```bash
 eugene@hermes:~$ ssh 10.122.0.3
-The authenticity of host '10.122.0.3 (10.122.0.3)' can't be established.
-<..snip..>
-Warning: Permanently added '10.122.0.3' (ED25519) to the list of known hosts.
-(eugene@10.122.0.3) Password:
 Last login: Tue Apr 16 09:57:28 2024
+
 eugene@calculon ~ % who am i
 eugene           ttys008      Apr 16 10:06 (10.122.0.1)
-eugene@calculon ~ %
-```
\ No newline at end of file
+```
diff --git a/nfpm/zrok-share.bash b/nfpm/zrok-share.bash
index 6f5bd9a3..4f0812a9 100644
--- a/nfpm/zrok-share.bash
+++ b/nfpm/zrok-share.bash
@@ -133,10 +133,9 @@ case "${ZROK_BACKEND_MODE}" in
           ;;
         vpn)
           if [[ -n "${ZROK_TARGET}" ]]; then
-            ZROK_SVC_FILE=/etc/systemd/system/zrok-share.service.d/override.conf
-            if ! grep -qE '^AmbientCapabilities=CAP_NET_ADMIN' "${ZROK_SVC_FILE}"; then
-              echo "ERROR: you must uncomment 'AmbientCapabilities=CAP_NET_ADMIN' in '${ZROK_SVC_FILE}'"\
-                    "and run 'systemctl daemon-reload' to enable VPN mode" >&2
+            if ! systemctl cat zrok-share.service | grep -qE '^AmbientCapabilities=.*CAP_NET_ADMIN' >/dev/null; then
+              echo "ERROR: you must 'systemctl edit zrok-share.service' and uncomment
+              'AmbientCapabilities=CAP_NET_ADMIN' to enable VPN mode" >&2
               exit 1
             fi
           fi
diff --git a/nfpm/zrok-share.env b/nfpm/zrok-share.env
index c2c67ac3..8539ad12 100644
--- a/nfpm/zrok-share.env
+++ b/nfpm/zrok-share.env
@@ -69,11 +69,11 @@ ZROK_TARGET=""                  # e.g., http://127.0.0.1:3000
 #ZROK_BACKEND_MODE="udpTunnel"
 #ZROK_TARGET="127.0.0.1:53"
 
-# you MUST grant NET_ADMIN capability to the service to enable vpn mode, e.g., run these two commands:
-# sed -Ei 's/.*AmbientCapabilities=CAP_NET_ADMIN/AmbientCapabilities=CAP_NET_ADMIN/' /etc/systemd/system/zrok-share.service.d/override.conf
-# systemctl daemon-reload
+# you MUST grant NET_ADMIN capability to the service to enable vpn mode, e.g., run:
+# systemctl edit zrok-share.service
+# uncomment 'AmbientCapabilities=CAP_NET_ADMIN'
 #ZROK_BACKEND_MODE="vpn"
-#ZROK_TARGET="172.16.0.1/12"
+#ZROK_TARGET="10.122.0.1/16"
 
 # there is no target for socks mode because the share is only a dynamic exit for the proxy client
 #ZROK_BACKEND_MODE="socks"

From 244fb693fb44631d285d0f90463e12839735742d Mon Sep 17 00:00:00 2001
From: Kenneth Bingham <kenneth.bingham@netfoundry.io>
Date: Fri, 27 Dec 2024 16:52:51 -0500
Subject: [PATCH 08/10] refine windows installation instructions

---
 docs/guides/install/windows.mdx | 32 +++++++++++++++++++-------------
 1 file changed, 19 insertions(+), 13 deletions(-)

diff --git a/docs/guides/install/windows.mdx b/docs/guides/install/windows.mdx
index 54a14e34..50e505ad 100644
--- a/docs/guides/install/windows.mdx
+++ b/docs/guides/install/windows.mdx
@@ -18,21 +18,14 @@ import styles from '@site/src/css/download-card.module.css';
   </div>
 </AssetsProvider>
 
-1. Unarchive the distribution in a temporary directory:
+1. Extract `zrok.exe` to `%USERPROFILE%\bin` and set search `%PATH%`.
 
     ```text
-    New-Item -Path "$env:TEMP\zrok" -ItemType Directory -ErrorAction Stop
-    tar -xf .\zrok*windows*.tar.gz -C "$env:TEMP\zrok"
-    ```
-
-1. Install the `zrok` executable and include HOME\bin in the search PATH.
-
-    ```text
-    $source = Join-Path -Path $env:TEMP -ChildPath "zrok\zrok.exe"
-    $destination = Join-Path -Path $env:USERPROFILE -ChildPath "bin\zrok.exe"
-    New-Item -Path $destination -ItemType Directory -ErrorAction SilentlyContinue
-    Copy-Item -Path $source -Destination $destination
-    $env:path += ";"+$destination
+    $binDir = Join-Path -Path $env:USERPROFILE -ChildPath "bin"
+    New-Item -Path $binDir -ItemType Directory -ErrorAction SilentlyContinue
+    $latest = Get-ChildItem -Path .\zrok*windows*.tar.gz | Sort-Object LastWriteTime | Select-Object -Last 1
+    tar -xf $latest.FullName -C $binDir zrok.exe
+    $env:path += ";"+$binDir
     ```
 
 1. With the `zrok` executable in your path, you can then execute the `zrok` directly.
@@ -50,3 +43,16 @@ import styles from '@site/src/css/download-card.module.css';
 
     v0.4.0 [c889005]
     ```
+
+## Enable Your Environment
+
+Enable your environment without saving the account token in shell history, i.e., `zrok enable {token}`.
+
+```text
+$zrokAccountToken=Read-Host "Enter your zrok account token" -AsSecureString;
+zrok enable ([System.Runtime.InteropServices.Marshal]::PtrToStringAuto([System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($zrokAccountToken)))
+```
+
+## Wintun for zrok VPN
+
+On Windows, you must install Wintun to use zrok's VPN backend mode. See the [VPN guide](/guides/vpn/vpn.md) for more details.

From 9c78fea0e10f387eb90421b2293fb87b22a4f19b Mon Sep 17 00:00:00 2001
From: Kenneth Bingham <kenneth.bingham@netfoundry.io>
Date: Sat, 28 Dec 2024 10:04:20 -0500
Subject: [PATCH 09/10] set the executable search path

---
 CHANGELOG.md                    |  2 ++
 docs/guides/install/windows.mdx | 18 +++++++-----------
 2 files changed, 9 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 39d7d1e5..30c30ff6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,8 @@ CHANGE: Use port 80 for the default Ziti API endpoint in the zrok Docker instanc
 
 CHANGE: Clarify OS requirements for zrok VPN
 
+CHANGE: Set the Windows executable search path in the Windows install guide.
+
 FEATURE: Linux service template for systemd user units (https://github.com/openziti/zrok/pull/818)
 
 ## v0.4.45
diff --git a/docs/guides/install/windows.mdx b/docs/guides/install/windows.mdx
index 50e505ad..e6bb4b76 100644
--- a/docs/guides/install/windows.mdx
+++ b/docs/guides/install/windows.mdx
@@ -18,14 +18,19 @@ import styles from '@site/src/css/download-card.module.css';
   </div>
 </AssetsProvider>
 
-1. Extract `zrok.exe` to `%USERPROFILE%\bin` and set search `%PATH%`.
+1. In PowerShell, install in `%USERPROFILE%\bin\zrok.exe` and set the search path.
 
     ```text
     $binDir = Join-Path -Path $env:USERPROFILE -ChildPath "bin"
     New-Item -Path $binDir -ItemType Directory -ErrorAction SilentlyContinue
     $latest = Get-ChildItem -Path .\zrok*windows*.tar.gz | Sort-Object LastWriteTime | Select-Object -Last 1
     tar -xf $latest.FullName -C $binDir zrok.exe
-    $env:path += ";"+$binDir
+    $currentPath = [System.Environment]::GetEnvironmentVariable('PATH', [System.EnvironmentVariableTarget]::User)
+    if ($currentPath -notlike "*$binDir*") {
+        $newPath = "$currentPath;$binDir"
+        [System.Environment]::SetEnvironmentVariable('PATH', $newPath, [System.EnvironmentVariableTarget]::User)
+        $env:Path = $newPath
+    }
     ```
 
 1. With the `zrok` executable in your path, you can then execute the `zrok` directly.
@@ -44,15 +49,6 @@ import styles from '@site/src/css/download-card.module.css';
     v0.4.0 [c889005]
     ```
 
-## Enable Your Environment
-
-Enable your environment without saving the account token in shell history, i.e., `zrok enable {token}`.
-
-```text
-$zrokAccountToken=Read-Host "Enter your zrok account token" -AsSecureString;
-zrok enable ([System.Runtime.InteropServices.Marshal]::PtrToStringAuto([System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($zrokAccountToken)))
-```
-
 ## Wintun for zrok VPN
 
 On Windows, you must install Wintun to use zrok's VPN backend mode. See the [VPN guide](/guides/vpn/vpn.md) for more details.

From 5bd78dfcaf32baf2e4926f20f06db6145a88baf2 Mon Sep 17 00:00:00 2001
From: Kenneth Bingham <kenneth.bingham@netfoundry.io>
Date: Wed, 18 Dec 2024 10:23:40 -0500
Subject: [PATCH 10/10] use specific macOS runners

---
 .github/workflows/build-wheels.yml | 10 +++++-----
 .github/workflows/release.yml      |  2 +-
 CHANGELOG.md                       |  4 +++-
 3 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/build-wheels.yml b/.github/workflows/build-wheels.yml
index b27d5e01..0fe9a743 100644
--- a/.github/workflows/build-wheels.yml
+++ b/.github/workflows/build-wheels.yml
@@ -14,7 +14,7 @@ jobs:
       matrix:
         spec:
           - { name: 'linux x86_64', runner: ubuntu-20.04, target: manylinux_2_27_x86_64 }
-          - { name: 'macOS x86_64', runner: macos-12, target: macosx_10_14_x86_64 }
+          - { name: 'macOS x86_64', runner: macos-13, target: macosx_10_14_x86_64 }
           - { name: 'Windows x86_64', runner: windows-2019, target: win_amd64 }
     name: building ${{ matrix.spec.name }}
     runs-on: ${{ matrix.spec.runner }}
@@ -68,12 +68,12 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           repository-url: https://test.pypi.org/legacy/
-          packages_dir: dist
-          skip_existing: true
+          packages-dir: dist
+          skip-existing: true
           verbose: true
 
       - name: Publish wheels (PyPI)
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          packages_dir: dist
-          verbose: true
\ No newline at end of file
+          packages-dir: dist
+          verbose: true
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index ebd59340..1537f517 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -227,7 +227,7 @@ jobs:
 
   build-darwin:
     if: github.repository_owner == 'openziti' || vars.ZROK_SKIP_MACOS_BUILD == 'false'
-    runs-on: macos-latest
+    runs-on: macos-14
     steps:
       - name: import distribution cert
         uses: apple-actions/import-codesign-certs@v3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 30c30ff6..2933da2d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## v0.4.46
 
+FEATURE: Linux service template for systemd user units (https://github.com/openziti/zrok/pull/818)
+
 FIX: Docker share examples had incorrect default path for zrok environment mountpoint
 
 FIX: Clarify how to use DNS providers like Route53 with the zrok Docker instance sample.
@@ -12,7 +14,7 @@ CHANGE: Clarify OS requirements for zrok VPN
 
 CHANGE: Set the Windows executable search path in the Windows install guide.
 
-FEATURE: Linux service template for systemd user units (https://github.com/openziti/zrok/pull/818)
+CHANGE: bump macOS runner for Python module from macos-12 to macos-13
 
 ## v0.4.45