zrok Documentation

zrok is an open-source platform designed for secure internet sharing of local services and files. It enables sharing without opening firewall ports or managing TLS by leveraging OpenZiti zero-trust networking.

Key capabilities include:

• Public HTTPS shares: Share web services or static files publicly with optional authentication and reserved hostnames.
• Private shares: Share resources (including TCP and UDP services) that are accessible only to other zrok users via a share token and specific permission grants.
• Deployment options: Use the hosted service at myzrok.io or self-host on Linux, Docker, or Kubernetes.

zrok frontdoor allows you to make your website or app available to a public audience using managed frontends provided by zrok.io. It works by proxying incoming public web traffic to your zrok backend shares via OpenZiti.

To use this service, you must have a free account at zrok.io.

When sharing resources with zrok, you can select from several backend modes depending on your target service:

• proxy mode: Forwards requests received by the frontend directly to a target server (e.g., an existing web service).
• web mode: Serves a specific target folder as a static file index web page.
• drive mode: Serves a target folder using the WebDAV protocol, allowing it to be mounted as a network drive.
• caddy mode: Runs the built-in Caddy server using a specified Caddyfile for advanced proxying or server configurations.

zrok enforces usage limits on shares to manage resources. When a share exceeds its allocated limits, the controller performs the following actions:

1. Limiting: The controller identifies the share exceeding limits (e.g., limiting 's0uzz1p7xjrr') and removes its dial service policy via DeleteServicePolicy. This effectively stops new connections to that share.
2. Warning: The system may trigger a warning (e.g., warning '7u9szn30ikh0') and send a limit warning email to the associated user.
3. Relaxing: Once usage falls back within acceptable parameters, the controller performs a relax action, recreating the dial service policy (e.g., created dial service policy '...') to restore access.

If a share remains over the limit during a relaxation attempt, the controller will log that the share is still over limit and will not restore access until usage decreases.

The zrok deployment on Docker Compose consists of several interconnected services that manage the control plane, data plane, and public sharing.

Core Services:

• ziti-controller: OpenZiti control plane (manages PKI, etc.).
• ziti-router: OpenZiti data plane (handles SDK traffic).
• postgresql: The zrok2 database.
• rabbitmq: Provides AMQP for frontend mapping updates.
• zrok2-init: A one-shot bootstrap service.
• zrok2-controller: Provides the zrok2 API and administrative functions.
• zrok2-frontend: Acts as the public share proxy.

Optional Services:

• caddy: Handles TLS termination.
• influxdb: Used for metrics storage.
• zrok2-metrics-bridge: Manages the metrics pipeline.

The zrok agent in v2.0 includes several enhancements:

• Automatic Retry: The agent automatically retries failed shares using exponential backoff. Errored processes receive transient err_XXXX tokens.
• Persistence: Shares using reserved names or private shares with --share-token will automatically restart after an abnormal exit or an agent restart.
• Improved Status: zrok2 agent status provides detailed error states, frontend endpoints for public shares, and specific failure messages.

Public Shares

When using zrok share public on a hosted instance (like zrok.io), the service operators have visibility into traffic, including logs of accessed URLs and headers maintained by the service's load balancers.

Private Shares

When you create private shares (using zrok share private, zrok reserve, or zrok share reserved) and access them via zrok access private on your own infrastructure, the service operators only see that data is moving between the environments. They do not have visibility into the specific URLs, headers, or content of the traffic.

zrok provides four distinct modes for handling HTTP/HTTPS content. Choose the mode based on whether you want to proxy an existing server, serve static files, expose a network drive, or use a custom Caddy configuration:

• proxy: Forwards incoming requests to a target HTTP/HTTPS server running on your machine.
• web: Serves a local directory as a browsable file index or a static website.
• drive: Exposes a local directory over WebDAV, allowing it to be mounted as a network drive.
• caddy: Runs the built-in Caddy server using a Caddyfile that you provide.

In zrok v2.0, persistent shares are managed through a hierarchy of namespaces and names.

• Namespaces: Logical containers for names (similar to DNS zones). They can be Open (accessible to all users) or Closed (requiring explicit grants).
• Names: Unique identifiers within a namespace.
  • Reserved names: Persistent across multiple runs of zrok2 share.
  • Ephemeral names: Temporary and deleted when the share terminates.

Example: A name api in the public namespace results in a share accessible at https://api.share.zrok.io.

Starting in v0.3, zrok supports two primary sharing modes:

• Public Sharing: Allows any configured frontend instances to send traffic to a backend. The zrok CLI defaults to selecting public frontend instances. This mode is suitable for internet-facing services where you want to leverage high-capacity, multi-tenant frontend fleets (e.g., *.share.zrok.io).
• Private Sharing: Access is restricted. zrok does not create policies for a service until a specific request for a frontend binding is made using the zrok access command. Private sharing supports both identified users (with a provisioned environment) and ephemeral users (where the controller creates a single-use environment).

zrok provides several modes for handling backend HTTP requests depending on your sharing goal:

• proxy mode: Forwards requests received by the frontend directly to the target server.
• web mode: Serves a target folder as a file index web page.
• drive mode: Serves a target folder using the WebDAV protocol.
• caddy mode: Runs the built-in Caddy server using a specified Caddyfile.