zrok/docs/getting-started/index.html

<!doctype html>
<html lang="en" dir="ltr" class="docs-wrapper docs-doc-page docs-version-current plugin-docs plugin-id-default docs-doc-id-getting-started">
<head>
<meta charset="UTF-8">
<meta name="generator" content="Docusaurus v2.2.0">
<title data-rh="true">Getting Started with zrok | Zrok</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://zrok.io/docs/getting-started"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="Getting Started with zrok | Zrok"><meta data-rh="true" name="description" content="zrok is an open source, Apache v2 licensed sharing platform, built on top of OpenZiti,"><meta data-rh="true" property="og:description" content="zrok is an open source, Apache v2 licensed sharing platform, built on top of OpenZiti,"><link data-rh="true" rel="icon" href="/img/space-ziggy.png"><link data-rh="true" rel="canonical" href="https://zrok.io/docs/getting-started"><link data-rh="true" rel="alternate" href="https://zrok.io/docs/getting-started" hreflang="en"><link data-rh="true" rel="alternate" href="https://zrok.io/docs/getting-started" hreflang="x-default"><link rel="alternate" type="application/rss+xml" href="/blog/rss.xml" title="Zrok RSS Feed">
<link rel="alternate" type="application/atom+xml" href="/blog/atom.xml" title="Zrok Atom Feed"><link rel="stylesheet" href="/assets/css/styles.7d4a02e4.css">
<link rel="preload" href="/assets/js/runtime~main.111dd388.js" as="script">
<link rel="preload" href="/assets/js/main.26b076b4.js" as="script">
</head>
<body class="navigation-with-keyboard">
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"dark")}()</script><div id="__docusaurus">
<div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#docusaurus_skipToContent_fallback">Skip to main content</a></div><nav class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a href="https://zrok.io" target="_self" rel="noopener noreferrer" class="navbar__brand"><div class="navbar__logo"><img src="/img/space-ziggy.png" alt="Ziggy Goes to Space" class="themedImage_ToTc themedImage--light_HNdA"><img src="/img/space-ziggy.png" alt="Ziggy Goes to Space" class="themedImage_ToTc themedImage--dark_i4oU"></div><b class="navbar__title text--truncate">zrok</b></a></div><div class="navbar__items navbar__items--right"><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs/getting-started">What is zrok?</a><a href="https://github.com/orgs/openziti/projects/16" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Roadmap<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs/getting-started">Docs</a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs/downloads">Downloads</a><a href="https://github.com/openziti/zrok" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="Switch between dark and light mode (currently dark mode)" aria-label="Switch between dark and light mode (currently dark mode)" aria-live="polite"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" class="darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg></button></div><div class="searchBox_ZlJk"></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_z2l0 docsWrapper_BCFX"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docPage__5DB"><aside class="theme-doc-sidebar-container docSidebarContainer_b6E3"><div class="sidebar_njMd"><nav class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" href="/docs/getting-started">Getting Started with zrok</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/docs/core-features/">Core Features</a><button aria-label="Toggle the collapsible sidebar category &#x27;Core Features&#x27;" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/docs/category/guides">Guides</a><button aria-label="Toggle the collapsible sidebar category &#x27;Guides&#x27;" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/downloads">Downloads</a></li></ul></nav></div></aside><main class="docMainContainer_gTbr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_OVgt"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">Getting Started with zrok</span><meta itemprop="position" content="1"></li></ul></nav><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><h1>Getting Started with zrok</h1><p><code>zrok</code> is an open source, Apache v2 licensed sharing platform, built on top of <a href="https://docs.openziti.io/docs/learn/introduction/" target="_blank" rel="noopener noreferrer">OpenZiti</a>,
a programmable zero trust network overlay. <code>zrok</code> is an <em>OpenZiti Native Application</em>. You can choose to self-host <code>zrok</code>
or leverage the free, managed offering provided by NetFoundry: <a href="https://zrok.io" target="_blank" rel="noopener noreferrer">https://zrok.io</a></p><p>As of version <code>v0.3.0</code>, <code>zrok</code> provides the ability to:</p><ul><li>share resources <a href="/docs/core-features/sharing-public">publicly</a>, similar to other distributed reverse proxies.</li><li>share <a href="/docs/core-features/sharing-private">privately</a>. It does this by leveraging
<a href="https://docs.openziti.io/docs/learn/introduction/" target="_blank" rel="noopener noreferrer">OpenZiti</a> to support zero trust, peer to peer connections without
the need for any open ports on the internet.</li><li>use <code>web</code> sharing; easily share files with others using a single <code>zrok</code> command</li></ul><p>Let&#x27;s take a look at how to get started with <code>zrok</code>.</p><div class="theme-admonition theme-admonition-note alert alert--secondary admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span><mdxadmonitiontitle><code>zrok</code> moves fast!</mdxadmonitiontitle></div><div class="admonitionContent_S0QG"><p><code>zrok</code> is currently in a closed-beta phase and requires an invitation token. If you would like to try <code>zrok</code> and provide
feedback, please send an email to <a href="mailto:invite@zrok.io." target="_blank" rel="noopener noreferrer">invite@zrok.io.</a> <code>zrok</code> is an open source project and is in its early development
phases. We&#x27;re doing our development publicly. See the <a href="https://github.com/orgs/openziti/projects/16" target="_blank" rel="noopener noreferrer">roadmap</a> for details
about the project. We are highly interested in feedback as we continue to iterate quickly. Please provide feedback in
<a href="https://openziti.discourse.group/" target="_blank" rel="noopener noreferrer">Discourse</a>, raise <a href="https://github.com/openziti/zrok/issues" target="_blank" rel="noopener noreferrer">GitHub Issues</a>, or reach
out directly.</p></div></div><h2 class="anchor anchorWithStickyNavbar_LWe7" id="downloading-zrok">Downloading zrok<a class="hash-link" href="#downloading-zrok" title="Direct link to heading"></a></h2><p>Releases are also available from the <code>zrok</code> project repository on GitHub at <a href="https://github.com/openziti/zrok/releases/latest" target="_blank" rel="noopener noreferrer">https://github.com/openziti/zrok/releases/latest</a></p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="extract-zrok-distribution">Extract zrok Distribution<a class="hash-link" href="#extract-zrok-distribution" title="Direct link to heading"></a></h3><p>Move the downloaded <code>zrok</code> distribution into a directory on your system. In my case, I&#x27;ve placed it in my home directory:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ ls -lF zrok*</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">-rwxr-xr-x 1 michael michael 12724747 Jan 17 12:57 zrok_0.3.0-rc1_linux_amd64.tar.gz*</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Create a directory where the extracted distribution will sit:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ mkdir zrok</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ cd zrok/</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Extract the <code>zrok</code> distribution:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ tar zxvf ../zrok_0.3.0-rc1_linux_amd64.tar.gz</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">CHANGELOG.md</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">README.md</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">zrok</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><blockquote><p>NOTE: On Windows platforms the distribution is shipped as a <code>zip</code> archive. Windows Explorer includes support for extracting <code>zip</code> archives natively.</p></blockquote><p>Add <code>zrok</code> to your shell&#x27;s environment.</p><p>For Linux or macos:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ export PATH=`pwd`:$PATH</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>For Windows (using Command Prompt):</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">&gt; set PATH=%CD%;%PATH%</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>For Windows (using PowerShell):</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$env:path += &quot;;&quot;+$pwd.Path</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>With the <code>zrok</code> executable in your path, you can then execute the <code>zrok</code> command from your shell:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok version</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">               _    </span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> _____ __ ___ | | __</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">|_  / &#x27;__/ _ \| |/ /</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> / /| | | (_) |   &lt; </span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">/___|_|  \___/|_|\_\</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">v0.3.0-rc1 [0d43b55]</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h2 class="anchor anchorWithStickyNavbar_LWe7" id="configure-your-zrok-service-instance">Configure Your zrok Service Instance<a class="hash-link" href="#configure-your-zrok-service-instance" title="Direct link to heading"></a></h2><div class="theme-admonition theme-admonition-note alert alert--secondary admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_S0QG"><p>Most users can safely skip this section and proceed to &quot;Generating an Invitation&quot; below.</p><p>This section is relevant if you want to use the <code>zrok</code> CLI with an alternate service instance (in the case of self-hosting, etc.).</p></div></div><p><code>zrok</code> is both an installable utility that you interact with from your local computer, and also a <em>service</em> that exists on the network. NetFoundry operates the public <em>service instance</em> that is available at <code>api.zrok.io</code>, but because <code>zrok</code> is open source and self-hostable, you&#x27;re free to create your own <code>zrok</code> service instance.</p><p>The <code>zrok</code> executable defaults to using the <code>zrok</code> service instance at <code>api.zrok.io</code>. Should you need to change the endpoint to use a different service instance, you can do that with the following command:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok config set apiEndpoint https://zrok.mydomain.com</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[WARNING]: unable to open zrokdir metadata; ignoring</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">zrok configuration updated</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><div class="theme-admonition theme-admonition-note alert alert--secondary admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_S0QG"><p>The <code>WARNING</code> about <code>zrokdir metadata</code> is ignorable. Running the <code>zrok config set</code> command writes a small piece of metadata into a <code>.zrok</code> folder inside your home directory. This allows <code>zrok</code> to identify the version of its settings, providing a mechanism to upgrade your installation as new versions are released. This <code>WARNING</code> is letting you know that your current environment has not been initialized by <code>zrok</code>.</p></div></div><p>You can use the <code>zrok status</code> command to inspect the state of your local <em>environment</em>. <code>zrok</code> refers to each shell where you install and <code>enable</code> a copy of <code>zrok</code> as as an <em>environment</em>.</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok status</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Config:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> CONFIG       VALUE                      SOURCE </span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> apiEndpoint  https://zrok.mydomain.com  config </span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[WARNING]: Unable to load your local environment!</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">To create a local environment use the zrok enable command.</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><div class="theme-admonition theme-admonition-note alert alert--secondary admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_S0QG"><p>The <code>WARNING</code> about being <code>unable to load your local environment</code> will go away once you&#x27;ve successfully enabled (<code>zrok enable</code>) for your shell (we&#x27;ll get to that below). For now, this warning is ignorable.</p></div></div><p>The <code>zrok status</code> command shows the configured API service that your environment is using, as well as the <code>SOURCE</code> where the setting was retrieved. In this case, <code>config</code> means that the setting was set into the environment using the <code>zrok config</code> command.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="generating-an-invitation">Generating an Invitation<a class="hash-link" href="#generating-an-invitation" title="Direct link to heading"></a></h2><p>In order to create an account with the <code>zrok</code> service instance, you will need to create an invitation. </p><div class="theme-admonition theme-admonition-note alert alert--secondary admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_S0QG"><p>Some environments take advantage of <em>invitation tokens</em>, 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.</p></div></div><p>We generate an invitation with the <code>zrok invite</code> command:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok invite</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">enter and confirm your email address...</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">&gt; user@domain.com</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">&gt; user@domain.com</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ Submit ]</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">invitation sent to &#x27;user@domain.com&#x27;!</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>The <code>zrok invite</code> command presents a small form that allows you to enter (and then confirm) your email address. Tabbing to the <code>[ Submit ]</code> button will send the request to your configured <code>zrok</code> service.</p><p>Next, check the email where you sent the invite. You should receive a message asking you to click a link to create your <code>zrok</code> 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:</p><p><img loading="lazy" alt="Enter a Password" src="/assets/images/zrok_verify-9c83189dde04c6fbab19b62ace653319.png" width="1556" height="1229" class="img_ev3q"></p><p>Enter a password and it&#x27;s confirmation, and click the <code>Register Account</code> button. You&#x27;ll see the following:</p><p><img loading="lazy" alt="Successful Registration" src="/assets/images/zrok_registration_success-3f3689bf6d7e28d4f4ec8081e94cd835.png" width="1556" height="1229" class="img_ev3q"></p><p>For now, we&#x27;ll ignore the &quot;enable your shell for zrok&quot; section. Just click the <code>zrok web portal</code> link:</p><p><img loading="lazy" alt="Web Login" src="/assets/images/zrok_web_login-2d339ab0b7c1e0aad4710d928b511cb0.png" width="1556" height="1229" class="img_ev3q"></p><p>After clicking the <code>Log In</code> button, you&#x27;ll be brought into the <code>zrok</code> <em>web console</em>:</p><p><img loading="lazy" alt="Web Console; Empty" src="/assets/images/zrok_web_console_empty-863f7acf00cc43148999a937deb19830.png" width="1556" height="1229" class="img_ev3q"></p><p>Congratulations! Your <code>zrok</code> account is ready to go!</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="enabling-your-zrok-environment">Enabling Your zrok Environment<a class="hash-link" href="#enabling-your-zrok-environment" title="Direct link to heading"></a></h2><p>When your <code>zrok</code> account was created, the service generated a <em>secret token</em> that identifies and authenticates in a single step. Protect your secret token as if it were a password, or an important account number; it&#x27;s a <em>secret</em>, protect it.</p><p>When we left off you had downloaded, extracted, and configured your <code>zrok</code> environment. In order to use that environment with your account, you&#x27;ll need to <code>enable</code> it. Enabling an environment generates a secure identity and the necessary underlying security policies with the OpenZiti network hosting the <code>zrok</code> service.</p><p>From the web console, click on your email address in the upper right corner of the header. That drop down menu contains an <code>Enable Your Environment</code> link. Click that link and a modal dialog will be shown like this:</p><p><img loading="lazy" alt="Enable Modal Dialog" src="/assets/images/zrok_enable_modal-c62345bd12e17ec9dac2df2f46fc05e8.png" width="1556" height="1229" class="img_ev3q"></p><p>This dialog box shows you the <code>zrok enable</code> command that you can use to enable any shell to work with your <code>zrok</code> account with a single command.</p><p>Let&#x27;s copy that command and paste it into your shell:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok enable klFEoIi0QAg7 </span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">⣻  contacting the zrok service...</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>After a few seconds, the message will change and indicate that the enable operation suceeded:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok enable klFEoIi0QAg7 </span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">⣻  the zrok environment was successfully enabled...</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Now, if we run a <code>zrok status</code> command, you will see the details of your environment:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok status</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Config:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> CONFIG       VALUE                SOURCE </span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> apiEndpoint  https://api.zrok.io  env    </span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Environment:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> PROPERTY       VALUE        </span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> Secret Token   klFEoIi0QAg7 </span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> Ziti Identity  FTpvelYD6h   </span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Excellent... our environment is now fully enabled.</p><p>If we return to the <em>web console</em>, we&#x27;ll now see the new environment reflected in the explorer view:</p><p><img loading="lazy" alt="New Environment in Web UI" src="/assets/images/zrok_web_ui_new_environment-a2745e4475025446ae38e5bd7708a9bf.png" width="1556" height="1229" class="img_ev3q"></p><p>In my case, the environment is named <code>michael@ziti-lx</code>, which is the username of my shell and the hostname of the system the shell is running on.</p><div class="theme-admonition theme-admonition-note alert alert--secondary admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_S0QG"><p>Should you want to use a non-default name for your environment, you can pass the <code>-d</code> option to the <code>zrok enable</code> command. See <code>zrok enable --help</code> for details.</p></div></div><p>If you click on the environment node in the explorer in the <em>web console</em>, the details panel shown at the bottom of the page will change:</p><p><img loading="lazy" alt="Empty Environment" src="/assets/images/zrok_web_ui_empty_shares-a2ecccae2bbb1c006ea2a0ba1e85e335.png" width="1556" height="1229" class="img_ev3q"></p><p>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 <img loading="lazy" alt="Zoom to Fit" src="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==" width="30" height="25" class="img_ev3q"> <em>zoom to fit</em> icon in the lower right corner of the explorer.</p><p>If we click on the <code>Detail</code> tab for our environment, we&#x27;ll see something like:</p><p><img loading="lazy" alt="Environment Detail" src="/assets/images/zrok_web_ui_empty_environment_detail-1a3a35ddab829e3a9b951ef57cecde45.png" width="1556" height="1229" class="img_ev3q"></p><div class="theme-admonition theme-admonition-note alert alert--secondary admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_S0QG"><p>With your <code>zrok</code> account you can <code>zrok enable</code> multiple environments. This will allow you to run <code>zrok share</code> in one environment, and <code>zrok access</code> in other environments.</p></div></div><p>Your environment is fully ready to go. Now we can move on to the fun stuff...</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="sharing">Sharing<a class="hash-link" href="#sharing" title="Direct link to heading"></a></h2><p><code>zrok</code> is designed to make sharing resources as effortless as possible, while providing a high degree of security and control.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="ephemeral-by-default">Ephemeral by Default<a class="hash-link" href="#ephemeral-by-default" title="Direct link to heading"></a></h3><p>Shared resources are <em>ephemeral</em> by default; as soon as you terminate the <code>zrok share</code> 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.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="public-shares-and-frontends">Public Shares and Frontends<a class="hash-link" href="#public-shares-and-frontends" title="Direct link to heading"></a></h3><p>Resources that are shared <em>publicly</em> are exposed to any users on the internet who have access to the <code>zrok</code> service instance&#x27;s &quot;frontend&quot;.</p><p>A frontend is an HTTPS listener exposed to the internet, that lets any user with your ephemeral share token access your publicly shared resources.</p><p>For example, I might create a public share using the <code>zrok share public</code> command, which results in my <code>zrok</code> service instance exposing the following URL to access my resources:</p><p><a href="https://h0fz2ts9c84t.share.zrok.io" target="_blank" rel="noopener noreferrer">https://h0fz2ts9c84t.share.zrok.io</a></p><p>In this case my share was given the &quot;share token&quot; of <code>h0fz2ts9c84t</code>. 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.</p><div class="theme-admonition theme-admonition-note alert alert--secondary admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_S0QG"><p>Here is the <code>--help</code> output from <code>zrok share public</code>:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok share public</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Error: accepts 1 arg(s), received 0</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Usage:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  zrok share public &lt;target&gt; [flags]</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Flags:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      --backend-mode string      The backend mode {proxy, web} (default &quot;proxy&quot;)</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      --basic-auth stringArray   Basic authentication users (&lt;username:password&gt;,...)</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      --frontends stringArray    Selected frontends to use for the share (default [public])</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      --headless                 Disable TUI and run headless</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -h, --help                     help for public</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">      --insecure                 Enable insecure TLS certificate validation for &lt;target&gt;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Global Flags:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -p, --panic     Panic instead of showing pretty errors</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">  -v, --verbose   Enable verbose logging</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ERROR]: an error occurred (accepts 1 arg(s), received 0)</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p><code>&lt;target&gt;</code> defines the path to the local resource that you intend to share. The form of <code>&lt;target&gt;</code> depends on the <code>--backend-mode</code> that you&#x27;re using. </p><p>In the case of <code>--backend-mode proxy</code>, <code>&lt;target&gt;</code> should be a URL to an HTTP endpoint.</p><p>In the case of <code>--backend-mode web</code>, <code>&lt;target&gt;</code> is the path to a file on disk that serves as the &quot;root&quot; of the file tree to be shared.</p></div></div><p>If we return to the web console, we see our share in the explorer:</p><p><img loading="lazy" alt="Web Console Share" src="/assets/images/zrok_web_console_explorer_share-7e6430b99ed60358da14491a97f153ae.png" width="1556" height="1229" class="img_ev3q"></p><p>If we click on our new share in the explorer, we can see the share details:
<img loading="lazy" alt="Share Details" src="/assets/images/zrok_web_console_share_detail-9c3f99ededaba7d1225cacd5ec81a06d.png" width="1556" height="1229" class="img_ev3q"></p><p>If we click on the <em>frontend endpoint</em> a new browser tab opens and we see the content of our share:
<img loading="lazy" alt="Share Frontend" src="/assets/images/zrok_web_console_share_frontend-d36b169cea46f834e74af4aa456d0b89.png" width="1556" height="1229" class="img_ev3q"></p><p>If we click on the environment in the explorer, we&#x27;re shown all of the shares for that environment (including our new share), along with a spark line that shows the activity:</p><p><img loading="lazy" alt="Environment Spark Line" src="/assets/images/zrok_web_console_environment_spark-eeea921884089d320f4b9b2ba2038a1d.png" width="1556" height="1229" class="img_ev3q"></p><p>And as soon as I terminate the <code>zrok share</code> client, the resources are removed from the <code>zrok</code> environment.</p><p>If we try to reload the frontend endpoint in our web browser, we&#x27;ll see:</p><p><img loading="lazy" alt="Not Found" src="/assets/images/zrok_not_found-fa3415937c341eb10e1eb98c9b063583.png" width="1556" height="1229" class="img_ev3q"></p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="private-shares">Private Shares<a class="hash-link" href="#private-shares" title="Direct link to heading"></a></h3><p><code>zrok</code> also provides a powerful <em>private</em> sharing model. If I execute the following command:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok share private http://localhost:8080</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>The <code>zrok</code> service will respond with the following:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">access your share with: zrok access private wvszln4dyz9q</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Rather than allowing access to your service through a public frontend, a <em>private</em> share is only exposed to the underlying OpenZiti network, and can only be accessed using the <code>zrok access</code> command.</p><p>The <code>zrok access private wvszln4dyz9q</code> command can be run by any <code>zrok</code> user, allowing them to create and bind a local HTTP listener, that allows for private access to your shared resources.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="proxy-backend-mode">Proxy Backend Mode<a class="hash-link" href="#proxy-backend-mode" title="Direct link to heading"></a></h3><p>Without specifying a <em>backend mode</em>, the <code>zrok share</code> command will assume that you&#x27;re trying to share a <code>proxy</code> resource. A <code>proxy</code> 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 <code>localhost</code>, or only listening on a private LAN segment behind a firewall. </p><p>For these services a <code>proxy</code> share will allow those endpoints to be reached, either <em>publicly</em> or <em>privately</em> through the <code>zrok</code> service.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="web-backend-mode">Web Backend Mode<a class="hash-link" href="#web-backend-mode" title="Direct link to heading"></a></h3><p>The <code>zrok share</code> command accepts a <code>--backend-mode</code> option. Besides <code>proxy</code>, the current <code>v0.3</code> release (as of this writing) also supports a <code>web</code> mode. The <code>web</code> mode allows you to specify a local folder on your filesystem, and instantly turns your <code>zrok</code> client into a web server, exposing your web content either <em>publicly</em> or <em>privately</em> without having to a configure a web server.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="reserved-shares">Reserved Shares<a class="hash-link" href="#reserved-shares" title="Direct link to heading"></a></h3><p><code>zrok</code> shares are <em>ephemeral</em> unless you specifically create a &quot;reserved&quot; share.</p><p>A reserved share can be re-used multiple times; it will survive termination of the <code>zrok share</code> command, allowing for longer-lasting semi-permanent access to shared resources.</p><p>The first step is to create the reserved share:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok reserve public --backend-mode web v0.3_getting_started</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[   0.275]    INFO main.(*reserveCommand).run: your reserved share token is &#x27;mltwsinym1s2&#x27;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[   0.275]    INFO main.(*reserveCommand).run: reserved frontend endpoint: https://mltwsinym1s2.share.zrok.io</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>I&#x27;m asking the <code>zrok</code> service to reserve a share with a <code>web</code> backend mode, pointing at my local <code>docs</code> folder.</p><p>You&#x27;ll want to remember the share token (<code>mltwsinym1s2</code> in this case), and the frontend endpoint URL. If this were a <em>private</em> reserved share, there would not be a frontend URL.</p><p>If we do nothing else, and then point a web browser at the frontend endpoint, we get:</p><p><img loading="lazy" alt="Not Found" src="/assets/images/zrok_reserved_not_found-2519707e5cc3e635b7a6feb381c1d040.png" width="1556" height="1229" class="img_ev3q"></p><p>This is the <code>404</code> error message returned by the <code>zrok</code> frontend. We&#x27;re getting this because we haven&#x27;t yet started up a <code>zrok share</code> for the service. Let&#x27;s do that:</p><p>This command:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok share reserved mltwsinym1s2</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>...results in a new share backend starting up and connecting to the existing reserved share:</p><p><img loading="lazy" alt="zrok share reserved" src="/assets/images/zrok_share_reserved-6bce67775ce2c41abb0ef13ee1fad972.png" width="951" height="706" class="img_ev3q"></p><p>And now if we refresh the frontend endpoint URL in the web browser, we&#x27;ll see an index of the <code>docs</code> directory:</p><p><img loading="lazy" alt="zrok docs share" src="/assets/images/zrok_docs_share-1c87532d471ab25aaa1590d6215a1427.png" width="1556" height="1229" class="img_ev3q"></p><p>With the reserved share, we&#x27;re free to stop and restart the <code>zrok share reserved</code> command as many times as we want, without losing the token for our share.</p><p>When we&#x27;re done with the reserved share, we can <em>release</em> it using this command:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok release mltwsinym1s2</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[   0.230]    INFO main.(*releaseCommand).run: reserved share &#x27;mltwsinym1s2&#x27; released</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h2 class="anchor anchorWithStickyNavbar_LWe7" id="concepts-review">Concepts Review<a class="hash-link" href="#concepts-review" title="Direct link to heading"></a></h2><p>In summary, <code>zrok</code> lets you easily and securely share resources with both general internet users (through <em>public</em> sharing) and also with other <code>zrok</code> users (through <em>private</em> sharing).</p><p>Here&#x27;s a quick review of the <code>zrok</code> mental model and the vocabulary.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="service-instance-and-account">Service Instance and Account<a class="hash-link" href="#service-instance-and-account" title="Direct link to heading"></a></h3><p>You create an <em>account</em> with a <code>zrok</code> <em>service instance</em>. Your account is identified by a username and a password, which you use to log into the <em>web console</em>. Your account also has a <em>secret token</em>, which you will use to authenticate from the <code>zrok</code> command-line to interact with the <em>service instance</em>.</p><p>You create a new <em>account</em> with a <code>zrok</code> <em>service instance</em> through the <code>zrok invite</code> command.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="environment">Environment<a class="hash-link" href="#environment" title="Direct link to heading"></a></h3><p>Using your <em>secret token</em> you use the <code>zrok</code> command-line interface to create an <em>environment</em>. An <em>environment</em> corresponds to a single command-line user on a specific <em>host system</em>. </p><p>You create a new <em>environment</em> by using the <code>zrok enable</code> command.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="shares">Shares<a class="hash-link" href="#shares" title="Direct link to heading"></a></h3><p>Once you&#x27;ve enabled an <em>environment</em>, you then create one or more <em>shares</em>. Shares have either a <em>public</em> or <em>private</em> <em>sharing mode</em>. <em>Shares</em> share a specific type of resource using a <em>backend mode</em>. As of this writing <code>zrok</code> supports a <code>proxy</code> <em>backend mode</em> to share local HTTP resources as a <em>reverse proxy</em>. <code>zrok</code> also supports a <code>web</code> <em>backend mode</em> to share local file and HTML resources by enabling a basic HTTP server.</p><p>Every <em>share</em> is identified by a <em>share token</em>. <em>Public shares</em> can be accessed through either a <em>frontend</em> instance offered through the <code>zrok</code> <em>service instance</em>, or through the <code>zrok access</code> command. <em>Private shares</em> can only be accessed through the <code>zrok access</code> command.</p><p>You use the <code>zrok share</code> command to create and enable <em>ephemeral shares</em>.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="reserved-shares-1">Reserved Shares<a class="hash-link" href="#reserved-shares-1" title="Direct link to heading"></a></h3><p><code>zrok</code> supports creating <em>shares</em> that have a consistent <em>share token</em> that survives restarts of the <code>zrok share</code> command. These are considered <em>non-ephemeral</em>, and is callled a <em>reserved share</em>.</p><p>You use the <code>zrok reserve</code> command to create <em>reserved shares</em>. Reserved shares last until you use the <code>zrok release</code> command to delete them.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="self-hosting-a-service-instance">Self-Hosting a Service Instance<a class="hash-link" href="#self-hosting-a-service-instance" title="Direct link to heading"></a></h2><p>Interested in self-hosting your own <code>zrok</code> service instance? See the <a href="/docs/guides/v0.3_self_hosting_guide">self-hosting guide</a> for details.</p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="https://github.com/openziti/zrok/tree/main/../docs/getting-started.md" target="_blank" rel="noreferrer noopener" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_vwxv"></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages navigation"><a class="pagination-nav__link pagination-nav__link--next" href="/docs/core-features/"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Core Features</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#downloading-zrok" class="table-of-contents__link toc-highlight">Downloading zrok</a><ul><li><a href="#extract-zrok-distribution" class="table-of-contents__link toc-highlight">Extract zrok Distribution</a></li></ul></li><li><a href="#configure-your-zrok-service-instance" class="table-of-contents__link toc-highlight">Configure Your zrok Service Instance</a></li><li><a href="#generating-an-invitation" class="table-of-contents__link toc-highlight">Generating an Invitation</a></li><li><a href="#enabling-your-zrok-environment" class="table-of-contents__link toc-highlight">Enabling Your zrok Environment</a></li><li><a href="#sharing" class="table-of-contents__link toc-highlight">Sharing</a><ul><li><a href="#ephemeral-by-default" class="table-of-contents__link toc-highlight">Ephemeral by Default</a></li><li><a href="#public-shares-and-frontends" class="table-of-contents__link toc-highlight">Public Shares and Frontends</a></li><li><a href="#private-shares" class="table-of-contents__link toc-highlight">Private Shares</a></li><li><a href="#proxy-backend-mode" class="table-of-contents__link toc-highlight">Proxy Backend Mode</a></li><li><a href="#web-backend-mode" class="table-of-contents__link toc-highlight">Web Backend Mode</a></li><li><a href="#reserved-shares" class="table-of-contents__link toc-highlight">Reserved Shares</a></li></ul></li><li><a href="#concepts-review" class="table-of-contents__link toc-highlight">Concepts Review</a><ul><li><a href="#service-instance-and-account" class="table-of-contents__link toc-highlight">Service Instance and Account</a></li><li><a href="#environment" class="table-of-contents__link toc-highlight">Environment</a></li><li><a href="#shares" class="table-of-contents__link toc-highlight">Shares</a></li><li><a href="#reserved-shares-1" class="table-of-contents__link toc-highlight">Reserved Shares</a></li></ul></li><li><a href="#self-hosting-a-service-instance" class="table-of-contents__link toc-highlight">Self-Hosting a Service Instance</a></li></ul></div></div></div></div></main></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="footer__bottom text--center"><div class="footer__copyright">Copyright © 2023 NetFoundry Inc. Built with Docusaurus.</div></div></div></footer></div>
<script src="/assets/js/runtime~main.111dd388.js"></script>
<script src="/assets/js/main.26b076b4.js"></script>
</body>
</html>