Merge branch 'main' of github.com:openziti/zrok

README.md

@@ -1,6 +1,6 @@
 ![zrok](docs/images/zrok.png)
 
-`zrok` is a next-generation sharing platform built on top of [OpenZiti](https://docs.openziti.io), a programmable zero-trust network overlay. `zrok` is an OpenZiti _Native Application_.
+`zrok` is a next-generation sharing platform built on top of [OpenZiti](https://docs.openziti.io/docs/learn/introduction/), a programmable zero-trust network overlay. `zrok` is an OpenZiti _Native Application_.
 
 `zrok` facilitates sharing resources both publicly and privately, exposing them to an audience you can easily control.
 

docs/core-features/files.md

@@ -0,0 +1,26 @@
+---
+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)

docs/core-features/hosting.md

@@ -0,0 +1,15 @@
+---
+sidebar_position: 200
+---
+# Hosting
+
+## Self-Hosted
+
+`zrok` is not limited to a managed offering. You can host your own version of `zrok` as well. `zrok` is
+also freely available as open source software hosted by GitHub under a very permissive Apache v2 license.
+
+## Managed Service
+
+`zrok` is also offered as a cloud service, making it instantly accessible to a large population immediately.
+NetFoundry provides a manged version of `zrok` at https://zrok.io. This provides the easy-to-use,
+quick to demonstrate features of `zrok` without needing to deploy and host `zrok` yourself.

docs/core-features/index.md

@@ -0,0 +1,13 @@
+---
+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). 

docs/core-features/opensource.md

@@ -0,0 +1,26 @@
+---
+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
+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.
+
+## 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. 
+
+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.
+
+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!

docs/core-features/sharing-private.md

@@ -0,0 +1,34 @@
+---
+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`.

docs/core-features/sharing-public.md

@@ -0,0 +1,23 @@
+---
+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.

docs/core-features/sharing-reserved.md

@@ -0,0 +1,11 @@
+---
+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.

docs/getting-started.md

@@ -3,17 +3,31 @@ sidebar_position: 0
 ---
 # Getting Started with zrok
 
-`zrok` is a next-generation sharing platform built on top of [OpenZiti](https://github.com/openziti/ziti/stargazers), a programmable zero trust network overlay. `zrok` is an _OpenZiti Native Application_.
+`zrok` is an open source, Apache v2 licensed sharing platform, built on top of [OpenZiti](https://docs.openziti.io/docs/learn/introduction/), 
+a programmable zero trust network overlay. `zrok` is an _OpenZiti Native Application_. You can choose to self-host `zrok`
+or leverage the free, managed offering provided by NetFoundry: https://zrok.io
 
-`zrok` facilitates sharing resources publicly and privately with an audience of your choosing.
+As of version `v0.3.0`, `zrok` provides the ability to:
 
-As of version `v0.3.0`, `zrok` provides users the ability to publicly proxy local HTTP endpoints (similar to other offerings in this space). Additionally, `zrok` provides the ability to:
-
-* _privately_ share resources with other `zrok` users; in _private_ usage scenarios, your private resources are not exposed to any public endpoints, and all communication is securely and privately transported between `zrok` clients
+* share resources [publicly](./core-features/sharing-public.md), similar to other distributed reverse proxies.
+* share [privately](./core-features/sharing-private.md). It does this by leveraging
+  [OpenZiti](https://docs.openziti.io/docs/learn/introduction/) to support zero trust, peer to peer connections without
+  the need for any open ports on the internet.
 * use `web` sharing; easily share files with others using a single `zrok` command
 
 Let's take a look at how to get started with `zrok`.
 
+:::note `zrok` moves fast!
+
+`zrok` is currently in a closed-beta phase and requires an invitation token. If you would like to try `zrok` and provide
+feedback, please send an email to [email protected]. `zrok` is an open source project and is in its early development
+phases. We're doing our development publicly. See the [roadmap](https://github.com/orgs/openziti/projects/16) for details
+about the project. We are highly interested in feedback as we continue to iterate quickly. Please provide feedback in
+[Discourse](https://openziti.discourse.group/), raise [GitHub Issues](https://github.com/openziti/zrok/issues), or reach
+out directly.
+
+:::
+
 ## Downloading zrok
 
 Releases are also available from the `zrok` project repository on GitHub at https://github.com/openziti/zrok/releases/latest
@@ -418,5 +432,5 @@ You use the `zrok reserve` command to create _reserved shares_. Reserved shares
 
 Interested in self-hosting your own `zrok` service instance? See the [self-hosting guide](guides/v0.3_self_hosting_guide.md) for details.
 
-[openziti]: https://docs.openziti.io/	"OpenZiti"
+[openziti]: https://docs.openziti.io/docs/learn/introduction/	"OpenZiti"
 [ zrok-download]: https://zrok.io "Zrok Download"

docs/guides/v0.3_self_hosting_guide.md

@@ -1,16 +1,17 @@
 # Self-Hosting Guide
 
-## OpenZiti Quickstart
+## Before you Begin
 
-https://openziti.github.io/docs/quickstarts/network/
+This will get you up and running with a self-hosted instance of zrok. I'll assume you have the following:
 
-I specifically used the "no docker" variant:
+* a Linux server with a public IP
+* a wildcard DNS record like `*.zrok.quigley.com` that resolves to the server IP
 
-```bash
-$ source /dev/stdin <<< "$(wget -qO- https://get.openziti.io/quick/ziti-cli-functions.sh)"; expressInstall
-$ startController
-$ startRouter
-```
+## OpenZiti Quickstart
+
+The first step is to log in to your Linux server and run the OpenZiti quickstart. This will install a Ziti controller and Ziti router as systemd services.
+
+I specifically used the "Host OpenZiti Anywhere" variant because it provides a public controller. We'll need that to use zrok with multiple devices across different networks.
 
 Keep track of the generated admin password when running the `expressInstall` script. The script will prompt you like this:
 
@@ -19,6 +20,12 @@ Do you want to keep the generated admin password 'XO0xHp75uuyeireO2xmmVlK91T7B9f
 ```
 You'll need that generated password (`XO0xHp75uuyeireO2xmmVlK91T7B9fpD`) when building your `zrok` controller configuration.
 
+BEGIN: [Run the OpenZiti Quickstart](https://docs.openziti.io/docs/learn/quickstarts/network/hosted)
+
+## Install zrok
+
+Download [the latest release](https://github.com/openziti/zrok/releases/latest) from GitHub.
+
 ## Configure the Controller
 
 Create a controller configuration file in `etc/ctrl.yml`. The controller does not provide server TLS, but you may front the server with a reverse proxy. This example will expose the non-TLS listener for the controller.
@@ -30,7 +37,7 @@ Create a controller configuration file in `etc/ctrl.yml`. The controller does no
 #   /___|_|  \___/|_|\_\
 # controller configuration
 
-v:                  1
+v:                  2
 
 admin:
   secrets:
@@ -62,12 +69,12 @@ The `ziti` section defines how the `zrok` controller should communicate with you
 
 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.
 
-To work with a local `zrok` deployment, you'll need to set the `ZROK_API_ENDPOINT` environment variable to point to the address where your `zrok` controller will be listening, according to `endpoint` in the configuration file above.
+To work with a self-hosted `zrok` deployment, you'll need to set the `ZROK_API_ENDPOINT` environment variable to point to the address where your `zrok` controller will be listening, according to `endpoint` in the configuration file above.
 
 In my case, I've set:
 
 ```bash
-$ export ZROK_API_ENDPOINT=http://localhost:18080
+export ZROK_API_ENDPOINT=http://localhost:18080
 ```
 
 ## Bootstrap OpenZiti for zrok
@@ -113,6 +120,8 @@ Notice this warning:
 [   0.120] WARNING zrok/controller.Bootstrap: missing public frontend for ziti id 'sqJRAINSiB'; please use 'zrok admin create frontend sqJRAINSiB public https://{token}.your.dns.name' to create a frontend instance
 ```
 
+## Run zrok Controller
+
 The `zrok` bootstrap process wants us to create a "public frontend" for our service. `zrok` uses public frontends to allow users to specify where they would like public traffic to ingress from.
 
 The `zrok admin create frontend` command requires a running `zrok` controller, so let's start that up first:
@@ -133,14 +142,29 @@ $ zrok controller etc/ctrl.yml
 [   0.085]    INFO zrok/controller.(*metricsAgent).listen: started
 ```
 
+## Create zrok Frontend
+
 With our `ZROK_ADMIN_TOKEN` and `ZROK_API_ENDPOINT` environment variables set, we can create our public frontend like this:
 
 ```bash
 $ zrok admin create frontend sqJRAINSiB public http://{token}.zrok.quigley.com:8080
 [   0.037]    INFO main.(*adminCreateFrontendCommand).run: created global public frontend 'WEirJNHVlcW9'
 ```
 
-Now our `zrok` controller is fully configured.
+The id of the frontend was emitted earlier in by the zrok controller when we ran the bootstrap command. If you don't have that log message the you can find the id again with the `ziti` CLI like this:
+
+```bash
+# initialize the Ziti quickstart env
+source ~/.ziti/quickstart/$(hostname -s)/$(hostname -s).env
+# login as admin
+zitiLogin
+# list Ziti identities created by the quickstart and bootstrap
+ziti edge list identities
+```
+
+The id is shown for the "frontend" identity. 
+
+Nice work! The `zrok` controller is fully configured now that you have created the zrok frontend.
 
 ## Configure the Public Frontend