--- title: zrok Front Door sidebar_label: Front Door sidebar_position: 40 --- ## Goal Proxy a reserved public subdomain to a backend target with a Linux service. ## How it Works The `zrok-share` package creates a `zrok-share.service` unit in systemd. The administrator edits the service's configuration file to specify the: 1. zrok environment enable token 1. target URL or files to be shared and backend mode, e.g. `proxy` 1. authentication options, if wanted When the service starts it will: 1. enable the zrok environment unless `/var/lib/zrok-share/.zrok/environment.json` exists 1. reserve a public subdomain for the service unless `/var/lib/zrok-share/.zrok/reserved.json` exists 1. start sharing the target specified in the configuration file ## Installation 1. Install `zrok` by following the package repo setup instructions in [the Linux install guide](/guides/install/linux.mdx). 1. Install the `zrok-share` package. ```bash title="Ubuntu, Debian" sudo sudo apt install zrok-share ``` ```bash title="Fedora, Rocky" sudo dnf install zrok-share ``` ## Enable Save the enable token from the zrok console in the configuration file. ```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_ENABLE_TOKEN="14cbfca9772f" ``` ## Use Cases You may change the target for the current backend mode, e.g. `proxy`, by editing the configuration file and restarting the service. The reserved subdomain will remain the same. You may switch between backend modes or change authentication options by deleting `/var/lib/zrok-share/.zrok/reserved.json` and restarting the service. A new subdomain will be reserved. ### Proxy a Web Server 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. ```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_TARGET="http://127.0.0.1:3000" ZROK_BACKEND_MODE="proxy" ``` ### Serve Static Files Run zrok's embedded web server to serve the files in a directory. If there's an `index.html` 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. `chmod -R o+rX /var/www/html`. ```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_TARGET="/var/www/html" ZROK_BACKEND_MODE="web" ``` ### Caddy Server 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. ```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_TARGET="/opt/openziti/etc/zrok/multiple_upstream.Caddyfile" ZROK_BACKEND_MODE="caddy" ``` ### Network Drive This uses zrok's `drive` backend mode to serve a directory of static files as a virtual network drive. The directory must be readable by 'other', e.g. `chmod -R o+rX /usr/share/doc`. ```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_TARGET="/usr/share/doc" ZROK_BACKEND_MODE="drive" ``` [Learn more about this feature in this blog post](https://blog.openziti.io/zrok-drives-an-early-preview). ## Authentication You can limit access to certain email addresses with OAuth or require a password. ### OAuth 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. ```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_OAUTH_PROVIDER="github" # or google ZROK_OAUTH_EMAILS="bob@example.com @acme.example.com" ``` ### Password Enable HTTP basic authentication by adding the following to the configuration file. ```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_BASIC_AUTH="user:passwd" ``` ## Start the Service Start the service, and check the zrok console or the service log for the reserved subdomain. ```bash title="run now and at startup" sudo systemctl enable --now zrok-share.service ``` ```bash title="run now" sudo systemctl restart zrok-share.service ``` ```bash journalctl -u zrok-share.service ``` ## Compatibility The Linux distribution must have a package manager that understands the `.deb` or `.rpm` format and be running systemd v232 or newer. The service was tested with: * Ubuntu 20.04, 22.04, 23.04 * Debian 11 12 * Rocky 8, 9 * Fedora 37, 38 ## Package Contents The files included in the `zrok-share` package are sourced [here in GitHub](https://github.com/openziti/zrok/tree/main/nfpm).