zrok

https://netfoundry.io/docs/zrok/
Admin
zrok is an open-source sharing platform that enables sharing local services and files securely over...
Tokens:41,581
Snippets:645
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start and verify frontend

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Commands to enable the frontend service and monitor its logs.

```bash
sudo systemctl enable --now zrok2-frontend  
```

```bash
sudo journalctl -u zrok2-frontend -f  
```

--------------------------------

### Start Public Frontend

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/error-pages

Launch the public frontend using the path to your configuration file.

```bash
zrok2 access public /path/to/frontend-config.yml
```

--------------------------------

### Open nssm configuration

Source: https://netfoundry.io/docs/zrok/how-tos/agent/windows-service

Launch the nssm GUI to install the zrokAgent service.

```batch
C:\Program Files\zrok2>nssm install zrokAgent  
```

--------------------------------

### Start the dynamicProxy frontend

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

Execute the dynamicProxy frontend using the specified configuration file.

```bash
zrok2 access dynamicProxy etc/dynamicProxy.yml  
```

--------------------------------

### Start and verify Docker agent

Source: https://netfoundry.io/docs/zrok/how-tos/agent/run-docker-agent

Commands to start the containerized agent and check its logs.

```bash
docker compose up -d
```

```bash
docker compose logs zrok-agent
```

--------------------------------

### Install RabbitMQ and PostgreSQL

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Commands to install core database and messaging services on Debian/Ubuntu or RHEL/Fedora systems.

```bash
sudo apt install rabbitmq-server postgresql
```

```bash
sudo dnf install rabbitmq-server postgresql-server

sudo postgresql-setup --initdb   # RHEL/Fedora only
```

--------------------------------

### Install zrok2-agent via one-liner

Source: https://netfoundry.io/docs/zrok/how-tos/agent/setup-linux-service

Use this command to set up the repository and install the agent package in a single step.

```bash
curl -sSLf https://get.openziti.io/install.bash \
| sudo bash -s zrok2-agent
```

--------------------------------

### Example account token output

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

The token returned after successfully creating an account.

```text
SuGzRPjVDIcF
```

--------------------------------

### Start the systemd service

Source: https://netfoundry.io/docs/zrok/how-tos/agent/setup-linux-service

Enable and start the agent service to ensure it runs automatically upon user login.

```bash
systemctl --user enable --now zrok2-agent.service
```

--------------------------------

### Install RabbitMQ on Ubuntu/Debian

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

Install and enable the RabbitMQ server service on Debian-based systems.

```bash
sudo apt-get install rabbitmq-server
sudo systemctl enable rabbitmq-server
sudo systemctl start rabbitmq-server
```

--------------------------------

### Install service via CLI

Source: https://netfoundry.io/docs/zrok/how-tos/agent/windows-service

Create the zrokAgent service using the nssm command-line interface.

```batch
C:\Program Files\zrok2>nssm install zrokAgent "C:\Program Files\zrok2\zrok2.exe" agent start  
```

--------------------------------

### Start the Agent

Source: https://netfoundry.io/docs/zrok/how-tos/agent/run-docker-agent

Command to initialize and start the zrok agent services in the background.

```bash
docker compose up -d  
```

--------------------------------

### Create and verify a test share

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

Commands to enable the environment, configure the namespace, and share a resource to test the proxy setup.

```bash
# First, enable a zrok environment if you haven't already  

zrok2 enable <accountToken>  

  

# Set the default namespace for convenience  

zrok2 config set defaultNamespace <namespaceToken>  

  

# Create a reserved name in the namespace  

zrok2 create name -n <namespaceToken> my-test-share  

  

# Share a resource using the reserved name  

zrok2 share public --backend-mode web -n <namespaceToken>:my-test-share ~/public  
```

--------------------------------

### Install RabbitMQ on RHEL/CentOS/Fedora

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

Install and enable the RabbitMQ server service on RHEL-based systems.

```bash
sudo dnf install rabbitmq-server
sudo systemctl enable rabbitmq-server
sudo systemctl start rabbitmq-server
```

--------------------------------

### Verify zrok installation

Source: https://netfoundry.io/docs/zrok/how-tos/install/macos

Check the installed version of zrok to confirm successful setup.

```bash
zrok2 version
```

--------------------------------

### Deploy with Caddy overlay

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/docker

Start the Docker Compose stack including the Caddy configuration file.

```bash
COMPOSE_FILE=compose.yml:compose.caddy.yml docker compose up -d
```

--------------------------------

### Start service via sc

Source: https://netfoundry.io/docs/zrok/how-tos/agent/windows-service

Start the configured service using the Windows Service Control manager.

```batch
C:\Program Files\zrok2>sc start zrokAgent  
```

--------------------------------

### Automated installation script

Source: https://netfoundry.io/docs/zrok/how-tos/install/linux

Automatically detect architecture and install zrok2 to /usr/local/bin/ using sudo.

```bash
cd $(mktemp -d);  

ZROK_VERSION=$(  
  curl -sSf https://api.github.com/repos/openziti/zrok/releases/latest \
  | jq -r '.tag_name'  
);

case $(uname -m) in  
  x86_64)         GOXARCH=amd64  
  ;;
  aarch64|arm64)  GOXARCH=arm64  
  ;;
  arm*)           GOXARCH=armv7  
  ;;
  *)              echo "ERROR: unknown arch '$(uname -m)'" >&2  
                  exit 1  
  ;;
esac;

curl -sSfL \
  "https://github.com/openziti/zrok/releases/download/${ZROK_VERSION}/zrok2_${ZROK_VERSION#v}_linux_${GOXARCH}.tar.gz" \
  | tar -xz -f -;

sudo install -o root -g root ./zrok2 /usr/local/bin/;

zrok2 version;
```

--------------------------------

### Initialize InfluxDB

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Command to perform the initial setup of InfluxDB, including organization and bucket creation.

```bash
influx setup \
  --org zrok \
  --bucket zrok \
  --username admin \
  --password "$(head -c24 /dev/urandom | base64 -w0)" \
  --token "<your-influx-token>" \
  --retention 0 \
  --force
```

--------------------------------

### Navigate to installation directory

Source: https://netfoundry.io/docs/zrok/how-tos/agent/windows-service

Change the working directory to the location of the zrok2 and nssm executables.

```batch
cd "\Program Files\zrok2"  
```

--------------------------------

### Ansible playbook for zrok installation

Source: https://netfoundry.io/docs/zrok/how-tos/install/linux

Use this YAML playbook to automate the setup of package repositories and installation of zrok2 across multiple hosts.

```yaml
- 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 zrok2 package  
gather_facts: false  
hosts: all  
become: true  
tasks:  
- name: Install zrok2  
  ansible.builtin.package:  
    name: zrok2  
    state: present
```

--------------------------------

### Example index.html content

Source: https://netfoundry.io/docs/zrok/how-tos/shares/share-websites-and-files

Basic HTML content that triggers static website serving mode.

```html
<html>  

<body>  

        <h1>Hello <code>zrok</code></h1>  

</html>  

```

--------------------------------

### Install the zrok2 executable

Source: https://netfoundry.io/docs/zrok/how-tos/install/macos

Move the extracted binary to the local user bin directory.

```bash
mkdir -p ~/bin && install /tmp/zrok2/zrok2 ~/bin/
```

--------------------------------

### Start zrok2 controller service

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Command to enable and start the zrok2 controller systemd service.

```bash
sudo systemctl enable --now zrok2-controller
```

--------------------------------

### Example static website directory structure

Source: https://netfoundry.io/docs/zrok/how-tos/shares/share-websites-and-files

A sample directory listing containing an index.html file, which zrok will serve as a static website.

```text
-rw-rw-r--+ 1 Michael None 56 Jun 26 13:23 index.html  

```

--------------------------------

### Start a local test endpoint

Source: https://netfoundry.io/docs/zrok/get-started/create-share

Initializes a simple HTTP listener on port 9090 to serve as a target for zrok sharing.

```bash
zrok2 test endpoint  
```

--------------------------------

### Start RabbitMQ Container

Source: https://netfoundry.io/docs/zrok/self-hosting/metrics-and-limits/configure-metrics

Run the RabbitMQ management container to serve as the AMQP implementation.

```bash
docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3.11-management  
```

--------------------------------

### Install zrok2-agent package

Source: https://netfoundry.io/docs/zrok/how-tos/agent/setup-linux-service

Install the agent package using the system's native package manager if the repository is already configured.

```bash
sudo apt install zrok2-agent
```

```bash
sudo dnf install zrok2-agent
```

--------------------------------

### Start zrok Metrics Bridge

Source: https://netfoundry.io/docs/zrok/self-hosting/metrics-and-limits/configure-metrics

Execute the metrics bridge process using the zrok controller configuration file.

```bash
zrok2 controller metrics bridge <path/to/zrok-controller.yaml>  
```

--------------------------------

### Scenario 3: Ephemeral shares

Source: https://netfoundry.io/docs/zrok/how-tos/migration/migrate-v1-to-v2

Example of an ephemeral share command that remains compatible with v2.0.

```bash
# v1.x - still works in v2.0  

$ zrok2 share public :8080
```

--------------------------------

### Install zrok2 binary

Source: https://netfoundry.io/docs/zrok/how-tos/install/windows

Create a bin directory, extract the zrok2 executable from the downloaded tarball, and add the directory to the user's PATH environment variable.

```powershell
$binDir = Join-Path -Path $env:USERPROFILE -ChildPath "bin"

New-Item -Path $binDir -ItemType Directory -ErrorAction SilentlyContinue

$latest = Get-ChildItem -Path .\zrok*windows*.tar.gz | Sort-Object LastWriteTime | Select-Object -Last 1

tar -xf $latest.FullName -C $binDir zrok2.exe

$currentPath = [System.Environment]::GetEnvironmentVariable('PATH', [System.EnvironmentVariableTarget]::User)

if ($currentPath -notlike "*$binDir*") {

    $newPath = "$currentPath;$binDir"

    [System.Environment]::SetEnvironmentVariable('PATH', $newPath, [System.EnvironmentVariableTarget]::User)

    $env:Path = $newPath

}
```

--------------------------------

### Manage the systemd service

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

Commands to enable, start, and check the status of the zrok-dynamicproxy service.

```bash
sudo systemctl enable zrok-dynamicproxy  

sudo systemctl start zrok-dynamicproxy  

sudo systemctl status zrok-dynamicproxy  
```

--------------------------------

### Configure Ingress with Traefik and cert-manager

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/kubernetes

Example values configuration for enabling controller and frontend ingress using Traefik and cert-manager.

```yaml
controller:
  ingress:
    enabled: true
    className: traefik
    hosts:
      - zrok2.share.example.com
    tls:
      - secretName: zrok2-api-tls
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt-dns

frontend:
  ingress:
    enabled: true
    className: traefik
    tls:
      - secretName: zrok2-wildcard-tls
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt-dns
```

--------------------------------

### Verify environment status

Source: https://netfoundry.io/docs/zrok/get-started/enable-env

Displays the current configuration and environment status to confirm successful setup.

```bash
zrok2 status
```

--------------------------------

### Install RabbitMQ via Docker

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

Run a RabbitMQ container with management UI enabled for testing purposes.

```bash
docker run -d --name rabbitmq \
  -p 5672:5672 \
  -p 15672:15672 \
  rabbitmq:3-management
```

--------------------------------

### Start and verify metrics bridge

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Commands to enable the metrics bridge service and monitor its logs.

```bash
sudo systemctl enable --now zrok2-metrics-bridge  
```

```bash
sudo journalctl -u zrok2-metrics-bridge -f  
```

--------------------------------

### Insert unscoped bandwidth class

Source: https://netfoundry.io/docs/zrok/self-hosting/metrics-and-limits/limits

Example SQL to create a limit class that overrides default bandwidth values.

```sql
insert into limit_classes (period_minutes, total_bytes, limit_action) values (2, 204800, 'limit');  
```

--------------------------------

### Install zrok2 via Helm

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/kubernetes

Deploys the zrok2 chart into a dedicated namespace with custom values and admin password.

```bash
helm install zrok2 openziti/zrok2 \
  --namespace zrok2 --create-namespace \
  --values my-values.yaml \
  --set ziti.password="your-ziti-admin-password"
```

--------------------------------

### Configure Private Access Template

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/error-pages

Use the --template-path flag when starting a private access frontend to specify a custom HTML file.

```bash
zrok2 access private --template-path /path/to/custom-template.html <shareToken>
```

--------------------------------

### Start the zrok agent in the foreground

Source: https://netfoundry.io/docs/zrok/get-started/set-up-agent

Initializes the zrok agent process in the current terminal session.

```bash
zrok2 agent start
```

--------------------------------

### Complete dynamicProxy YAML configuration

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

A full example of the dynamic proxy configuration file including all optional settings like TLS, interstitial pages, and multiple OAuth providers.

```yaml
v: 1  

  

# Frontend identification  

frontend_token: KMmfE0VXO7Pp  

identity: public  

bind_address: "0.0.0.0:8080"  

  

# Mapping refresh interval  

mapping_refresh_interval: 1m  

  

# AMQP subscriber for receiving mapping updates  

amqp_subscriber:  

  url: amqp://guest:guest@localhost:5672  

  exchange_name: dynamicProxy  

  queue_depth: 1024  # Optional: buffer size for mapping updates (default: 1024)  

  

# Controller client for gRPC queries  

controller:  

  identity_path: /home/zrok/.zrok2/identities/public.json  

  service_name: dynamicProxyController  

  timeout: 30s  # Optional: gRPC request timeout (default: 30s)  

  

# Optional: TLS configuration for HTTPS  

tls:  

  cert_path: /etc/letsencrypt/live/zrok.example.com/fullchain.pem  

  key_path: /etc/letsencrypt/live/zrok.example.com/privkey.pem  

  

# Optional: Interstitial page configuration  

interstitial:  

  enabled: true  

  html_path: /etc/zrok/interstitial.html  

  user_agent_prefixes:  

    - "Mozilla/"  

    - "Chrome/"  

  

# Optional: OAuth configuration  

oauth:  

  bind_address: "127.0.0.1:8181"  

  endpoint_url: "https://oauth.zrok.example.com:8443"  

  cookie_name: "zrok-auth-session"  

  cookie_domain: "zrok.example.com"  

  max_cookie_chunks: 10  # Optional: maximum cookie stripes to accept or emit (default: 10)  

  session_lifetime: "6h"  

  intermediate_lifetime: "5m"  

  signing_key: "your-32-plus-character-signing-key-here"  

  encryption_key: "your-24-plus-character-encryption-key-here"  

  max_cookie_size: 3072  # Optional: maximum cookie size in bytes (default: 3072)  

  

  providers:  

    # Google OAuth  

    - name: "google"  

      type: "google"  

      client_id: "your-google-client-id"  

      client_secret: "your-google-client-secret"  

  

    # GitHub OAuth  

    - name: "github"  

      type: "github"  

      client_id: "your-github-client-id"  

      client_secret: "your-github-client-secret"  

  

    # Generic OIDC  

    - name: "microsoft"  

      type: "oidc"  

      client_id: "your-oidc-client-id"  

      client_secret: "your-oidc-client-secret"  

      scopes: ["openid", "email", "profile"]  

      issuer: "https://login.microsoftonline.com/<tenant-id>/v2.0"  

      supports_pkce: true
```

--------------------------------

### Example file directory structure

Source: https://netfoundry.io/docs/zrok/how-tos/shares/share-websites-and-files

A sample directory listing containing files without an index.html, which zrok will serve as a browsable file tree.

```text
-rw-r--r--+ 1 Michael None     7090 Apr 17 12:53 CHANGELOG.md  

-rw-r--r--+ 1 Michael None    11346 Apr 17 12:53 LICENSE  

-rw-r--r--+ 1 Michael None     2885 Apr 17 12:53 README.md  

-rwxr-xr-x+ 1 Michael None 44250624 Apr 17 13:00 zrok.exe*  


```

--------------------------------

### Configure applications for SOCKS5 proxy

Source: https://netfoundry.io/docs/zrok/how-tos/shares/socks-proxy-mode

Examples for routing traffic through the local SOCKS5 proxy at 127.0.0.1:1080.

```bash
curl --socks5-hostname 127.0.0.1:1080 http://internal-server:8080/api
```

```bash
ssh -o ProxyCommand='nc -x 127.0.0.1:1080 %h %p' user@internal-host
```

--------------------------------

### Enable metrics profile

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/docker

Starts the zrok instance with the metrics profile enabled to include InfluxDB and the metrics bridge.

```bash
docker compose --profile metrics up -d
```

--------------------------------

### Share a local HTTP service publicly

Source: https://netfoundry.io/docs/zrok/how-tos/shares/share-http-proxy

Starts a public share for a local service running on the specified port.

```bash
zrok2 share public 8080
```

--------------------------------

### Create a public proxy share

Source: https://netfoundry.io/docs/zrok/concepts/public-shares

Starts a public share that forwards incoming requests to a local HTTP service on port 80.

```bash
zrok2 share public 80
```

--------------------------------

### Install zrok via shell script

Source: https://netfoundry.io/docs/zrok/how-tos/install/linux

Use this command to install zrok2 on a single Linux machine via the official installation script.

```bash
curl -sSf https://get.openziti.io/install.bash | sudo bash -s zrok2
```

--------------------------------

### Initialize and build from repository

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/docker

Clones the repository and performs an initial build of the zrok instance.

```bash
git clone https://github.com/openziti/zrok.git
cd zrok/docker/compose/zrok2-instance
cp .env.example .env
# edit .env with your values...
COMPOSE_FILE=compose.yml:compose.build.yml docker compose up -d --build --wait
```

--------------------------------

### Install InfluxDB

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Commands to add the InfluxData repository and install InfluxDB on Linux distributions.

```bash
curl -fsSL https://repos.influxdata.com/influxdata-archive.key \
  | sudo gpg --dearmor -o /usr/share/keyrings/influxdata-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/influxdata-archive-keyring.gpg] https://repos.influxdata.com/debian stable main" \
  | sudo tee /etc/apt/sources.list.d/influxdata.list

sudo apt update && sudo apt install influxdb2
```

```bash
cat <<'EOF' | sudo tee /etc/yum.repos.d/influxdata.repo
[influxdata]
name = InfluxData Repository - Stable
baseurl = https://repos.influxdata.com/stable/$basearch/main
enabled = 1
gpgcheck = 1
gpgkey = https://repos.influxdata.com/influxdata-archive_compat.key
EOF

sudo dnf install influxdb2
```

--------------------------------

### Share a local HTTP service in headless mode

Source: https://netfoundry.io/docs/zrok/how-tos/shares/share-http-proxy

Starts a public share without the interactive terminal UI, outputting logs to stdout instead.

```bash
zrok2 share public --headless 8080
```

--------------------------------

### Insert unscoped resource count class

Source: https://netfoundry.io/docs/zrok/self-hosting/metrics-and-limits/limits

Example SQL to create a limit class that overrides default resource count values.

```sql
insert into limit_classes (environments, shares, reserved_shares, unique_names, share_frontends) values (1, 1, 1, 1, 1);  
```

--------------------------------

### Initialize environment configuration

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/docker

Copy the template environment file to create a local configuration file.

```bash
cp .env.example .env  
```

--------------------------------

### Enable zrok account

Source: https://netfoundry.io/docs/zrok/how-tos/agent/setup-linux-service

Initialize the zrok environment by providing your account token.

```bash
zrok2 enable <your_account_token>
```

--------------------------------

### Create an organization

Source: https://netfoundry.io/docs/zrok/self-hosting/user-management/organizations

View help for creating an organization or create one with a description.

```bash
zrok2 admin create organization --help
```

```bash
zrok2 admin create organization -d "documentation"
```

--------------------------------

### Configure Environment Variables

Source: https://netfoundry.io/docs/zrok/how-tos/agent/run-docker-agent

Create a .env file to provide the required account token and optional configuration overrides.

```text
ZROK2_ENABLE_TOKEN=<your_account_token>  

# ZROK2_API_ENDPOINT=https://zrok.example.com  # uncomment for self-hosted  

# ZROK2_AGENT_CONSOLE_PORT=8888                # agent web console port  
```

--------------------------------

### Install zrok2 packages on Debian/Ubuntu

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Install the necessary zrok2 components using the apt package manager.

```bash
sudo apt install zrok2 zrok2-controller zrok2-frontend zrok2-metrics-bridge
```

--------------------------------

### Unarchive the zrok distribution

Source: https://netfoundry.io/docs/zrok/how-tos/install/macos

Extract the downloaded tarball into a temporary directory for installation.

```bash
cd ~/Downloads && mkdir -p /tmp/zrok2 && tar -xf ./zrok*darwin*.tar.gz -C /tmp/zrok2
```

--------------------------------

### Enable zrok environment

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Configures the CLI to point to the instance and enables the environment using an account token.

```bash
zrok2 config set apiEndpoint https://zrok.example.com

zrok2 enable <account-token>
```

--------------------------------

### Create a frontend with a specific identity

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/scaling-frontends

Command to register a dynamic frontend using a dedicated OpenZiti identity ID.

```bash
zrok2 admin create frontend --dynamic -- <public-2-ziti-id> frontend-2
```

--------------------------------

### Enable and Configure Services

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Commands to enable system services and restrict RabbitMQ to localhost for security.

```bash
sudo systemctl enable --now rabbitmq-server postgresql influxdb
```

```bash
NODE_IP_ADDRESS=127.0.0.1
SERVER_ADDITIONAL_ERL_ARGS="-kernel inet_dist_use_interface {127,0,0,1}"
```

```bash
sudo systemctl restart rabbitmq-server
```

--------------------------------

### Enable zrok environment

Source: https://netfoundry.io/docs/zrok/how-tos/agent/windows-service

Initialize the zrok environment for the service user.

```batch
C:\Program Files\zrok2>zrok2 enable <accountToken>  
```

--------------------------------

### Download zrok2 instance files

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/docker

Use these commands to fetch the pre-configured Docker Compose project files or clone the repository for a source-based build.

```bash
curl -sSfL https://get.openziti.io/zrok2-instance/fetch.bash | bash  

cd zrok2-instance  
```

```bash
git clone --depth 1 https://github.com/openziti/zrok.git  

cd zrok/docker/compose/zrok2-instance  
```

--------------------------------

### Create a local directory for sharing

Source: https://netfoundry.io/docs/zrok/how-tos/shares/share-sync-drives

Prepare a local directory to be shared via zrok.

```bash
mkdir /tmp/junk  
```

--------------------------------

### Enable Client Environment

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/kubernetes

Configures the local zrok2 CLI to communicate with the self-hosted instance.

```bash
export ZROK2_API_ENDPOINT=https://zrok2.share.example.com
zrok2 enable <token>
```

--------------------------------

### Configure PostgreSQL Database

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Commands to create the zrok database and user.

```bash
sudo -u postgres psql -c "CREATE USER zrok2 WITH PASSWORD '<your-db-password>';"
sudo -u postgres psql -c "CREATE DATABASE zrok2 OWNER zrok2;"
```

--------------------------------

### Verify Metrics Logs

Source: https://netfoundry.io/docs/zrok/self-hosting/metrics-and-limits/configure-metrics

Example of expected controller log output when metrics are successfully processed.

```text
[5339.658]    INFO zrok/controller/metrics.(*influxWriter).Handle: share: 736z80mr4syu, circuit: Ad1V-6y48 backend {rx: 4.5 kB, tx: 4.6 kB} frontend {rx: 4.6 kB, tx: 4.5 kB}  

[5349.652]    INFO zrok/controller/metrics.(*influxWriter).Handle: share: 736z80mr4syu, circuit: Ad1V-6y48 backend {rx: 2.5 kB, tx: 2.6 kB} frontend {rx: 2.6 kB, tx: 2.5 kB}  

[5354.657]    INFO zrok/controller/metrics.(*influxWriter).Handle: share: 5a4u7lqxb7pa, circuit: iG1--6H4S backend {rx: 13.2 kB, tx: 13.3 kB} frontend {rx: 13.3 kB, tx: 13.2 kB}  
```

--------------------------------

### Initiate self-service invitation via CLI

Source: https://netfoundry.io/docs/zrok/self-hosting/user-management/self-service-invite

Users execute this command to begin the self-service account creation process.

```bash
zrok2 invite
```

--------------------------------

### Create a dynamic frontend

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

Register a new frontend with the dynamic flag enabled to support dynamicProxy.

```bash
zrok2 admin create frontend --dynamic -- <public-ziti-id> public
```

--------------------------------

### Build zrok from source

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/docker

Uses the build overlay to compile zrok services from source instead of using pre-built images.

```bash
COMPOSE_FILE=compose.yml:compose.build.yml docker compose up -d --build --wait
```

--------------------------------

### Scenario 1: Simple reserved public share migration

Source: https://netfoundry.io/docs/zrok/how-tos/migration/migrate-v1-to-v2

Comparison of v1.x and v2.0 workflows for reserved public shares.

```bash
# create a reserved share  

$ zrok reserve public --backend-mode web /var/www/mysite  

your reserved share token is 'abc123xyz'  

reserved frontend endpoint: https://abc123xyz.share.zrok.io  

  

# start sharing  

$ zrok share reserved abc123xyz  

  

# later, release it  

$ zrok release abc123xyz
```

```bash
# first, check available namespaces  

$ zrok2 list namespaces  

╭───────────────────────┬─────────────────┬─────────────╮  

│ NAME                  │ NAMESPACE TOKEN │ DESCRIPTION │  

├───────────────────────┼─────────────────┼─────────────┤  

│ example.com           │ public          │             │  

╰───────────────────────┴─────────────────┴─────────────╯  

  

# create a reserved name in the 'public' namespace  

$ zrok2 create name -n public api  

  

# start sharing using the name selection  

$ zrok2 share public localhost:8080 -n public:api  

  

# the name persists across share restarts  

$ zrok2 share public localhost:8080 -n public:api  

  

# when done, delete the name  

$ zrok2 delete name -n public api
```

--------------------------------

### Insert scoped limit class

Source: https://netfoundry.io/docs/zrok/self-hosting/metrics-and-limits/limits

Example SQL to create a limit class for a specific backend mode.

```sql
insert into limit_classes (backend_mode, shares, reserved_shares, unique_names, period_minutes, total_bytes, limit_action) values ('web', 2, 1, 1, 2, 4096000, 'limit');  
```

--------------------------------

### Common OIDC provider issuer URLs

Source: https://netfoundry.io/docs/zrok/self-hosting/oauth/integrations/oidc

Example issuer URLs for popular OIDC identity providers.

```yaml
issuer: "https://your-keycloak.com/realms/your-realm"  
```

```yaml
issuer: "https://your-domain.auth0.com/"  
```

```yaml
issuer: "https://login.microsoftonline.com/<tenant-id>/v2.0"  
```

```yaml
issuer: "https://your-domain.okta.com/oauth2/default"  
```

--------------------------------

### View environment overview

Source: https://netfoundry.io/docs/zrok/how-tos/migration/migrate-v1-to-v2

Provides a summary of your environment, with options for human-readable or JSON output.

```bash
$ zrok2 overview  
# shows human-readable format with names and namespaces  
  
# for json output  
$ zrok2 overview --json
```

--------------------------------

### Create a directory on a virtual drive

Source: https://netfoundry.io/docs/zrok/how-tos/shares/share-sync-drives

Organize files by creating a new directory within the virtual drive.

```bash
zrok2 mkdir zrok://wkcfb58vj51l/stuff  
```

--------------------------------

### Create an account via CLI

Source: https://netfoundry.io/docs/zrok/get-started/get-token

Use this command on a self-hosted zrok instance to create a new account as an administrator.

```bash
zrok2 admin create account <username> <password>
```

--------------------------------

### Create Namespaces

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

Commands to initialize open or closed namespaces for user resource management.

```bash
# Open namespace - users can freely create names  

zrok2 admin create namespace public "Public Shares" -o  

  

# Closed namespace - requires explicit grants  

zrok2 admin create namespace private "Private Shares"
```

--------------------------------

### Combine build and Caddy overlays

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/docker

Deploys the zrok instance using both the build and Caddy configuration overlays.

```bash
COMPOSE_FILE=compose.yml:compose.build.yml:compose.caddy.yml \
  docker compose up -d --build --wait
```

--------------------------------

### GET /<providerName>/logout

Source: https://netfoundry.io/docs/zrok/self-hosting/oauth/oauth-public-frontend

Terminates the user's authenticated session by revoking the OAuth token and clearing the local session cookie.

```APIDOC
## GET /<providerName>/logout

### Description
Terminates an authenticated session for a specific OAuth provider. This process revokes the access token with the provider and clears the local session cookie.

### Method
GET

### Endpoint
/<providerName>/logout

### Parameters
#### Path Parameters
- **providerName** (string) - Required - The name of the configured OAuth provider (e.g., google, github).

#### Query Parameters
- **redirect_url** (string) - Optional - A custom URL to redirect the user to after the logout process completes. If not provided, the user is redirected to the provider's login page.

### Request Example
GET https://oauth.your-domain.com/google/logout?redirect_url=https://example.com/goodbye
```

--------------------------------

### Execute the bootstrap script

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Run the automated deployment script with elevated privileges using the previously set environment variables.

```bash
sudo -E /usr/share/zrok/nfpm/zrok2-bootstrap.bash
```

--------------------------------

### Map frontends to a namespace

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/scaling-frontends

Commands to associate newly created frontend tokens with a specific public namespace.

```bash
zrok2 admin create namespace-frontend public <frontend-2-token>

zrok2 admin create namespace-frontend public <frontend-3-token>
```

--------------------------------

### Monitor initialization logs

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/docker

Follows the logs of the zrok2-init container to track the bootstrap process.

```bash
docker compose logs -f zrok2-init  
```

--------------------------------

### Configure Ziti Service and Routing Policies

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Automates the creation of the Ziti service and associated binding/dialing policies for the dynamic proxy controller.

```bash
CONTROLLER_ZID=$(ziti edge list identities 'name="dynamicProxyController"' -j \
  | jq -r '.data[0].id')
SERVICE_NAME="dynamicProxyController"

ziti edge create service "$SERVICE_NAME"

ziti edge create serp "${SERVICE_NAME}-serp" \
  --edge-router-roles '#all' \
  --service-roles "@${SERVICE_NAME}"

ziti edge create sp "${SERVICE_NAME}-bind" Bind \
  --identity-roles "@${CONTROLLER_ZID}" \
  --service-roles "@${SERVICE_NAME}"

ziti edge create sp "${SERVICE_NAME}-dial" Dial \
  --identity-roles "@public" \
  --service-roles "@${SERVICE_NAME}"
```

--------------------------------

### Configure Ziti Service and Policies

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

Set up the Ziti service, edge router policies, and bind/dial policies for the controller.

```bash
# Set variables for convenience
CONTROLLER_ZID="<ziti-id-from-step-1>"
SERVICE_NAME="dynamicProxyController"

# Create the service
ziti edge create service "$SERVICE_NAME"

# Create Service Edge Router Policy (allows edge routers to see the service)
ziti edge create serp "${SERVICE_NAME}-serp" \
  --edge-router-roles '#all' \
  --service-roles "@${SERVICE_NAME}"

# Create Service Policy for Bind (allows controller identity to bind the service)
ziti edge create sp "${SERVICE_NAME}-bind" Bind \
  --identity-roles "@${CONTROLLER_ZID}" \
  --service-roles "@${SERVICE_NAME}"

# Create Service Policy for Dial (allows frontend to dial the service)
# Note: Replace 'public' with your frontend identity name if different
ziti edge create sp "${SERVICE_NAME}-dial" Dial \
  --identity-roles "@public" \
  --service-roles "@${SERVICE_NAME}"
```

--------------------------------

### Scale frontends with Docker Compose and Caddy

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/scaling-frontends

Configure a scalable frontend service and a Caddy reverse proxy to handle ingress and load balancing via Docker DNS.

```yaml
services:  

  zrok2-frontend:  

    image: openziti/zrok2:latest  

    command: ["access", "public", "/config/frontend.yaml"]  

    deploy:  

      replicas: 3  

    volumes:  

      - zrok2-config:/config:ro  

    # No ports: — Caddy handles ingress  

  

  caddy:  

    image: caddy:2-alpine  

    ports:  

      - "0.0.0.0:443:443"  

    command: caddy reverse-proxy --from :443 --to zrok2-frontend:8080  


```

--------------------------------

### Map namespace to multiple frontends

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

Commands to register a namespace to multiple frontend tokens for high availability.

```bash
zrok2 admin create namespace-frontend <namespaceToken> <frontendToken1>  

zrok2 admin create namesapce-frontend <namespaceToken> <frontendToken2>
```

--------------------------------

### Create a private SOCKS share

Source: https://netfoundry.io/docs/zrok/how-tos/shares/socks-proxy-mode

Run this command on the remote machine to initialize the SOCKS5 proxy share.

```bash
zrok2 share private --backend-mode socks
```

--------------------------------

### List namespace and frontend mappings

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

View existing associations between namespaces and frontends.

```bash
# List frontends for a namespace  

zrok2 admin list namespaceFrontendMappings <namespaceToken>  

  

# List namespaces for a frontend  

zrok2 admin list frontendNamespaceMappings <frontendToken>
```

--------------------------------

### List Namespaces

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

Commands to view available namespaces for users or administrators.

```bash
zrok2 list namespaces
```

```bash
zrok2 admin list namespaces
```

--------------------------------

### Verify zrok2-init logs

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/docker

Check the logs of the zrok2-init service to troubleshoot 502 errors on the frontend.

```bash
docker compose logs zrok2-init
```

--------------------------------

### Set frontend file permissions

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Commands to set ownership and permissions for the frontend configuration file.

```bash
sudo chown zrok2-frontend:zrok2-frontend /etc/zrok2/frontend.yml  

sudo chmod 640 /etc/zrok2/frontend.yml  
```

--------------------------------

### Manage zrok frontend service

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Commands to enable the frontend service and follow its logs.

```bash
sudo systemctl enable --now zrok2-frontend  

sudo journalctl -u zrok2-frontend -f  
```

--------------------------------

### Map namespace to frontend

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

Link a namespace to a frontend to allow shares to be served by that frontend.

```bash
zrok2 admin create namespace-frontend <namespaceToken> <frontendToken>
```

--------------------------------

### Deploy dynamicProxyController Identity File

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Sets up the identity file permissions and location for the controller service user.

```bash
sudo mkdir -p /var/lib/zrok2-controller/.zrok2/identities
sudo cp ~/.zrok2/identities/dynamicProxyController.json \
  /var/lib/zrok2-controller/.zrok2/identities/
sudo chown -R zrok2-controller:zrok2-controller /var/lib/zrok2-controller/.zrok2
```

--------------------------------

### Create a share in open mode

Source: https://netfoundry.io/docs/zrok/how-tos/shares/configure-permission-modes

Use the --open flag to allow any user of the zrok service instance to access the share.

```bash
zrok2 share private --headless --open -b web .
```

```text
[   0.064]    INFO main.(*sharePrivateCommand).run: allow other to access your share with the following command:  

zrok2 access private s4czjylwk7wa  
```

--------------------------------

### Create additional dynamic frontends

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/scaling-frontends

Commands to register new dynamic frontend records in the controller with unique tokens.

```bash
zrok2 admin create frontend --dynamic -- <public-ziti-id> frontend-2

zrok2 admin create frontend --dynamic -- <public-ziti-id> frontend-3
```

--------------------------------

### Create zrok2 account

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/docker

Creates a new account on the zrok2 instance and returns an enable token.

```bash
docker compose exec zrok2-controller \
  zrok2 admin create account you@example.com yourpassword  
```

--------------------------------

### Deploy Public Frontend Identity File

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Sets up the identity file permissions and location for the frontend service user.

```bash
sudo mkdir -p /var/lib/zrok2-frontend/.zrok2/identities
sudo cp ~/.zrok2/identities/public.json \
  /var/lib/zrok2-frontend/.zrok2/identities/
sudo chown -R zrok2-frontend:zrok2-frontend /var/lib/zrok2-frontend/.zrok2
```

--------------------------------

### Check ziti-controller logs

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/docker

Use this command to inspect the logs of the ziti-controller service when bootstrap fails with a connection refused error.

```bash
docker compose logs ziti-controller
```

--------------------------------

### Copy a local directory to a virtual drive

Source: https://netfoundry.io/docs/zrok/how-tos/shares/share-sync-drives

Upload a local directory structure into the virtual drive.

```bash
zrok2 copy util/ zrok://wkcfb58vj51l/stuff  
```

```text
[   0.123]    INFO zrok/drives/sync.OneWay: => /email.go  

[   0.194]    INFO zrok/drives/sync.OneWay: => /headers.go  

[   0.267]    INFO zrok/drives/sync.OneWay: => /proxy.go  

[   0.337]    INFO zrok/drives/sync.OneWay: => /size.go  

[   0.408]    INFO zrok/drives/sync.OneWay: => /uniqueName.go  

copy complete!  
```

--------------------------------

### Configure Public Frontend Template

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/error-pages

Add the template_path key to your public frontend configuration YAML file.

```yaml
v: 4

identity: public

address: 0.0.0.0:8080


# Path to custom error page template

template_path: /path/to/custom-template.html


# Other configuration options...
```

--------------------------------

### Create Public Namespace

Source: https://netfoundry.io/docs/zrok/self-hosting/deployment/linux

Registers a new public namespace for share name organization.

```bash
zrok2 admin create namespace --token public --open zrok.example.com
```

--------------------------------

### Scenario 2: Private reserved share migration

Source: https://netfoundry.io/docs/zrok/how-tos/migration/migrate-v1-to-v2

Comparison of v1.x and v2.0 workflows for private reserved shares.

```bash
# reserve a private share  

$ zrok reserve private http://localhost:8080  

your reserved share token is 'xyz789abc'  

  

# share it  

$ zrok share reserved xyz789abc  

  

# access from another environment  

$ zrok access private xyz789abc
```

```bash
# share privately using the name (-s specifies a share token name)  

$ zrok2 share private http://localhost:8080 -s myapi-prod  

  

# access from another environment  

$ zrok2 access private myapi-prod
```

--------------------------------

### Check Frontend Logs

Source: https://netfoundry.io/docs/zrok/self-hosting/frontends/dynamic-proxy

View systemd logs for the zrok dynamic proxy to verify AMQP subscriber connections or mapping presence.

```bash
# If using systemd  

sudo journalctl -u zrok-dynamicproxy -f  
```

--------------------------------

### List virtual drive contents

Source: https://netfoundry.io/docs/zrok/how-tos/shares/share-sync-drives

Display the files and directories present on the virtual drive.

```bash
zrok2 ls zrok://wkcfb58vj51l  
```

```text
┌──────┬─────────┬─────────┬───────────────────────────────┐  

│ TYPE │ NAME    │ SIZE    │ MODIFIED                      │  

├──────┼─────────┼─────────┼───────────────────────────────┤  

│      │ LICENSE │ 11.3 kB │ 2024-01-19 12:16:46 -0500 EST │  

└──────┴─────────┴─────────┴───────────────────────────────┘  
```
Tokens:
Raw