From 7c422a5db3244bc4c11aa074fb9c42da34e7f915 Mon Sep 17 00:00:00 2001 From: michaelquigley Date: Tue, 25 Jul 2023 15:15:06 +0000 Subject: [PATCH] deploy: d93188b1f3b07a5cfb318fa62b0b5e9eaa2f6d69 --- 404.html | 4 ++-- assets/js/8d0344ba.b4e0ea48.js | 1 - assets/js/8d0344ba.be075eec.js | 1 + ...time~main.8a473bbe.js => runtime~main.485bff31.js} | 2 +- docs/category/docker-share/index.html | 4 ++-- docs/category/guides/index.html | 4 ++-- docs/category/metrics-and-limits/index.html | 4 ++-- docs/category/self-hosting/index.html | 4 ++-- docs/concepts/files/index.html | 4 ++-- docs/concepts/hosting/index.html | 4 ++-- docs/concepts/http/index.html | 4 ++-- docs/concepts/index.html | 4 ++-- docs/concepts/opensource/index.html | 4 ++-- docs/concepts/sharing-private/index.html | 4 ++-- docs/concepts/sharing-public/index.html | 4 ++-- docs/concepts/sharing-reserved/index.html | 4 ++-- docs/concepts/tunnels/index.html | 4 ++-- docs/downloads/index.html | 4 ++-- docs/getting-started/index.html | 11 +++-------- .../docker_private_share_guide/index.html | 4 ++-- .../docker-share/docker_public_share_guide/index.html | 4 ++-- .../metrics-and-limits/configuring-limits/index.html | 4 ++-- .../metrics-and-limits/configuring-metrics/index.html | 4 ++-- docs/guides/self-hosting/nginx_tls_guide/index.html | 4 ++-- .../guides/self-hosting/self_hosting_guide/index.html | 4 ++-- index.html | 4 ++-- search/index.html | 4 ++-- 27 files changed, 51 insertions(+), 56 deletions(-) delete mode 100644 assets/js/8d0344ba.b4e0ea48.js create mode 100644 assets/js/8d0344ba.be075eec.js rename assets/js/{runtime~main.8a473bbe.js => runtime~main.485bff31.js} (98%) diff --git a/404.html b/404.html index 0886fc4e..883d089f 100644 --- a/404.html +++ b/404.html @@ -4,13 +4,13 @@ Page Not Found | Zrok - +
Skip to main content

Page Not Found

We could not find what you were looking for.

Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/assets/js/8d0344ba.b4e0ea48.js b/assets/js/8d0344ba.b4e0ea48.js deleted file mode 100644 index 2380863a..00000000 --- a/assets/js/8d0344ba.b4e0ea48.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[218],{3905:(e,t,n)=>{n.d(t,{Zo:()=>d,kt:()=>h});var a=n(7294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function i(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=a.createContext({}),p=function(e){var t=a.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},d=function(e){var t=p(e.components);return a.createElement(l.Provider,{value:t},e.children)},c="mdxType",m={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},k=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,o=e.originalType,l=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),c=p(n),k=r,h=c["".concat(l,".").concat(k)]||c[k]||m[k]||o;return n?a.createElement(h,i(i({ref:t},d),{},{components:n})):a.createElement(h,i({ref:t},d))}));function h(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=n.length,i=new Array(o);i[0]=k;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[c]="string"==typeof e?e:r,i[1]=s;for(var p=2;p{n.r(t),n.d(t,{assets:()=>l,contentTitle:()=>i,default:()=>c,frontMatter:()=>o,metadata:()=>s,toc:()=>p});var a=n(7462),r=(n(7294),n(3905));const o={sidebar_position:0},i="Getting Started with zrok",s={unversionedId:"getting-started",id:"getting-started",title:"Getting Started with zrok",description:"zrok is a next-generation sharing platform, designed to make sharing network and file resources simple and secure. zrok is a Ziti Native Application, built on top of the OpenZiti programmable zero trust network overlay. zrok is open source, licensed under the Apache v2 license. You can choose to self-host zrok or leverage the free, managed offering provided by NetFoundry at https://zrok.io.",source:"@site/../docs/getting-started.md",sourceDirName:".",slug:"/getting-started",permalink:"/docs/getting-started",draft:!1,editUrl:"https://github.com/openziti/zrok/blob/main/docs/../docs/getting-started.md",tags:[],version:"current",sidebarPosition:0,frontMatter:{sidebar_position:0},sidebar:"tutorialSidebar",next:{title:"Concepts",permalink:"/docs/concepts/"}},l={},p=[{value:"Downloading zrok",id:"downloading-zrok",level:2},{value:"Extract zrok Distribution",id:"extract-zrok-distribution",level:3},{value:"Configure Your zrok Service Instance",id:"configure-your-zrok-service-instance",level:2},{value:"Generating an Invitation",id:"generating-an-invitation",level:2},{value:"Enabling Your zrok Environment",id:"enabling-your-zrok-environment",level:2},{value:"Sharing",id:"sharing",level:2},{value:"Ephemeral by Default",id:"ephemeral-by-default",level:3},{value:"Public Shares and Frontends",id:"public-shares-and-frontends",level:3},{value:"Private Shares",id:"private-shares",level:3},{value:"Proxy Backend Mode",id:"proxy-backend-mode",level:3},{value:"Web Backend Mode",id:"web-backend-mode",level:3},{value:"Reserved Shares",id:"reserved-shares",level:3},{value:"Concepts Review",id:"concepts-review",level:2},{value:"Service Instance and Account",id:"service-instance-and-account",level:3},{value:"Environment",id:"environment",level:3},{value:"Shares",id:"shares",level:3},{value:"Reserved Shares",id:"reserved-shares-1",level:3},{value:"Self-Hosting a Service Instance",id:"self-hosting-a-service-instance",level:2}],d={toc:p};function c(e){let{components:t,...o}=e;return(0,r.kt)("wrapper",(0,a.Z)({},d,o,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("h1",{id:"getting-started-with-zrok"},"Getting Started with zrok"),(0,r.kt)("p",null,(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is a next-generation sharing platform, designed to make sharing network and file resources simple and secure. ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is a ",(0,r.kt)("em",{parentName:"p"},"Ziti Native Application"),", built on top of the ",(0,r.kt)("a",{parentName:"p",href:"https://docs.openziti.io/docs/learn/introduction/"},"OpenZiti")," programmable zero trust network overlay. ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is open source, licensed under the Apache v2 license. You can choose to self-host ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," or leverage the free, managed offering provided by NetFoundry at ",(0,r.kt)("a",{parentName:"p",href:"https://zrok.io"},"https://zrok.io"),"."),(0,r.kt)("p",null,"As of version ",(0,r.kt)("inlineCode",{parentName:"p"},"v0.4.0"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," provides the ability to:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"share resources ",(0,r.kt)("a",{parentName:"li",href:"/docs/concepts/sharing-public"},"publicly"),", 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"),(0,r.kt)("li",{parentName:"ul"},"share resources ",(0,r.kt)("a",{parentName:"li",href:"/docs/concepts/sharing-private"},"privately"),"; private sharing uses peer-to-peer connectivity between two parties by leveraging the OpenZiti overlay. We believe the private sharing offered by ",(0,r.kt)("inlineCode",{parentName:"li"},"zrok")," provides a unique level of security and privacy for this type of sharing.")),(0,r.kt)("p",null,"As of version ",(0,r.kt)("inlineCode",{parentName:"p"},"v0.4.0"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," allows sharing these kinds of resources:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"HTTP/S resources; ",(0,r.kt)("inlineCode",{parentName:"li"},"zrok")," provides reverse proxy capabilities for your HTTP/S endpoints, both publicly and privately"),(0,r.kt)("li",{parentName:"ul"},"file resources; ",(0,r.kt)("inlineCode",{parentName:"li"},"zrok")," provides built in ",(0,r.kt)("inlineCode",{parentName:"li"},"web")," capabilities, allowing you to share your files with other users, both publicly and privately"),(0,r.kt)("li",{parentName:"ul"},"TCP and UDP tunnels; ",(0,r.kt)("inlineCode",{parentName:"li"},"zrok")," provides built-in ",(0,r.kt)("inlineCode",{parentName:"li"},"tunnel")," capabilities, allowing you to share your TCP and UDP endpoints directly with other users privately (",(0,r.kt)("inlineCode",{parentName:"li"},"zrok")," does not currently offer public sharing of these kinds of resources)")),(0,r.kt)("p",null,"Let's take a look at how to get started with ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok"),"."),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("mdxAdmonitionTitle",{parentName:"admonition"},(0,r.kt)("inlineCode",{parentName:"mdxAdmonitionTitle"},"zrok")," moves fast!"),(0,r.kt)("p",{parentName:"admonition"},(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is currently in a closed-beta phase and requires an invitation token. If you would like to try ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," and provide\nfeedback, please send an email to ",(0,r.kt)("a",{parentName:"p",href:"mailto:invite@zrok.io."},"invite@zrok.io.")," ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is an open source project and is in its early development\nphases. We're doing our development publicly. See the ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/orgs/openziti/projects/16"},"roadmap")," for details\nabout the project. We are highly interested in feedback as we continue to iterate quickly. Please provide feedback in\n",(0,r.kt)("a",{parentName:"p",href:"https://openziti.discourse.group/"},"Discourse"),", raise ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/openziti/zrok/issues"},"GitHub Issues"),", or reach\nout directly.")),(0,r.kt)("h2",{id:"downloading-zrok"},"Downloading zrok"),(0,r.kt)("p",null,"Releases are also available from the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," project repository on GitHub at ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/openziti/zrok/releases/latest"},"https://github.com/openziti/zrok/releases/latest"),". If you're a Linux user and you're not sure which download to use then check out the hints on ",(0,r.kt)("a",{parentName:"p",href:"/docs/downloads"},"the Downloads page"),"."),(0,r.kt)("h3",{id:"extract-zrok-distribution"},"Extract zrok Distribution"),(0,r.kt)("p",null,"Move the downloaded ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," distribution into a directory on your system. In my case, I've placed it in my home directory:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ ls -lF zrok*\n-rwxr-xr-x 1 michael michael 14459159 May 31 13:46 zrok_0.4.0-rc6_linux_amd64.tar.gz*\n")),(0,r.kt)("p",null,"Create a directory where the extracted distribution will sit:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ mkdir zrok\n$ cd zrok/\n")),(0,r.kt)("p",null,"Extract the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," distribution:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ tar zxvf ../zrok_0.4.0-rc1_linux_amd64.tar.gz\nCHANGELOG.md\nREADME.md\nzrok\n")),(0,r.kt)("blockquote",null,(0,r.kt)("p",{parentName:"blockquote"},"NOTE: On Windows platforms the distribution is shipped as a ",(0,r.kt)("inlineCode",{parentName:"p"},"zip")," archive. Windows Explorer includes support for extracting ",(0,r.kt)("inlineCode",{parentName:"p"},"zip")," archives natively.")),(0,r.kt)("p",null,"Add ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," to your shell's environment."),(0,r.kt)("p",null,"For Linux or macos:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ export PATH=`pwd`:$PATH\n")),(0,r.kt)("p",null,"For Windows (using Command Prompt):"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"> set PATH=%CD%;%PATH%\n")),(0,r.kt)("p",null,"For Windows (using PowerShell):"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},'$env:path += ";"+$pwd.Path\n')),(0,r.kt)("p",null,"With the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," executable in your path, you can then execute the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," command from your shell:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ ./zrok version\n _ \n _____ __ ___ | | __\n|_ / '__/ _ \\| |/ /\n / /| | | (_) | < \n/___|_| \\___/|_|\\_\\\n\nv0.4.0-rc6 [c889005]\n")),(0,r.kt)("h2",{id:"configure-your-zrok-service-instance"},"Configure Your zrok Service Instance"),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("p",{parentName:"admonition"},'Most users can safely skip this section and proceed to "Generating an Invitation" below.'),(0,r.kt)("p",{parentName:"admonition"},"This section is relevant if you want to use the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," CLI with an alternate service instance (in the case of self-hosting, etc.).")),(0,r.kt)("p",null,(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is both an installable utility that you interact with from your local computer, and also a ",(0,r.kt)("em",{parentName:"p"},"service")," that exists on the network. NetFoundry operates the public ",(0,r.kt)("em",{parentName:"p"},"service instance")," that is available at ",(0,r.kt)("inlineCode",{parentName:"p"},"api.zrok.io"),", but because ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is open source and self-hostable, you're free to create your own ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service instance."),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," executable defaults to using the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service instance at ",(0,r.kt)("inlineCode",{parentName:"p"},"api.zrok.io"),". Should you need to change the endpoint to use a different service instance, you can do that with the following command:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok config set apiEndpoint https://zrok.mydomain.com\n[WARNING]: unable to open zrokdir metadata; ignoring\n\nzrok configuration updated\n")),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("p",{parentName:"admonition"},"The ",(0,r.kt)("inlineCode",{parentName:"p"},"WARNING")," about ",(0,r.kt)("inlineCode",{parentName:"p"},"zrokdir metadata")," is ignorable. Running the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok config set")," command writes a small piece of metadata into a ",(0,r.kt)("inlineCode",{parentName:"p"},".zrok")," folder inside your home directory. This allows ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," to identify the version of its settings, providing a mechanism to upgrade your installation as new versions are released. This ",(0,r.kt)("inlineCode",{parentName:"p"},"WARNING")," is letting you know that your current environment has not been initialized by ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok"),".")),(0,r.kt)("p",null,"You can use the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok status")," command to inspect the state of your local ",(0,r.kt)("em",{parentName:"p"},"environment"),". ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," refers to each shell where you install and ",(0,r.kt)("inlineCode",{parentName:"p"},"enable")," a copy of ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," as as an ",(0,r.kt)("em",{parentName:"p"},"environment"),"."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok status\n\nConfig:\n\n CONFIG VALUE SOURCE \n apiEndpoint https://zrok.mydomain.com config \n\n[WARNING]: Unable to load your local environment!\n\nTo create a local environment use the zrok enable command.\n")),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("p",{parentName:"admonition"},"The ",(0,r.kt)("inlineCode",{parentName:"p"},"WARNING")," about being ",(0,r.kt)("inlineCode",{parentName:"p"},"unable to load your local environment")," will go away once you've successfully enabled (",(0,r.kt)("inlineCode",{parentName:"p"},"zrok enable"),") for your shell (we'll get to that below). For now, this warning is ignorable.")),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok status")," command shows the configured API service that your environment is using, as well as the ",(0,r.kt)("inlineCode",{parentName:"p"},"SOURCE")," where the setting was retrieved. In this case, ",(0,r.kt)("inlineCode",{parentName:"p"},"config")," means that the setting was set into the environment using the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok config")," command."),(0,r.kt)("h2",{id:"generating-an-invitation"},"Generating an Invitation"),(0,r.kt)("p",null,"In order to create an account with the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service instance, you will need to create an invitation. "),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("p",{parentName:"admonition"},"Some environments take advantage of ",(0,r.kt)("em",{parentName:"p"},"invitation tokens"),", which limit who is able to request an invitation on the service instance. If your service uses invitation tokens, the administrator of your instance will include details about how to use your token to generate your invitation.")),(0,r.kt)("p",null,"We generate an invitation with the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok invite")," command. A service instance that allows open registration will provide an input form like this:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok invite\n\nenter and confirm your email address...\n\n> user@domain.com\n> user@domain.com\n\n[ Submit ]\n\ninvitation sent to 'user@domain.com'!\n")),(0,r.kt)("p",null,"A service instance that requires token-based invitation authentication will present a form that looks like this:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok invite\n\nenter and confirm your email address...\n\nIf you don't already have one, request an invite token at: michael@quigley.com\n\n> Email Address\n> Confirm Email\n> Token\n\n\n[ Submit ]\n")),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok invite")," command presents a small form that allows you to enter (and then confirm) your email address. Tabbing to the ",(0,r.kt)("inlineCode",{parentName:"p"},"[ Submit ]")," button will send the request to your configured ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service."),(0,r.kt)("p",null,"Next, check the email where you sent the invite. You should receive a message asking you to click a link to create your ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," account. When you click that link, you will be brought to a web page that will allow you to set a password for your new account:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Enter a Password",src:n(9744).Z,width:"1791",height:"1362"})),(0,r.kt)("p",null,"Enter a password and it's confirmation, and click the ",(0,r.kt)("inlineCode",{parentName:"p"},"Register Account")," button. You'll see the following:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Successful Registration",src:n(242).Z,width:"1791",height:"1369"})),(0,r.kt)("p",null,'For now, we\'ll ignore the "enable your shell for zrok" section. Just click the ',(0,r.kt)("inlineCode",{parentName:"p"},"zrok web portal")," link:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Web Login",src:n(9509).Z,width:"1791",height:"1362"})),(0,r.kt)("p",null,"After clicking the ",(0,r.kt)("inlineCode",{parentName:"p"},"Log In")," button, you'll be brought into the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," ",(0,r.kt)("em",{parentName:"p"},"web console"),":"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Web Console; Empty",src:n(2945).Z,width:"1791",height:"1362"})),(0,r.kt)("p",null,"Congratulations! Your ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," account is ready to go!"),(0,r.kt)("h2",{id:"enabling-your-zrok-environment"},"Enabling Your zrok Environment"),(0,r.kt)("p",null,"When your ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," account was created, the service generated a ",(0,r.kt)("em",{parentName:"p"},"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 ",(0,r.kt)("em",{parentName:"p"},"secret"),", protect it."),(0,r.kt)("p",null,"When we left off you had downloaded, extracted, and configured your ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," environment. In order to use that environment with your account, you'll need to ",(0,r.kt)("inlineCode",{parentName:"p"},"enable")," it. Enabling an environment generates a secure identity and the necessary underlying security policies with the OpenZiti network hosting the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service."),(0,r.kt)("p",null,"From the web console, click on your email address in the upper right corner of the header. That drop down menu contains an ",(0,r.kt)("inlineCode",{parentName:"p"},"Enable Your Environment")," link. Click that link and a modal dialog will be shown like this:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Enable Modal Dialog",src:n(9042).Z,width:"1791",height:"1369"})),(0,r.kt)("p",null,"This dialog box shows you the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok enable")," command that you can use to enable any shell to work with your ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," account with a single command."),(0,r.kt)("p",null,"Let's copy that command and paste it into your shell:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok enable klFEoIi0QAg7 \n\u28fb contacting the zrok service...\n")),(0,r.kt)("p",null,"After a few seconds, the message will change and indicate that the enable operation suceeded:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok enable klFEoIi0QAg7 \n\u28fb the zrok environment was successfully enabled...\n")),(0,r.kt)("p",null,"Now, if we run a ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok status")," command, you will see the details of your environment:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok status\n\nConfig:\n\n CONFIG VALUE SOURCE\n apiEndpoint https://api.staging.zrok.io env\n\nEnvironment:\n\n PROPERTY VALUE\n Secret Token <>\n Ziti Identity <>\n")),(0,r.kt)("p",null,"Excellent... our environment is now fully enabled."),(0,r.kt)("p",null,"If we return to the ",(0,r.kt)("em",{parentName:"p"},"web console"),", we'll now see the new environment reflected in the explorer view:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"New Environment in Web UI",src:n(5546).Z,width:"1791",height:"1369"})),(0,r.kt)("p",null,"In my case, the environment is named ",(0,r.kt)("inlineCode",{parentName:"p"},"michael@ziti-lx"),", which is the username of my shell and the hostname of the system the shell is running on."),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("p",{parentName:"admonition"},"Should you want to use a non-default name for your environment, you can pass the ",(0,r.kt)("inlineCode",{parentName:"p"},"-d")," option to the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok enable")," command. See ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok enable --help")," for details.")),(0,r.kt)("p",null,"If you click on the environment node in the explorer in the ",(0,r.kt)("em",{parentName:"p"},"web console"),", the details panel shown at the bottom of the page will change:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Empty Environment",src:n(3858).Z,width:"1791",height:"1369"})),(0,r.kt)("p",null,"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 ",(0,r.kt)("img",{alt:"Zoom to Fit",src:n(3843).Z,width:"30",height:"25"})," ",(0,r.kt)("em",{parentName:"p"},"zoom to fit")," icon in the lower right corner of the explorer."),(0,r.kt)("p",null,"If we click on the ",(0,r.kt)("inlineCode",{parentName:"p"},"Detail")," tab for our environment, we'll see something like:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Environment Detail",src:n(2534).Z,width:"1791",height:"1369"})),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("p",{parentName:"admonition"},"With your ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," account you can ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok enable")," multiple environments. This will allow you to run ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," in one environment, and ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok access")," in other environments.")),(0,r.kt)("p",null,"Your environment is fully ready to go. Now we can move on to the fun stuff..."),(0,r.kt)("h2",{id:"sharing"},"Sharing"),(0,r.kt)("p",null,(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is designed to make sharing resources as effortless as possible, while providing a high degree of security and control."),(0,r.kt)("h3",{id:"ephemeral-by-default"},"Ephemeral by Default"),(0,r.kt)("p",null,"Shared resources are ",(0,r.kt)("em",{parentName:"p"},"ephemeral")," by default; as soon as you terminate the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," command, the entire share is removed and is no longer available to any users. Identifiers for shared resources are randomly allocated when the share is created."),(0,r.kt)("h3",{id:"public-shares-and-frontends"},"Public Shares and Frontends"),(0,r.kt)("p",null,"Resources that are shared ",(0,r.kt)("em",{parentName:"p"},"publicly")," are exposed to any users on the internet who have access to the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok"),' service instance\'s "frontend".'),(0,r.kt)("p",null,"A frontend is an HTTPS listener exposed to the internet, that lets any user with your ephemeral share token access your publicly shared resources."),(0,r.kt)("p",null,"For example, I might create a public share using the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share public")," command, which results in my ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service instance exposing the following URL to access my resources:"),(0,r.kt)("p",null,(0,r.kt)("a",{parentName:"p",href:"https://2ptgbr8tlfvk.share.zrok.io"},"https://2ptgbr8tlfvk.share.zrok.io")),(0,r.kt)("p",null,'In this case my share was given the "share token" of ',(0,r.kt)("inlineCode",{parentName:"p"},"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."),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("p",{parentName:"admonition"},"Here is the ",(0,r.kt)("inlineCode",{parentName:"p"},"--help")," output from ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share public"),":"),(0,r.kt)("pre",{parentName:"admonition"},(0,r.kt)("code",{parentName:"pre"},'$ zrok share public\nError: accepts 1 arg(s), received 0\nUsage:\n zrok share public [flags]\n\nFlags:\n --backend-mode string The backend mode {proxy, web} (default "proxy")\n --basic-auth stringArray Basic authentication users (,...)\n --frontends stringArray Selected frontends to use for the share (default [public])\n --headless Disable TUI and run headless\n -h, --help help for public\n --insecure Enable insecure TLS certificate validation for \n\nGlobal Flags:\n -p, --panic Panic instead of showing pretty errors\n -v, --verbose Enable verbose logging\n\n[ERROR]: an error occurred (accepts 1 arg(s), received 0)\n')),(0,r.kt)("p",{parentName:"admonition"},(0,r.kt)("inlineCode",{parentName:"p"},"")," defines the path to the local resource that you intend to share. The form of ",(0,r.kt)("inlineCode",{parentName:"p"},"")," depends on the ",(0,r.kt)("inlineCode",{parentName:"p"},"--backend-mode")," that you're using. "),(0,r.kt)("p",{parentName:"admonition"},"In the case of ",(0,r.kt)("inlineCode",{parentName:"p"},"--backend-mode proxy"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"")," should be a URL to an HTTP endpoint."),(0,r.kt)("p",{parentName:"admonition"},"In the case of ",(0,r.kt)("inlineCode",{parentName:"p"},"--backend-mode web"),", ",(0,r.kt)("inlineCode",{parentName:"p"},""),' is the path to a file on disk that serves as the "root" of the file tree to be shared.')),(0,r.kt)("p",null,"If we return to the web console, we see our share in the explorer:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Web Console Share",src:n(6097).Z,width:"1791",height:"1369"})),(0,r.kt)("p",null,"If we click on our new share in the explorer, we can see the share details:\n",(0,r.kt)("img",{alt:"Share Details",src:n(4647).Z,width:"1791",height:"1369"})),(0,r.kt)("p",null,"If we click on the ",(0,r.kt)("em",{parentName:"p"},"frontend endpoint")," a new browser tab opens and we see the content of our share:\n",(0,r.kt)("img",{alt:"Share Frontend",src:n(6254).Z,width:"1556",height:"1229"})),(0,r.kt)("p",null,"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:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Environment Spark Line",src:n(9737).Z,width:"1791",height:"1369"})),(0,r.kt)("p",null,"And as soon as I terminate the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," client, the resources are removed from the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," environment."),(0,r.kt)("p",null,"If we try to reload the frontend endpoint in our web browser, we'll see:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Not Found",src:n(5724).Z,width:"1556",height:"1229"})),(0,r.kt)("h3",{id:"private-shares"},"Private Shares"),(0,r.kt)("p",null,(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," also provides a powerful ",(0,r.kt)("em",{parentName:"p"},"private")," sharing model. If I execute the following command:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok share private http://localhost:8080\n")),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service will respond with the following:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"access your share with: zrok access private wvszln4dyz9q\n")),(0,r.kt)("p",null,"Rather than allowing access to your service through a public frontend, a ",(0,r.kt)("em",{parentName:"p"},"private")," share is only exposed to the underlying OpenZiti network, and can only be accessed using the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok access")," command."),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok access private wvszln4dyz9q")," command can be run by any ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," user, allowing them to create and bind a local HTTP listener, that allows for private access to your shared resources."),(0,r.kt)("h3",{id:"proxy-backend-mode"},"Proxy Backend Mode"),(0,r.kt)("p",null,"Without specifying a ",(0,r.kt)("em",{parentName:"p"},"backend mode"),", the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," command will assume that you're trying to share a ",(0,r.kt)("inlineCode",{parentName:"p"},"proxy")," resource. A ",(0,r.kt)("inlineCode",{parentName:"p"},"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 ",(0,r.kt)("inlineCode",{parentName:"p"},"localhost"),", or only listening on a private LAN segment behind a firewall. "),(0,r.kt)("p",null,"For these services a ",(0,r.kt)("inlineCode",{parentName:"p"},"proxy")," share will allow those endpoints to be reached, either ",(0,r.kt)("em",{parentName:"p"},"publicly")," or ",(0,r.kt)("em",{parentName:"p"},"privately")," through the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service."),(0,r.kt)("h3",{id:"web-backend-mode"},"Web Backend Mode"),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," command accepts a ",(0,r.kt)("inlineCode",{parentName:"p"},"--backend-mode")," option. Besides ",(0,r.kt)("inlineCode",{parentName:"p"},"proxy"),", the current ",(0,r.kt)("inlineCode",{parentName:"p"},"v0.3")," release (as of this writing) also supports a ",(0,r.kt)("inlineCode",{parentName:"p"},"web")," mode. The ",(0,r.kt)("inlineCode",{parentName:"p"},"web")," mode allows you to specify a local folder on your filesystem, and instantly turns your ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," client into a web server, exposing your web content either ",(0,r.kt)("em",{parentName:"p"},"publicly")," or ",(0,r.kt)("em",{parentName:"p"},"privately")," without having to a configure a web server."),(0,r.kt)("h3",{id:"reserved-shares"},"Reserved Shares"),(0,r.kt)("p",null,(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," shares are ",(0,r.kt)("em",{parentName:"p"},"ephemeral"),' unless you specifically create a "reserved" share.'),(0,r.kt)("p",null,"A reserved share can be re-used multiple times; it will survive termination of the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," command, allowing for longer-lasting semi-permanent access to shared resources."),(0,r.kt)("p",null,"The first step is to create the reserved share:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok reserve public --backend-mode web v0.3_getting_started\n[ 0.275] INFO main.(*reserveCommand).run: your reserved share token is 'mltwsinym1s2'\n[ 0.275] INFO main.(*reserveCommand).run: reserved frontend endpoint: https://mltwsinym1s2.share.zrok.io\n")),(0,r.kt)("p",null,"I'm asking the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service to reserve a share with a ",(0,r.kt)("inlineCode",{parentName:"p"},"web")," backend mode, pointing at my local ",(0,r.kt)("inlineCode",{parentName:"p"},"docs")," folder."),(0,r.kt)("p",null,"You'll want to remember the share token (",(0,r.kt)("inlineCode",{parentName:"p"},"mltwsinym1s2")," in this case), and the frontend endpoint URL. If this were a ",(0,r.kt)("em",{parentName:"p"},"private")," reserved share, there would not be a frontend URL."),(0,r.kt)("p",null,"If we do nothing else, and then point a web browser at the frontend endpoint, we get:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Not Found",src:n(7369).Z,width:"1556",height:"1229"})),(0,r.kt)("p",null,"This is the ",(0,r.kt)("inlineCode",{parentName:"p"},"404")," error message returned by the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," frontend. We're getting this because we haven't yet started up a ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," for the service. Let's do that:"),(0,r.kt)("p",null,"This command:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok share reserved mltwsinym1s2\n")),(0,r.kt)("p",null,"...results in a new share backend starting up and connecting to the existing reserved share:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"zrok share reserved",src:n(1577).Z,width:"951",height:"706"})),(0,r.kt)("p",null,"And now if we refresh the frontend endpoint URL in the web browser, we'll see an index of the ",(0,r.kt)("inlineCode",{parentName:"p"},"docs")," directory:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"zrok docs share",src:n(6377).Z,width:"1556",height:"1229"})),(0,r.kt)("p",null,"With the reserved share, we're free to stop and restart the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share reserved")," command as many times as we want, without losing the token for our share."),(0,r.kt)("p",null,"When we're done with the reserved share, we can ",(0,r.kt)("em",{parentName:"p"},"release")," it using this command:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok release mltwsinym1s2\n[ 0.230] INFO main.(*releaseCommand).run: reserved share 'mltwsinym1s2' released\n")),(0,r.kt)("h2",{id:"concepts-review"},"Concepts Review"),(0,r.kt)("p",null,"In summary, ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," lets you easily and securely share resources with both general internet users (through ",(0,r.kt)("em",{parentName:"p"},"public")," sharing) and also with other ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," users (through ",(0,r.kt)("em",{parentName:"p"},"private")," sharing)."),(0,r.kt)("p",null,"Here's a quick review of the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," mental model and the vocabulary."),(0,r.kt)("h3",{id:"service-instance-and-account"},"Service Instance and Account"),(0,r.kt)("p",null,"You create an ",(0,r.kt)("em",{parentName:"p"},"account")," with a ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," ",(0,r.kt)("em",{parentName:"p"},"service instance"),". Your account is identified by a username and a password, which you use to log into the ",(0,r.kt)("em",{parentName:"p"},"web console"),". Your account also has a ",(0,r.kt)("em",{parentName:"p"},"secret token"),", which you will use to authenticate from the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," command-line to interact with the ",(0,r.kt)("em",{parentName:"p"},"service instance"),"."),(0,r.kt)("p",null,"You create a new ",(0,r.kt)("em",{parentName:"p"},"account")," with a ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," ",(0,r.kt)("em",{parentName:"p"},"service instance")," through the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok invite")," command."),(0,r.kt)("h3",{id:"environment"},"Environment"),(0,r.kt)("p",null,"Using your ",(0,r.kt)("em",{parentName:"p"},"secret token")," you use the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," command-line interface to create an ",(0,r.kt)("em",{parentName:"p"},"environment"),". An ",(0,r.kt)("em",{parentName:"p"},"environment")," corresponds to a single command-line user on a specific ",(0,r.kt)("em",{parentName:"p"},"host system"),". "),(0,r.kt)("p",null,"You create a new ",(0,r.kt)("em",{parentName:"p"},"environment")," by using the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok enable")," command."),(0,r.kt)("h3",{id:"shares"},"Shares"),(0,r.kt)("p",null,"Once you've enabled an ",(0,r.kt)("em",{parentName:"p"},"environment"),", you then create one or more ",(0,r.kt)("em",{parentName:"p"},"shares"),". Shares have either a ",(0,r.kt)("em",{parentName:"p"},"public")," or ",(0,r.kt)("em",{parentName:"p"},"private")," ",(0,r.kt)("em",{parentName:"p"},"sharing mode"),". ",(0,r.kt)("em",{parentName:"p"},"Shares")," share a specific type of resource using a ",(0,r.kt)("em",{parentName:"p"},"backend mode"),". As of this writing ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," supports a ",(0,r.kt)("inlineCode",{parentName:"p"},"proxy")," ",(0,r.kt)("em",{parentName:"p"},"backend mode")," to share local HTTP resources as a ",(0,r.kt)("em",{parentName:"p"},"reverse proxy"),". ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," also supports a ",(0,r.kt)("inlineCode",{parentName:"p"},"web")," ",(0,r.kt)("em",{parentName:"p"},"backend mode")," to share local file and HTML resources by enabling a basic HTTP server."),(0,r.kt)("p",null,"Every ",(0,r.kt)("em",{parentName:"p"},"share")," is identified by a ",(0,r.kt)("em",{parentName:"p"},"share token"),". ",(0,r.kt)("em",{parentName:"p"},"Public shares")," can be accessed through either a ",(0,r.kt)("em",{parentName:"p"},"frontend")," instance offered through the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," ",(0,r.kt)("em",{parentName:"p"},"service instance"),", or through the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok access")," command. ",(0,r.kt)("em",{parentName:"p"},"Private shares")," can only be accessed through the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok access")," command."),(0,r.kt)("p",null,"You use the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," command to create and enable ",(0,r.kt)("em",{parentName:"p"},"ephemeral shares"),"."),(0,r.kt)("h3",{id:"reserved-shares-1"},"Reserved Shares"),(0,r.kt)("p",null,(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," supports creating ",(0,r.kt)("em",{parentName:"p"},"shares")," that have a consistent ",(0,r.kt)("em",{parentName:"p"},"share token")," that survives restarts of the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," command. These are considered ",(0,r.kt)("em",{parentName:"p"},"non-ephemeral"),", and is callled a ",(0,r.kt)("em",{parentName:"p"},"reserved share"),"."),(0,r.kt)("p",null,"You use the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok reserve")," command to create ",(0,r.kt)("em",{parentName:"p"},"reserved shares"),". Reserved shares last until you use the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok release")," command to delete them."),(0,r.kt)("h2",{id:"self-hosting-a-service-instance"},"Self-Hosting a Service Instance"),(0,r.kt)("p",null,"Interested in self-hosting your own ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service instance? See the ",(0,r.kt)("a",{parentName:"p",href:"/docs/guides/self-hosting/self_hosting_guide"},"self-hosting guide")," for details."))}c.isMDXComponent=!0},6377:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_docs_share-1c87532d471ab25aaa1590d6215a1427.png"},9042:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_enable_modal-45da63a6907e930daaa4c798272ce5fa.png"},5724:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_not_found-fa3415937c341eb10e1eb98c9b063583.png"},242:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_registration_success-05e7e328284f6dc38cd993322698d38b.png"},7369:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_reserved_not_found-2519707e5cc3e635b7a6feb381c1d040.png"},1577:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_share_reserved-6bce67775ce2c41abb0ef13ee1fad972.png"},9744:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_verify-22a26d401b9a77a4278f3c0f54d2a981.png"},2945:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_console_empty-cce147eaf8e7bc83abe556336a4aea98.png"},9737:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_console_environment_spark-925c0709ed7a42f0a708ab0523cdeb5f.png"},6097:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_console_explorer_share-11236f68819da60014d5444e7429c189.png"},4647:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_console_share_detail-efeaa472d5e5c225a160f6d5647086b3.png"},6254:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_console_share_frontend-d36b169cea46f834e74af4aa456d0b89.png"},9509:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_login-a6161cc79e66932fab76994bdfb8f9c1.png"},2534:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_ui_empty_environment_detail-153c921ade86f924079947b0f734e3ff.png"},3858:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_ui_empty_shares-048c08c18477bcabb9fa8c1b58537012.png"},5546:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_ui_new_environment-414d8e8fc25b09f257cb40ba47d6acbb.png"},3843:(e,t,n)=>{n.d(t,{Z:()=>a});const a="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAB4AAAAZCAIAAACpVwlNAAAEr2lUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNS41LjAiPgogPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIgogICAgeG1sbnM6dGlmZj0iaHR0cDovL25zLmFkb2JlLmNvbS90aWZmLzEuMC8iCiAgICB4bWxuczpleGlmPSJodHRwOi8vbnMuYWRvYmUuY29tL2V4aWYvMS4wLyIKICAgIHhtbG5zOnBob3Rvc2hvcD0iaHR0cDovL25zLmFkb2JlLmNvbS9waG90b3Nob3AvMS4wLyIKICAgIHhtbG5zOnhtcD0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wLyIKICAgIHhtbG5zOnhtcE1NPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvbW0vIgogICAgeG1sbnM6c3RFdnQ9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZUV2ZW50IyIKICAgdGlmZjpJbWFnZUxlbmd0aD0iMjUiCiAgIHRpZmY6SW1hZ2VXaWR0aD0iMzAiCiAgIHRpZmY6UmVzb2x1dGlvblVuaXQ9IjIiCiAgIHRpZmY6WFJlc29sdXRpb249Ijk2LzEiCiAgIHRpZmY6WVJlc29sdXRpb249Ijk2LzEiCiAgIGV4aWY6UGl4ZWxYRGltZW5zaW9uPSIzMCIKICAgZXhpZjpQaXhlbFlEaW1lbnNpb249IjI1IgogICBleGlmOkNvbG9yU3BhY2U9IjEiCiAgIHBob3Rvc2hvcDpDb2xvck1vZGU9IjMiCiAgIHBob3Rvc2hvcDpJQ0NQcm9maWxlPSJzUkdCIElFQzYxOTY2LTIuMSIKICAgeG1wOk1vZGlmeURhdGU9IjIwMjMtMDEtMTlUMTA6NTY6NTYtMDU6MDAiCiAgIHhtcDpNZXRhZGF0YURhdGU9IjIwMjMtMDEtMTlUMTA6NTY6NTYtMDU6MDAiPgogICA8eG1wTU06SGlzdG9yeT4KICAgIDxyZGY6U2VxPgogICAgIDxyZGY6bGkKICAgICAgc3RFdnQ6YWN0aW9uPSJwcm9kdWNlZCIKICAgICAgc3RFdnQ6c29mdHdhcmVBZ2VudD0iQWZmaW5pdHkgUGhvdG8gMi4wLjMiCiAgICAgIHN0RXZ0OndoZW49IjIwMjMtMDEtMTlUMTA6NTY6NTYtMDU6MDAiLz4KICAgIDwvcmRmOlNlcT4KICAgPC94bXBNTTpIaXN0b3J5PgogIDwvcmRmOkRlc2NyaXB0aW9uPgogPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KPD94cGFja2V0IGVuZD0iciI/Pq+HLHgAAAGBaUNDUHNSR0IgSUVDNjE5NjYtMi4xAAAokXWRy0tCQRSHP7UwemBQixYtJKyVRg8Q27RQyoJqYQZZbfTmI/BxuVcJaRu0FQqiNr0W9RfUNmgdBEURRNtaF7UpuZ2rghF5hjnzzW/OOcycAWs4rWT0piHIZPNaKOh3LkaWnPYXLHThwIclqujq7PxkmIb2eS/RYrces1bjuH+tbTWuK2BpER5XVC0vPCU8s55XTd4R7lZS0VXhM2G3JhcUvjP1WJVfTU5W+dtkLRwKgLVT2Jn8xbFfrKS0jLC8HFcmXVBq9zFf0h7PLszL2iezF50QQfw4mWaCAF6GGRPvxcMIg7KjQf5QJX+OnOQq4lWKaKyRJEUet6gFqR6XNSF6XEaaotn/v33VE6Mj1ertfmh+Noz3frBvQ7lkGF9HhlE+BtsTXGbr+blD8H2IXqprrgNwbML5VV2L7cLFFvQ8qlEtWpFsMq2JBLydQkcEum6gdbnas9o5Jw8Q3pCvuoa9fRiQeMfKD2DYZ+PDGzxnAAAACXBIWXMAAA7EAAAOxAGVKw4bAAABZklEQVRIie2VvW7CMBDHr1UfwE5fII7lvahIWUEiQ7qxMLEwsVQMSB0YKsTExsDGxFs0QyqlYyMVld3k4wWw/QgMlqp+JXFQGZB649n3k+9/f9sX9w+PcJq4PBH3H/0zrkrWfK99jVF5/V6qIIzqod1m485rC6nK0S5GAPArvRDNHFtINZ0vviQp4Un2OTObjIs6q6G122yMhgPfaxvuN0VbGDHHBgDm2FbVAGqgLYyEVPFmCwDB84uQilHyB2i32ej3uoySvZDT+YInGaPE77QqlSkznz5vv9cFAEbJdL4QUlkYjYYDnYnf3o9HC6mewog5ttZBq7xcrf1OK95sy61ZgQaAIIx2lGgdRsPBcrXmSbYXstLyRmPkSWZh5HdaAODe3uipVlaZmk9IxdMcAHiam3DBRJCPCMJol+bfbuMxaJ7mjJLZZFxeb2Gku6mDTrJXjExeviILFqJF8WtpGOf5y5wn+gBcXI4F9z6rgwAAAABJRU5ErkJggg=="}}]); \ No newline at end of file diff --git a/assets/js/8d0344ba.be075eec.js b/assets/js/8d0344ba.be075eec.js new file mode 100644 index 00000000..c596f327 --- /dev/null +++ b/assets/js/8d0344ba.be075eec.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[218],{3905:(e,t,n)=>{n.d(t,{Zo:()=>d,kt:()=>h});var a=n(7294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function i(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=a.createContext({}),p=function(e){var t=a.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},d=function(e){var t=p(e.components);return a.createElement(l.Provider,{value:t},e.children)},c="mdxType",m={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},k=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,o=e.originalType,l=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),c=p(n),k=r,h=c["".concat(l,".").concat(k)]||c[k]||m[k]||o;return n?a.createElement(h,i(i({ref:t},d),{},{components:n})):a.createElement(h,i({ref:t},d))}));function h(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=n.length,i=new Array(o);i[0]=k;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[c]="string"==typeof e?e:r,i[1]=s;for(var p=2;p{n.r(t),n.d(t,{assets:()=>l,contentTitle:()=>i,default:()=>c,frontMatter:()=>o,metadata:()=>s,toc:()=>p});var a=n(7462),r=(n(7294),n(3905));const o={sidebar_position:0},i="Getting Started with zrok",s={unversionedId:"getting-started",id:"getting-started",title:"Getting Started with zrok",description:"zrok is a next-generation sharing platform, designed to make sharing network and file resources simple and secure. zrok is a Ziti Native Application, built on top of the OpenZiti programmable zero trust network overlay. zrok is open source, licensed under the Apache v2 license. You can choose to self-host zrok or leverage the free, managed offering provided by NetFoundry at https://zrok.io.",source:"@site/../docs/getting-started.md",sourceDirName:".",slug:"/getting-started",permalink:"/docs/getting-started",draft:!1,editUrl:"https://github.com/openziti/zrok/blob/main/docs/../docs/getting-started.md",tags:[],version:"current",sidebarPosition:0,frontMatter:{sidebar_position:0},sidebar:"tutorialSidebar",next:{title:"Concepts",permalink:"/docs/concepts/"}},l={},p=[{value:"Downloading zrok",id:"downloading-zrok",level:2},{value:"Extract zrok Distribution",id:"extract-zrok-distribution",level:3},{value:"Configure Your zrok Service Instance",id:"configure-your-zrok-service-instance",level:2},{value:"Generating an Invitation",id:"generating-an-invitation",level:2},{value:"Enabling Your zrok Environment",id:"enabling-your-zrok-environment",level:2},{value:"Sharing",id:"sharing",level:2},{value:"Ephemeral by Default",id:"ephemeral-by-default",level:3},{value:"Public Shares and Frontends",id:"public-shares-and-frontends",level:3},{value:"Private Shares",id:"private-shares",level:3},{value:"Proxy Backend Mode",id:"proxy-backend-mode",level:3},{value:"Web Backend Mode",id:"web-backend-mode",level:3},{value:"Reserved Shares",id:"reserved-shares",level:3},{value:"Concepts Review",id:"concepts-review",level:2},{value:"Service Instance and Account",id:"service-instance-and-account",level:3},{value:"Environment",id:"environment",level:3},{value:"Shares",id:"shares",level:3},{value:"Reserved Shares",id:"reserved-shares-1",level:3},{value:"Self-Hosting a Service Instance",id:"self-hosting-a-service-instance",level:2}],d={toc:p};function c(e){let{components:t,...o}=e;return(0,r.kt)("wrapper",(0,a.Z)({},d,o,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("h1",{id:"getting-started-with-zrok"},"Getting Started with zrok"),(0,r.kt)("p",null,(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is a next-generation sharing platform, designed to make sharing network and file resources simple and secure. ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is a ",(0,r.kt)("em",{parentName:"p"},"Ziti Native Application"),", built on top of the ",(0,r.kt)("a",{parentName:"p",href:"https://docs.openziti.io/docs/learn/introduction/"},"OpenZiti")," programmable zero trust network overlay. ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is open source, licensed under the Apache v2 license. You can choose to self-host ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," or leverage the free, managed offering provided by NetFoundry at ",(0,r.kt)("a",{parentName:"p",href:"https://zrok.io"},"https://zrok.io"),"."),(0,r.kt)("p",null,"As of version ",(0,r.kt)("inlineCode",{parentName:"p"},"v0.4.0"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," provides the ability to:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"share resources ",(0,r.kt)("a",{parentName:"li",href:"/docs/concepts/sharing-public"},"publicly"),", 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"),(0,r.kt)("li",{parentName:"ul"},"share resources ",(0,r.kt)("a",{parentName:"li",href:"/docs/concepts/sharing-private"},"privately"),"; private sharing uses peer-to-peer connectivity between two parties by leveraging the OpenZiti overlay. We believe the private sharing offered by ",(0,r.kt)("inlineCode",{parentName:"li"},"zrok")," provides a unique level of security and privacy for this type of sharing.")),(0,r.kt)("p",null,"As of version ",(0,r.kt)("inlineCode",{parentName:"p"},"v0.4.0"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," allows sharing these kinds of resources:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"HTTP/S resources; ",(0,r.kt)("inlineCode",{parentName:"li"},"zrok")," provides reverse proxy capabilities for your HTTP/S endpoints, both publicly and privately"),(0,r.kt)("li",{parentName:"ul"},"file resources; ",(0,r.kt)("inlineCode",{parentName:"li"},"zrok")," provides built in ",(0,r.kt)("inlineCode",{parentName:"li"},"web")," capabilities, allowing you to share your files with other users, both publicly and privately"),(0,r.kt)("li",{parentName:"ul"},"TCP and UDP tunnels; ",(0,r.kt)("inlineCode",{parentName:"li"},"zrok")," provides built-in ",(0,r.kt)("inlineCode",{parentName:"li"},"tunnel")," capabilities, allowing you to share your TCP and UDP endpoints directly with other users privately (",(0,r.kt)("inlineCode",{parentName:"li"},"zrok")," does not currently offer public sharing of these kinds of resources)")),(0,r.kt)("p",null,"Let's take a look at how to get started with ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok"),"."),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("mdxAdmonitionTitle",{parentName:"admonition"},(0,r.kt)("inlineCode",{parentName:"mdxAdmonitionTitle"},"zrok")," moves fast!"),(0,r.kt)("p",{parentName:"admonition"},(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is an open source project and is in its early development phases. We're doing our development publicly. See the ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/orgs/openziti/projects/16"},"roadmap")," for details about the project. We are highly interested in feedback as we continue to iterate quickly. Please provide feedback in ",(0,r.kt)("a",{parentName:"p",href:"https://openziti.discourse.group/"},"Discourse"),", raise ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/openziti/zrok/issues"},"GitHub Issues"),", or reach out directly.")),(0,r.kt)("h2",{id:"downloading-zrok"},"Downloading zrok"),(0,r.kt)("p",null,"Releases are also available from the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," project repository on GitHub at ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/openziti/zrok/releases/latest"},"https://github.com/openziti/zrok/releases/latest"),". If you're a Linux user and you're not sure which download to use then check out the hints on ",(0,r.kt)("a",{parentName:"p",href:"/docs/downloads"},"the Downloads page"),"."),(0,r.kt)("h3",{id:"extract-zrok-distribution"},"Extract zrok Distribution"),(0,r.kt)("p",null,"Move the downloaded ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," distribution into a directory on your system. In my case, I've placed it in my home directory:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ ls -lF zrok*\n-rwxr-xr-x 1 michael michael 14459159 May 31 13:46 zrok_0.4.0-rc6_linux_amd64.tar.gz*\n")),(0,r.kt)("p",null,"Create a directory where the extracted distribution will sit:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ mkdir zrok\n$ cd zrok/\n")),(0,r.kt)("p",null,"Extract the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," distribution:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ tar zxvf ../zrok_0.4.0-rc1_linux_amd64.tar.gz\nCHANGELOG.md\nREADME.md\nzrok\n")),(0,r.kt)("blockquote",null,(0,r.kt)("p",{parentName:"blockquote"},"NOTE: On Windows platforms the distribution is shipped as a ",(0,r.kt)("inlineCode",{parentName:"p"},"zip")," archive. Windows Explorer includes support for extracting ",(0,r.kt)("inlineCode",{parentName:"p"},"zip")," archives natively.")),(0,r.kt)("p",null,"Add ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," to your shell's environment."),(0,r.kt)("p",null,"For Linux or macos:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ export PATH=`pwd`:$PATH\n")),(0,r.kt)("p",null,"For Windows (using Command Prompt):"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"> set PATH=%CD%;%PATH%\n")),(0,r.kt)("p",null,"For Windows (using PowerShell):"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},'$env:path += ";"+$pwd.Path\n')),(0,r.kt)("p",null,"With the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," executable in your path, you can then execute the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," command from your shell:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ ./zrok version\n _ \n _____ __ ___ | | __\n|_ / '__/ _ \\| |/ /\n / /| | | (_) | < \n/___|_| \\___/|_|\\_\\\n\nv0.4.0-rc6 [c889005]\n")),(0,r.kt)("h2",{id:"configure-your-zrok-service-instance"},"Configure Your zrok Service Instance"),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("p",{parentName:"admonition"},'Most users can safely skip this section and proceed to "Generating an Invitation" below.'),(0,r.kt)("p",{parentName:"admonition"},"This section is relevant if you want to use the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," CLI with an alternate service instance (in the case of self-hosting, etc.).")),(0,r.kt)("p",null,(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is both an installable utility that you interact with from your local computer, and also a ",(0,r.kt)("em",{parentName:"p"},"service")," that exists on the network. NetFoundry operates the public ",(0,r.kt)("em",{parentName:"p"},"service instance")," that is available at ",(0,r.kt)("inlineCode",{parentName:"p"},"api.zrok.io"),", but because ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is open source and self-hostable, you're free to create your own ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service instance."),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," executable defaults to using the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service instance at ",(0,r.kt)("inlineCode",{parentName:"p"},"api.zrok.io"),". Should you need to change the endpoint to use a different service instance, you can do that with the following command:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok config set apiEndpoint https://zrok.mydomain.com\n[WARNING]: unable to open zrokdir metadata; ignoring\n\nzrok configuration updated\n")),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("p",{parentName:"admonition"},"The ",(0,r.kt)("inlineCode",{parentName:"p"},"WARNING")," about ",(0,r.kt)("inlineCode",{parentName:"p"},"zrokdir metadata")," is ignorable. Running the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok config set")," command writes a small piece of metadata into a ",(0,r.kt)("inlineCode",{parentName:"p"},".zrok")," folder inside your home directory. This allows ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," to identify the version of its settings, providing a mechanism to upgrade your installation as new versions are released. This ",(0,r.kt)("inlineCode",{parentName:"p"},"WARNING")," is letting you know that your current environment has not been initialized by ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok"),".")),(0,r.kt)("p",null,"You can use the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok status")," command to inspect the state of your local ",(0,r.kt)("em",{parentName:"p"},"environment"),". ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," refers to each shell where you install and ",(0,r.kt)("inlineCode",{parentName:"p"},"enable")," a copy of ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," as as an ",(0,r.kt)("em",{parentName:"p"},"environment"),"."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok status\n\nConfig:\n\n CONFIG VALUE SOURCE \n apiEndpoint https://zrok.mydomain.com config \n\n[WARNING]: Unable to load your local environment!\n\nTo create a local environment use the zrok enable command.\n")),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("p",{parentName:"admonition"},"The ",(0,r.kt)("inlineCode",{parentName:"p"},"WARNING")," about being ",(0,r.kt)("inlineCode",{parentName:"p"},"unable to load your local environment")," will go away once you've successfully enabled (",(0,r.kt)("inlineCode",{parentName:"p"},"zrok enable"),") for your shell (we'll get to that below). For now, this warning is ignorable.")),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok status")," command shows the configured API service that your environment is using, as well as the ",(0,r.kt)("inlineCode",{parentName:"p"},"SOURCE")," where the setting was retrieved. In this case, ",(0,r.kt)("inlineCode",{parentName:"p"},"config")," means that the setting was set into the environment using the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok config")," command."),(0,r.kt)("h2",{id:"generating-an-invitation"},"Generating an Invitation"),(0,r.kt)("p",null,"In order to create an account with the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service instance, you will need to create an invitation. "),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("p",{parentName:"admonition"},"Some environments take advantage of ",(0,r.kt)("em",{parentName:"p"},"invitation tokens"),", which limit who is able to request an invitation on the service instance. If your service uses invitation tokens, the administrator of your instance will include details about how to use your token to generate your invitation.")),(0,r.kt)("p",null,"We generate an invitation with the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok invite")," command. A service instance that allows open registration will provide an input form like this:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok invite\n\nenter and confirm your email address...\n\n> user@domain.com\n> user@domain.com\n\n[ Submit ]\n\ninvitation sent to 'user@domain.com'!\n")),(0,r.kt)("p",null,"A service instance that requires token-based invitation authentication will present a form that looks like this:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok invite\n\nenter and confirm your email address...\n\nIf you don't already have one, request an invite token at: michael@quigley.com\n\n> Email Address\n> Confirm Email\n> Token\n\n\n[ Submit ]\n")),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok invite")," command presents a small form that allows you to enter (and then confirm) your email address. Tabbing to the ",(0,r.kt)("inlineCode",{parentName:"p"},"[ Submit ]")," button will send the request to your configured ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service."),(0,r.kt)("p",null,"Next, check the email where you sent the invite. You should receive a message asking you to click a link to create your ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," account. When you click that link, you will be brought to a web page that will allow you to set a password for your new account:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Enter a Password",src:n(9744).Z,width:"1791",height:"1362"})),(0,r.kt)("p",null,"Enter a password and it's confirmation, and click the ",(0,r.kt)("inlineCode",{parentName:"p"},"Register Account")," button. You'll see the following:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Successful Registration",src:n(242).Z,width:"1791",height:"1369"})),(0,r.kt)("p",null,'For now, we\'ll ignore the "enable your shell for zrok" section. Just click the ',(0,r.kt)("inlineCode",{parentName:"p"},"zrok web portal")," link:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Web Login",src:n(9509).Z,width:"1791",height:"1362"})),(0,r.kt)("p",null,"After clicking the ",(0,r.kt)("inlineCode",{parentName:"p"},"Log In")," button, you'll be brought into the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," ",(0,r.kt)("em",{parentName:"p"},"web console"),":"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Web Console; Empty",src:n(2945).Z,width:"1791",height:"1362"})),(0,r.kt)("p",null,"Congratulations! Your ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," account is ready to go!"),(0,r.kt)("h2",{id:"enabling-your-zrok-environment"},"Enabling Your zrok Environment"),(0,r.kt)("p",null,"When your ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," account was created, the service generated a ",(0,r.kt)("em",{parentName:"p"},"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 ",(0,r.kt)("em",{parentName:"p"},"secret"),", protect it."),(0,r.kt)("p",null,"When we left off you had downloaded, extracted, and configured your ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," environment. In order to use that environment with your account, you'll need to ",(0,r.kt)("inlineCode",{parentName:"p"},"enable")," it. Enabling an environment generates a secure identity and the necessary underlying security policies with the OpenZiti network hosting the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service."),(0,r.kt)("p",null,"From the web console, click on your email address in the upper right corner of the header. That drop down menu contains an ",(0,r.kt)("inlineCode",{parentName:"p"},"Enable Your Environment")," link. Click that link and a modal dialog will be shown like this:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Enable Modal Dialog",src:n(9042).Z,width:"1791",height:"1369"})),(0,r.kt)("p",null,"This dialog box shows you the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok enable")," command that you can use to enable any shell to work with your ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," account with a single command."),(0,r.kt)("p",null,"Let's copy that command and paste it into your shell:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok enable klFEoIi0QAg7 \n\u28fb contacting the zrok service...\n")),(0,r.kt)("p",null,"After a few seconds, the message will change and indicate that the enable operation suceeded:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok enable klFEoIi0QAg7 \n\u28fb the zrok environment was successfully enabled...\n")),(0,r.kt)("p",null,"Now, if we run a ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok status")," command, you will see the details of your environment:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok status\n\nConfig:\n\n CONFIG VALUE SOURCE\n apiEndpoint https://api.staging.zrok.io env\n\nEnvironment:\n\n PROPERTY VALUE\n Secret Token <>\n Ziti Identity <>\n")),(0,r.kt)("p",null,"Excellent... our environment is now fully enabled."),(0,r.kt)("p",null,"If we return to the ",(0,r.kt)("em",{parentName:"p"},"web console"),", we'll now see the new environment reflected in the explorer view:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"New Environment in Web UI",src:n(5546).Z,width:"1791",height:"1369"})),(0,r.kt)("p",null,"In my case, the environment is named ",(0,r.kt)("inlineCode",{parentName:"p"},"michael@ziti-lx"),", which is the username of my shell and the hostname of the system the shell is running on."),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("p",{parentName:"admonition"},"Should you want to use a non-default name for your environment, you can pass the ",(0,r.kt)("inlineCode",{parentName:"p"},"-d")," option to the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok enable")," command. See ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok enable --help")," for details.")),(0,r.kt)("p",null,"If you click on the environment node in the explorer in the ",(0,r.kt)("em",{parentName:"p"},"web console"),", the details panel shown at the bottom of the page will change:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Empty Environment",src:n(3858).Z,width:"1791",height:"1369"})),(0,r.kt)("p",null,"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 ",(0,r.kt)("img",{alt:"Zoom to Fit",src:n(3843).Z,width:"30",height:"25"})," ",(0,r.kt)("em",{parentName:"p"},"zoom to fit")," icon in the lower right corner of the explorer."),(0,r.kt)("p",null,"If we click on the ",(0,r.kt)("inlineCode",{parentName:"p"},"Detail")," tab for our environment, we'll see something like:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Environment Detail",src:n(2534).Z,width:"1791",height:"1369"})),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("p",{parentName:"admonition"},"With your ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," account you can ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok enable")," multiple environments. This will allow you to run ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," in one environment, and ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok access")," in other environments.")),(0,r.kt)("p",null,"Your environment is fully ready to go. Now we can move on to the fun stuff..."),(0,r.kt)("h2",{id:"sharing"},"Sharing"),(0,r.kt)("p",null,(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," is designed to make sharing resources as effortless as possible, while providing a high degree of security and control."),(0,r.kt)("h3",{id:"ephemeral-by-default"},"Ephemeral by Default"),(0,r.kt)("p",null,"Shared resources are ",(0,r.kt)("em",{parentName:"p"},"ephemeral")," by default; as soon as you terminate the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," command, the entire share is removed and is no longer available to any users. Identifiers for shared resources are randomly allocated when the share is created."),(0,r.kt)("h3",{id:"public-shares-and-frontends"},"Public Shares and Frontends"),(0,r.kt)("p",null,"Resources that are shared ",(0,r.kt)("em",{parentName:"p"},"publicly")," are exposed to any users on the internet who have access to the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok"),' service instance\'s "frontend".'),(0,r.kt)("p",null,"A frontend is an HTTPS listener exposed to the internet, that lets any user with your ephemeral share token access your publicly shared resources."),(0,r.kt)("p",null,"For example, I might create a public share using the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share public")," command, which results in my ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service instance exposing the following URL to access my resources:"),(0,r.kt)("p",null,(0,r.kt)("a",{parentName:"p",href:"https://2ptgbr8tlfvk.share.zrok.io"},"https://2ptgbr8tlfvk.share.zrok.io")),(0,r.kt)("p",null,'In this case my share was given the "share token" of ',(0,r.kt)("inlineCode",{parentName:"p"},"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."),(0,r.kt)("admonition",{type:"note"},(0,r.kt)("p",{parentName:"admonition"},"Here is the ",(0,r.kt)("inlineCode",{parentName:"p"},"--help")," output from ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share public"),":"),(0,r.kt)("pre",{parentName:"admonition"},(0,r.kt)("code",{parentName:"pre"},'$ zrok share public\nError: accepts 1 arg(s), received 0\nUsage:\n zrok share public [flags]\n\nFlags:\n --backend-mode string The backend mode {proxy, web} (default "proxy")\n --basic-auth stringArray Basic authentication users (,...)\n --frontends stringArray Selected frontends to use for the share (default [public])\n --headless Disable TUI and run headless\n -h, --help help for public\n --insecure Enable insecure TLS certificate validation for \n\nGlobal Flags:\n -p, --panic Panic instead of showing pretty errors\n -v, --verbose Enable verbose logging\n\n[ERROR]: an error occurred (accepts 1 arg(s), received 0)\n')),(0,r.kt)("p",{parentName:"admonition"},(0,r.kt)("inlineCode",{parentName:"p"},"")," defines the path to the local resource that you intend to share. The form of ",(0,r.kt)("inlineCode",{parentName:"p"},"")," depends on the ",(0,r.kt)("inlineCode",{parentName:"p"},"--backend-mode")," that you're using. "),(0,r.kt)("p",{parentName:"admonition"},"In the case of ",(0,r.kt)("inlineCode",{parentName:"p"},"--backend-mode proxy"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"")," should be a URL to an HTTP endpoint."),(0,r.kt)("p",{parentName:"admonition"},"In the case of ",(0,r.kt)("inlineCode",{parentName:"p"},"--backend-mode web"),", ",(0,r.kt)("inlineCode",{parentName:"p"},""),' is the path to a file on disk that serves as the "root" of the file tree to be shared.')),(0,r.kt)("p",null,"If we return to the web console, we see our share in the explorer:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Web Console Share",src:n(6097).Z,width:"1791",height:"1369"})),(0,r.kt)("p",null,"If we click on our new share in the explorer, we can see the share details:\n",(0,r.kt)("img",{alt:"Share Details",src:n(4647).Z,width:"1791",height:"1369"})),(0,r.kt)("p",null,"If we click on the ",(0,r.kt)("em",{parentName:"p"},"frontend endpoint")," a new browser tab opens and we see the content of our share:\n",(0,r.kt)("img",{alt:"Share Frontend",src:n(6254).Z,width:"1556",height:"1229"})),(0,r.kt)("p",null,"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:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Environment Spark Line",src:n(9737).Z,width:"1791",height:"1369"})),(0,r.kt)("p",null,"And as soon as I terminate the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," client, the resources are removed from the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," environment."),(0,r.kt)("p",null,"If we try to reload the frontend endpoint in our web browser, we'll see:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Not Found",src:n(5724).Z,width:"1556",height:"1229"})),(0,r.kt)("h3",{id:"private-shares"},"Private Shares"),(0,r.kt)("p",null,(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," also provides a powerful ",(0,r.kt)("em",{parentName:"p"},"private")," sharing model. If I execute the following command:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok share private http://localhost:8080\n")),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service will respond with the following:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"access your share with: zrok access private wvszln4dyz9q\n")),(0,r.kt)("p",null,"Rather than allowing access to your service through a public frontend, a ",(0,r.kt)("em",{parentName:"p"},"private")," share is only exposed to the underlying OpenZiti network, and can only be accessed using the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok access")," command."),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok access private wvszln4dyz9q")," command can be run by any ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," user, allowing them to create and bind a local HTTP listener, that allows for private access to your shared resources."),(0,r.kt)("h3",{id:"proxy-backend-mode"},"Proxy Backend Mode"),(0,r.kt)("p",null,"Without specifying a ",(0,r.kt)("em",{parentName:"p"},"backend mode"),", the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," command will assume that you're trying to share a ",(0,r.kt)("inlineCode",{parentName:"p"},"proxy")," resource. A ",(0,r.kt)("inlineCode",{parentName:"p"},"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 ",(0,r.kt)("inlineCode",{parentName:"p"},"localhost"),", or only listening on a private LAN segment behind a firewall. "),(0,r.kt)("p",null,"For these services a ",(0,r.kt)("inlineCode",{parentName:"p"},"proxy")," share will allow those endpoints to be reached, either ",(0,r.kt)("em",{parentName:"p"},"publicly")," or ",(0,r.kt)("em",{parentName:"p"},"privately")," through the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service."),(0,r.kt)("h3",{id:"web-backend-mode"},"Web Backend Mode"),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," command accepts a ",(0,r.kt)("inlineCode",{parentName:"p"},"--backend-mode")," option. Besides ",(0,r.kt)("inlineCode",{parentName:"p"},"proxy"),", the current ",(0,r.kt)("inlineCode",{parentName:"p"},"v0.3")," release (as of this writing) also supports a ",(0,r.kt)("inlineCode",{parentName:"p"},"web")," mode. The ",(0,r.kt)("inlineCode",{parentName:"p"},"web")," mode allows you to specify a local folder on your filesystem, and instantly turns your ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," client into a web server, exposing your web content either ",(0,r.kt)("em",{parentName:"p"},"publicly")," or ",(0,r.kt)("em",{parentName:"p"},"privately")," without having to a configure a web server."),(0,r.kt)("h3",{id:"reserved-shares"},"Reserved Shares"),(0,r.kt)("p",null,(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," shares are ",(0,r.kt)("em",{parentName:"p"},"ephemeral"),' unless you specifically create a "reserved" share.'),(0,r.kt)("p",null,"A reserved share can be re-used multiple times; it will survive termination of the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," command, allowing for longer-lasting semi-permanent access to shared resources."),(0,r.kt)("p",null,"The first step is to create the reserved share:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok reserve public --backend-mode web v0.3_getting_started\n[ 0.275] INFO main.(*reserveCommand).run: your reserved share token is 'mltwsinym1s2'\n[ 0.275] INFO main.(*reserveCommand).run: reserved frontend endpoint: https://mltwsinym1s2.share.zrok.io\n")),(0,r.kt)("p",null,"I'm asking the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service to reserve a share with a ",(0,r.kt)("inlineCode",{parentName:"p"},"web")," backend mode, pointing at my local ",(0,r.kt)("inlineCode",{parentName:"p"},"docs")," folder."),(0,r.kt)("p",null,"You'll want to remember the share token (",(0,r.kt)("inlineCode",{parentName:"p"},"mltwsinym1s2")," in this case), and the frontend endpoint URL. If this were a ",(0,r.kt)("em",{parentName:"p"},"private")," reserved share, there would not be a frontend URL."),(0,r.kt)("p",null,"If we do nothing else, and then point a web browser at the frontend endpoint, we get:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Not Found",src:n(7369).Z,width:"1556",height:"1229"})),(0,r.kt)("p",null,"This is the ",(0,r.kt)("inlineCode",{parentName:"p"},"404")," error message returned by the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," frontend. We're getting this because we haven't yet started up a ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," for the service. Let's do that:"),(0,r.kt)("p",null,"This command:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok share reserved mltwsinym1s2\n")),(0,r.kt)("p",null,"...results in a new share backend starting up and connecting to the existing reserved share:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"zrok share reserved",src:n(1577).Z,width:"951",height:"706"})),(0,r.kt)("p",null,"And now if we refresh the frontend endpoint URL in the web browser, we'll see an index of the ",(0,r.kt)("inlineCode",{parentName:"p"},"docs")," directory:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"zrok docs share",src:n(6377).Z,width:"1556",height:"1229"})),(0,r.kt)("p",null,"With the reserved share, we're free to stop and restart the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share reserved")," command as many times as we want, without losing the token for our share."),(0,r.kt)("p",null,"When we're done with the reserved share, we can ",(0,r.kt)("em",{parentName:"p"},"release")," it using this command:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"$ zrok release mltwsinym1s2\n[ 0.230] INFO main.(*releaseCommand).run: reserved share 'mltwsinym1s2' released\n")),(0,r.kt)("h2",{id:"concepts-review"},"Concepts Review"),(0,r.kt)("p",null,"In summary, ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," lets you easily and securely share resources with both general internet users (through ",(0,r.kt)("em",{parentName:"p"},"public")," sharing) and also with other ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," users (through ",(0,r.kt)("em",{parentName:"p"},"private")," sharing)."),(0,r.kt)("p",null,"Here's a quick review of the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," mental model and the vocabulary."),(0,r.kt)("h3",{id:"service-instance-and-account"},"Service Instance and Account"),(0,r.kt)("p",null,"You create an ",(0,r.kt)("em",{parentName:"p"},"account")," with a ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," ",(0,r.kt)("em",{parentName:"p"},"service instance"),". Your account is identified by a username and a password, which you use to log into the ",(0,r.kt)("em",{parentName:"p"},"web console"),". Your account also has a ",(0,r.kt)("em",{parentName:"p"},"secret token"),", which you will use to authenticate from the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," command-line to interact with the ",(0,r.kt)("em",{parentName:"p"},"service instance"),"."),(0,r.kt)("p",null,"You create a new ",(0,r.kt)("em",{parentName:"p"},"account")," with a ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," ",(0,r.kt)("em",{parentName:"p"},"service instance")," through the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok invite")," command."),(0,r.kt)("h3",{id:"environment"},"Environment"),(0,r.kt)("p",null,"Using your ",(0,r.kt)("em",{parentName:"p"},"secret token")," you use the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," command-line interface to create an ",(0,r.kt)("em",{parentName:"p"},"environment"),". An ",(0,r.kt)("em",{parentName:"p"},"environment")," corresponds to a single command-line user on a specific ",(0,r.kt)("em",{parentName:"p"},"host system"),". "),(0,r.kt)("p",null,"You create a new ",(0,r.kt)("em",{parentName:"p"},"environment")," by using the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok enable")," command."),(0,r.kt)("h3",{id:"shares"},"Shares"),(0,r.kt)("p",null,"Once you've enabled an ",(0,r.kt)("em",{parentName:"p"},"environment"),", you then create one or more ",(0,r.kt)("em",{parentName:"p"},"shares"),". Shares have either a ",(0,r.kt)("em",{parentName:"p"},"public")," or ",(0,r.kt)("em",{parentName:"p"},"private")," ",(0,r.kt)("em",{parentName:"p"},"sharing mode"),". ",(0,r.kt)("em",{parentName:"p"},"Shares")," share a specific type of resource using a ",(0,r.kt)("em",{parentName:"p"},"backend mode"),". As of this writing ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," supports a ",(0,r.kt)("inlineCode",{parentName:"p"},"proxy")," ",(0,r.kt)("em",{parentName:"p"},"backend mode")," to share local HTTP resources as a ",(0,r.kt)("em",{parentName:"p"},"reverse proxy"),". ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," also supports a ",(0,r.kt)("inlineCode",{parentName:"p"},"web")," ",(0,r.kt)("em",{parentName:"p"},"backend mode")," to share local file and HTML resources by enabling a basic HTTP server."),(0,r.kt)("p",null,"Every ",(0,r.kt)("em",{parentName:"p"},"share")," is identified by a ",(0,r.kt)("em",{parentName:"p"},"share token"),". ",(0,r.kt)("em",{parentName:"p"},"Public shares")," can be accessed through either a ",(0,r.kt)("em",{parentName:"p"},"frontend")," instance offered through the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," ",(0,r.kt)("em",{parentName:"p"},"service instance"),", or through the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok access")," command. ",(0,r.kt)("em",{parentName:"p"},"Private shares")," can only be accessed through the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok access")," command."),(0,r.kt)("p",null,"You use the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," command to create and enable ",(0,r.kt)("em",{parentName:"p"},"ephemeral shares"),"."),(0,r.kt)("h3",{id:"reserved-shares-1"},"Reserved Shares"),(0,r.kt)("p",null,(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," supports creating ",(0,r.kt)("em",{parentName:"p"},"shares")," that have a consistent ",(0,r.kt)("em",{parentName:"p"},"share token")," that survives restarts of the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok share")," command. These are considered ",(0,r.kt)("em",{parentName:"p"},"non-ephemeral"),", and is callled a ",(0,r.kt)("em",{parentName:"p"},"reserved share"),"."),(0,r.kt)("p",null,"You use the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok reserve")," command to create ",(0,r.kt)("em",{parentName:"p"},"reserved shares"),". Reserved shares last until you use the ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok release")," command to delete them."),(0,r.kt)("h2",{id:"self-hosting-a-service-instance"},"Self-Hosting a Service Instance"),(0,r.kt)("p",null,"Interested in self-hosting your own ",(0,r.kt)("inlineCode",{parentName:"p"},"zrok")," service instance? See the ",(0,r.kt)("a",{parentName:"p",href:"/docs/guides/self-hosting/self_hosting_guide"},"self-hosting guide")," for details."))}c.isMDXComponent=!0},6377:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_docs_share-1c87532d471ab25aaa1590d6215a1427.png"},9042:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_enable_modal-45da63a6907e930daaa4c798272ce5fa.png"},5724:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_not_found-fa3415937c341eb10e1eb98c9b063583.png"},242:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_registration_success-05e7e328284f6dc38cd993322698d38b.png"},7369:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_reserved_not_found-2519707e5cc3e635b7a6feb381c1d040.png"},1577:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_share_reserved-6bce67775ce2c41abb0ef13ee1fad972.png"},9744:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_verify-22a26d401b9a77a4278f3c0f54d2a981.png"},2945:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_console_empty-cce147eaf8e7bc83abe556336a4aea98.png"},9737:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_console_environment_spark-925c0709ed7a42f0a708ab0523cdeb5f.png"},6097:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_console_explorer_share-11236f68819da60014d5444e7429c189.png"},4647:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_console_share_detail-efeaa472d5e5c225a160f6d5647086b3.png"},6254:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_console_share_frontend-d36b169cea46f834e74af4aa456d0b89.png"},9509:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_login-a6161cc79e66932fab76994bdfb8f9c1.png"},2534:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_ui_empty_environment_detail-153c921ade86f924079947b0f734e3ff.png"},3858:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_ui_empty_shares-048c08c18477bcabb9fa8c1b58537012.png"},5546:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/zrok_web_ui_new_environment-414d8e8fc25b09f257cb40ba47d6acbb.png"},3843:(e,t,n)=>{n.d(t,{Z:()=>a});const a="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAB4AAAAZCAIAAACpVwlNAAAEr2lUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNS41LjAiPgogPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIgogICAgeG1sbnM6dGlmZj0iaHR0cDovL25zLmFkb2JlLmNvbS90aWZmLzEuMC8iCiAgICB4bWxuczpleGlmPSJodHRwOi8vbnMuYWRvYmUuY29tL2V4aWYvMS4wLyIKICAgIHhtbG5zOnBob3Rvc2hvcD0iaHR0cDovL25zLmFkb2JlLmNvbS9waG90b3Nob3AvMS4wLyIKICAgIHhtbG5zOnhtcD0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wLyIKICAgIHhtbG5zOnhtcE1NPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvbW0vIgogICAgeG1sbnM6c3RFdnQ9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZUV2ZW50IyIKICAgdGlmZjpJbWFnZUxlbmd0aD0iMjUiCiAgIHRpZmY6SW1hZ2VXaWR0aD0iMzAiCiAgIHRpZmY6UmVzb2x1dGlvblVuaXQ9IjIiCiAgIHRpZmY6WFJlc29sdXRpb249Ijk2LzEiCiAgIHRpZmY6WVJlc29sdXRpb249Ijk2LzEiCiAgIGV4aWY6UGl4ZWxYRGltZW5zaW9uPSIzMCIKICAgZXhpZjpQaXhlbFlEaW1lbnNpb249IjI1IgogICBleGlmOkNvbG9yU3BhY2U9IjEiCiAgIHBob3Rvc2hvcDpDb2xvck1vZGU9IjMiCiAgIHBob3Rvc2hvcDpJQ0NQcm9maWxlPSJzUkdCIElFQzYxOTY2LTIuMSIKICAgeG1wOk1vZGlmeURhdGU9IjIwMjMtMDEtMTlUMTA6NTY6NTYtMDU6MDAiCiAgIHhtcDpNZXRhZGF0YURhdGU9IjIwMjMtMDEtMTlUMTA6NTY6NTYtMDU6MDAiPgogICA8eG1wTU06SGlzdG9yeT4KICAgIDxyZGY6U2VxPgogICAgIDxyZGY6bGkKICAgICAgc3RFdnQ6YWN0aW9uPSJwcm9kdWNlZCIKICAgICAgc3RFdnQ6c29mdHdhcmVBZ2VudD0iQWZmaW5pdHkgUGhvdG8gMi4wLjMiCiAgICAgIHN0RXZ0OndoZW49IjIwMjMtMDEtMTlUMTA6NTY6NTYtMDU6MDAiLz4KICAgIDwvcmRmOlNlcT4KICAgPC94bXBNTTpIaXN0b3J5PgogIDwvcmRmOkRlc2NyaXB0aW9uPgogPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KPD94cGFja2V0IGVuZD0iciI/Pq+HLHgAAAGBaUNDUHNSR0IgSUVDNjE5NjYtMi4xAAAokXWRy0tCQRSHP7UwemBQixYtJKyVRg8Q27RQyoJqYQZZbfTmI/BxuVcJaRu0FQqiNr0W9RfUNmgdBEURRNtaF7UpuZ2rghF5hjnzzW/OOcycAWs4rWT0piHIZPNaKOh3LkaWnPYXLHThwIclqujq7PxkmIb2eS/RYrces1bjuH+tbTWuK2BpER5XVC0vPCU8s55XTd4R7lZS0VXhM2G3JhcUvjP1WJVfTU5W+dtkLRwKgLVT2Jn8xbFfrKS0jLC8HFcmXVBq9zFf0h7PLszL2iezF50QQfw4mWaCAF6GGRPvxcMIg7KjQf5QJX+OnOQq4lWKaKyRJEUet6gFqR6XNSF6XEaaotn/v33VE6Mj1ertfmh+Noz3frBvQ7lkGF9HhlE+BtsTXGbr+blD8H2IXqprrgNwbML5VV2L7cLFFvQ8qlEtWpFsMq2JBLydQkcEum6gdbnas9o5Jw8Q3pCvuoa9fRiQeMfKD2DYZ+PDGzxnAAAACXBIWXMAAA7EAAAOxAGVKw4bAAABZklEQVRIie2VvW7CMBDHr1UfwE5fII7lvahIWUEiQ7qxMLEwsVQMSB0YKsTExsDGxFs0QyqlYyMVld3k4wWw/QgMlqp+JXFQGZB649n3k+9/f9sX9w+PcJq4PBH3H/0zrkrWfK99jVF5/V6qIIzqod1m485rC6nK0S5GAPArvRDNHFtINZ0vviQp4Un2OTObjIs6q6G122yMhgPfaxvuN0VbGDHHBgDm2FbVAGqgLYyEVPFmCwDB84uQilHyB2i32ej3uoySvZDT+YInGaPE77QqlSkznz5vv9cFAEbJdL4QUlkYjYYDnYnf3o9HC6mewog5ttZBq7xcrf1OK95sy61ZgQaAIIx2lGgdRsPBcrXmSbYXstLyRmPkSWZh5HdaAODe3uipVlaZmk9IxdMcAHiam3DBRJCPCMJol+bfbuMxaJ7mjJLZZFxeb2Gku6mDTrJXjExeviILFqJF8WtpGOf5y5wn+gBcXI4F9z6rgwAAAABJRU5ErkJggg=="}}]); \ No newline at end of file diff --git a/assets/js/runtime~main.8a473bbe.js b/assets/js/runtime~main.485bff31.js similarity index 98% rename from assets/js/runtime~main.8a473bbe.js rename to assets/js/runtime~main.485bff31.js index 0310f677..84300b69 100644 --- a/assets/js/runtime~main.8a473bbe.js +++ b/assets/js/runtime~main.485bff31.js @@ -1 +1 @@ -(()=>{"use strict";var e,t,r,a,o,b={},f={};function c(e){var t=f[e];if(void 0!==t)return t.exports;var r=f[e]={id:e,loaded:!1,exports:{}};return b[e].call(r.exports,r,r.exports,c),r.loaded=!0,r.exports}c.m=b,c.c=f,e=[],c.O=(t,r,a,o)=>{if(!r){var b=1/0;for(i=0;i=o)&&Object.keys(c.O).every((e=>c.O[e](r[n])))?r.splice(n--,1):(f=!1,o0&&e[i-1][2]>o;i--)e[i]=e[i-1];e[i]=[r,a,o]},c.n=e=>{var t=e&&e.__esModule?()=>e.default:()=>e;return c.d(t,{a:t}),t},r=Object.getPrototypeOf?e=>Object.getPrototypeOf(e):e=>e.__proto__,c.t=function(e,a){if(1&a&&(e=this(e)),8&a)return e;if("object"==typeof e&&e){if(4&a&&e.__esModule)return e;if(16&a&&"function"==typeof e.then)return e}var o=Object.create(null);c.r(o);var b={};t=t||[null,r({}),r([]),r(r)];for(var f=2&a&&e;"object"==typeof f&&!~t.indexOf(f);f=r(f))Object.getOwnPropertyNames(f).forEach((t=>b[t]=()=>e[t]));return b.default=()=>e,c.d(o,b),o},c.d=(e,t)=>{for(var r in t)c.o(t,r)&&!c.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:t[r]})},c.f={},c.e=e=>Promise.all(Object.keys(c.f).reduce(((t,r)=>(c.f[r](e,t),t)),[])),c.u=e=>"assets/js/"+({22:"0654c903",53:"935f2afb",55:"613b9d03",76:"2e812224",161:"04b79425",176:"6272ba0e",195:"c4f5d8e4",196:"bbbe662c",198:"50ef9c44",212:"8ae7f3b1",218:"8d0344ba",318:"8ef4b25e",360:"34e1d3b9",364:"60d45520",402:"5b30ef33",514:"1be78505",542:"7b87748c",711:"9a9d4214",732:"c015c796",817:"14eb3368",828:"48230885",838:"75b20590",848:"e6ffb4b4",889:"339d500a",905:"07d0b302",918:"17896441",920:"1a4e3797",945:"bc747cac",964:"f5020ab1",992:"f2348458"}[e]||e)+"."+{22:"c12cbc94",53:"8d0169ed",55:"70520b78",76:"f1e4de88",161:"740c756e",176:"80ce924b",195:"6798201d",196:"b5867e23",198:"d7719acf",212:"0cb2d38d",218:"b4e0ea48",318:"6f4db50f",360:"cbef2106",364:"b80527ca",402:"58e5f77e",514:"0c24f0b7",542:"178bbe40",711:"1eaae2f3",732:"67d24e4e",780:"64f5d662",817:"a0c98557",828:"5b9dfec1",838:"da313344",848:"23b860d7",889:"f0aa2810",894:"e787cecf",905:"cb0d3b7a",918:"9f5d97a4",920:"f76be9ed",945:"0ba762cf",964:"b9410de0",969:"ba5129f7",972:"dc0f5947",992:"e27de763"}[e]+".js",c.miniCssF=e=>{},c.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),c.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),a={},o="website:",c.l=(e,t,r,b)=>{if(a[e])a[e].push(t);else{var f,n;if(void 0!==r)for(var d=document.getElementsByTagName("script"),i=0;i{f.onerror=f.onload=null,clearTimeout(s);var o=a[e];if(delete a[e],f.parentNode&&f.parentNode.removeChild(f),o&&o.forEach((e=>e(r))),t)return t(r)},s=setTimeout(l.bind(null,void 0,{type:"timeout",target:f}),12e4);f.onerror=l.bind(null,f.onerror),f.onload=l.bind(null,f.onload),n&&document.head.appendChild(f)}},c.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},c.p="/",c.gca=function(e){return e={17896441:"918",48230885:"828","0654c903":"22","935f2afb":"53","613b9d03":"55","2e812224":"76","04b79425":"161","6272ba0e":"176",c4f5d8e4:"195",bbbe662c:"196","50ef9c44":"198","8ae7f3b1":"212","8d0344ba":"218","8ef4b25e":"318","34e1d3b9":"360","60d45520":"364","5b30ef33":"402","1be78505":"514","7b87748c":"542","9a9d4214":"711",c015c796:"732","14eb3368":"817","75b20590":"838",e6ffb4b4:"848","339d500a":"889","07d0b302":"905","1a4e3797":"920",bc747cac:"945",f5020ab1:"964",f2348458:"992"}[e]||e,c.p+c.u(e)},(()=>{var e={303:0,532:0};c.f.j=(t,r)=>{var a=c.o(e,t)?e[t]:void 0;if(0!==a)if(a)r.push(a[2]);else if(/^(303|532)$/.test(t))e[t]=0;else{var o=new Promise(((r,o)=>a=e[t]=[r,o]));r.push(a[2]=o);var b=c.p+c.u(t),f=new Error;c.l(b,(r=>{if(c.o(e,t)&&(0!==(a=e[t])&&(e[t]=void 0),a)){var o=r&&("load"===r.type?"missing":r.type),b=r&&r.target&&r.target.src;f.message="Loading chunk "+t+" failed.\n("+o+": "+b+")",f.name="ChunkLoadError",f.type=o,f.request=b,a[1](f)}}),"chunk-"+t,t)}},c.O.j=t=>0===e[t];var t=(t,r)=>{var a,o,b=r[0],f=r[1],n=r[2],d=0;if(b.some((t=>0!==e[t]))){for(a in f)c.o(f,a)&&(c.m[a]=f[a]);if(n)var i=n(c)}for(t&&t(r);d{"use strict";var e,t,r,a,o,b={},f={};function c(e){var t=f[e];if(void 0!==t)return t.exports;var r=f[e]={id:e,loaded:!1,exports:{}};return b[e].call(r.exports,r,r.exports,c),r.loaded=!0,r.exports}c.m=b,c.c=f,e=[],c.O=(t,r,a,o)=>{if(!r){var b=1/0;for(i=0;i=o)&&Object.keys(c.O).every((e=>c.O[e](r[n])))?r.splice(n--,1):(f=!1,o0&&e[i-1][2]>o;i--)e[i]=e[i-1];e[i]=[r,a,o]},c.n=e=>{var t=e&&e.__esModule?()=>e.default:()=>e;return c.d(t,{a:t}),t},r=Object.getPrototypeOf?e=>Object.getPrototypeOf(e):e=>e.__proto__,c.t=function(e,a){if(1&a&&(e=this(e)),8&a)return e;if("object"==typeof e&&e){if(4&a&&e.__esModule)return e;if(16&a&&"function"==typeof e.then)return e}var o=Object.create(null);c.r(o);var b={};t=t||[null,r({}),r([]),r(r)];for(var f=2&a&&e;"object"==typeof f&&!~t.indexOf(f);f=r(f))Object.getOwnPropertyNames(f).forEach((t=>b[t]=()=>e[t]));return b.default=()=>e,c.d(o,b),o},c.d=(e,t)=>{for(var r in t)c.o(t,r)&&!c.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:t[r]})},c.f={},c.e=e=>Promise.all(Object.keys(c.f).reduce(((t,r)=>(c.f[r](e,t),t)),[])),c.u=e=>"assets/js/"+({22:"0654c903",53:"935f2afb",55:"613b9d03",76:"2e812224",161:"04b79425",176:"6272ba0e",195:"c4f5d8e4",196:"bbbe662c",198:"50ef9c44",212:"8ae7f3b1",218:"8d0344ba",318:"8ef4b25e",360:"34e1d3b9",364:"60d45520",402:"5b30ef33",514:"1be78505",542:"7b87748c",711:"9a9d4214",732:"c015c796",817:"14eb3368",828:"48230885",838:"75b20590",848:"e6ffb4b4",889:"339d500a",905:"07d0b302",918:"17896441",920:"1a4e3797",945:"bc747cac",964:"f5020ab1",992:"f2348458"}[e]||e)+"."+{22:"c12cbc94",53:"8d0169ed",55:"70520b78",76:"f1e4de88",161:"740c756e",176:"80ce924b",195:"6798201d",196:"b5867e23",198:"d7719acf",212:"0cb2d38d",218:"be075eec",318:"6f4db50f",360:"cbef2106",364:"b80527ca",402:"58e5f77e",514:"0c24f0b7",542:"178bbe40",711:"1eaae2f3",732:"67d24e4e",780:"64f5d662",817:"a0c98557",828:"5b9dfec1",838:"da313344",848:"23b860d7",889:"f0aa2810",894:"e787cecf",905:"cb0d3b7a",918:"9f5d97a4",920:"f76be9ed",945:"0ba762cf",964:"b9410de0",969:"ba5129f7",972:"dc0f5947",992:"e27de763"}[e]+".js",c.miniCssF=e=>{},c.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),c.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),a={},o="website:",c.l=(e,t,r,b)=>{if(a[e])a[e].push(t);else{var f,n;if(void 0!==r)for(var d=document.getElementsByTagName("script"),i=0;i{f.onerror=f.onload=null,clearTimeout(s);var o=a[e];if(delete a[e],f.parentNode&&f.parentNode.removeChild(f),o&&o.forEach((e=>e(r))),t)return t(r)},s=setTimeout(l.bind(null,void 0,{type:"timeout",target:f}),12e4);f.onerror=l.bind(null,f.onerror),f.onload=l.bind(null,f.onload),n&&document.head.appendChild(f)}},c.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},c.p="/",c.gca=function(e){return e={17896441:"918",48230885:"828","0654c903":"22","935f2afb":"53","613b9d03":"55","2e812224":"76","04b79425":"161","6272ba0e":"176",c4f5d8e4:"195",bbbe662c:"196","50ef9c44":"198","8ae7f3b1":"212","8d0344ba":"218","8ef4b25e":"318","34e1d3b9":"360","60d45520":"364","5b30ef33":"402","1be78505":"514","7b87748c":"542","9a9d4214":"711",c015c796:"732","14eb3368":"817","75b20590":"838",e6ffb4b4:"848","339d500a":"889","07d0b302":"905","1a4e3797":"920",bc747cac:"945",f5020ab1:"964",f2348458:"992"}[e]||e,c.p+c.u(e)},(()=>{var e={303:0,532:0};c.f.j=(t,r)=>{var a=c.o(e,t)?e[t]:void 0;if(0!==a)if(a)r.push(a[2]);else if(/^(303|532)$/.test(t))e[t]=0;else{var o=new Promise(((r,o)=>a=e[t]=[r,o]));r.push(a[2]=o);var b=c.p+c.u(t),f=new Error;c.l(b,(r=>{if(c.o(e,t)&&(0!==(a=e[t])&&(e[t]=void 0),a)){var o=r&&("load"===r.type?"missing":r.type),b=r&&r.target&&r.target.src;f.message="Loading chunk "+t+" failed.\n("+o+": "+b+")",f.name="ChunkLoadError",f.type=o,f.request=b,a[1](f)}}),"chunk-"+t,t)}},c.O.j=t=>0===e[t];var t=(t,r)=>{var a,o,b=r[0],f=r[1],n=r[2],d=0;if(b.some((t=>0!==e[t]))){for(a in f)c.o(f,a)&&(c.m[a]=f[a]);if(n)var i=n(c)}for(t&&t(r);d Docker Share | Zrok - +
Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/category/guides/index.html b/docs/category/guides/index.html index 48ad0851..32fd99aa 100644 --- a/docs/category/guides/index.html +++ b/docs/category/guides/index.html @@ -4,13 +4,13 @@ Guides | Zrok - +
Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/category/metrics-and-limits/index.html b/docs/category/metrics-and-limits/index.html index 2b1ac35a..131083f6 100644 --- a/docs/category/metrics-and-limits/index.html +++ b/docs/category/metrics-and-limits/index.html @@ -4,13 +4,13 @@ Metrics and Limits | Zrok - +
Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/category/self-hosting/index.html b/docs/category/self-hosting/index.html index c9c2d86d..7617f921 100644 --- a/docs/category/self-hosting/index.html +++ b/docs/category/self-hosting/index.html @@ -4,13 +4,13 @@ Self Hosting | Zrok - +
Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/concepts/files/index.html b/docs/concepts/files/index.html index 700677f0..9d36e9d9 100644 --- a/docs/concepts/files/index.html +++ b/docs/concepts/files/index.html @@ -4,7 +4,7 @@ Sharing Websites and Files | Zrok - + @@ -12,7 +12,7 @@

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:

-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: 

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

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:

-rw-rw-r--+ 1 Michael None 56 Jun 26 13:23 index.html

If index.html contains valid HTML, like this:

<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_share_web_website

zrok contains a built-in web server, which you can use to serve static websites as a share.

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/concepts/hosting/index.html b/docs/concepts/hosting/index.html index 3208ae87..9b9896c6 100644 --- a/docs/concepts/hosting/index.html +++ b/docs/concepts/hosting/index.html @@ -4,7 +4,7 @@ Hosting | Zrok - + @@ -13,7 +13,7 @@ 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.

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/concepts/http/index.html b/docs/concepts/http/index.html index 7f30e3a2..74105073 100644 --- a/docs/concepts/http/index.html +++ b/docs/concepts/http/index.html @@ -4,13 +4,13 @@ Sharing HTTP Servers | Zrok - +

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.

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/concepts/index.html b/docs/concepts/index.html index ac6d194e..175bef4c 100644 --- a/docs/concepts/index.html +++ b/docs/concepts/index.html @@ -4,14 +4,14 @@ Concepts | Zrok - +

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 or private. Naturally, regular web-based resources can be shared but zrok also includes support for sharing raw TCP and UDP network connections, and also includes a website and file sharing feature.

Learn about zrok hosting here, including instructions on how to install your own zrok instance.

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/concepts/opensource/index.html b/docs/concepts/opensource/index.html index 975752c7..3c2d226c 100644 --- a/docs/concepts/opensource/index.html +++ b/docs/concepts/opensource/index.html @@ -4,7 +4,7 @@ Open Source | Zrok - + @@ -15,7 +15,7 @@ you want to help spread the word of zrok give the project a star. I 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 Ziti native application.

If you are interested in learning more about OpenZiti head over to the docs, try the quickstart, and don't forget to star that project too. We couldn't build zrok without OpenZiti!

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/concepts/sharing-private/index.html b/docs/concepts/sharing-private/index.html index 6eb88c36..9ceaf5c8 100644 --- a/docs/concepts/sharing-private/index.html +++ b/docs/concepts/sharing-private/index.html @@ -4,14 +4,14 @@ Private Shares | Zrok - +

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

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 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.

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/concepts/sharing-public/index.html b/docs/concepts/sharing-public/index.html index ca17ebde..108cbfa4 100644 --- a/docs/concepts/sharing-public/index.html +++ b/docs/concepts/sharing-public/index.html @@ -4,13 +4,13 @@ Public Shares | Zrok - +

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

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.

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/concepts/sharing-reserved/index.html b/docs/concepts/sharing-reserved/index.html index b70aafdf..5a5df459 100644 --- a/docs/concepts/sharing-reserved/index.html +++ b/docs/concepts/sharing-reserved/index.html @@ -4,13 +4,13 @@ Reserved Shares | Zrok - +

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.

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/concepts/tunnels/index.html b/docs/concepts/tunnels/index.html index 0948e5b4..286fe84a 100644 --- a/docs/concepts/tunnels/index.html +++ b/docs/concepts/tunnels/index.html @@ -4,13 +4,13 @@ Sharing TCP and UDP Servers | Zrok - +

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.

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/downloads/index.html b/docs/downloads/index.html index 28c9507e..a6e7e35e 100644 --- a/docs/downloads/index.html +++ b/docs/downloads/index.html @@ -4,13 +4,13 @@ Downloads | Zrok - +

Downloads

Right now all zrok binaries are delivered from the release page at GitHub.

Head over to https://github.com/openziti/zrok/releases/latest to find the latest downloads.

You need the right download for your OS and CPU. This can be confusing because the OS, e.g., Raspberry Pi OS, could be 32bit even if you have a 64bit Pi (v3, 4, or Zero 2). Linux users can always find the right version by looking up the result of uname -m in this table.

ResultLinux Download Name
x86_64linux-amd64
aarch64, arm/v8linux-arm64
armhf, arm/v7linux-armv7
Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/getting-started/index.html b/docs/getting-started/index.html index 0b346b88..ec1daf4f 100644 --- a/docs/getting-started/index.html +++ b/docs/getting-started/index.html @@ -4,20 +4,15 @@ Getting Started with zrok | Zrok - +
-

Getting Started with zrok

zrok is a next-generation sharing platform, designed to make sharing network and file resources simple and secure. zrok is a Ziti Native Application, built on top of the OpenZiti programmable zero trust network overlay. zrok is open source, licensed under the Apache v2 license. You can choose to self-host zrok or leverage the free, managed offering provided by NetFoundry at https://zrok.io.

As of version v0.4.0, zrok provides the ability to:

  • share resources publicly, 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; 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:

  • HTTP/S resources; zrok provides reverse proxy capabilities for your HTTP/S endpoints, both publicly and privately
  • file resources; zrok provides built in web capabilities, allowing you to share your files with other users, both publicly and privately
  • TCP and UDP tunnels; zrok provides built-in tunnel capabilities, allowing you to share your TCP and UDP endpoints directly with other users privately (zrok does not currently offer public sharing of these kinds of resources)

Let's take a look at how to get started with zrok.

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 invite@zrok.io. zrok is an open source project and is in its early development -phases. We're doing our development publicly. See the roadmap for details -about the project. We are highly interested in feedback as we continue to iterate quickly. Please provide feedback in -Discourse, raise GitHub 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. If you're a Linux user and you're not sure which download to use then check out the hints on the Downloads page.

Extract zrok Distribution​

Move the downloaded zrok distribution into a directory on your system. In my case, I've placed it in my home directory:

$ ls -lF zrok*
-rwxr-xr-x 1 michael michael 14459159 May 31 13:46 zrok_0.4.0-rc6_linux_amd64.tar.gz*

Create a directory where the extracted distribution will sit:

$ mkdir zrok
$ cd zrok/

Extract the zrok distribution:

$ tar zxvf ../zrok_0.4.0-rc1_linux_amd64.tar.gz
CHANGELOG.md
README.md
zrok

NOTE: On Windows platforms the distribution is shipped as a zip archive. Windows Explorer includes support for extracting zip archives natively.

Add zrok to your shell's environment.

For Linux or macos:

$ export PATH=`pwd`:$PATH

For Windows (using Command Prompt):

> set PATH=%CD%;%PATH%

For Windows (using PowerShell):

$env:path += ";"+$pwd.Path

With the zrok executable in your path, you can then execute the zrok command from your shell:

$ ./zrok version
               _    
 _____ __ ___ | | __
|_  / '__/ _ \| |/ /
 / /| | | (_) |   < 
/___|_|  \___/|_|\_\

v0.4.0-rc6 [c889005]

Configure Your zrok Service Instance​

note

Most users can safely skip this section and proceed to "Generating an Invitation" below.

This section is relevant if you want to use the zrok CLI with an alternate service instance (in the case of self-hosting, etc.).

zrok is both an installable utility that you interact with from your local computer, and also a service that exists on the network. NetFoundry operates the public service instance that is available at api.zrok.io, but because zrok is open source and self-hostable, you're free to create your own zrok service instance.

The zrok executable defaults to using the zrok service instance at api.zrok.io. Should you need to change the endpoint to use a different service instance, you can do that with the following command:

$ zrok config set apiEndpoint https://zrok.mydomain.com
[WARNING]: unable to open zrokdir metadata; ignoring

zrok configuration updated
note

The WARNING about zrokdir metadata is ignorable. Running the zrok config set command writes a small piece of metadata into a .zrok folder inside your home directory. This allows zrok to identify the version of its settings, providing a mechanism to upgrade your installation as new versions are released. This WARNING is letting you know that your current environment has not been initialized by zrok.

You can use the zrok status command to inspect the state of your local environment. zrok refers to each shell where you install and enable a copy of zrok as as an environment.

$ zrok status

Config:

 CONFIG       VALUE                      SOURCE 
 apiEndpoint  https://zrok.mydomain.com  config 

[WARNING]: Unable to load your local environment!

To create a local environment use the zrok enable command.
note

The WARNING about being unable to load your local environment will go away once you've successfully enabled (zrok enable) for your shell (we'll get to that below). For now, this warning is ignorable.

The zrok status command shows the configured API service that your environment is using, as well as the SOURCE where the setting was retrieved. In this case, config means that the setting was set into the environment using the zrok config command.

Generating an Invitation​

In order to create an account with the zrok service instance, you will need to create an invitation.

note

Some environments take advantage of invitation tokens, which limit who is able to request an invitation on the service instance. If your service uses invitation tokens, the administrator of your instance will include details about how to use your token to generate your invitation.

We generate an invitation with the zrok invite command. A service instance that allows open registration will provide an input form like this:

$ zrok invite

enter and confirm your email address...

> user@domain.com
> user@domain.com

[ Submit ]

invitation sent to 'user@domain.com'!

A service instance that requires token-based invitation authentication will present a form that looks like this:

$ zrok invite

enter and confirm your email address...

If you don't already have one, request an invite token at: michael@quigley.com

> Email Address
> Confirm Email
> Token


[ Submit ]

The zrok invite command presents a small form that allows you to enter (and then confirm) your email address. Tabbing to the [ Submit ] button will send the request to your configured zrok service.

Next, check the email where you sent the invite. You should receive a message asking you to click a link to create your zrok account. When you click that link, you will be brought to a web page that will allow you to set a password for your new account:

Enter a Password

Enter a password and it's confirmation, and click the Register Account button. You'll see the following:

Successful Registration

For now, we'll ignore the "enable your shell for zrok" section. Just click the zrok web portal link:

Web Login

After clicking the Log In button, you'll be brought into the zrok web console:

Web Console; Empty

Congratulations! Your zrok account is ready to go!

Enabling Your zrok Environment​

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 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.

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:

Enable Modal Dialog

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.

Let's copy that command and paste it into your shell:

$ zrok enable klFEoIi0QAg7 
⣻  contacting the zrok service...

After a few seconds, the message will change and indicate that the enable operation suceeded:

$ zrok enable klFEoIi0QAg7 
⣻  the zrok environment was successfully enabled...

Now, if we run a zrok status command, you will see the details of your environment:

$ zrok status

Config:

 CONFIG       VALUE                        SOURCE
 apiEndpoint  https://api.staging.zrok.io  env

Environment:

 PROPERTY       VALUE
 Secret Token   <<SET>>
 Ziti Identity  <<SET>>

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:

New Environment in Web UI

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.

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.

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

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 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

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.

Your environment is fully ready to go. Now we can move on to the fun stuff...

Sharing​

zrok is designed to make sharing resources as effortless as possible, while providing a high degree of security and control.

Ephemeral by Default​

Shared resources are ephemeral by default; as soon as you terminate the zrok share command, the entire share is removed and is no longer available to any users. Identifiers for shared resources are randomly allocated when the share is created.

Public Shares and Frontends​

Resources that are shared publicly are exposed to any users on the internet who have access to the zrok service instance's "frontend".

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 service instance exposing the following URL to access my resources:

https://2ptgbr8tlfvk.share.zrok.io

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:

$ zrok share public
Error: accepts 1 arg(s), received 0
Usage:
  zrok share public <target> [flags]

Flags:
      --backend-mode string      The backend mode {proxy, web} (default "proxy")
      --basic-auth stringArray   Basic authentication users (<username:password>,...)
      --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 <target>

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)

<target> defines the path to the local resource that you intend to share. The form of <target> depends on the --backend-mode that you're using.

In the case of --backend-mode proxy, <target> should be a URL to an HTTP endpoint.

In the case of --backend-mode web, <target> is the path to a file on disk that serves as the "root" of the file tree to be shared.

If we return to the web console, we see our share in the explorer:

Web Console Share

If we click on our new share in the explorer, we can see the share details: +

Getting Started with zrok

zrok is a next-generation sharing platform, designed to make sharing network and file resources simple and secure. zrok is a Ziti Native Application, built on top of the OpenZiti programmable zero trust network overlay. zrok is open source, licensed under the Apache v2 license. You can choose to self-host zrok or leverage the free, managed offering provided by NetFoundry at https://zrok.io.

As of version v0.4.0, zrok provides the ability to:

  • share resources publicly, 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; 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:

  • HTTP/S resources; zrok provides reverse proxy capabilities for your HTTP/S endpoints, both publicly and privately
  • file resources; zrok provides built in web capabilities, allowing you to share your files with other users, both publicly and privately
  • TCP and UDP tunnels; zrok provides built-in tunnel capabilities, allowing you to share your TCP and UDP endpoints directly with other users privately (zrok does not currently offer public sharing of these kinds of resources)

Let's take a look at how to get started with zrok.

zrok moves fast!

zrok is an open source project and is in its early development phases. We're doing our development publicly. See the roadmap for details about the project. We are highly interested in feedback as we continue to iterate quickly. Please provide feedback in Discourse, raise GitHub 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. If you're a Linux user and you're not sure which download to use then check out the hints on the Downloads page.

Extract zrok Distribution​

Move the downloaded zrok distribution into a directory on your system. In my case, I've placed it in my home directory:

$ ls -lF zrok*
-rwxr-xr-x 1 michael michael 14459159 May 31 13:46 zrok_0.4.0-rc6_linux_amd64.tar.gz*

Create a directory where the extracted distribution will sit:

$ mkdir zrok
$ cd zrok/

Extract the zrok distribution:

$ tar zxvf ../zrok_0.4.0-rc1_linux_amd64.tar.gz
CHANGELOG.md
README.md
zrok

NOTE: On Windows platforms the distribution is shipped as a zip archive. Windows Explorer includes support for extracting zip archives natively.

Add zrok to your shell's environment.

For Linux or macos:

$ export PATH=`pwd`:$PATH

For Windows (using Command Prompt):

> set PATH=%CD%;%PATH%

For Windows (using PowerShell):

$env:path += ";"+$pwd.Path

With the zrok executable in your path, you can then execute the zrok command from your shell:

$ ./zrok version
               _    
 _____ __ ___ | | __
|_  / '__/ _ \| |/ /
 / /| | | (_) |   < 
/___|_|  \___/|_|\_\

v0.4.0-rc6 [c889005]

Configure Your zrok Service Instance​

note

Most users can safely skip this section and proceed to "Generating an Invitation" below.

This section is relevant if you want to use the zrok CLI with an alternate service instance (in the case of self-hosting, etc.).

zrok is both an installable utility that you interact with from your local computer, and also a service that exists on the network. NetFoundry operates the public service instance that is available at api.zrok.io, but because zrok is open source and self-hostable, you're free to create your own zrok service instance.

The zrok executable defaults to using the zrok service instance at api.zrok.io. Should you need to change the endpoint to use a different service instance, you can do that with the following command:

$ zrok config set apiEndpoint https://zrok.mydomain.com
[WARNING]: unable to open zrokdir metadata; ignoring

zrok configuration updated
note

The WARNING about zrokdir metadata is ignorable. Running the zrok config set command writes a small piece of metadata into a .zrok folder inside your home directory. This allows zrok to identify the version of its settings, providing a mechanism to upgrade your installation as new versions are released. This WARNING is letting you know that your current environment has not been initialized by zrok.

You can use the zrok status command to inspect the state of your local environment. zrok refers to each shell where you install and enable a copy of zrok as as an environment.

$ zrok status

Config:

 CONFIG       VALUE                      SOURCE 
 apiEndpoint  https://zrok.mydomain.com  config 

[WARNING]: Unable to load your local environment!

To create a local environment use the zrok enable command.
note

The WARNING about being unable to load your local environment will go away once you've successfully enabled (zrok enable) for your shell (we'll get to that below). For now, this warning is ignorable.

The zrok status command shows the configured API service that your environment is using, as well as the SOURCE where the setting was retrieved. In this case, config means that the setting was set into the environment using the zrok config command.

Generating an Invitation​

In order to create an account with the zrok service instance, you will need to create an invitation.

note

Some environments take advantage of invitation tokens, which limit who is able to request an invitation on the service instance. If your service uses invitation tokens, the administrator of your instance will include details about how to use your token to generate your invitation.

We generate an invitation with the zrok invite command. A service instance that allows open registration will provide an input form like this:

$ zrok invite

enter and confirm your email address...

> user@domain.com
> user@domain.com

[ Submit ]

invitation sent to 'user@domain.com'!

A service instance that requires token-based invitation authentication will present a form that looks like this:

$ zrok invite

enter and confirm your email address...

If you don't already have one, request an invite token at: michael@quigley.com

> Email Address
> Confirm Email
> Token


[ Submit ]

The zrok invite command presents a small form that allows you to enter (and then confirm) your email address. Tabbing to the [ Submit ] button will send the request to your configured zrok service.

Next, check the email where you sent the invite. You should receive a message asking you to click a link to create your zrok account. When you click that link, you will be brought to a web page that will allow you to set a password for your new account:

Enter a Password

Enter a password and it's confirmation, and click the Register Account button. You'll see the following:

Successful Registration

For now, we'll ignore the "enable your shell for zrok" section. Just click the zrok web portal link:

Web Login

After clicking the Log In button, you'll be brought into the zrok web console:

Web Console; Empty

Congratulations! Your zrok account is ready to go!

Enabling Your zrok Environment​

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 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.

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:

Enable Modal Dialog

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.

Let's copy that command and paste it into your shell:

$ zrok enable klFEoIi0QAg7 
⣻  contacting the zrok service...

After a few seconds, the message will change and indicate that the enable operation suceeded:

$ zrok enable klFEoIi0QAg7 
⣻  the zrok environment was successfully enabled...

Now, if we run a zrok status command, you will see the details of your environment:

$ zrok status

Config:

 CONFIG       VALUE                        SOURCE
 apiEndpoint  https://api.staging.zrok.io  env

Environment:

 PROPERTY       VALUE
 Secret Token   <<SET>>
 Ziti Identity  <<SET>>

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:

New Environment in Web UI

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.

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.

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

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 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

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.

Your environment is fully ready to go. Now we can move on to the fun stuff...

Sharing​

zrok is designed to make sharing resources as effortless as possible, while providing a high degree of security and control.

Ephemeral by Default​

Shared resources are ephemeral by default; as soon as you terminate the zrok share command, the entire share is removed and is no longer available to any users. Identifiers for shared resources are randomly allocated when the share is created.

Public Shares and Frontends​

Resources that are shared publicly are exposed to any users on the internet who have access to the zrok service instance's "frontend".

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 service instance exposing the following URL to access my resources:

https://2ptgbr8tlfvk.share.zrok.io

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:

$ zrok share public
Error: accepts 1 arg(s), received 0
Usage:
  zrok share public <target> [flags]

Flags:
      --backend-mode string      The backend mode {proxy, web} (default "proxy")
      --basic-auth stringArray   Basic authentication users (<username:password>,...)
      --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 <target>

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)

<target> defines the path to the local resource that you intend to share. The form of <target> depends on the --backend-mode that you're using.

In the case of --backend-mode proxy, <target> should be a URL to an HTTP endpoint.

In the case of --backend-mode web, <target> is the path to a file on disk that serves as the "root" of the file tree to be shared.

If we return to the web console, we see our share in the explorer:

Web Console Share

If we click on our new share in the explorer, we can see the share details: Share Details

If we click on the frontend endpoint a new browser tab opens and we see the content of our share: Share Frontend

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:

Environment Spark Line

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

Private Shares​

zrok also provides a powerful private sharing model. If I execute the following command:

$ zrok share private http://localhost:8080

The zrok service will respond with the following:

access your share with: zrok access private wvszln4dyz9q

Rather than allowing access to your service through a public frontend, a private share is only exposed to the underlying OpenZiti network, and can only be accessed using the zrok access command.

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.

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.

For these services a proxy share will allow those endpoints to be reached, either publicly or privately through the zrok service.

Web Backend Mode​

The zrok share command accepts a --backend-mode option. Besides proxy, the current v0.3 release (as of this writing) also supports a web mode. The web mode allows you to specify a local folder on your filesystem, and instantly turns your zrok client into a web server, exposing your web content either publicly or privately without having to a configure a web server.

Reserved Shares​

zrok shares are ephemeral unless you specifically create a "reserved" share.

A reserved share can be re-used multiple times; it will survive termination of the zrok share command, allowing for longer-lasting semi-permanent access to shared resources.

The first step is to create the reserved share:

$ 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

I'm asking the zrok service to reserve a share with a web backend mode, pointing at my local docs folder.

You'll want to remember the share token (mltwsinym1s2 in this case), and the frontend endpoint URL. If this were a private reserved share, there would not be a frontend URL.

If we do nothing else, and then point a web browser at the frontend endpoint, we get:

Not Found

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:

$ zrok share reserved mltwsinym1s2

...results in a new share backend starting up and connecting to the existing reserved share:

zrok share reserved

And now if we refresh the frontend endpoint URL in the web browser, we'll see an index of the docs directory:

zrok docs share

With the reserved share, we're free to stop and restart the zrok share reserved command as many times as we want, without losing the token for our share.

When we're done with the reserved share, we can release it using this command:

$ zrok release mltwsinym1s2
[   0.230]    INFO main.(*releaseCommand).run: reserved share 'mltwsinym1s2' released

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).

Here's a quick review of the zrok mental model and the vocabulary.

Service Instance and Account​

You create an account with a zrok service instance. Your account is identified by a username and a password, which you use to log into the web console. Your account also has a secret token, which you will use to authenticate from the zrok command-line to interact with the service instance.

You create a new account with a zrok service instance through the zrok invite command.

Environment​

Using your secret token you use the zrok command-line interface to create an environment. An environment corresponds to a single command-line user on a specific host system.

You create a new environment by using the zrok enable command.

Shares​

Once you've enabled an environment, you then create one or more shares. Shares have either a public or private sharing mode. Shares share a specific type of resource using a backend mode. As of this writing zrok supports a proxy backend mode to share local HTTP resources as a reverse proxy. zrok also supports a web backend mode to share local file and HTML resources by enabling a basic HTTP server.

Every share is identified by a share token. Public shares can be accessed through either a frontend instance offered through the zrok service instance, or through the zrok access command. Private shares can only be accessed through the zrok access command.

You use the zrok share command to create and enable ephemeral shares.

Reserved Shares​

zrok supports creating shares that have a consistent share token that survives restarts of the zrok share command. These are considered non-ephemeral, and is callled a reserved share.

You use the zrok reserve command to create reserved shares. Reserved shares last until you use the zrok release command to delete them.

Self-Hosting a Service Instance​

Interested in self-hosting your own zrok service instance? See the self-hosting guide for details.

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/guides/docker-share/docker_private_share_guide/index.html b/docs/guides/docker-share/docker_private_share_guide/index.html index b09c5ebe..f5bd4bb4 100644 --- a/docs/guides/docker-share/docker_private_share_guide/index.html +++ b/docs/guides/docker-share/docker_private_share_guide/index.html @@ -4,13 +4,13 @@ Docker Private Share | Zrok - +

Docker Private Share

With zrok, you can privately share a server app that's running in Docker, or any server that's reachable by the zrok container. Then, a zrok private access running somewhere else can use the private share. In this guide we'll cover both sides: the private share and the private access.

Walkthrough Video​

Before You Begin​

To follow this guide you will need Docker and the Docker Compose plugin for running docker compose commands in your terminal.

If you have installed Docker Desktop on macOS or Windows then you are all set.

Private Share with Docker Compose​

First, let's create the private share.

  1. Make a folder on your computer to use as a Docker Compose project for your zrok private share.

  2. In your terminal, change directory to your newly-created project folder.

  3. Download the zrok-private-share Docker Compose project file into your new project folder and make sure it's named docker-compose.yml.

  4. Copy your zrok environment token from the zrok web console to your clipboard and paste it in a file named .env in the same folder like this:

    # file name ".env"
    ZROK_ENABLE_TOKEN="8UL9-48rN0ua"

  5. If you are self-hosting zrok then it's important to set your API endpoint URL too. If you're using the hosted zrok service then you can skip this step.

    # file name ".env"
    ZROK_API_ENDPOINT="https://zrok.example.com"

  6. Run your Compose project to start sharing the built-in demo web server:

    docker compose up

  7. Read the private share token from the output. One of the last lines is like this:

    zrok-private-share-1  | zrok access private wr3hpf2z5fiy

    Keep track of this token so you can use it in your zrok private access project.

Private Access with Docker Compose​

Now that we have a private share we can access it with zrok running in Docker. Next, let's access the demo web server in a web browser.

  1. Make a folder on your computer to use as a Docker Compose project for your zrok private access.

  2. In your terminal, change directory to your newly-created project folder.

  3. Download the zrok-private-access Docker Compose project file into your new project folder and make sure it's named docker-compose.yml.

  4. Copy your zrok environment token from the zrok web console to your clipboard and paste it in a file named .env in the same folder like this:

    # file name ".env"
    ZROK_ENABLE_TOKEN="8UL9-48rN0ua"

  5. Now copy the zrok private access token from the zrok private share project's output to your clipboard and paste it in the same file named .env here in your private share project folder like this:

    # file name ".env"
    ZROK_ENABLE_TOKEN="8UL9-48rN0ua"
    ZROK_ACCESS_TOKEN="wr3hpf2z5fiy"

  6. Run your Compose project to start accessing the private share:

    docker compose up zrok-private-access

  7. Now your zrok private access proxy is ready on http://127.0.0.1:9191. You can visit the demo web server in your browser.

Going Further with Private Access​

  1. Try changing the demo web server used in the private share project. One alternative demo server is provided: httpbin.

  2. Try accessing the private share from inside a container running in the private access project. One demo client is provided: demo-client. You can run it like this.

    docker compose up demo-client

  3. You'll see in the terminal output that the demo-client container is getting a response from the private share indicating the source IP of the request from the perspective of the demo server: httpbin that's running in the private share project.

Cleaning Up​

Run the "down" command in both Compose projects to destroy them when you're all done. This will stop the running containers and delete zrok environments' storage volumes. Then delete the selected zrok environment by clicking "Actions" in the web console.

docker compose down --remove-orphans --volumes
Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/guides/docker-share/docker_public_share_guide/index.html b/docs/guides/docker-share/docker_public_share_guide/index.html index 65a1bf5a..4b531231 100644 --- a/docs/guides/docker-share/docker_public_share_guide/index.html +++ b/docs/guides/docker-share/docker_public_share_guide/index.html @@ -4,13 +4,13 @@ Docker Public Share | Zrok - +

Docker Public Share

With zrok, you can publicly share a server app that's running in another Docker container, or any server that's reachable by the zrok container.

Walkthrough Video​

Before You Begin​

To follow this guide you will need Docker and the Docker Compose plugin for running docker compose commands in your terminal.

Public Share with Docker Compose​

  1. Make a folder on your computer to use as a Docker Compose project for your zrok public share.

  2. In your terminal, change directory to your newly-created project folder.

  3. Download the zrok-public-share Docker Compose project file into your new project folder.

  4. Copy your zrok environment token from the zrok web console to your clipboard and paste it in a file named .env in the same folder like this:

    # file name ".env"
    ZROK_ENABLE_TOKEN="8UL9-48rN0ua"

  5. If you are self-hosting zrok then it's important to set your API endpoint URL too. If you're using the hosted zrok service then you can skip this step.

    # file name ".env"
    ZROK_API_ENDPOINT="https://zrok.example.com"

  6. Run your Compose project to start sharing the built-in demo web server:

    docker compose up

  7. Read the public share URL from the output. One of the last lines is like this:

    zrok-public-share-1  |  https://w6r1vesearkj.in.zrok.io/

    You can swap in a different server app container instead of the demo server, or you could change the Docker network to "host" and share something running on the Docker host's localhost interface.

  8. Edit the file docker-compose.yml. Replace the following line:

    command: share public --headless http://zrok-test:9090

    Replace that line with this to start sharing the HTTPBin server app container instead of the zrok test endpoint.

    command: share public --headless http://httpbin-test:8080

  9. Re-run your project to load the new server configuration.

    docker-compose up --force-recreate

    Now you'll have a new public share URL for the httpbin API testing server.

  10. Run "down" to destroy the Compose project when you're done. Then delete the selected zrok environment by clicking "Actions" in the web console.

    docker compose down --remove-orphans --volumes
Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/guides/metrics-and-limits/configuring-limits/index.html b/docs/guides/metrics-and-limits/configuring-limits/index.html index 7e9d3e6e..b92b527e 100644 --- a/docs/guides/metrics-and-limits/configuring-limits/index.html +++ b/docs/guides/metrics-and-limits/configuring-limits/index.html @@ -4,13 +4,13 @@ Configuring Limits | Zrok - +

Configuring Limits

If you have not yet configured metrics, please visit the metrics guide first before working through the limits configuration.

The limits facility in zrok is responsible for controlling the number of resources in use (environments, shares) and also for ensuring that any single account, environment, or share is held below the configured thresholds.

Take this zrok controller configuration stanza as an example:

limits:
  enforcing:        true
  cycle:            1m
  environments:     -1
  shares:           -1
  bandwidth:
    per_account:
      period:       5m
      warning:
        rx:         -1
        tx:         -1
        total:      7242880
      limit:
        rx:         -1
        tx:         -1
        total:      10485760
    per_environment:
      period:       5m
      warning:
        rx:         -1
        tx:         -1
        total:      -1
      limit:
        rx:         -1
        tx:         -1
        total:      -1
    per_share:
      period:       5m
      warning:
        rx:         -1
        tx:         -1
        total:      -1
      limit:
        rx:         -1
        tx:         -1
        total:      -1

The Global Controls​

The enforcing boolean will globally enable or disable limits for the controller.

The cycle value controls how frequently the limits system will look for limited resources to re-enable.

Resource Limits​

The environments and shares values control the number of environments and shares that are allowed per-account. Any limit value can be set to -1, which means unlimited.

Bandwidth Limits​

The bandwidth section is designed to provide a configurable system for controlling the amount of data transfer that can be performed by users of the zrok service instance. The bandwidth limits are configurable for each share, environment, and account.

per_account, per_environment, and per_share are all configured the same way:

The period specifies the time window for the bandwidth limit. See the documentation for time.Duration.ParseDuration for details about the format used for these durations. If the period is set to 5 minutes, then the limits implementation will monitor the send and receive traffic for the resource (share, environment, or account) for the last 5 minutes, and if the amount of data is greater than either the warning or the limit threshold, action will be taken.

The rx value is the number of bytes received by the resource. The tx value is the number of bytes transmitted by the resource. And total is the combined rx+tx value.

If the traffic quantity is greater than the warning threshold, the user will receive an email notification letting them know that their data transfer size is rising and will eventually be limited (the email details the limit threshold).

If the traffic quantity is greater than the limit threshold, the resources will be limited until the traffic in the window (the last 5 minutes in our example) falls back below the limit threshold.

Limit Actions​

When a resource is limited, the actions taken differ depending on what kind of resource is being limited.

When a share is limited, the dial service policies for that share are removed. No other action is taken. This means that public frontends will simply return a 404 as if the share is no longer there. Private frontends will also return 404 errors. When the limit is relaxed, the dial policies are put back in place and the share will continue operating normally.

When an environment is limited, all of the shares in that environment become limited, and the user is not able to create new shares in that environment. When the limit is relaxed, all of the share limits are relaxed and the user is again able to add shares to the environment.

When an account is limited, all of the environments in that account become limited (limiting all of the shares), and the user is not able to create new environments or shares. When the limit is relaxed, all of the environments and shares will return to normal operation.

Unlimited Accounts​

The accounts table in the database includes a limitless column. When this column is set to true the account is not subject to any of the limits in the system.

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/guides/metrics-and-limits/configuring-metrics/index.html b/docs/guides/metrics-and-limits/configuring-metrics/index.html index a919badf..ffd740f8 100644 --- a/docs/guides/metrics-and-limits/configuring-metrics/index.html +++ b/docs/guides/metrics-and-limits/configuring-metrics/index.html @@ -4,13 +4,13 @@ Configuring Metrics | Zrok - +

Configuring Metrics

A fully configured, production-scale zrok service instance looks like this:

zrok Metrics Architecture

zrok metrics builds on top of the fabric.usage event type from OpenZiti. The OpenZiti controller has a number of way to emit events. The zrok controller has several ways to consume fabric.usage events. Smaller installations could be configured in these ways:

zrok simplified metrics architecture

Environments that horizontally scale the zrok control plane with multiple controllers should use an AMQP-based queue to "fan out" the metrics workload across the entire control plane. Simpler installations that use a single zrok controller can collect fabric.usage events from the OpenZiti controller by "tailing" the events log file, or collecting them from the OpenZiti controller's websocket implementation.

Configuring the OpenZiti Controller​

This requires a version of OpenZiti with a fabric dependency of v0.22.52 or newer, which is satisfed by the v0.27.6 release of OpenZiti Controller.

Emitting fabric.usage events to a file is currently the most reliable mechanism to capture usage events into zrok. We're going to configure the OpenZiti controller to append fabric.usage events to a file, by adding this stanza to the OpenZiti controller configuration:

events:
  jsonLogger:
    subscriptions:
      - type: fabric.usage
        version: 3
    handler:
      type: file
      format: json
      path: /tmp/fabric-usage.json

You'll want to adjust the events/jsonLogger/handler/path to wherever you would like to send these events for ingestion into zrok. There are additional OpenZiti options that control file rotation. Be sure to consult the OpenZiti docs to tune these settings to be appropriate for your environment.

By default, the OpenZiti events infrastructure reports and batches events in 1 minute buckets. 1 minute is too large of an interval to provide a snappy zrok metrics experience. So, let's increase the frequency to every 5 seconds. Add this to the network stanza of your OpenZiti controller's configuration:

network:
  intervalAgeThreshold: 5s 
  metricsReportInterval: 5s

And you'll want to add this stanza to the tail-end of the router configuration for every router on your OpenZiti network:

metrics:
  reportInterval: 5s
  intervalAgeThreshold: 5s

Be sure to restart all of the components of your OpenZiti network after making these configuration changes.

Configuring the zrok Metrics Bridge​

zrok currently uses a "metrics bridge" component (running as a separate process) to consume the fabric.usage events from the OpenZiti controller, and publish them onto an AMQP queue. Add a stanza like the following to your zrok controller configuration:

bridge:
  source:
    type:           fileSource
    path:           /tmp/fabric-usage.json
  sink:
    type:           amqpSink
    url:            amqp://guest:guest@localhost:5672
    queue_name:     events

This configuration consumes the fabric.usage events from the file we previously specified in our OpenZiti controller configuration, and publishes them onto an AMQP queue.

RabbitMQ​

For this example, we're going to use RabbitMQ as our AMQP implementation. The stock, default RabbitMQ configuration, launched as a docker container will work just fine:

$ docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3.11-management

Once RabbitMQ is running, you can start the zrok metrics bridge by pointing it at your zrok controller configuration, like this:

$ zrok ctrl metrics bridge <path/to/zrok-controller.yaml>

Configuring zrok Metrics​

Configure the metrics section of your zrok controller. Here is an example:

metrics:
  agent:
    source:
      type:         amqpSource
      url:          amqp://guest:guest@localhost:5672
      queue_name:   events
  influx:
    url:            "http://127.0.0.1:8086"
    bucket:         zrok  # the bucket and org must be
    org:            zrok  # created in advance in InfluxDB
    token:          "<secret token>"

This configures the zrok controller to consume usage events from the AMQP queue, and configures the InfluxDB metrics store. The InfluxDB organization and bucket must be created in advance. The zrok controller will not create these for you.

Testing Metrics​

With all of the components configured and running, either use zrok test loop or manually create share(s) to generate traffic on the zrok instance. If everything is working correctly, you should see log messages from the controller like the following, which indicate that that the controller is processing OpenZiti usage events, and generating zrok metrics:

[5339.658]    INFO zrok/controller/metrics.(*influxWriter).Handle: share: 736z80mr4syu, circuit: Ad1V-6y48 backend {rx: 4.5 kB, tx: 4.6 kB} frontend {rx: 4.6 kB, tx: 4.5 kB}
[5349.652]    INFO zrok/controller/metrics.(*influxWriter).Handle: share: 736z80mr4syu, circuit: Ad1V-6y48 backend {rx: 2.5 kB, tx: 2.6 kB} frontend {rx: 2.6 kB, tx: 2.5 kB}
[5354.657]    INFO zrok/controller/metrics.(*influxWriter).Handle: share: 5a4u7lqxb7pa, circuit: iG1--6H4S backend {rx: 13.2 kB, tx: 13.3 kB} frontend {rx: 13.3 kB, tx: 13.2 kB}

The zrok web console should also be showing activity for your share(s) like the following:

zrok web console activity

With metrics configured, you might be interested in configuring limits.

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/guides/self-hosting/nginx_tls_guide/index.html b/docs/guides/self-hosting/nginx_tls_guide/index.html index 2347c47e..88491875 100644 --- a/docs/guides/self-hosting/nginx_tls_guide/index.html +++ b/docs/guides/self-hosting/nginx_tls_guide/index.html @@ -4,13 +4,13 @@ Nginx Reverse Proxy for zrok | Zrok - +

Nginx Reverse Proxy for zrok

Walkthrough Video​

Before You Begin​

I'll assume you have a running zrok controller and public frontend and wish to front both with Nginx providing server TLS. Go back to Self-Hosting Guide if you still need to spin those up.

Choose a Reverse Proxy Address​

I'll use https://api.zrok.quigley.com:443 in this example, and assume you already set up wildcard DNS like *.zrok.quigley.com. This lets us elect api.zrok.quigley.com as the controller DNS name, and forward any other incoming requests to the zrok public frontend.

Obtain a Wildcard Server Certificate​

You must complete a DNS challenge to obtain a wildcard certificate from Let's Encrypt. I'll assume you know how to create the necessary TXT record in the DNS zone you're using with zrok.

  1. Install certbot: https://eff-certbot.readthedocs.io/en/stable/install.html

  2. Run certbot with the manual plugin: https://certbot.eff.org/docs/using.html#manual

    # install cert for *.zrok.quigley.com in /etc/letsencrypt
    sudo certbot certonly --manual

Install Nginx​

Configure Nginx​

server {
    listen              443 ssl;
    server_name         api.zrok.quigley.com;
    ssl_certificate     /etc/letsencrypt/live/zrok.quigley.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/zrok.quigley.com/privkey.pem;
    ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    location / {
      proxy_pass      http://127.0.0.1:18080;
      error_log       /var/log/nginx/zrok-controller.log;
    }

}

server {
    listen              443 ssl;
    server_name         *.zrok.quigley.com;
    ssl_certificate     /etc/letsencrypt/live/zrok.quigley.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/zrok.quigley.com/privkey.pem;
    ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    location / {
      proxy_pass       http://127.0.0.1:8080;
      proxy_set_header Host $host;
      error_log        /var/log/nginx/zrok-frontend.log;
      proxy_busy_buffers_size   512k;
      proxy_buffers    4 512k;
      proxy_buffer_size   256k;

    }

}

Restart Nginx​

Load the new configuration by restarting Nginx. Check the logs to make sure it's happy.

Started A high performance web server and a reverse proxy server.

Check the Firewall​

If you followed the non-TLS quickstart then you may have opened 8080,108080/tcp in your firewall. You can go ahead and replace those exceptions with 443/tcp because only Nginx needs to be reachable for zrok to function.

Update the zrok Frontend​

List available frontends to obtain the token identifier of the frontend named "public". You may need to set ZROK_ADMIN_TOKEN or ZROK_API_ENDPOINT before running zrok admin.

$ zrok admin list frontends

 TOKEN         ZID        PUBLIC NAME  URL TEMPLATE                              CREATED AT                         UPDATED AT                    
 2NiDTRYUww18  7DsLh9DXG  public       http://{token}.zrok.quigley.com:8080  2023-01-19 05:29:20.793 +0000 UTC  2023-01-19 06:17:25 +0000 UTC

Update the URL template to use Nginx.

$ zrok admin update frontend 2NiDTRYUww18 --url-template https://{token}.zrok.quigley.com:443
[   0.028]    INFO main.(*adminUpdateFrontendCommand).run: updated global frontend '2NiDTRYUww18'
Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/docs/guides/self-hosting/self_hosting_guide/index.html b/docs/guides/self-hosting/self_hosting_guide/index.html index 59f8755b..bb1f558e 100644 --- a/docs/guides/self-hosting/self_hosting_guide/index.html +++ b/docs/guides/self-hosting/self_hosting_guide/index.html @@ -4,13 +4,13 @@ Self-Hosting Guide for Linux | Zrok - +

Self-Hosting Guide for Linux

Walkthrough Video​

Before you Begin​

This will get you up and running with a self-hosted instance of zrok. I'll assume you have the following:

  • a Linux server with a public IP
  • a wildcard DNS record like *.zrok.quigley.com that resolves to the server IP

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:

Do you want to keep the generated admin password 'XO0xHp75uuyeireO2xmmVlK91T7B9fpD'? (Y/n)

You'll need that generated password (XO0xHp75uuyeireO2xmmVlK91T7B9fpD) when building your zrok controller configuration.

BEGIN: Run the OpenZiti Quickstart

Install zrok​

Download the latest release 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.

#    _____ __ ___ | | __
#   |_  / '__/ _ \| |/ /
#    / /| | | (_) |   <
#   /___|_|  \___/|_|\_\
# controller configuration

v:                  3

admin:
  # generate these admin tokens from a source of randomness, e.g. 
  #  LC_ALL=C tr -dc _A-Z-a-z-0-9 < /dev/urandom | head -c32
  secrets:
    -               Q8V0LqnNb5wNX9kE1fgQ0H6VlcvJybB1  # be sure to change this!

endpoint:
  host:             0.0.0.0
  port:             18080

invites:
  invites_open:    true

store:
  path:             zrok.db
  type:             sqlite3

ziti:
  api_endpoint:     "https://127.0.0.1:8441"
  username:         admin
  password:         "XO0xHp75uuyeireO2xmmVlK91T7B9fpD"

The admin section defines privileged administrative credentials and must be set in the ZROK_ADMIN_TOKEN environment variable in shells where you want to run zrok admin.

The endpoint section defines where your zrok controller will listen.

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 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 and configuring limits 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.

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:

export ZROK_API_ENDPOINT=http://127.0.0.1:18080

Bootstrap OpenZiti for zrok​

With your OpenZiti network running and your configuration saved to a local file (I refer to mine as etc/ctrl.yml in these examples), you're ready to bootstrap the Ziti network.

Use the zrok admin bootstrap command to bootstrap like this:

$ zrok admin bootstrap etc/ctrl.yml 
[   0.002]    INFO main.(*adminBootstrap).run: {
    ...
}
[   0.002]    INFO zrok/controller/store.Open: database connected
[   0.006]    INFO zrok/controller/store.(*Store).migrate: applied 0 migrations
[   0.006]    INFO zrok/controller.Bootstrap: connecting to the ziti edge management api
[   0.039]    INFO zrok/controller.Bootstrap: creating identity for controller ziti access
[   0.071]    INFO zrok/controller.Bootstrap: controller identity: jKd8AINSz
[   0.082]    INFO zrok/controller.assertIdentity: asserted identity 'jKd8AINSz'
[   0.085]    INFO zrok/controller.assertErpForIdentity: asserted erps for 'ctrl' (jKd8AINSz)
[   0.085]    INFO zrok/controller.Bootstrap: creating identity for frontend ziti access
[   0.118]    INFO zrok/controller.Bootstrap: frontend identity: sqJRAINSiB
[   0.119]    INFO zrok/controller.assertIdentity: asserted identity 'sqJRAINSiB'
[   0.120]    INFO zrok/controller.assertErpForIdentity: asserted erps for 'frontend' (sqJRAINSiB)
[   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
[   0.123]    INFO zrok/controller.assertZrokProxyConfigType: found 'zrok.proxy.v1' config type with id '33CyjNbIepkXHN5VzGDA8L'
[   0.124]    INFO zrok/controller.assertMetricsService: creating 'metrics' service
[   0.126]    INFO zrok/controller.assertMetricsService: asserted 'metrics' service (5RpPZZ7T8bZf1ENjwGiPc3)
[   0.128]    INFO zrok/controller.assertMetricsSerp: creating 'metrics' serp
[   0.130]    INFO zrok/controller.assertMetricsSerp: asserted 'metrics' serp
[   0.134]    INFO zrok/controller.assertCtrlMetricsBind: creating 'ctrl-metrics-bind' service policy
[   0.135]    INFO zrok/controller.assertCtrlMetricsBind: asserted 'ctrl-metrics-bind' service policy
[   0.138]    INFO zrok/controller.assertFrontendMetricsDial: creating 'frontend-metrics-dial' service policy
[   0.140]    INFO zrok/controller.assertFrontendMetricsDial: asserted 'frontend-metrics-dial' service policy
[   0.140]    INFO main.(*adminBootstrap).run: bootstrap complete!

The zrok admin bootstrap command configures the zrok database, the necessary OpenZiti identities, and all of the OpenZiti policies required to run a zrok service.

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:

$ zrok controller etc/ctrl.yml 
[   0.003]    INFO main.(*controllerCommand).run: {
    ...
}
[   0.016]    INFO zrok/controller.inspectZiti: inspecting ziti controller configuration
[   0.048]    INFO zrok/controller.findZrokProxyConfigType: found 'zrok.proxy.v1' config type with id '33CyjNbIepkXHN5VzGDA8L'
[   0.048]    INFO zrok/controller/store.Open: database connected
[   0.048]    INFO zrok/controller/store.(*Store).migrate: applied 0 migrations
[   0.049]    INFO zrok/controller.(*metricsAgent).run: starting
[   0.064]    INFO zrok/rest_server_zrok.setupGlobalMiddleware: configuring
[   0.064]    INFO zrok/ui.StaticBuilder: building
[   0.065]    INFO zrok/rest_server_zrok.(*Server).Logf: Serving zrok at http://[::]:18080
[   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:

$ zrok admin create frontend sqJRAINSiB public http://{token}.zrok.quigley.com:8080
[   0.037]    INFO main.(*adminCreateFrontendCommand).run: created global public frontend 'WEirJNHVlcW9'

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:

# 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​

Create etc/http-frontend.yml. This frontend config file has a host_match pattern that represents the DNS zone you're using with this instance of zrok. Incoming HTTP requests with a matching Host header will be handled by this frontend. You may also specify the interface address where the frontend will listen for public access requests.

The frontend does not provide server TLS, but you may front the server with a reverse proxy. It is essential the reverse proxy forwards the Host header supplied by the viewer. This example will expose the non-TLS listener for the frontend.

host_match: zrok.quigley.com
address: 0.0.0.0:8080

Start Public Frontend​

In another terminal window, run:

$ zrok access public etc/http-frontend.yml
[   0.002]    INFO main.(*accessPublicCommand).run: {
    ...
}
[   0.002]    INFO zrok/endpoints/public_frontend.newMetricsAgent: loaded 'frontend' identity

This process uses the frontend identity created during the bootstrap process to provide public access for the zrok deployment. It is expected that the configured listener for this frontend corresponds to the DNS template specified when creating the public frontend record above.

Invite Yourself​

$ zrok invite
New Email: user@domain.com
Confirm Email: user@domain.com
invitation sent to 'user@domain.com'!

If you look at the console output from your zrok controller, you'll see a message like this:

[ 238.168]    INFO zrok/controller.(*inviteHandler).Handle: account request for 'user@domain.com' has registration token 'U2Ewt1UCn3ql'

You can access your zrok controller's registration UI by pointing a web browser at:

http://localhost:18080/register/U2Ewt1UCn3ql

The UI will ask you to set a password for your new account. Go ahead and do that.

After doing that, I see the following output in my controller console:

[ 516.778]    INFO zrok/controller.(*registerHandler).Handle: created account 'user@domain.com' with token 'SuGzRPjVDIcF'

Keep track of the token listed above (SuGzRPjVDIcF). We'll use this to enable our shell for this zrok deployment.

Enable Your Shell​

$ zrok enable SuGzRPjVDIcF
zrok environment '2AS1WZ3Sz' enabled for 'SuGzRPjVDIcF'

Congratulations. You have a working zrok environment!

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file diff --git a/index.html b/index.html index 5508d964..75a191cb 100644 --- a/index.html +++ b/index.html @@ -4,13 +4,13 @@ Zrok - +
- + \ No newline at end of file diff --git a/search/index.html b/search/index.html index b9889c79..4ef6cd16 100644 --- a/search/index.html +++ b/search/index.html @@ -4,13 +4,13 @@ Search the documentation | Zrok - +

Search the documentation

Copyright © 2023 NetFoundry Inc. Built with Docusaurus.
- + \ No newline at end of file