diff --git a/CHANGELOG.md b/CHANGELOG.md index 7ecb23bc..83612a62 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ FEATURE: The zrok Agent now persists private accesses and reserved shares betwee FEATURE: zrok-agent Linux package runs the agent as a user service (https://github.com/openziti/zrok/issues/883) +CHANGE: Updated the "Getting Started" guide to be slightly more streamlined and reflect the `v1.0` changes (https://github.com/openziti/zrok/issues/877) + CHANGE: let the Docker instance set the Caddy HTTPS port (https://github.com/openziti/zrok/pull/920) CHANGE: Add Traefik option for TLS termination in the Docker instance (https://github.com/openziti/zrok/issues/808) diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx index 184a09fa..ca3577b0 100644 --- a/docs/getting-started.mdx +++ b/docs/getting-started.mdx @@ -25,6 +25,16 @@ Use the command `zrok rebase apiEndpoint https://api-v1.zrok.io/` to update your `zrok` (*/ziːɹɒk/ ZEE-rock*) is a secure, open-source, self-hostable sharing platform that simplifies shielding and sharing network services or files. There's a hardened zrok-as-a-service offering available at [myzrok.io](https://myzrok.io) with a generous free tier. +## What's it for? + +Use `zrok` to share a running service, like a web server or a network socket, or to share a directory of static files. `zrok` goes beyond simple tunneling to provide sharing solutions for a variety of network and storage use cases. + +When using `zrok` to [share publicly](./concepts/sharing-public.mdx), you can reserve a public hostname, enable authentication options, or both. Public shares proxy HTTPS to your service or files. + +If [sharing privately](./concepts/sharing-private.mdx), only users with the share token (and the appropriate permission grants) can access your share. In addition to what you can share publicly, private shares can include TCP and UDP services. + +Here's a quick overview of what's involved in getting started with `zrok`: + ### Your First Share 1. Get an account token @@ -47,7 +57,7 @@ There's a hardened zrok-as-a-service offering available at [myzrok.io](https://m -

Self-Hosted zrok

+

Self-Hosted zrok

 Run a zrok instance on Linux, Docker, or Kubernetes. @@ -62,7 +72,7 @@ There's a hardened zrok-as-a-service offering available at [myzrok.io](https://m 2. [Download the zrok binary](#installing-the-zrok-command) -3. Enable zrok for your [user environment](#enabling-your-zrok-environment) +3. Enable zrok for your [environment](#enabling-your-zrok-environment) ```bash zrok enable @@ -76,41 +86,11 @@ There's a hardened zrok-as-a-service offering available at [myzrok.io](https://m 5. Visit the public URL displayed in your terminal - ![zrok share public](images/zrok_share_public.png) + ![zrok share public](images/zrok-share-public.png) -## Share Backend Modes +# A Deeper Look at Getting Started -zrok shares can be public or private, with different options for backend modes, including: - -* [Public shares](./concepts/sharing-public.mdx) for [web services](./concepts/http.md) or [files](./concepts/files.md) -* [Private shares for web services or files](./concepts/sharing-private.mdx) -* [TCP Tunnels](./concepts/tunnels.md) -* [UDP Tunnels](./concepts/tunnels.md) -* [File Drives](./guides/drives.mdx) -* [VPN](./guides/vpn/vpn.md) - - -## Open Source - -`zrok` is licensed under Apache 2.0. - -Check [the roadmap](https://github.com/orgs/openziti/projects/16) if you're thinking about the future. We would love to hear your ideas for `zrok`! - -The best ways to engage are [Discourse](https://openziti.discourse.group/) for questions and [GitHub Issues](https://github.com/openziti/zrok/issues) for documenting problems. - -[Read more about zrok open source](/concepts/opensource.md). - -### Ziti native - -`zrok` is a _Ziti Native Application_, built on the [OpenZiti](https://openziti.io) platform, and supported by the OpenZiti community and NetFoundry team. - -## What's it for? - -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.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.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. +Here's a deeper, more thorough look at getting started with `zrok`: ## Installing the zrok Command @@ -122,56 +102,64 @@ After you have [an account](#your-first-share), you can enable your `zrok` envir A zrok environment usually refers to an enabled device where shares and accesses can be created, .e.g., `~/.zrok` on a Unix machine. It can be a specific user's environment or a system-wide agent's environment owned by the administrator. -When your `zrok` account was created, the service generated a _secret token_ that identifies and authenticates in a single step. Protect your secret token as if it were a password, or an important account number; it's a _secret_, protect it. +When your `zrok` account was created, the service generated an _account token_ that identifies and authenticates in a single step. Protect your account token as if it were a password, or an important account number; it's a _secret_, protect it. -When we left off you had downloaded, extracted, and configured your `zrok` environment. In order to use that environment with your account, you'll need to `enable` it. Enabling an environment generates a secure identity and the necessary underlying security policies with the OpenZiti network hosting the `zrok` service. +When we left off you had downloaded, extracted, and configured your `zrok` software. In order to use that environment with your account, you'll need to `enable` an _environment_ on your system. Enabling an environment generates a secure identity and the necessary underlying security policies with the OpenZiti network hosting the `zrok` service so that you can begin sharing. -From the web console, click on your email address in the upper right corner of the header. That drop down menu contains an `Enable Your Environment` link. Click that link and a modal dialog will be shown like this: +Log into the API console at: -![Enable Modal Dialog](images/zrok_enable_modal.png) +[https://api-v1.zrok.io/](https://api-v1.zrok.io/) -This dialog box shows you the `zrok enable` command that you can use to enable any shell to work with your `zrok` account with a single command. +When you first log into your account on the API console, your interface will look like this: -Let's copy that command and paste it into your shell: +![zrok API console, empty](images/zrok-getting-started-button.png) -```buttonless title="Example" -$ zrok enable klFEoIi0QAg7 +In the toolbar, there is a big green button that says "CLICK HERE TO GET STARTED!". If you click that button, you'll see the getting started wizard, which looks like this: + +![zrok getting started modal](images/zrok-getting-started-modal.png) + +This wizard is broken into multiple steps. The first step we've already covered, which gets the zrok software installed onto your system. + +Below "step 2" is a command: `zrok enable 7g3K6gVKikWb` (your account will have a different account token, other than `7g3K6gVKikWb`). You'll want to copy this command into your shell and execute it: + +```txt +$ zrok enable 7g3K6gVKikWb ⣻ contacting the zrok service... ``` After a few seconds, the message will change and indicate that the enable operation succeeded: -```buttonless title="Example" -$ zrok enable klFEoIi0QAg7 +```txt +$ zrok enable 7g3K6gVKikWb ⣻ the zrok environment was successfully enabled... ``` Now, if we run a `zrok status` command, you will see the details of your environment: ```txt -zrok status -``` +$ zrok status -```buttonless title="Output" Config: - CONFIG VALUE SOURCE - apiEndpoint https://api.staging.zrok.io env + CONFIG VALUE SOURCE + apiEndpoint https://api-v1.zrok.io env + defaultFrontend public binary + headless false binary Environment: - PROPERTY VALUE - Secret Token <> - Ziti Identity <> + PROPERTY VALUE + Account Token <> + Ziti Identity <> ``` Excellent... our environment is now fully enabled. -If we return to the _web console_, we'll now see the new environment reflected in the explorer view: +If we return to the _API console_, we'll now see the new environment reflected in the API console visualizer: -![New Environment in Web UI](images/zrok_web_ui_new_environment.png) +![New Environment in Web UI](images/zrok-visualizer-enabled.png) -In my case, the environment is named `michael@ziti-lx`, which is the username of my shell and the hostname of the system the shell is running on. +In my case, the environment is named `michael@testing`, which is the username of my shell and the hostname of the system the shell is running on. :::note Should you want to use a non-default name for your environment, you can pass the `-d` option to the `zrok enable` command. See `zrok enable --help` for details. @@ -179,16 +167,12 @@ Should you want to use a non-default name for your environment, you can pass the If you click on the environment node in the explorer in the _web console_, the details panel shown at the bottom of the page will change: -![Empty Environment](images/zrok_web_ui_empty_shares.png) +![Empty Environment](images/zrok-visualizer-environment.png) -The explorer supports clicking, dragging, mouse wheel zooming, and selecting the nodes in the graph for more information (and available actions) for the selected node. If you ever get lost in the explorer, click the ![Zoom to Fit](images/zrok_zoom_to_fit.png) _zoom to fit_ icon in the lower right corner of the explorer. - -If we click on the `Detail` tab for our environment, we'll see something like: - -![Environment Detail](images/zrok_web_ui_empty_environment_detail.png) +The visualizer supports clicking, dragging, mouse wheel zooming, and selecting the nodes in the graph for more information (and available actions) for the selected node. If you ever get lost in the visualizer, click the ![Zoom to Fit](images/zrok-zoom-to-fit.png) _zoom to fit_ icon in the lower right corner of the explorer. :::note -With your `zrok` account you can `zrok enable` multiple environments. This will allow you to run `zrok share` in one environment, and `zrok access` in other environments. +With your `zrok` account you can `zrok enable` multiple environments. This will allow you to share (and access your shares) from multiple environments simultaneously. ::: Your environment is fully ready to go. Now we can move on to the fun stuff... @@ -207,63 +191,30 @@ Resources that are shared _publicly_ are exposed to any users on the internet wh A frontend is an HTTPS listener exposed to the internet, that lets any user with your ephemeral share token access your publicly shared resources. -For example, I might create a public share using the `zrok share public` command, which results in my `zrok` instance exposing a URL like `https://2ptgbr8tlfvk.share.zrok.io` to access my resources. +For example, I might create a public share using the `zrok share public` command, which results in my `zrok` instance exposing a URL like `https://xxr2b7tzfx64.share.zrok.io` to access my resources. -In this case, my share was given the "share token" of `2ptgbr8tlfvk`. That URL can be given to any user, allowing them to immediately access the shared resources directly from my local environment, all without exposing any access to my private, secure environment. The physical network location of my environment is not exposed to anonymous consumers of my resources. - -:::note -Here is the `--help` output from `zrok share public`: - -```text -zrok share public +``` +$ zrok share public --backend-mode web . ``` -```buttonless title="Output" -Error: accepts 1 arg(s), received 0 -Usage: - zrok share public [flags] - -Flags: - --backend-mode string The backend mode {proxy, web, caddy, drive} (default "proxy") - --basic-auth stringArray Basic authentication users (,...) - --frontends stringArray Selected frontends to use for the share (default [public]) - --headless Disable TUI and run headless - -h, --help help for public - --insecure Enable insecure TLS certificate validation for - -Global Flags: - -p, --panic Panic instead of showing pretty errors - -v, --verbose Enable verbose logging - -[ERROR]: an error occurred (accepts 1 arg(s), received 0) -``` - -`` defines the path to the local resource that you intend to share. The form of `` depends on the `--backend-mode` that you're using. - -In the case of `--backend-mode proxy`, `` should be a URL to an HTTP endpoint. - -In the case of `--backend-mode web`, `` is the path to a file on disk that serves as the "root" of the file tree to be shared. -::: +In this case, my share was given the "share token" of `xxr2b7tzfx64`. That URL can be given to any user, allowing them to immediately access the shared resources directly from my local environment, all without exposing any access to my private, secure environment. The physical network location of my environment is not exposed to anonymous consumers of my resources. If we return to the web console, we see our share in the explorer: -![Web Console Share](images/zrok_web_console_explorer_share.png) - -If we click on our new share in the explorer, we can see the share details: -![Share Details](images/zrok_web_console_share_detail.png) +![Web Console Share](images/zrok-visualizer-public-share.png) If we click on the _frontend endpoint_ a new browser tab opens and we see the content of our share: ![Share Frontend](images/zrok_web_console_share_frontend.png) -If we click on the environment in the explorer, we're shown all of the shares for that environment (including our new share), along with a spark line that shows the activity: +When we start accessing our share, notice the _sparkline_ graphs showing the activity: -![Environment Spark Line](images/zrok_web_console_environment_spark.png) +![Environment Spark Line](images/zrok-visualizer-sparklines.png) And as soon as I terminate the `zrok share` client, the resources are removed from the `zrok` environment. If we try to reload the frontend endpoint in our web browser, we'll see: -![Not Found](images/zrok_not_found.png) +![Not Found](images/zrok-not-found.png) [More about public shares](/concepts/sharing-public.mdx) @@ -271,7 +222,7 @@ If we try to reload the frontend endpoint in our web browser, we'll see: `zrok` also provides a powerful _private_ sharing model. If I execute the following command: -```buttonless title="Example" +```buttonless $ zrok share private http://localhost:8080 ``` @@ -305,7 +256,7 @@ A reserved share can be re-used multiple times; it will survive termination of t The first step is to create the reserved share: -```txt title="Example" +```txt $ zrok reserve public --backend-mode web v0.3_getting_started [ 0.275] INFO main.(*reserveCommand).run: your reserved share token is 'mltwsinym1s2' [ 0.275] INFO main.(*reserveCommand).run: reserved frontend endpoint: https://mltwsinym1s2.share.zrok.io @@ -317,13 +268,13 @@ You'll want to remember the share token (`mltwsinym1s2` in this case), and the f If we do nothing else, and then point a web browser at the frontend endpoint, we get: -![Not Found](images/zrok_reserved_not_found.png) +![Not Found](images/zrok-reserved-not-found.png) This is the `404` error message returned by the `zrok` frontend. We're getting this because we haven't yet started up a `zrok share` for the service. Let's do that: This command: -```txt title="Example" +```txt $ zrok share reserved mltwsinym1s2 ``` @@ -339,7 +290,7 @@ With the reserved share, we're free to stop and restart the `zrok share reserved When we're done with the reserved share, we can _release_ it using this command: -```txt title="Example" +```txt $ zrok release mltwsinym1s2 [ 0.230] INFO main.(*releaseCommand).run: reserved share 'mltwsinym1s2' released ``` diff --git a/docs/images/zrok-getting-started-button.png b/docs/images/zrok-getting-started-button.png new file mode 100644 index 00000000..6382d4d7 Binary files /dev/null and b/docs/images/zrok-getting-started-button.png differ diff --git a/docs/images/zrok-getting-started-modal.png b/docs/images/zrok-getting-started-modal.png new file mode 100644 index 00000000..1facd17b Binary files /dev/null and b/docs/images/zrok-getting-started-modal.png differ diff --git a/docs/images/zrok-not-found.png b/docs/images/zrok-not-found.png new file mode 100755 index 00000000..02a16278 Binary files /dev/null and b/docs/images/zrok-not-found.png differ diff --git a/docs/images/zrok-reserved-not-found.png b/docs/images/zrok-reserved-not-found.png new file mode 100755 index 00000000..61145f10 Binary files /dev/null and b/docs/images/zrok-reserved-not-found.png differ diff --git a/docs/images/zrok-share-public.png b/docs/images/zrok-share-public.png new file mode 100755 index 00000000..6eb77983 Binary files /dev/null and b/docs/images/zrok-share-public.png differ diff --git a/docs/images/zrok-visualizer-enabled.png b/docs/images/zrok-visualizer-enabled.png new file mode 100644 index 00000000..4d75ff3b Binary files /dev/null and b/docs/images/zrok-visualizer-enabled.png differ diff --git a/docs/images/zrok-visualizer-environment.png b/docs/images/zrok-visualizer-environment.png new file mode 100644 index 00000000..744c9a31 Binary files /dev/null and b/docs/images/zrok-visualizer-environment.png differ diff --git a/docs/images/zrok-visualizer-public-share.png b/docs/images/zrok-visualizer-public-share.png new file mode 100644 index 00000000..5429331e Binary files /dev/null and b/docs/images/zrok-visualizer-public-share.png differ diff --git a/docs/images/zrok-visualizer-sparklines.png b/docs/images/zrok-visualizer-sparklines.png new file mode 100644 index 00000000..3fe5367f Binary files /dev/null and b/docs/images/zrok-visualizer-sparklines.png differ diff --git a/docs/images/zrok-zoom-to-fit.png b/docs/images/zrok-zoom-to-fit.png new file mode 100644 index 00000000..2dbde0c1 Binary files /dev/null and b/docs/images/zrok-zoom-to-fit.png differ diff --git a/docs/images/zrok_web_console.png b/docs/images/zrok_web_console.png old mode 100755 new mode 100644 diff --git a/docs/images/zrok_zoom_to_fit.png b/docs/images/zrok_zoom_to_fit.png deleted file mode 100644 index 431980f9..00000000 Binary files a/docs/images/zrok_zoom_to_fit.png and /dev/null differ