diff --git a/CHANGELOG.md b/CHANGELOG.md index c71db275..c0d8cc97 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,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. @@ -228,7 +230,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..1b06e694 --- /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](/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)) diff --git a/docs/concepts/http.md b/docs/concepts/http.md index a8ac241b..19c9945e 100644 --- a/docs/concepts/http.md +++ b/docs/concepts/http.md @@ -29,4 +29,4 @@ When you execute this command, you'll get a `zrok` bridge like the following: The URL shown at the top of the bridge shows the address where you can access your `public` share. -Hit `CTRL-C` or `q` in the bridge to exit it and delete the `public` share. \ No newline at end of file +Hit `CTRL-C` or `q` in the bridge to exit it and delete the `public` share. diff --git a/docs/concepts/index.md b/docs/concepts/index.md index 59f8b058..eb92da7c 100644 --- a/docs/concepts/index.md +++ b/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). diff --git a/docs/concepts/sharing-private.md b/docs/concepts/sharing-private.mdx similarity index 77% rename from docs/concepts/sharing-private.md rename to docs/concepts/sharing-private.mdx index 6937a747..4a23ed5e 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,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 +``` + + +- `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)) diff --git a/docs/concepts/sharing-public.md b/docs/concepts/sharing-public.mdx similarity index 74% rename from docs/concepts/sharing-public.md rename to docs/concepts/sharing-public.mdx index 858b78bf..0e6f1e26 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,14 @@ 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. + +## 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 +``` + + diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx index b29cb326..0b577fea 100644 --- a/docs/getting-started.mdx +++ b/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). diff --git a/docs/guides/docker-share/docker_private_share_guide.md b/docs/guides/docker-share/docker_private_share_guide.md index 1d7eda86..e9102f4a 100644 --- a/docs/guides/docker-share/docker_private_share_guide.md +++ b/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 diff --git a/docs/guides/docker-share/docker_public_share_guide.md b/docs/guides/docker-share/docker_public_share_guide.md index 1d534a94..e4c5af1d 100644 --- a/docs/guides/docker-share/docker_public_share_guide.md +++ b/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 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: '/',