mirror of
https://github.com/openziti/zrok.git
synced 2025-02-24 14:11:37 +01:00
Merge pull request #355 from openziti/v0.4.0_tunnel_docs
Docs Site Updates (Tunnels) (#336)
This commit is contained in:
Michael Quigley
GitHub
commit
5b7ff0968d
50
docs/concepts/files.md
Normal file
50
docs/concepts/files.md
Normal file
@ -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` 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
|
||||
<html>
|
||||
<body>
|
||||
<h1>Hello <code>zrok</code></h1>
|
||||
</html>
|
||||
```
|
||||
|
||||
Sharing the directory will result in the following when you access the share in a web browser:
|
||||
|
||||
|
||||
|
||||
`zrok` contains a built-in web server, which you can use to serve static websites as a share.
|
||||
32
docs/concepts/http.md
Normal file
32
docs/concepts/http.md
Normal file
@ -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.
|
||||
12
docs/concepts/index.md
Normal file
12
docs/concepts/index.md
Normal file
@ -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).
|
||||
@ -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!
|
||||
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!
|
||||
29
docs/concepts/sharing-private.md
Normal file
29
docs/concepts/sharing-private.md
Normal file
@ -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
|
||||
|
||||
|
||||
|
||||
`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.
|
||||
16
docs/concepts/sharing-public.md
Normal file
16
docs/concepts/sharing-public.md
Normal file
@ -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
|
||||
|
||||
|
||||
|
||||
`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.
|
||||
14
docs/concepts/sharing-reserved.md
Normal file
14
docs/concepts/sharing-reserved.md
Normal file
@ -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.
|
||||
85
docs/concepts/tunnels.md
Normal file
85
docs/concepts/tunnels.md
Normal file
@ -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`.
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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).
|
||||
@ -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
|
||||
|
||||
|
||||
|
||||
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`.
|
||||
@ -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
|
||||
|
||||
|
||||
|
||||
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.
|
||||
@ -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.
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 15 KiB |
BIN
docs/images/zrok_share_web_files.png
Executable file
BIN
docs/images/zrok_share_web_files.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
BIN
docs/images/zrok_share_web_website.png
Executable file
BIN
docs/images/zrok_share_web_website.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Loading…
Reference in New Issue
Block a user