Merge branch 'main' into canary_1

.github/issue_template.md

@@ -0,0 +1,9 @@
+Thank you for taking the time to reach out regarding zrok!
+
+If you think you have found a bug in zrok, or you need help with a specific issue, please reach out for support on the OpenZiti Discourse group at:
+
+https://openziti.discourse.group/
+
+There is a zrok topic available there. The entire zrok and OpenZiti team are monitoring that forum. They're not monitoring this issue database. If you decide to open an issue here anyway, we're probably still going to guide you to the Discourse forum to assist you. Going there first will get you help faster. :-)
+
+This issue database is for vetted roadmap items and confirmed bugs within the core open-source portion of zrok.

.goreleaser-darwin.yml

@@ -30,8 +30,8 @@ builds:
       - arm64
     hooks:
       post:
-        - cmd: 'codesign -s "Developer ID Application: NetFoundry Inc" -v dist/zrok-arm64_darwin_arm64/zrok --options=runtime'
+        - cmd: 'codesign -s "Developer ID Application: NetFoundry Inc" -v dist/zrok-arm64_darwin_arm64_v8.0/zrok --options=runtime'
           output: true
-        - cmd: zip "dist/zrok-arm64_darwin_arm64/zrok.zip" dist/zrok-arm64_darwin_arm64/zrok
-        - cmd: xcrun notarytool submit "dist/zrok-arm64_darwin_arm64/zrok.zip" --apple-id {{ .Env.AC_USERNAME }} --password {{ .Env.AC_PASSWORD }} --team-id MN5S649TXM --wait
+        - cmd: zip "dist/zrok-arm64_darwin_arm64_v8.0/zrok.zip" dist/zrok-arm64_darwin_arm64_v8.0/zrok
+        - cmd: xcrun notarytool submit "dist/zrok-arm64_darwin_arm64_v8.0/zrok.zip" --apple-id {{ .Env.AC_USERNAME }} --password {{ .Env.AC_PASSWORD }} --team-id MN5S649TXM --wait
           output: true

CHANGELOG.md

@@ -1,5 +1,23 @@
 # CHANGELOG
 
+## v0.4.45
+
+FIX: Update indirect dependency `github.com/golang-jwt/jwt/v4` to version `v4.5.1` (https://github.com/openziti/zrok/issues/794)
+
+FIX: Document unique names
+
+FIX: reduce Docker image sizes (https://github.com/openziti/zrok/pull/783)
+
+FIX: Docker reserved private share startup error (https://github.com/openziti/zrok/pull/801)
+
+FIX: Correct the download URL for the armv7 Linux release (https://github.com/openziti/zrok/issues/782)
+
+CHANGE: briefly mention the backend modes that apply to public and private share concepts
+
+## v0.4.44
+
+FIX: Fix for goreleaser build action to align with changed ARM64 build path.
+
 ## v0.4.43
 
 CHANGE: Update `github.com/openziti/sdk-golang` to version `v0.23.44`. Remove old `github.com/openziti/fabric` dependency, instead pulling in the modern `github.com/openziti/ziti` dependency.
@@ -214,7 +232,7 @@ CHANGE: The OpenZiti SDK for golang (https://github.com/openziti/sdk-golang) has
 
 ## v0.4.23
 
-FEATURE: New CLI commands have been implemented for working with the `drive` share backend mode (part of the "zrok Drives" functionality). These commands include `zrok cp`, `zrok mkdir` `zrok mv`, `zrok ls`, and `zrok rm`. These are initial, minimal versions of these commands and very likely contain bugs and ergonomic annoyances. There is a guide available at (`docs/guides/drives/cli.md`) that explains how to work with these tools in detail (https://github.com/openziti/zrok/issues/438)
+FEATURE: New CLI commands have been implemented for working with the `drive` share backend mode (part of the "zrok Drives" functionality). These commands include `zrok cp`, `zrok mkdir` `zrok mv`, `zrok ls`, and `zrok rm`. These are initial, minimal versions of these commands and very likely contain bugs and ergonomic annoyances. There is a guide available at (`docs/guides/drives.mdx`) that explains how to work with these tools in detail (https://github.com/openziti/zrok/issues/438)
 
 FEATURE: Python SDK now has a decorator for integrating with various server side frameworks. See the `http-server` example.
 

docker/compose/zrok-instance/README.md

@@ -224,7 +224,7 @@ The `ziti-quickstart` and `caddy` containers publish ports to all devices that u
 
 1. My provider, e.g., Route53 doesn't give me 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.
+    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.
 
     ```json
     tls {

docker/compose/zrok-instance/zrok-controller.Dockerfile

@@ -18,8 +18,7 @@ ARG ZITI_CTRL_ADVERTISED_PORT
 ARG ZITI_PWD
 
 # render zrok controller config.yml
-COPY ./envsubst.bash ./bootstrap-controller.bash /usr/local/bin/
-RUN chmod 0755 /usr/local/bin/envsubst.bash /usr/local/bin/bootstrap-controller.bash
+COPY --chmod=0755 ./envsubst.bash ./bootstrap-controller.bash /usr/local/bin/
 COPY ./zrok-controller-config.yml.envsubst /tmp/
 RUN mkdir -p /etc/zrok-controller/
 RUN envsubst.bash \

docker/compose/zrok-instance/zrok-frontend.Dockerfile

@@ -21,8 +21,7 @@ ARG ZROK_OAUTH_GITHUB_CLIENT_ID
 ARG ZROK_OAUTH_GITHUB_CLIENT_SECRET
 
 # render zrok frontend config.yml
-COPY ./envsubst.bash ./bootstrap-frontend.bash /usr/local/bin/
-RUN chmod 0755 /usr/local/bin/envsubst.bash /usr/local/bin/bootstrap-frontend.bash
+COPY --chmod=0755 ./envsubst.bash ./bootstrap-frontend.bash /usr/local/bin/
 COPY ./zrok-frontend-config.yml.envsubst /tmp/
 RUN mkdir -p /etc/zrok-frontend/
 RUN envsubst.bash \

docker/images/cross-build/Dockerfile

@@ -31,7 +31,6 @@ RUN wget -qO- https://deb.nodesource.com/setup_18.x | bash \
 
 
 COPY --from=golang /usr/local/go /usr/local/go
-# RUN chmod -R go+rX ${go_path} ${go_cache}
 
 COPY --from=goreleaser /usr/bin/goreleaser /usr/local/bin/goreleaser
 

docker/images/zrok/Dockerfile

@@ -1,5 +1,5 @@
 # this builds docker.io/openziti/zrok
-FROM docker.io/openziti/ziti-cli:1.1.7
+FROM docker.io/openziti/ziti-cli:1.1.15
 
 ARG ARTIFACTS_DIR=./dist
 ARG DOCKER_BUILD_DIR=.
@@ -24,14 +24,10 @@ RUN mkdir -p -m0755 /licenses
 COPY ./LICENSE /licenses/apache.txt
 
 RUN mkdir -p /usr/local/bin
-COPY ${ARTIFACTS_DIR}/${TARGETARCH}/${TARGETOS}/zrok \
+COPY --chmod=0755 ${ARTIFACTS_DIR}/${TARGETARCH}/${TARGETOS}/zrok \
       ./nfpm/zrok-enable.bash \
       ./nfpm/zrok-share.bash \
       /usr/local/bin/
-RUN chmod 0755 \
-      /usr/local/bin/zrok \
-      /usr/local/bin/zrok-enable.bash \
-      /usr/local/bin/zrok-share.bash
 
 USER ziggy
 ENTRYPOINT [ "zrok" ]

docs/concepts/_backend_http.mdx

@@ -0,0 +1,5 @@
+
+- `proxy` mode forwards requests received by the frontend to the target server ([more](/concepts/http.md))
+- `web` mode serves a target folder as a file index web page ([more](/concepts/files.md))
+- `drive` mode serves a target folder with WebDAV ([guide](/guides/drives.mdx))
+- `caddy` mode runs the built-in Caddy server with the targeted Caddyfile ([example](pathname:///simple_reverse_proxy.Caddyfile))

docs/concepts/index.md

@@ -7,7 +7,7 @@ sidebar_position: 25
 
 `zrok` was designed to make sharing local resources both secure and easy. In this section of the `zrok` documentation, we'll tour through all of the most important features.
 
-Sharing with `zrok` can be either [`public`](./sharing-public.md) or [`private`](./sharing-private.md).
+Sharing with `zrok` can be either [`public`](./sharing-public.mdx) or [`private`](./sharing-private.mdx).
 Naturally, regular web-based resources can be shared but `zrok` also includes support for sharing raw [TCP](./tunnels.md) and [UDP](./tunnels.md) network connections, and also includes a [website and file sharing](./files.md) feature.
 
 Learn about `zrok` [hosting here](./hosting.md), including instructions on how to [install your own `zrok` instance](/guides/self-hosting/linux/index.mdx).

docs/concepts/sharing-private.mdx

@@ -1,6 +1,9 @@
 ---
 sidebar_position: 0
 ---
+
+import BackendHttp from '/../docs/concepts/_backend_http.mdx'
+
 # Private Shares
 
 `zrok` was built to share and access digital resources. A `private` share allows a resource to be 
@@ -12,7 +15,7 @@ Peer-to-peer private resource sharing is one of the things that makes `zrok` uni
 
 Here's how private sharing works:
 
-# Peer to Peer
+## Peer to Peer
 
 ![zrok_public_share](../images/zrok_private_share.png)
 
@@ -27,3 +30,16 @@ The shared resource can be a development web server to share with friends and co
 The peer-to-peer capabilities of `zrok` are an important property of the underlying [OpenZiti](https://docs.openziti.io/docs/learn/introduction/) network that `zrok` uses to provide connectivity between users and resources.
 
 Creating `private` shares is easy and is accomplished using the `zrok share private` command. Run `zrok share private` to see the usage output and to further learn how to use the command.
+
+## Private Backend Modes
+
+The default backend mode is `proxy` which targets an HTTP URL that must be reachable by the backend.
+
+```bash title="proxy example"
+zrok share private 80
+```
+
+<BackendHttp/>
+- `tcpTunnel`, `udpTunnel` modes forward the data payload to the target server ([more](/concepts/tunnels.md))
+- `socks` mode provides a SOCKS5 dynamic proxy on the private access bind port that tunnels TCP payloads to the share backend where they are forwarded to their destinations ([blog](https://blog.openziti.io/the-zrok-socks-backend))
+- `vpn` mode provides a network layer tunnel between the private access and the share backend ([guide](guides/vpn/vpn.md))

docs/concepts/sharing-public.mdx

@@ -1,6 +1,9 @@
 ---
 sidebar_position: 10
 ---
+
+import BackendHttp from '/../docs/concepts/_backend_http.mdx'
+
 # Public Shares
 
 `zrok` supports `public` sharing for web-based (HTTP and HTTPS) resources. These resources are easily shared with the general internet through public access points.
@@ -14,3 +17,13 @@ sidebar_position: 10
 As with `private` sharing, `public` sharing does not require you to open any firewall ports or otherwise compromise the security of your local environments. A `public` share goes away as soon as you terminate the `zrok share` command.
 
 Using `public` shares is easy and is accomplished using the `zrok share public` command. Run `zrok share public` to see the command-line help and to learn how to use `public` shares.
+
+## Public Backend Modes
+
+The default backend mode is `proxy` which targets an HTTP URL that must be reachable by the backend.
+
+```bash title="proxy example"
+zrok share public 80
+```
+
+<BackendHttp/>

docs/concepts/sharing-reserved.md

@@ -1,9 +1,10 @@
 ---
 sidebar_position: 10
 ---
+
 # Reserved Shares
 
-By default a `public` or `private` share is assigned a _share token_ when you create a share using the `zrok share` command. The `zrok share` command is the bridge between your local environment and the users you are sharing with. When you terminate the `zrok share`, the bridge is eliminated and the _share token_ is deleted. If you run `zrok share` again, you will be allocated a brand new _share token_.
+By default, a `public` or `private` share is assigned a _share token_ when you create a share using the `zrok share` command. The `zrok share` command is the bridge between your local environment and the users you are sharing with. When you terminate the `zrok share`, the bridge is eliminated and the _share token_ is deleted. If you run `zrok share` again, you will be allocated a brand new _share token_.
 
 You can use a `reserved` share to persist your _share token_ across multiple runs of the `zrok share` bridge. When you use a `reserved` share, the share token will not be deleted between multiple runs of `zrok share`.
 
@@ -12,3 +13,19 @@ To use a `reserved` share, you will first run the `zrok reserve` command to crea
 This pattern works for both `public` and `private` shares, and for all resource types supported by `zrok`.
 
 To delete your `reserved` share use the `zrok release` command or click the delete button in the share's _Actions_ tab in the web console.
+
+## Unique Names
+
+The default is to generate a random _share token_ and you may specify a _unique name_.
+
+This reserves public share token "myshare."
+
+```bash title="Reserve with the Command Line"
+zrok reserve public 80 --unique-name "myshare"
+```
+
+This shares `127.0.0.1:80` as `https://myshare.zrok.example.com` where `https://{token}.zrok.example.com` is the frontend's template.
+
+```bash title="Share a Reserved Token"
+zrok share reserved "myshare"
+```

docs/getting-started.mdx

@@ -67,9 +67,9 @@ The best ways to engage are [Discourse](https://openziti.discourse.group/) for q
 
 Use `zrok` to share a running service, like a web server or a network socket, or to share a directory of static files.
 
-If [sharing publicly](./concepts/sharing-public.md), you can reserve a subdomain, enable authentication options, or both. Public shares proxy HTTPS to your service or files.
+If [sharing publicly](./concepts/sharing-public.mdx), you can reserve a subdomain, enable authentication options, or both. Public shares proxy HTTPS to your service or files.
 
-If [sharing privately](./concepts/sharing-private.md), only users with the share token can access your share. In addition to what you can share publicly, private shares can include TCP and UDP services.
+If [sharing privately](./concepts/sharing-private.mdx), only users with the share token can access your share. In addition to what you can share publicly, private shares can include TCP and UDP services.
 
 ## Installing the zrok Command
 
@@ -245,6 +245,8 @@ If we try to reload the frontend endpoint in our web browser, we'll see:
 
 ![Not Found](images/zrok_not_found.png)
 
+[More about public shares](/concepts/sharing-public.mdx)
+
 ### Private Shares
 
 `zrok` also provides a powerful _private_ sharing model. If I execute the following command:
@@ -263,6 +265,8 @@ Rather than allowing access to your service through a public frontend, a _privat
 
 The `zrok access private wvszln4dyz9q` command can be run by any `zrok` user, allowing them to create and bind a local HTTP listener, that allows for private access to your shared resources.
 
+[More about private shares](/concepts/sharing-private.mdx)
+
 ### Proxy Backend Mode
 
 Without specifying a _backend mode_, the `zrok share` command will assume that you're trying to share a `proxy` resource. A `proxy` resource is usually some private HTTP/HTTPS endpoint (like a development server, or a private application) running in your local environment. Usually such an endpoint would have no inbound connectivity except for however it is reachable from your local environment. It might be running on `localhost`, or only listening on a private LAN segment behind a firewall. 
@@ -320,6 +324,8 @@ $ zrok release mltwsinym1s2
 [   0.230]    INFO main.(*releaseCommand).run: reserved share 'mltwsinym1s2' released
 ```
 
+[More about reserved shares](/concepts/sharing-reserved.md)
+
 ## Concepts Review
 
 In summary, `zrok` lets you easily and securely share resources with both general internet users (through _public_ sharing) and also with other `zrok` users (through _private_ sharing).

docs/guides/docker-share/docker_private_share_guide.md

@@ -12,7 +12,7 @@ Privately share a Docker Compose service with a separate zrok environment and a
 
 With zrok, you can privately share a service that's running in Docker. You need a zrok private share running somewhere that it can reach the service you're sharing, and a zrok private access running somewhere else where you want to use the private share. Together, the private share and private access form a private point-to-point tunnel.
 
-Here's a short article with an overview of [private sharing with zrok](/concepts/sharing-private.md).
+Here's a short article with an overview of [private sharing with zrok](/concepts/sharing-private.mdx).
 
 ## Walkthrough Video
 

docs/guides/docker-share/docker_public_share_guide.md

@@ -12,7 +12,7 @@ Publicly share a Docker Compose service with a separate zrok environment and a p
 
 With zrok, you can publicly share a service that's running in Docker. You need a zrok public share running somewhere that it can reach the service you're sharing. As long as that public share is running and your service is available, anyone with the address can use your service.
 
-Here's a short article with an overview of [public sharing with zrok](/concepts/sharing-public.md).
+Here's a short article with an overview of [public sharing with zrok](/concepts/sharing-public.mdx).
 
 ## Walkthrough Video
 

docs/guides/drives.mdx

@@ -1,4 +1,5 @@
-# The Drives CLI
+
+# Drives
 
 The zrok drives CLI tools allow for simple, ergonomic management and synchronization of local and remote files.
 

docs/guides/install/linux.mdx

@@ -79,7 +79,7 @@ case $(uname -m) in
   ;;
   aarch64|arm64)  GOXARCH=arm64
   ;;
-  arm*)           GOXARCH=arm
+  arm*)           GOXARCH=armv7
   ;;
   *)              echo "ERROR: unknown arch '$(uname -m)'" >&2
                   exit 1

go.mod

@@ -128,7 +128,7 @@ require (
 	github.com/gobwas/httphead v0.1.0 // indirect
 	github.com/gobwas/pool v0.2.1 // indirect
 	github.com/gobwas/ws v1.2.1 // indirect
-	github.com/golang-jwt/jwt/v4 v4.5.0 // indirect
+	github.com/golang-jwt/jwt/v4 v4.5.1 // indirect
 	github.com/golang/glog v1.2.0 // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/golang/snappy v0.0.4 // indirect

go.sum

@@ -329,8 +329,8 @@ github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5x
 github.com/gofrs/uuid v4.0.0+incompatible h1:1SD/1F5pU8p29ybwgQSwpQk+mwdRrXCYuPhW6m+TnJw=
 github.com/gofrs/uuid v4.0.0+incompatible/go.mod h1:b2aQJv3Z4Fp6yNu3cdSllBxTCLRxnplIgP/c0N/04lM=
 github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
-github.com/golang-jwt/jwt/v4 v4.5.0 h1:7cYmW1XlMY7h7ii7UhUyChSgS5wUJEnm9uZVTGqOWzg=
-github.com/golang-jwt/jwt/v4 v4.5.0/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0=
+github.com/golang-jwt/jwt/v4 v4.5.1 h1:JdqV9zKUdtaa9gdPlywC3aeoEsR681PlKC+4F5gQgeo=
+github.com/golang-jwt/jwt/v4 v4.5.1/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0=
 github.com/golang-jwt/jwt/v5 v5.2.1 h1:OuVbFODueb089Lh128TAcimifWaLhJwVflnrgM17wHk=
 github.com/golang-jwt/jwt/v5 v5.2.1/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
 github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q=

nfpm/zrok-share.bash

@@ -217,12 +217,14 @@ else
     echo "ERROR: invalid JSON in $(realpath ~/.zrok)/reserved.json" >&2
     exit 1
   else
-    ZROK_PUBLIC_URLS=$(jq -cr '.frontend_endpoints' ~/.zrok/reserved.json 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
-      exit 1
-    else
-      echo "INFO: zrok public URLs: ${ZROK_PUBLIC_URLS}"
+    if [[ "${ZROK_FRONTEND_MODE:-}" == reserved-public ]]; then
+      ZROK_PUBLIC_URLS=$(jq -cr '.frontend_endpoints' ~/.zrok/reserved.json 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
+        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

website/docusaurus.config.js

@@ -7,7 +7,7 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula');
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: 'Zrok',
-  staticDirectories: ['static', '../docs/images', '../docker/compose'],
+  staticDirectories: ['static', '../docs/images', '../docker/compose', '../etc/caddy'],
   tagline: 'Globally distributed reverse proxy',
   url: 'https://docs.zrok.io',
   baseUrl: '/',

website/package.json

@@ -14,9 +14,9 @@
     "write-heading-ids": "docusaurus write-heading-ids"
   },
   "dependencies": {
-    "@docusaurus/core": "^3.5.2",
-    "@docusaurus/plugin-client-redirects": "^3.5.2",
-    "@docusaurus/preset-classic": "^3.5.2",
+    "@docusaurus/core": "^3.6.0",
+    "@docusaurus/plugin-client-redirects": "^3.6.0",
+    "@docusaurus/preset-classic": "^3.6.0",
     "@mdx-js/react": "^3.0.1",
     "clsx": "^1.2.1",
     "prism-react-renderer": "^1.3.5",
@@ -26,7 +26,7 @@
     "remark-math": "^5.1.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^3.5.2",
+    "@docusaurus/module-type-aliases": "^3.6.0",
     "yaml-loader": "^0.8.0"
   },
   "browserslist": {