diff --git a/docs/guides/v0.4_limits.md b/docs/_attic/v0.4_limits.md similarity index 100% rename from docs/guides/v0.4_limits.md rename to docs/_attic/v0.4_limits.md diff --git a/docs/concepts/files.md b/docs/concepts/files.md new file mode 100644 index 00000000..91d6a0e7 --- /dev/null +++ b/docs/concepts/files.md @@ -0,0 +1,50 @@ +--- +sidebar_position: 30 +--- +# Sharing Websites and Files + +With `zrok` it is possible to share files quickly and easily as well. To share files using `zrok` use +the `--backend-mode web`, for example: `zrok share private . --backend-mode web`. + +Running with this mode will make it trivially easy to share files from the directory which the command +was run from. + +For example if you have a directory with a structure like this: +```shell +-rw-r--r--+ 1 Michael None 7090 Apr 17 12:53 CHANGELOG.md +-rw-r--r--+ 1 Michael None 11346 Apr 17 12:53 LICENSE +-rw-r--r--+ 1 Michael None 2885 Apr 17 12:53 README.md +-rwxr-xr-x+ 1 Michael None 44250624 Apr 17 13:00 zrok.exe* +``` + +The files can be shared using a command such as: +```shell +zrok share public --backend-mode web . +``` + +Then the files can be access with a `private` or `public` share, for example as shown: + +![zrok_share_web_files](../images/zrok_share_web_files.png) + +`zrok` will automatically provide a stock website, which will allow the accessing user to browse and navigate the file tree. Clicking the files allows the user to download them. + +`zrok` can also share a pre-rendered static HTML website. If you have a directory like this: + +```shell +-rw-rw-r--+ 1 Michael None 56 Jun 26 13:23 index.html +``` + +If `index.html` contains valid HTML, like this: + +```html + + +

Hello zrok

+ +``` + +Sharing the directory will result in the following when you access the share in a web browser: + +![zrok_share_web_website](../images/zrok_share_web_website.png) + +`zrok` contains a built-in web server, which you can use to serve static websites as a share. \ No newline at end of file diff --git a/docs/core-features/hosting.md b/docs/concepts/hosting.md similarity index 100% rename from docs/core-features/hosting.md rename to docs/concepts/hosting.md diff --git a/docs/concepts/http.md b/docs/concepts/http.md new file mode 100644 index 00000000..a8ac241b --- /dev/null +++ b/docs/concepts/http.md @@ -0,0 +1,32 @@ +--- +sidebar_position: 22 +--- + +# Sharing HTTP Servers + +`zrok` can share HTTP and HTTPS resources natively. If you have an existing web server that you want to share with other users, you can use the `zrok share` command using the `--backend-mode proxy` flag. + +The `--backend-mode proxy` is the default backend mode, so if you do not specify a `--backend-mode` you will get the `proxy` mode by default. + +If you have a web server running on `localhost` that you want to expose to other users using `zrok`, you can execute a command like the following: + +``` +$ zrok share public localhost:8080 +``` +When you execute this command, you'll get a `zrok` bridge like the following: + +``` +╭───────────────────────────────────────────────────────────────╮╭────────────────╮ +│ http://cht7gj4g5pjf.share.zrok.io ││[PUBLIC] [PROXY]│ +╰───────────────────────────────────────────────────────────────╯╰────────────────╯ +╭─────────────────────────────────────────────────────────────────────────────────╮ +│ │ +│ │ +│ │ +│ │ +╰─────────────────────────────────────────────────────────────────────────────────╯ +``` + +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 diff --git a/docs/concepts/index.md b/docs/concepts/index.md new file mode 100644 index 00000000..3f49930b --- /dev/null +++ b/docs/concepts/index.md @@ -0,0 +1,12 @@ +--- +sidebar_title: Core Features +sidebar_position: 25 +--- +# Concepts + +`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). +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/self_hosting_guide.md). \ No newline at end of file diff --git a/docs/core-features/opensource.md b/docs/concepts/opensource.md similarity index 65% rename from docs/core-features/opensource.md rename to docs/concepts/opensource.md index 29d0a070..77796909 100644 --- a/docs/core-features/opensource.md +++ b/docs/concepts/opensource.md @@ -3,24 +3,21 @@ sidebar_position: 100 --- # Open Source -It's important to the `zrok` project that it remain free and open source software. The code is available on GitHub +It's important to the `zrok` project that it remain free and open source software. The code is available on [GitHub](https://github.com/openziti/zrok) for the world to use, inspect, and build upon! Check out the repository over on GitHub at https://github.com/openziti/zrok. If you find `zrok` to be useful, and you want to help spread the word of `zrok` give the project a star. It really does help get the word out about the project. -The project also uses a very permissive license: Apache v2. We encourage people to fork the repo and use `zrok` for -your own purposes how you see fit or contribute back to the project. +The project also uses a very permissive license: Apache v2. We encourage people to fork the repo and use `zrok` for your own purposes how you see fit or contribute back to the project. ## Built on OpenZiti The power of `zrok` really lies in `private` sharing. It's increasingly clear that security needs to be a first-class -member of any organization. To enable `private` sharing, `zrok` was built on top of another excellent open source -project named OpenZiti. +member of any organization. To enable `private` sharing, `zrok` was built on top of another excellent open source project named OpenZiti. OpenZiti is a secure overlay network focusing on bringing zero trust to applications. It is the __backbone__ of `zrok`. -In fact, `zrok` proudly proclaims itself as an OpenZiti _native_ application. +In fact, `zrok` proudly proclaims itself as an Ziti _native_ application. -If you are interested in learning more about OpenZiti head over to [the docs](https://docs.openziti.io/docs/learn/introduction/), -try the quickstart, and don't forget to star that project too. We couldn't build `zrok` without OpenZiti! \ No newline at end of file +If you are interested in learning more about OpenZiti head over to [the docs](https://docs.openziti.io/docs/learn/introduction/), try the quickstart, and don't forget to star that project too. We couldn't build `zrok` without OpenZiti! \ No newline at end of file diff --git a/docs/concepts/sharing-private.md b/docs/concepts/sharing-private.md new file mode 100644 index 00000000..642c22ae --- /dev/null +++ b/docs/concepts/sharing-private.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 0 +--- +# Private Shares + +`zrok` was built to share and access digital resources. A `private` share allows a resource to be +accessed on another user's system as if it were local to them. Privately shared resources can only be accessed by another `zrok` user who has the details of your unique share. You are in control of who can access your `private` shares by sharing the the share token. + +Peer-to-peer private resource sharing is one of the things that makes `zrok` unique. + +`zrok` also provides `public` sharing of resources with non-`zrok` users. Public resource sharing is limited to only resources that can be accessed over `HTTP` or `HTTPS`. `private` sharing works with all of the resources types that `zrok` supports. + +Here's how private sharing works: + +# Peer to Peer + +![zrok_public_share](../images/zrok_private_share.png) + +`private` shares are accessed using the `zrok access` command, and require the accessing user to have a `zrok enable`-d account on the same service instance where the share was created. + +The `private` share is identified by a _share token_. The accessing user will use the share token, along with the `zrok access` command to create a local endpoint on their system, which lets them use the shared resource as if it were local to their system. + +`zrok` does not require you to open any firewall ports or otherwise compromise the security of your local system; there is never an attack surface open to the public internet. As soon as you terminate the `zrok share` process, you immediately terminate any possible access to your shared resource. + +The shared resource can be a development web server to share with friends and colleagues, a webhook from a server running in the cloud which has `zrok` running and has been instructed to `access` the private resource. `zrok` can also share files, websites, and low-level TCP and UDP network connections using the `tunnel` backend. What matters is that the access to the shared resource is not done in a public way, and can only be accessed by other `zrok` users that have access to your share token. + +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. \ No newline at end of file diff --git a/docs/concepts/sharing-public.md b/docs/concepts/sharing-public.md new file mode 100644 index 00000000..fc403bbc --- /dev/null +++ b/docs/concepts/sharing-public.md @@ -0,0 +1,16 @@ +--- +sidebar_position: 10 +--- +# 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. + +## Peer to Public + +![zrok_public_share](../images/zrok_public_share.png) + +`public` sharing is most useful when the person or service accessing your resources does not have `zrok` running locally and cannot make use of the `private` sharing mode built into `zrok`. Many users share development web servers, webhooks, and other HTTP/HTTPS resources. + +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 diff --git a/docs/concepts/sharing-reserved.md b/docs/concepts/sharing-reserved.md new file mode 100644 index 00000000..5f0410fb --- /dev/null +++ b/docs/concepts/sharing-reserved.md @@ -0,0 +1,14 @@ +--- +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_. + +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`. + +To use a `reserved` share, you will first run the `zrok reserve` command to create the reserved share (see `zrok reserve --help` for details). Once you've created your `reserved` share, you will use the `zrok share reserved` command (see `--help` for details) to run the bridge for the shared resource. + +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. diff --git a/docs/concepts/tunnels.md b/docs/concepts/tunnels.md new file mode 100644 index 00000000..ac2bbc36 --- /dev/null +++ b/docs/concepts/tunnels.md @@ -0,0 +1,85 @@ +--- +sidebar_position: 25 +--- + +# Sharing TCP and UDP Servers + +`zrok` includes support for sharing low-level TCP and UDP network resources using the `tcpTunnel` and `udpTunnel` backend modes. + +As of version `v0.4`, `zrok` supports sharing TCP and UDP network resources using `private` sharing. + +To share a raw network resource using `zrok`, you'll want to use the `zrok share private` command from your `enable`-d environment, like this: + +``` +$ zrok share private --backend-mode tcpTunnel 192.168.9.1:22 +``` + +This will result in a share client starting, which looks like this: + +``` +╭───────────────────────────────────────────────────────────╮╭────────────────────╮ +│ access your share with: zrok access private 5adagwfl888k ││[PRIVATE][TCPTUNNEL]│ +╰───────────────────────────────────────────────────────────╯╰────────────────────╯ +╭─────────────────────────────────────────────────────────────────────────────────╮ +│ │ +│ │ +│ │ +│ │ +╰─────────────────────────────────────────────────────────────────────────────────╯ +``` + +Then on the system where you want to access your shared resource (an SSH endpoint in this case), you'll need an `enable`-d `zrok` environment. Run the following command (shown in the banner at the top of the `zrok share` client above): + +``` +$ zrok access private 5adagwfl888k +``` + +This will start an `access` client on this system: +``` +╭─────────────────────────────────────────────────────────────────────────────────╮ +│ tcp://127.0.0.1:9191 -> 5adagwfl888k │ +╰─────────────────────────────────────────────────────────────────────────────────╯ +╭─────────────────────────────────────────────────────────────────────────────────╮ +│ │ +│ │ +│ │ +│ │ +╰─────────────────────────────────────────────────────────────────────────────────╯ +``` + +The `access` client shows the endpoint at the top where the service can be accessed. In this case, you'll want to connect your SSH client to `127.0.0.1:9191`. We'll just use `nc` (netcat) to access the shared TCP port: +``` +$ nc 127.0.0.1 9191 +SSH-2.0-OpenSSH_9.2 FreeBSD-openssh-portable-9.2.p1,1 +``` + +And both the `share` client and the `access` client show the traffic: + +``` +╭──────────────────────────────────────────────────────────╮╭─────────────────────╮ +│ access your share with: zrok access private 5adagwfl888k ││[PRIVATE] [TCPTUNNEL]│ +╰──────────────────────────────────────────────────────────╯╰─────────────────────╯ +╭─────────────────────────────────────────────────────────────────────────────────╮ +│Friday, 23-Jun-23 15:33:10 EDT ziti-edge-router │ +│connId=2147483648, logical=ziti- │ +│sdk[router=tls:ziti-lx:3022] -> ACCEPT 192.168.9.1:22 │ +│ │ +│ │ +╰─────────────────────────────────────────────────────────────────────────────────╯ +``` + +``` +╭─────────────────────────────────────────────────────────────────────────────────╮ +│ tcp://127.0.0.1:9191 -> 5adagwfl888k │ +╰─────────────────────────────────────────────────────────────────────────────────╯ +╭─────────────────────────────────────────────────────────────────────────────────╮ +│Friday, 23-Jun-23 15:33:10 EDT 127.0.0.1:42312 -> ACCEPT 5adagwfl888k │ +│ │ +│ │ +│ │ +╰─────────────────────────────────────────────────────────────────────────────────╯ +``` + +Exit the `access` client to remove the local access to the shared TCP port. Exit the `share` client to disable further accesses to the shared resource. + +For UDP network resources just use the `zrok share private --backend-mode udpTunnel` instead of `tcpTunnel`. diff --git a/docs/core-features/files.md b/docs/core-features/files.md deleted file mode 100644 index 070acb86..00000000 --- a/docs/core-features/files.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -sidebar_position: 30 ---- -# File Sharing - -With `zrok` it is possible to share files quickly and easily as well. To share files using `zrok` use -the `--backend-mode web`, for example: `zrok share private . --backend-mode web`. - -Running with this mode will make it trivially easy to share files from the directory which the command -was run from. - -For example if you have a directory with a structure like this: -```shell --rwxrwxrwx 1 cd cd 2506 Jan 26 11:57 README.md --rwxrwxrwx 1 cd cd 2971 Jan 26 11:57 CHANGELOG.md --rwxrwxrwx 1 cd cd 41544024 Jan 26 12:00 zrok -``` - -The files can be shared using a command such as: -```shell -zrok share public . --backend-mode web -``` - -Then the files can be access with a `private` or `public` share, for example as shown: - -![zrok_public_share](../images/zrok_share_file.png) \ No newline at end of file diff --git a/docs/core-features/index.md b/docs/core-features/index.md deleted file mode 100644 index f0d4ec31..00000000 --- a/docs/core-features/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_title: Core Features -sidebar_position: 25 ---- -# Core Features - -`zrok` was built for sharing resources. This doc is meant to explain the core features of `zrok` sharing -as well as other important features. - -Sharing with `zrok` can be either [`public`](./sharing-public.md) or [`private`](./sharing-private.md). -Naturally, regular web-based resources can be shared but `zrok` also includes a [file sharing](./files.md) feature. - -Learn about `zrok` [hosting here](./hosting.md). \ No newline at end of file diff --git a/docs/core-features/sharing-private.md b/docs/core-features/sharing-private.md deleted file mode 100644 index a756e97d..00000000 --- a/docs/core-features/sharing-private.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_position: 0 ---- -# Shares - Private - -`zrok` was built to share and access digital resources. A `private` share allows a resource to be -shared through a __privately__ available endpoint. Sharing a resource with `private` is __a differentiating__ -feature of `zrok`. - -# Peer to Peer - -![zrok_public_share](../images/zrok_private_share.png) - -A `private` share will require `zrok` to access the share and will also require a special shared -secret token. This access token, combined with the `zrok access` command will be how the private share is accessed. - -Sharing something with `private` is similar to sharing something publicly. The main difference is -obvious, the shared resource is `private` and the share is __not__ open to the public. With `zrok`, you -can share resources on a private network without needing to expose the service to the internet. The share is not -through an obfuscated, difficult to guess url. Instead the sharing is accomplished using a secure, zero trust overlay -network provided by [OpenZiti](https://docs.openziti.io/docs/learn/introduction/). With this private, peer to peer -sharing model, there will never an attack surface available to the open internet. - -The shared resource can be a development web server to share with friends and colleagues or perhaps, -it could be a webhook from a server running in the cloud which has `zrok` running and has been instructed -to `access` the private resource. What matters is that the access to the shared resource __should not__ -be done in a public way, for more secure access. - -Using `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. - -Unlike public shares, `private` shares do not need to be [reserved](./sharing-reserved.md) to be predictable. When sharing a -resource with `private`, the resource is shared at a known location. Resources shared with `private` do not -need to be `reserved`. \ No newline at end of file diff --git a/docs/core-features/sharing-public.md b/docs/core-features/sharing-public.md deleted file mode 100644 index d3eeb55f..00000000 --- a/docs/core-features/sharing-public.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_position: 10 ---- -# Shares - Public - -`zrok` was built to share and access digital resources. a `public` share allows something to be shared through -a publicly available endpoint. - -## Public Sharing - -![zrok_public_share](../images/zrok_public_share.png) - -Sharing something with `public` is useful when the person or service accessing the thing being shared doesn't -have `zrok` running locally and can't make use of the `private` sharing mode built into `zrok`. This could be -a development web server to share with friends and colleagues, or perhaps a webhook from a -server running in the cloud which can't have `zrok` installed onto it. What matters is that the access to the -shared resource needs to be done in a public way, generally for easy access. - -Using `public` shares is easy and is accomplished using the `zrok share public` command. Run `zrok share public` -to see the usage output and to further learn how to use the command. - -Unless `reserved` (see [Sharing - Reserved](./sharing-reserved.md), all 'public' shares are ephemeral. When the -sharing is stopped, the shared url will be reclaimed. \ No newline at end of file diff --git a/docs/core-features/sharing-reserved.md b/docs/core-features/sharing-reserved.md deleted file mode 100644 index b111d12d..00000000 --- a/docs/core-features/sharing-reserved.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_position: 10 ---- -# Shares - Reserved - -`zrok` was built to share and access digital resources. A `reserved` share allows the user to have a reliable, -public, persistent shared url. (the share name not ephemeral, it is `reserved`). This means that the share -will be able to be used and regardless of how many times the resource is shared. This is useful when the -url must be known. - -Use the `zrok reserve` command to create a reserved share. diff --git a/docs/getting-started.md b/docs/getting-started.md index 35ba9b9b..7ab2fe79 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -7,8 +7,8 @@ sidebar_position: 0 As of version `v0.4.0`, `zrok` provides the ability to: -* share resources [publicly](./core-features/sharing-public.md), similar to other distributed reverse proxies; this allows you to easily expose your private HTTP/S resources to the public internet without changing your network security -* share resources [privately](./core-features/sharing-private.md); private sharing uses peer-to-peer connectivity between two parties by leveraging the OpenZiti overlay. We believe the private sharing offered by `zrok` provides a unique level of security and privacy for this type of sharing. +* share resources [publicly](./concepts/sharing-public.md), similar to other distributed reverse proxies; this allows you to easily expose your private HTTP/S resources to the public internet without changing your network security +* share resources [privately](./concepts/sharing-private.md); private sharing uses peer-to-peer connectivity between two parties by leveraging the OpenZiti overlay. We believe the private sharing offered by `zrok` provides a unique level of security and privacy for this type of sharing. As of version `v0.4.0`, `zrok` allows sharing these kinds of resources: diff --git a/docs/guides/self-hosting/self_hosting_guide.md b/docs/guides/self-hosting/self_hosting_guide.md index 0ee17a35..04e8ddaf 100644 --- a/docs/guides/self-hosting/self_hosting_guide.md +++ b/docs/guides/self-hosting/self_hosting_guide.md @@ -81,6 +81,14 @@ The `store` section defines the local `sqlite3` database used by the controller. The `ziti` section defines how the `zrok` controller should communicate with your OpenZiti installation. When using the OpenZiti quickstart, an administrative password will be generated; the `password` in the `ziti` stanza should reflect this password. +:::note + +Be sure to see the [reference configuration at `etc/ctrl.yml`](../../../etc/ctrl.yml) for the complete documentation of the current configuration file format for the `zrok` controller and service instance components. + +See the separate guides on [configuring metrics](../metrics-and-limits/configuring-metrics.md) and [configuring limits](../metrics-and-limits/configuring-limits.md) for details about both of these specialized areas of service instance configuration. + +::: + ## Environment Variables The `zrok` binaries are configured to work with the global `zrok.io` service, and default to using `api.zrok.io` as the endpoint for communicating with the service. diff --git a/docs/images/zrok_share_file.png b/docs/images/zrok_share_file.png deleted file mode 100644 index 19f0d4c2..00000000 Binary files a/docs/images/zrok_share_file.png and /dev/null differ diff --git a/docs/images/zrok_share_web_files.png b/docs/images/zrok_share_web_files.png new file mode 100755 index 00000000..5d558fbf Binary files /dev/null and b/docs/images/zrok_share_web_files.png differ diff --git a/docs/images/zrok_share_web_website.png b/docs/images/zrok_share_web_website.png new file mode 100755 index 00000000..9facc7e4 Binary files /dev/null and b/docs/images/zrok_share_web_website.png differ