zrok/docs/guides/linux-service.md

title	sidebar_position
Linux Service	40

Goal

Proxy a reserved public subdomain to a backend target with a Linux service.

Requirements

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-22, Debian 11-12, Rocky 8-9, and Fedora 37-38.

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
2. target URL or files to be shared and backend mode, e.g. proxy
3. authentication options, if wanted

When the service starts it will:

1. enable the zrok environment unless /var/lib/zrok-share/.zrok/environment.json exists
2. reserve a public subdomain for the service unless /var/lib/zrok-share/.zrok/reserved.json exists
3. start sharing the target specified in the configuration file

Installation

1. Download the OpenZiti install script.

   curl -sSo ./openziti-install.bash https://get.openziti.io/install.bash
   

2. Inspect the script to ensure it is suitable to run as root on your system.

   less ./openziti-install.bash
   

3. Run the script as root to install the zrok-share package.

   sudo bash ./openziti-install.bash zrok-share
   

Enable

Save the enable token from the zrok console in the configuration file.

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.

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 directory. The directory must be readable by 'other' users, i.e. chmod o+rX /var/www/html.

ZROK_TARGET="/var/www/html"
ZROK_BACKEND_MODE="web"

WebDAV Server

This uses zrok's drive backend mode to serve a directory of static files as a WebDAV resource. The directory must be readable by 'other' users, i.e. chmod o+rX /usr/share/doc.

ZROK_TARGET="/usr/share/doc"
ZROK_BACKEND_MODE="drive"

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 template is provided. Set these in the configuration file.

ZROK_TARGET="/opt/openziti/etc/zrok/multiple_upstream.Caddyfile"
ZROK_BACKEND_MODE="caddy"

Authentication

You can require a password or OAuth email address suffix.

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.

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.

ZROK_BASIC_AUTH="user:passwd"

Start the Service

Start the service, and check the zrok console or the service log for the reserved subdomain.

sudo systemctl enable --now zrok-share.service

sudo systemctl restart zrok-share.service

journalctl -u zrok-share.service

Package Contents

The files included in the zrok-share package are sourced here in GitHub.