zrok/docs/guides/self-hosting/linux/index.html

138 lines
74 KiB
HTML
Raw Normal View History

<!doctype html>
<html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-guides/self-hosting/linux/index" data-has-hydrated="false">
<head>
<meta charset="UTF-8">
<meta name="generator" content="Docusaurus v3.3.2">
<title data-rh="true">Self-Hosting Guide for Linux | 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://docs.zrok.io/docs/guides/self-hosting/linux/"><meta data-rh="true" property="og:locale" content="en"><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="Self-Hosting Guide for Linux | Zrok"><meta data-rh="true" name="description" content="Walkthrough Video"><meta data-rh="true" property="og:description" content="Walkthrough Video"><link data-rh="true" rel="icon" href="/img/space-ziggy.png"><link data-rh="true" rel="canonical" href="https://docs.zrok.io/docs/guides/self-hosting/linux/"><link data-rh="true" rel="alternate" href="https://docs.zrok.io/docs/guides/self-hosting/linux/" hreflang="en"><link data-rh="true" rel="alternate" href="https://docs.zrok.io/docs/guides/self-hosting/linux/" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://CO73R59OLO-dsn.algolia.net" crossorigin="anonymous"><link rel="preconnect" href="https://www.googletagmanager.com">
<script>window.dataLayer=window.dataLayer||[]</script>
<script>!function(e,t,a,n,g){e[n]=e[n]||[],e[n].push({"gtm.start":(new Date).getTime(),event:"gtm.js"});var m=t.getElementsByTagName(a)[0],r=t.createElement(a);r.async=!0,r.src="https://www.googletagmanager.com/gtm.js?id=GTM-MDFLZPK8",m.parentNode.insertBefore(r,m)}(window,document,"script","dataLayer")</script>
<link rel="search" type="application/opensearchdescription+xml" title="Zrok" href="/opensearch.xml"><link rel="stylesheet" href="/assets/css/styles.44f28847.css">
<script src="/assets/js/runtime~main.6fc8bd33.js" defer="defer"></script>
<script src="/assets/js/main.53605760.js" defer="defer"></script>
</head>
<body class="navigation-with-keyboard">
<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-MDFLZPK8" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return localStorage.getItem("theme")}catch(t){}}();t(null!==e?e:"dark")}(),function(){try{const c=new URLSearchParams(window.location.search).entries();for(var[t,e]of c)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</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 aria-label="Main" 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="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/img/space-ziggy.png" alt="Ziggy Goes to Space" class="themedComponent_mlkZ themedComponent--dark_xIcU"></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/">Docs</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 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
<iframe width="100%" height="315" src="https://www.youtube.com/embed/870A5dke_u4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"></iframe>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="before-you-begin">Before you Begin<a href="#before-you-begin" class="hash-link" aria-label="Direct link to Before you Begin" title="Direct link to Before you Begin"></a></h2>
<p>This will get you up and running with a self-hosted instance of <code>zrok</code>. I&#x27;ll assume you have the following:</p>
<ul>
<li>a Linux server with a public IP</li>
<li>a wildcard DNS record like <code>*.zrok.quigley.com</code> that resolves to the server IP</li>
</ul>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="openziti">OpenZiti<a href="#openziti" class="hash-link" aria-label="Direct link to OpenZiti" title="Direct link to OpenZiti"></a></h2>
<p>OpenZiti (a.k.a. &quot;Ziti&quot;) provides secure network backhaul for <code>zrok</code> public and private shares. You need a Ziti Controller and a Ziti Router. You can run everything on the same Linux VPS.</p>
<ol>
<li>
<p>Install the Ziti Controller package by following the <a href="https://openziti.io/docs/category/deployments" target="_blank" rel="noopener noreferrer">Linux controller deployment guide</a>.</p>
</li>
<li>
<p>Ensure your answer file (<code>/opt/openziti/etc/controller/bootstrap.env</code>) has the FQDN of your Linux server and an admin password defined.</p>
</li>
<li>
<p>Ensure your firewall allows the controller port from the answer file.</p>
</li>
<li>
<p>Start the controller service (<code>ziti-controller.service</code>) and check the status.</p>
</li>
<li>
<p>Log in to the Ziti Controller</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">ziti edge login localhost:1280 -u admin -p &lt;password&gt;</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
</li>
<li>
<p>Administratively Create a Ziti Router</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">ziti edge create edge-router &quot;router1&quot; -o /tmp/router1.jwt</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
</li>
<li>
<p>Install the Ziti Router package by following <a href="https://openziti.io/docs/category/deployments" target="_blank" rel="noopener noreferrer">the Linux router deployment guide</a>.</p>
</li>
<li>
<p>Ensure your answer file (<code>/opt/openziti/etc/router/bootstrap.env</code>) has the FQDN of your Linux server for both controller and router addresses and the enrollment token from the previous step.</p>
</li>
<li>
<p>Ensure your firewall allows the router port from the answer file.</p>
</li>
<li>
<p>Start the router service (<code>ziti-router.service</code>) and check the status.</p>
</li>
<li>
<p>Verify the new router is online.</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">ziti edge list edge-routers</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
</li>
</ol>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="install-zrok">Install zrok<a href="#install-zrok" class="hash-link" aria-label="Direct link to Install zrok" title="Direct link to Install zrok"></a></h2>
<p>Debian and RPM packages are available for <code>zrok</code>.</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">sudo apt install 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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<p>Follow <a href="/docs/guides/install/linux/">the Linux installation guide</a> to install the <code>zrok</code> package from the repository or manually install the binary for your platform.</p>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="configure-the-controller">Configure the Controller<a href="#configure-the-controller" class="hash-link" aria-label="Direct link to Configure the Controller" title="Direct link to Configure the Controller"></a></h2>
<p>Create a <code>zrok</code> controller configuration file in <code>etc/ctrl.yml</code>. The controller can terminate TLS or you may front the server with a reverse proxy that continually renews the necessary wildcard certificate (e.g., Caddy w/ a DNS provider plugin). This example will expose the non-TLS listener for the controller.</p>
<div class="language-yaml codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-yaml codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token comment" style="color:rgb(98, 114, 164)"># _____ __ ___ | | __</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token comment" style="color:rgb(98, 114, 164)"># |_ / &#x27;__/ _ \| |/ /</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token comment" style="color:rgb(98, 114, 164)"># / /| | | (_) | &lt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token comment" style="color:rgb(98, 114, 164)"># /___|_| \___/|_|\_\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token comment" style="color:rgb(98, 114, 164)"># controller configuration</span><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"></span><span class="token key atrule">v</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token number">3</span><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"></span><span class="token key atrule">admin</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token comment" style="color:rgb(98, 114, 164)"># generate these admin tokens from a source of randomness, e.g. </span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token comment" style="color:rgb(98, 114, 164)"># LC_ALL=C tr -dc _A-Z-a-z-0-9 &lt; /dev/urandom | head -c32</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">secrets</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain"> Q8V0LqnNb5wNX9kE1fgQ0H6VlcvJybB1 </span><span class="token comment" style="color:rgb(98, 114, 164)"># be sure to change this!</span><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"></span><span class="token key atrule">endpoint</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">host</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> 0.0.0.0</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">port</span><span class="token punctuation" styl
<p>The <code>admin</code> section defines privileged administrative credentials and must be set in the <code>ZROK_ADMIN_TOKEN</code> environment variable in shells where you want to run <code>zrok admin</code>.</p>
<p>The <code>endpoint</code> section defines where your <code>zrok</code> controller will listen.</p>
<p>The <code>store</code> section defines the local <code>sqlite3</code> database used by the controller.</p>
<p>The <code>ziti</code> section defines how the <code>zrok</code> controller should communicate with your OpenZiti installation. When using the OpenZiti quickstart, an administrative password will be generated; the <code>password</code> in the <code>ziti</code> stanza should reflect this password.</p>
<div class="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><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_BuS1"><p>Be sure to see the <a href="/assets/files/ctrl-6c22ae02cafe307b82e5a1f783497950.yml/" target="_blank">reference configuration at <code>etc/ctrl.yml</code></a> for the complete documentation of the current configuration file format for the <code>zrok</code> controller and service instance components.</p><p>See the separate guides on <a href="/docs/guides/self-hosting/metrics-and-limits/configuring-metrics/">configuring metrics</a> and <a href="/docs/guides/self-hosting/metrics-and-limits/configuring-limits/">configuring limits</a> for details about both of these specialized areas of service instance configuration.</p></div></div>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="environment-variables">Environment Variables<a href="#environment-variables" class="hash-link" aria-label="Direct link to Environment Variables" title="Direct link to Environment Variables"></a></h2>
<p>The <code>zrok</code> binaries are configured to work with the global <code>zrok.io</code> service, and default to using <code>api.zrok.io</code> as the endpoint for communicating with the service.</p>
<p>To work with a self-hosted <code>zrok</code> deployment, you&#x27;ll need to set the <code>ZROK_API_ENDPOINT</code> environment variable to point to the address where your <code>zrok</code> controller will be listening, according to <code>endpoint</code> in the configuration file above.</p>
<p>In my case, I&#x27;ve set:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">export ZROK_API_ENDPOINT=http://127.0.0.1:18080</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<p><a href="/docs/guides/self-hosting/instance-configuration/">Read more about configuring your self-hosted <code>zrok</code> instance</a>.</p>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="bootstrap-openziti-for-zrok">Bootstrap OpenZiti for zrok<a href="#bootstrap-openziti-for-zrok" class="hash-link" aria-label="Direct link to Bootstrap OpenZiti for zrok" title="Direct link to Bootstrap OpenZiti for zrok"></a></h2>
<p>With your OpenZiti network running and your configuration saved to a local file (I refer to mine as <code>etc/ctrl.yml</code> in these examples), you&#x27;re ready to bootstrap the Ziti network.</p>
<p>Use the <code>zrok admin bootstrap</code> command to bootstrap like this:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok admin bootstrap etc/ctrl.yml</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.002] INFO main.(*adminBootstrap).run: {</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">[ 0.002] INFO zrok/controller/store.Open: database connected</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.006] INFO zrok/controller/store.(*Store).migrate: applied 0 migrations</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.006] INFO zrok/controller.Bootstrap: connecting to the ziti edge management api</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.039] INFO zrok/controller.Bootstrap: creating identity for controller ziti access</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.071] INFO zrok/controller.Bootstrap: controller identity: jKd8AINSz</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.082] INFO zrok/controller.assertIdentity: asserted identity &#x27;jKd8AINSz&#x27;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.085] INFO zrok/controller.assertErpForIdentity: asserted erps for &#x27;ctrl&#x27; (jKd8AINSz)</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.085] INFO zrok/controller.Bootstrap: creating identity for frontend ziti access</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.118] INFO zrok/controller.Bootstrap: frontend identity: sqJRAINSiB</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.119] INFO zrok/controller.assertIdentity: asserted identity &#x27;sqJRAINSiB&#x27;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.120] INFO zrok/controller.assertErpForIdentity: asserted erps for &#x27;frontend&#x27; (sqJRAINSiB)</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.120] WARNING zrok/controller.Bootstrap: missing public frontend for ziti id &#x27;sqJRAINSiB&#x27;; please use &#x27;zrok admin create frontend sqJRAINSiB public https://{token}.your.dns.name&#x27; to create a frontend instance</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.123] INFO zrok/controller.assertZrokProxyConfigType: found &#x27;zrok.proxy.v1&#x27; config type with id &#x27;33CyjNbIepkXHN5VzGDA8L&#x27;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.124] INFO zrok/controller.assertMetricsService: creating &#x27;metrics&#x27; service</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.126] INFO zrok/controller.assertMetricsService: asserted &#x27;metrics&#x27; service (5RpPZZ7T8bZf1ENjwGiPc3)</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.128] INFO zrok/controller.assertMetricsSerp: creating &#x27;metrics&#x27; serp</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.130] INFO zrok/controller.assertMetricsSerp: asserted &#x27;metrics&#x27; serp</span><br></span><span class="token-line" style="color:#F8F8F2"><s
<p>The <code>zrok admin bootstrap</code> command configures the <code>zrok</code> database, the necessary OpenZiti identities, and all of the OpenZiti policies required to run a <code>zrok</code> service.</p>
<p>Notice this warning:</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" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.120] WARNING zrok/controller.Bootstrap: missing public frontend for ziti id &#x27;sqJRAINSiB&#x27;; please use &#x27;zrok admin create frontend sqJRAINSiB public https://{token}.your.dns.name&#x27; to create a frontend instance</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<p>If you find it necessary to re-run the <code>zrok admin bootstrap</code> command, you may need to add the <code>--skip-frontend</code> flag to avoid re-creating the default <code>public</code> frontend&#x27;s Ziti identity and router policy.</p>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="run-zrok-controller">Run zrok Controller<a href="#run-zrok-controller" class="hash-link" aria-label="Direct link to Run zrok Controller" title="Direct link to Run zrok Controller"></a></h2>
<p>The <code>zrok</code> bootstrap process wants us to create a &quot;public frontend&quot; for our service. <code>zrok</code> uses public frontends to allow users to specify where they would like public traffic to ingress from.</p>
<p>The <code>zrok admin create frontend</code> command requires a running <code>zrok</code> controller, so let&#x27;s start that up first:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok controller etc/ctrl.yml </span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.003] INFO main.(*controllerCommand).run: {</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">[ 0.016] INFO zrok/controller.inspectZiti: inspecting ziti controller configuration</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.048] INFO zrok/controller.findZrokProxyConfigType: found &#x27;zrok.proxy.v1&#x27; config type with id &#x27;33CyjNbIepkXHN5VzGDA8L&#x27;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.048] INFO zrok/controller/store.Open: database connected</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.048] INFO zrok/controller/store.(*Store).migrate: applied 0 migrations</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.049] INFO zrok/controller.(*metricsAgent).run: starting</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.064] INFO zrok/rest_server_zrok.setupGlobalMiddleware: configuring</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.064] INFO zrok/ui.StaticBuilder: building</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.065] INFO zrok/rest_server_zrok.(*Server).Logf: Serving zrok at http://[::]:18080</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.085] INFO zrok/controller.(*metricsAgent).listen: started</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" 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="create-zrok-frontend">Create zrok Frontend<a href="#create-zrok-frontend" class="hash-link" aria-label="Direct link to Create zrok Frontend" title="Direct link to Create zrok Frontend"></a></h2>
<p>With our <code>ZROK_ADMIN_TOKEN</code> and <code>ZROK_API_ENDPOINT</code> environment variables set, we can create our public frontend like this:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok admin create frontend sqJRAINSiB public http://{token}.zrok.quigley.com:8080</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.037] INFO main.(*adminCreateFrontendCommand).run: created global public frontend &#x27;WEirJNHVlcW9&#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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" 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 id of the frontend was emitted earlier in by the <code>zrok</code> controller when we ran the bootstrap command. If you don&#x27;t have that log message the you can find the id again with the <code>ziti</code> CLI like this:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain"># log in as admin (example)</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">ziti edge login localhost:1280 -u admin -p XO0xHp75uuyeireO2xmmVlK91T7B9fpD</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"># list Ziti identities created by the quickstart and bootstrap</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">ziti edge list identities</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" 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 id is shown for the frontend identity named &quot;public.&quot;</p>
<p>Nice work! The <code>zrok</code> controller is fully configured now that you have created the <code>zrok</code> frontend.</p>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="configure-the-public-frontend">Configure the Public Frontend<a href="#configure-the-public-frontend" class="hash-link" aria-label="Direct link to Configure the Public Frontend" title="Direct link to Configure the Public Frontend"></a></h2>
<p>Create an http frontend configuration file in <code>etc/http-frontend.yml</code>.</p>
<div class="language-yaml codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-yaml codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token key atrule">v</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token number">3</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key atrule">host_match</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> zrok.quigley.com</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key atrule">address</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> 0.0.0.0</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token number">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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<p>This frontend config file has a <code>host_match</code> pattern that represents the DNS zone you&#x27;re using with this instance of <code>zrok</code>. Incoming HTTP requests with a matching <code>Host</code> header will be handled by this frontend. You may also specify the interface address where the frontend will listen for public access requests.</p>
<p>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 <code>Host</code> header supplied by the viewer. This example will expose the non-TLS listener for the frontend.</p>
<p>You can also specify an <code>oauth</code> configuration in this file, full details of are found in <a href="/docs/guides/self-hosting/oauth/configuring-oauth/#configuring-your-public-frontend">OAuth Public Frontend Configuration</a>.</p>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="start-public-frontend">Start Public Frontend<a href="#start-public-frontend" class="hash-link" aria-label="Direct link to Start Public Frontend" title="Direct link to Start Public Frontend"></a></h2>
<p>In another terminal window, run:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok access public etc/http-frontend.yml</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 0.002] INFO main.(*accessPublicCommand).run: {</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">[ 0.002] INFO zrok/endpoints/public_frontend.newMetricsAgent: loaded &#x27;public&#x27; identity</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" 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> frontend uses the <code>public</code> identity created during the bootstrap process to securely access zrok backends. to provide public access for the <code>zrok</code> deployment. It is expected that the configured listener for this frontend corresponds to the DNS template specified when creating the public frontend record above.</p>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="create-a-user-account">Create a User Account<a href="#create-a-user-account" class="hash-link" aria-label="Direct link to Create a User Account" title="Direct link to Create a User Account"></a></h2>
<p>With our <code>ZROK_ADMIN_TOKEN</code> and <code>ZROK_API_ENDPOINT</code> environment variables set, we can create our first user account.</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">zrok admin create account etc/ctrl.yml &lt;email&gt; &lt;password&gt;</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" 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 output is the account token you will use to enable each device&#x27;s zrok environment.</p>
<div class="language-buttonless codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockTitle_Ktv7">Example output</div><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-buttonless codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">SuGzRPjVDIcF</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" 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="invite-additional-users">Invite Additional Users<a href="#invite-additional-users" class="hash-link" aria-label="Direct link to Invite Additional Users" title="Direct link to Invite Additional Users"></a></h2>
<p>Offer this onboarding method to your users if you have configured an email-sending service in your <code>zrok</code> controller configuration.</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><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">New Email: user@domain.com</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Confirm Email: user@domain.com</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<p>If you look at the console output from your <code>zrok</code> controller, you&#x27;ll see a message like this:</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" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 238.168] INFO zrok/controller.(*inviteHandler).Handle: account request for &#x27;user@domain.com&#x27; has registration token &#x27;U2Ewt1UCn3ql&#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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<p>You can access your <code>zrok</code> controller&#x27;s registration UI by pointing a web browser at:</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" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">http://localhost:18080/register/U2Ewt1UCn3ql</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" 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 UI will ask you to set a password for your new account. Go ahead and do that.</p>
<p>After doing that, I see the following output in my controller console:</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" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">[ 516.778] INFO zrok/controller.(*registerHandler).Handle: created account &#x27;user@domain.com&#x27; with token &#x27;SuGzRPjVDIcF&#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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<p>Keep track of the token listed above (<code>SuGzRPjVDIcF</code>). We&#x27;ll use this to enable our shell for this <code>zrok</code> deployment.</p>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="enable-your-environment">Enable Your Environment<a href="#enable-your-environment" class="hash-link" aria-label="Direct link to Enable Your Environment" title="Direct link to Enable Your Environment"></a></h2>
<p>On another device that can reach your Linux server by FQDN, configure the API endpoint and enable the environment with the account token you received when you created the first user account.</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">export ZROK_API_ENDPOINT=https://zrok.quigley.com</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"># or</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">zrok config set apiEndpoint https://zrok.quigley.com</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" 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="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">zrok enable SuGzRPjVDIcF</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" 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="language-buttonless codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockTitle_Ktv7">Example output</div><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-buttonless codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">zrok environment &#x27;2AS1WZ3Sz&#x27; enabled for &#x27;SuGzRPjVDIcF&#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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" 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="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">zrok status --secrets</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" 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="language-buttonless codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockTitle_Ktv7">Example output</div><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-buttonless codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><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.quigley.com 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 SuGzRPjVDIcF</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> Ziti Identity 2AS1WZ3Sz</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 viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" 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 viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<p>Congratulations. You have a working <code>zrok</code> environment!</p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col"><a href="https://github.com/openziti/zrok/blob/main/docs/../docs/guides/self-hosting/linux/index.mdx" target="_blank" rel="noopener noreferrer" 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_JAkA"></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/docs/category/self-hosting/"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Self Hosting</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/docs/guides/self-hosting/linux/nginx/"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">NGINX TLS</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="#walkthrough-video" class="table-of-contents__link toc-highlight">Walkthrough Video</a></li><li><a href="#before-you-begin" class="table-of-contents__link toc-highlight">Before you Begin</a></li><li><a href="#openziti" class="table-of-contents__link toc-highlight">OpenZiti</a></li><li><a href="#install-zrok" class="table-of-contents__link toc-highlight">Install zrok</a></li><li><a href="#configure-the-controller" class="table-of-contents__link toc-highlight">Configure the Controller</a></li><li><a href="#environment-variables" class="table-of-contents__link toc-highlight">Environment Variables</a></li><li><a href="#bootstrap-openziti-for-zrok" class="table-of-contents__link toc-highlight">Bootstrap OpenZiti for zrok</a></li><li><a href="#run-zrok-controller" class="table-of-contents__link toc-highlight">Run zrok Controller</a></li><li><a href="#create-zrok-frontend" class="table-of-contents__link toc-highlight">Create zrok Frontend</a></li><li><a href="#configure-the-public-frontend" class="table-of-contents__link toc-highlight">Configure the Public Frontend</a></li><li><a href="#start-public-frontend" class="table-of-contents__link toc-highlight">Start Public Frontend</a></li><li><a href="#create-a-user-account" class="table-of-contents__link toc-highlight">Create a User Account</a></li><li><a href="#invite-additional-users" class="table-of-contents__link toc-highlight">Invite Additional Users</a></li><li><a href="#enable-your-environment" class="table-of-contents__link toc-highlight">Enable Your Environment</a></li></ul></div></div></div></div></main></div></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="footer__bottom text--center"><div class="footer__copyright">Copyright © 2024 NetFoundry Inc. Built with Docusaurus.</div></div></div></footer></div>
</body>
</html>