From 595a1d65c4bcfaf89e5269028e6e0fb674d4aae9 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Thu, 7 Nov 2024 17:19:23 -0500 Subject: [PATCH] briefly mention backend modes that apply to public and private share concepts --- CHANGELOG.md | 4 +++- docs/concepts/_backend_http.mdx | 5 ++++ ...sharing-private.md => sharing-private.mdx} | 23 ++++++++++++++++++- .../{sharing-public.md => sharing-public.mdx} | 19 ++++++++++++++- docs/guides/{drives/cli.md => drives.mdx} | 3 ++- website/docusaurus.config.js | 2 +- 6 files changed, 51 insertions(+), 5 deletions(-) create mode 100644 docs/concepts/_backend_http.mdx rename docs/concepts/{sharing-private.md => sharing-private.mdx} (79%) rename docs/concepts/{sharing-public.md => sharing-public.mdx} (71%) rename docs/guides/{drives/cli.md => drives.mdx} (99%) diff --git a/CHANGELOG.md b/CHANGELOG.md index dbc56450..0e8d8a8e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ FIX: reduce Docker image sizes (https://github.com/openziti/zrok/pull/783) 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. @@ -226,7 +228,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. diff --git a/docs/concepts/_backend_http.mdx b/docs/concepts/_backend_http.mdx new file mode 100644 index 00000000..085a8aa7 --- /dev/null +++ b/docs/concepts/_backend_http.mdx @@ -0,0 +1,5 @@ + +- `proxy` mode forwards requests received by the frontend to the target server ([more](/getting-started.mdx#proxy-backend-mode)) +- `web` mode serves a target folder as a file index web page ([more](/getting-started.mdx#web-backend-mode)) +- `drive` mode serves a target folder with WebDAV ([more](/guides/drives.mdx)) +- `caddy` mode runs the built-in Caddy server with the targeted Caddyfile ([example](pathname:///simple_reverse_proxy.Caddyfile)) diff --git a/docs/concepts/sharing-private.md b/docs/concepts/sharing-private.mdx similarity index 79% rename from docs/concepts/sharing-private.md rename to docs/concepts/sharing-private.mdx index 6937a747..4425fc7a 100644 --- a/docs/concepts/sharing-private.md +++ b/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,21 @@ 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. + +## 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 +``` + +### HTTP Modes + + + +### Networking Modes + +- `tcpTunnel`, `udpTunnel` modes forward the data payload to the target server +- `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 +- `vpn` mode provides a network layer tunnel between the private access and the share backend diff --git a/docs/concepts/sharing-public.md b/docs/concepts/sharing-public.mdx similarity index 71% rename from docs/concepts/sharing-public.md rename to docs/concepts/sharing-public.mdx index 858b78bf..8303d5eb 100644 --- a/docs/concepts/sharing-public.md +++ b/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. @@ -13,4 +16,18 @@ 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. \ No newline at end of file +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. + +## 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 +``` + +Public shares support any of zrok's HTTP modes. + +### HTTP Modes + + diff --git a/docs/guides/drives/cli.md b/docs/guides/drives.mdx similarity index 99% rename from docs/guides/drives/cli.md rename to docs/guides/drives.mdx index 84249a30..1b4fe345 100644 --- a/docs/guides/drives/cli.md +++ b/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. diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index e201d23f..270db7dd 100644 --- a/website/docusaurus.config.js +++ b/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: '/',