4.1 KiB
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. This includes Ubuntu 20+,
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:
- zrok environment enable token
- target URL or files to be shared and backend mode, e.g.
proxy
- authentication options, if wanted
When the service starts it will:
- enable the zrok environment unless
/var/lib/zrok-share/.zrok/environment.json
exists - reserve a public subdomain for the service unless
/var/lib/zrok-share/.zrok/reserved.json
exists - start sharing the target specified in the configuration file
Installation
-
Download the OpenZiti install script.
curl -sSo ./openziti-install.bash https://get.openziti.io/install.bash
-
Inspect the script to ensure it is suitable to run as root on your system.
less ./openziti-install.bash
-
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 can change the share target by modifying the configuration file and restarting the service. Changing the target does not require reserving a new subdomain.
You may switch between backend modes or change authentication options by deleting the /var/lib/zrok-share/.zrok/reserved.json
file 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.
# run now and at startup
sudo systemctl enable --now zrok-share.service
# or
# run now
sudo systemctl restart zrok-share.service
journalctl -u zrok-share.service