Skip to main content

zrok frontdoor

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.

Overview​

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 zrok.io frontend, you're using zrok frontdoor. zrok.io is zrok-as-a-service by NetFoundry, the team behind OpenZiti. You need a free account to use zrok frontdoor.

frontdoor diagramfrontdoor diagram

Choose your OS​

Choose between installing the Linux package or running zrok with Docker (Linux, macOS, or Windows).

On Linux, zrok frontdoor is implemented natively as a system service provided by the zrok-share DEB or RPM package.

Goal​

Proxy a reserved public subdomain to a backend target with an always-on Linux system 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
  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 as ZROK_TARGET in the environment file

Installation​

  1. Set up zrok's Linux package repository by following the Linux install guide, or run this one-liner to complete the repo setup and install packages.

    curl -sSLf https://get.openziti.io/install.bash \
    | sudo bash -s zrok-share

  2. If you set up the repository by following the guide, then also install the zrok-share package. This package provides the systemd service.

    Ubuntu, Debian
    sudo apt install zrok-share
    Fedora, Rocky
    sudo dnf install zrok-share
Ansible Playbook
Set up package repository and install zrok-share
- name: Set up zrok Package Repo
  gather_facts: true
  hosts: all
  become: true
  tasks:
    - name: Set up apt repo
      when: ansible_os_family == "Debian"
      block:
        - name: Install playbook dependencies
          ansible.builtin.package:
            name:
              - gnupg
            state: present
        - name: Fetch armored pubkey
          ansible.builtin.uri:
            url: https://get.openziti.io/tun/package-repos.gpg
            return_content: 'yes'
          register: armored_pubkey
        - name: Dearmor pubkey
          ansible.builtin.shell: >
            gpg --dearmor --output /usr/share/keyrings/openziti.gpg <<< "{{
            armored_pubkey.content }}"
          args:
            creates: /usr/share/keyrings/openziti.gpg
            executable: /bin/bash
        - name: Set pubkey filemode
          ansible.builtin.file:
            path: /usr/share/keyrings/openziti.gpg
            mode: a+rX
        - name: Install OpenZiti repo deb source
          ansible.builtin.copy:
            dest: /etc/apt/sources.list.d/openziti-release.list
            content: >
              deb [signed-by=/usr/share/keyrings/openziti.gpg]
              https://packages.openziti.org/zitipax-openziti-deb-stable debian
              main
        - name: Refresh Repo Sources
          ansible.builtin.apt:
            update_cache: 'yes'
            cache_valid_time: 3600
    - name: Set up yum repo
      when: ansible_os_family == "RedHat"
      block:
        - name: Install OpenZiti repo rpm source
          ansible.builtin.yum_repository:
            name: OpenZitiRelease
            description: OpenZiti Release
            baseurl: >-
              https://packages.openziti.org/zitipax-openziti-rpm-stable/redhat/$basearch
            enabled: 'yes'
            gpgkey: >-
              https://packages.openziti.org/zitipax-openziti-rpm-stable/redhat/$basearch/repodata/repomd.xml.key
            repo_gpgcheck: 'yes'
            gpgcheck: 'no'

- name: Install zrok-share package
  gather_facts: false
  hosts: all 
  become: true
  tasks:
  - name: Install zrok-share
    ansible.builtin.package:
      name: zrok-share
      state: present

  - name: Copy env config from Ansible controller to target
    copy:
      dest: /opt/openziti/etc/zrok/zrok-share.env
      src: /opt/openziti/etc/zrok/zrok-share.env

  - name: Enable and restart service
    systemd:
      name: zrok-share
      enabled: yes
      state: restarted
      daemon_reload: yes

  - name: Wait for service
    systemd:
      name: zrok-share
      state: started
    register: service_status
    until: service_status.status.ActiveState == 'active'
    retries: 30
    delay: 1

Enable​

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

/opt/openziti/etc/zrok/zrok-share.env
ZROK_ENABLE_TOKEN="14cbfca9772f"

Name your Share​

This unique name becomes part of the domain name of the share, e.g. https://my-prod-app.in.zrok.io. A random name is generated if you don't specify one.

/opt/openziti/etc/zrok/zrok-share.env
ZROK_UNIQUE_NAME="my-prod-app"

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.

/opt/openziti/etc/zrok/zrok-share.env
ZROK_TARGET="http://127.0.0.1:3000"
ZROK_BACKEND_MODE="proxy"

If your HTTPS server has an unverifiable TLS server certificate then you must set --insecure.

/opt/openziti/etc/zrok/zrok-share.env
ZROK_INSECURE="--insecure"

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.

/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.

/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.

/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.

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.

/opt/openziti/etc/zrok/zrok-share.env
ZROK_OAUTH_PROVIDER="github"  # or google
ZROK_OAUTH_EMAILS="alice@example.com *@acme.example.com"

Password​

Enable HTTP basic authentication by adding the following to the configuration file.

/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.

run now and at startup
sudo systemctl enable --now zrok-share.service
run now
sudo systemctl restart zrok-share.service
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.

Concepts​

Overview of zrok reserved shares