<titledata-rh="true">zrok frontdoor | Zrok</title><metadata-rh="true"name="viewport"content="width=device-width,initial-scale=1"><metadata-rh="true"name="twitter:card"content="summary_large_image"><metadata-rh="true"property="og:url"content="https://docs.zrok.io/docs/guides/frontdoor/"><metadata-rh="true"property="og:locale"content="en"><metadata-rh="true"name="docusaurus_locale"content="en"><metadata-rh="true"name="docsearch:language"content="en"><metadata-rh="true"name="docusaurus_version"content="current"><metadata-rh="true"name="docusaurus_tag"content="docs-default-current"><metadata-rh="true"name="docsearch:version"content="current"><metadata-rh="true"name="docsearch:docusaurus_tag"content="docs-default-current"><metadata-rh="true"property="og:title"content="zrok frontdoor | Zrok"><metadata-rh="true"name="description"content="zrok frontdoor is the heavy-duty front door to your app or site. It makes your website or app available to your online audience through the shield of zrok.io's hardened, managed frontends."><metadata-rh="true"property="og:description"content="zrok frontdoor is the heavy-duty front door to your app or site. It makes your website or app available to your online audience through the shield of zrok.io's hardened, managed frontends."><linkdata-rh="true"rel="icon"href="/img/space-ziggy.png"><linkdata-rh="true"rel="canonical"href="https://docs.zrok.io/docs/guides/frontdoor/"><linkdata-rh="true"rel="alternate"href="https://docs.zrok.io/docs/guides/frontdoor/"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://docs.zrok.io/docs/guides/frontdoor/"hreflang="x-default"><linkdata-rh="true"rel="preconnect"href="https://CO73R59OLO-dsn.algolia.net"crossorigin="anonymous"><linkrel="preconnect"href="https://www.googletagmanager.com">
<iframewidth="100%"height="315"src="https://www.youtube.com/embed/5Vi8GKuTi_I"title="YouTube video player"frameborder="0"allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"></iframe>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="overview">Overview<ahref="#overview"class="hash-link"aria-label="Direct link to Overview"title="Direct link to Overview"></a></h2>
<p>zrok frontends are the parts of zrok that proxy incoming public web traffic to zrok backend shares via OpenZiti. When you use zrok with a <code>zrok.io</code> frontend, you're using <strong>zrok frontdoor</strong>. <code>zrok.io</code> is zrok-as-a-service by NetFoundry, the team behind OpenZiti. You need a free account to use <strong>zrok frontdoor</strong>.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="choose-your-os">Choose your OS<ahref="#choose-your-os"class="hash-link"aria-label="Direct link to Choose your OS"title="Direct link to Choose your OS"></a></h2>
<p>Choose between installing the Linux package or running zrok with Docker (Linux, macOS, or Windows).</p>
<divclass="tabs-container tabList__CuJ"><ulrole="tablist"aria-orientation="horizontal"class="tabs"><lirole="tab"tabindex="0"aria-selected="true"class="tabs__item tabItem_LNqP tabs__item--active">Linux</li><lirole="tab"tabindex="-1"aria-selected="false"class="tabs__item tabItem_LNqP">Docker</li></ul><divclass="margin-top--md"><divrole="tabpanel"class="tabItem_Ymn6"><p>On Linux, zrok frontdoor is implemented natively as a system service provided by the <code>zrok-share</code> DEB or RPM package.</p><h2class="anchor anchorWithStickyNavbar_LWe7"id="goal">Goal<ahref="#goal"class="hash-link"aria-label="Direct link to Goal"title="Direct link to Goal"></a></h2>
<p>Proxy a reserved public subdomain to a backend target with an always-on Linux system service.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="how-it-works">How it Works<ahref="#how-it-works"class="hash-link"aria-label="Direct link to How it Works"title="Direct link to How it Works"></a></h2>
<p>The <code>zrok-share</code> package creates a <code>zrok-share.service</code> unit in systemd. The administrator edits the service's configuration file to specify the:</p>
<ol>
<li>zrok environment enable token</li>
<li>target URL or files to be shared and backend mode, e.g. <code>proxy</code></li>
<li>authentication options, if wanted</li>
</ol>
<p>When the service starts it will:</p>
<ol>
<li>enable the zrok environment unless <code>/var/lib/zrok-share/.zrok/environment.json</code> exists</li>
<li>reserve a public subdomain for the service unless <code>/var/lib/zrok-share/.zrok/reserved.json</code> exists</li>
<li>start sharing the target specified as <code>ZROK_TARGET</code> in the environment file</li>
</ol>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="installation">Installation<ahref="#installation"class="hash-link"aria-label="Direct link to Installation"title="Direct link to Installation"></a></h2>
<p>Set up <code>zrok</code>'s Linux package repository by following <ahref="/docs/guides/install/linux/#install-zrok-from-the-repository">the Linux install guide</a>, or run this one-liner to complete the repo setup and install packages.</p>
<p>If you set up the repository by following the guide, then also install the <code>zrok-share</code> package. This package provides the systemd service.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="enable">Enable<ahref="#enable"class="hash-link"aria-label="Direct link to Enable"title="Direct link to Enable"></a></h2>
<p>Save the enable token from the zrok console in the configuration file.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="name-your-share">Name your Share<ahref="#name-your-share"class="hash-link"aria-label="Direct link to Name your Share"title="Direct link to Name your Share"></a></h2>
<p>This unique name becomes part of the domain name of the share, e.g. <code>https://my-prod-app.in.zrok.io</code>. A random name is generated if you don't specify one.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="use-cases">Use Cases<ahref="#use-cases"class="hash-link"aria-label="Direct link to Use Cases"title="Direct link to Use Cases"></a></h2>
<p>You may change the target for the current backend mode, e.g. <code>proxy</code>, by editing the configuration file and restarting the service. The reserved subdomain will remain the same.</p>
<p>You may switch between backend modes or change authentication options by deleting <code>/var/lib/zrok-share/.zrok/reserved.json</code> and restarting the service. A new subdomain will be reserved.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="proxy-a-web-server">Proxy a Web Server<ahref="#proxy-a-web-server"class="hash-link"aria-label="Direct link to Proxy a Web Server"title="Direct link to Proxy a Web Server"></a></h3>
<p>Proxy a reserved subdomain to an existing web server. The web server could be on a private network or on the same host as zrok.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="serve-static-files">Serve Static Files<ahref="#serve-static-files"class="hash-link"aria-label="Direct link to Serve Static Files"title="Direct link to Serve Static Files"></a></h3>
<p>Run zrok's embedded web server to serve the files in a directory. If there's an <code>index.html</code> file in the directory then visitors will see that web page in their browser, otherwise they'll see a generated index of the files. The directory must be readable by 'other', e.g. <code>chmod -R o+rX /var/www/html</code>.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="caddy-server">Caddy Server<ahref="#caddy-server"class="hash-link"aria-label="Direct link to Caddy Server"title="Direct link to Caddy Server"></a></h3>
<p>Use zrok's built-in Caddy server to serve static files or as a reverse proxy to multiple web servers with various HTTP routes or as a load-balanced set. A sample Caddyfile is available in the path shown.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="network-drive">Network Drive<ahref="#network-drive"class="hash-link"aria-label="Direct link to Network Drive"title="Direct link to Network Drive"></a></h3>
<p>This uses zrok's <code>drive</code> backend mode to serve a directory of static files as a virtual network drive. The directory must be readable by 'other', e.g. <code>chmod -R o+rX /usr/share/doc</code>.</p>
<p><ahref="https://blog.openziti.io/zrok-drives-an-early-preview"target="_blank"rel="noopener noreferrer">Learn more about this feature in this blog post</a>.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="authentication">Authentication<ahref="#authentication"class="hash-link"aria-label="Direct link to Authentication"title="Direct link to Authentication"></a></h2>
<p>You can limit access to certain email addresses with OAuth or require a password.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="oauth">OAuth<ahref="#oauth"class="hash-link"aria-label="Direct link to OAuth"title="Direct link to OAuth"></a></h3>
<p>You can require that visitors authenticate with an email address that matches at least one of the suffixes you specify. Add the following to the configuration file.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="password">Password<ahref="#password"class="hash-link"aria-label="Direct link to Password"title="Direct link to Password"></a></h3>
<p>Enable HTTP basic authentication by adding the following to the configuration file.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="start-the-service">Start the Service<ahref="#start-the-service"class="hash-link"aria-label="Direct link to Start the Service"title="Direct link to Start the Service"></a></h2>
<p>Start the service, and check the zrok console or the service log for the reserved subdomain.</p>
<divclass="language-bash codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><divclass="codeBlockTitle_Ktv7">run now and at startup</div><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-bash codeBlock_bY9V thin-scrollbar"style="color:#F8F8F2;background-color:#282A36"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">sudo systemctl enable --now zrok-share.service</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="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><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="compatibility">Compatibility<ahref="#compatibility"class="hash-link"aria-label="Direct link to Compatibility"title="Direct link to Compatibility"></a></h2>
<p>The Linux distribution must have a package manager that understands the <code>.deb</code> or <code>.rpm</code> format and be running systemd v232 or newer. The service was tested with:</p>
<ul>
<li>Ubuntu 20.04, 22.04, 23.04</li>
<li>Debian 11 12</li>
<li>Rocky 8, 9</li>
<li>Fedora 37, 38</li>
</ul>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="package-contents">Package Contents<ahref="#package-contents"class="hash-link"aria-label="Direct link to Package Contents"title="Direct link to Package Contents"></a></h2>
<p>The files included in the <code>zrok-share</code> package are sourced <ahref="https://github.com/openziti/zrok/tree/main/nfpm"target="_blank"rel="noopener noreferrer">here in GitHub</a>.</p></div><divrole="tabpanel"class="tabItem_Ymn6"hidden=""><p>On macOS and Windows, zrok frontdoor is implemented as a Docker Compose project which reserves a public subdomain for your website or service and manages a zrok environment that's separate from the Docker host. <ahref="/docs/guides/docker-share/docker_public_share_guide/">Link to the Docker Public Share Guide</a></p></div></div></div>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="concepts">Concepts<ahref="#concepts"class="hash-link"aria-label="Direct link to Concepts"title="Direct link to Concepts"></a></h2>
