What does `zrok frontdoor` actually do differently from a regular share?

zrok
1

Hi all!

I'm confused about what the difference is between zrok frontdoor and just running a reserved http share that gets started by the zrok agent automatically and runs all the time. I've read all the documentation I can find, and I can see that frontdoor seems to do a couple of things:

  • That it is a "heavy-duty" front door to an app. But I see no description of what this actually means practically or technically.
  • That it can restrict access based on OAuth to Google or Github (vs. normal shares which afaik can only restrict access to private shares via zrok.io accounts?)
  • That it is packaged as a separate app/package/docker image
  • That is designed to be run by systemd on boot (vs. zrok agent which wants to run as a user unit, I believe, so will only be up while the user is logged in?)

Am I understanding this correctly? Am I missing key things, or misunderstanding any of the things I've said above?

Thanks!

2

Hi and welcome, @eletari .

You're correct. zrok frontdoor is a way of using zrok with NetFoundry's zrok.io service, which provides a robust frontend with automatic TLS for your public shares.

The zrok frontdoor guide needs a refresh to help with using the new zrok agent. I've been enjoying using it myself, so here's a quick overview.

  1. Set up the zrok agent as an always-on service with your Windows or Linux user account. Remember to run zrok enable with your zrok account token to create a zrok environment on the device owned by your login.
  2. After the agent is running (zrok agent status), optionally enroll the agent so you can control it remotely through the console.
  3. Create a public share with the console if you enabled "remoting," or run the commands locally if not remoting (zrok reserve public; zrok share reserved).
  4. Now your web thing has a strong front door!

Here's a Docker Compose sample I've been playing with on Linux based on the Docker guide. You have to set env var UID on some distributions to id -u. I don't know if this will work with Docker Desktop on Win/Mac because those use a virtual machine to provide the container runtime, so you'd have to confirm the bind volume path and permissions, if it's even possible to mount a Win/Mac host dir in the VM.

The main difference with using the agent this way is that it re-uses the zrok environment created by your login user instead of creating a separate zrok environment for the agent, but I plan to eventually document doing it both ways.

services:
  zrok-agent:
    image: docker.io/openziti/zrok
    restart: unless-stopped
    entrypoint: bash -c "rm -f /mnt/.zrok/agent.socket && exec \"$@\""
    command: -- zrok agent start
    user: "${UID}"
    volumes:
      - ${HOME}/.zrok:/home/ziggy/.zrok

Controlling access to public shares with Google or GitHub OAuth is a feature of zrok, and it's preconfigured for you when you use NetFoundry's zrok.io service. The usage hints for adding OAuth to a zrok public share are all the way at the bottom of this page: OAuth Public Frontend Configuration | zrok

Here's what we have available:

  • Linux
    • zrok-share.service - runs any one share backend as a system service with a separate, dedicated zrok environment (documented as "zrok frontdoor")
    • zrok-agent.service - runs many share backends as a user service, sharing the login user's zrok environment
  • Docker
    • zrok-share service - runs any one share backend as a Docker service with a separate, dedicated zrok environment
    • zrok-agent service - runs many share backends, sharing the login user's zrok environment
  • Windows
3

Got it, thanks! I was getting some "these docs seem out of date" vibes, sounds like it's basically all there in the main package at this point. Much appreciation for the answer!

1 Like