Complete zrok Setup and Usage Guide for Raspberry Pi

Self-hosted Applications
,
1

Complete zrok Setup and Usage Guide for Raspberry Pi

Table of Contents

  1. Introduction
  2. Installation
  3. Initial Setup
  4. Running zrok as a Service
  5. Usage
  6. Connecting from a Client
  7. Security Considerations
  8. Troubleshooting

Introduction

zrok is a powerful and flexible tunneling tool that allows you to share local services securely over the internet. It’s similar to ngrok but offers some unique features and capabilities. This guide will walk you through the process of installing, setting up, and using zrok on a Raspberry Pi.

Installation

To install zrok on a Raspberry Pi running Raspberry Pi OS (formerly Raspbian), use the following command:

(set -euo pipefail;

curl -sSLf https://get.openziti.io/tun/package-repos.gpg \
| sudo gpg --dearmor --output /usr/share/keyrings/openziti.gpg;
sudo chmod a+r /usr/share/keyrings/openziti.gpg;

sudo tee /etc/apt/sources.list.d/openziti-release.list >/dev/null <<EOF;
deb [signed-by=/usr/share/keyrings/openziti.gpg] https://packages.openziti.org/zitipax-openziti-deb-stable debian main
EOF

sudo apt update;
sudo apt install zrok;
zrok version;
)

This command will:

  1. Add the OpenZiti package repository
  2. Update the package list
  3. Install zrok
  4. Display the installed zrok version

Make sure you’re logged in as the pi user or another user with sudo privileges when running this command.

Initial Setup

Before using zrok, you need to enable it with a token. Here’s how:

  1. Visit https://api.zrok.io in your web browser.
  2. Sign up or log in to your account.
  3. Obtain your unique token from the dashboard.
  4. Run the following command, replacing YOUR_TOKEN with the token you obtained:
zrok enable YOUR_TOKEN

This command will:

  1. Authenticate your zrok installation with your account.
  2. Generate and store credentials locally.
  3. Enable zrok for your account.

Follow any additional prompts to complete the setup process.

Running zrok as a Service

To run zrok as a systemd service for SSH sharing:

  1. Create a service file:
sudo nano /etc/systemd/system/zrok.service
  1. Add the following content:
[Unit]
Description=zrok persistent share
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/bin/bash -c 'zrok share private --headless --backend-mode tcpTunnel 127.0.0.1:22'
Restart=always
RestartSec=3
User=pi

[Install]
WantedBy=multi-user.target

This service configuration:

  • Uses zrok share private to create a private share
  • Uses --headless mode, which is suitable for running as a service
  • Specifies --backend-mode tcpTunnel for SSH access
  • Points to 127.0.0.1:22, which is the local SSH server
  • Runs the service as the pi user
  • Will restart the service automatically if it fails
  1. Enable and start the service:
sudo systemctl daemon-reload
sudo systemctl enable zrok.service
sudo systemctl start zrok.service

Usage

The service will start automatically on boot. To manage it:

  • Start the service: sudo systemctl start zrok.service
  • Stop the service: sudo systemctl stop zrok.service
  • Restart the service: sudo systemctl restart zrok.service
  • Check the status: sudo systemctl status zrok.service

To create a temporary share manually:

zrok share private --backend-mode tcpTunnel 127.0.0.1:22

Connecting from a Client

To connect to a zrok share from a client machine:

  1. Ensure zrok is installed and set up on the client machine as well.

  2. Visit https://api.zrok.io and log in to your account.

  3. Look for the green resource box on the dashboard. This box contains the share code for your active shares.

  4. Use the zrok access command followed by the share code you found. For example:

zrok access private YOUR_SHARE_CODE

Replace YOUR_SHARE_CODE with the actual code you found in the green resource box on the api.zrok.io dashboard.

  1. zrok will establish a connection and provide you with a local address and port to use, typically localhost with a specific port number.

  2. You can now connect to this local address and port using your desired application (e.g., SSH client, web browser, etc.), and zrok will tunnel your connection to the shared service.

For example, to connect to the SSH service on your Raspberry Pi, use:

ssh pi@localhost -p 9191

This command assumes that:

  • The user on the Raspberry Pi is ‘pi’
  • zrok has mapped the service to port 9191 on your local machine

Adjust the username and port as necessary based on your specific setup and the information provided by zrok when you run the zrok access command.

Security Considerations

  1. Keep your zrok token and credentials secure.
  2. Use strong authentication for shared services.
  3. Regularly review and update your shares and access permissions.
  4. For SSH, consider using key-based authentication instead of passwords.
  5. The service runs as the pi user. Ensure this user has the necessary permissions but not more than needed.
  6. The share code displayed in the green resource box on api.zrok.io is sensitive information. Treat it like a password and do not share it publicly.

Troubleshooting

  • View zrok logs:
    journalctl -u zrok.service
  • Ensure your firewall allows outgoing connections on the required ports.
  • If the service fails to start, check the zrok command syntax in the ExecStart line of the service file.
  • Make sure the pi user (or whichever user you specify) has permission to run zrok and access the necessary resources.
  • If you encounter authentication issues, you may need to re-run the zrok enable command with a new token from https://api.zrok.io.
  • If you can’t connect from a client, verify that you’re using the correct share code from the api.zrok.io dashboard and that the share is still active on the server.
  • Remember that the share code may change if you restart the zrok service or create a new share. Always check the api.zrok.io dashboard for the most current share code.

For more detailed information and advanced usage, refer to the official zrok documentation.