# Complete zrok Setup and Usage Guide for Raspberry Pi

**URL:** <https://forum.hhf.technology/t/complete-zrok-setup-and-usage-guide-for-raspberry-pi/281>\
**Category:** Self-hosted Applications\
**Tags:** zrok, raspberry-pi\
**Created:** [June 18, 2024, 6:30pm UTC](https://forum.hhf.technology/t/complete-zrok-setup-and-usage-guide-for-raspberry-pi/281 "2024-06-18T18:30:00Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![hhf.technoloy](https://forum.hhf.technology/user_avatar/forum.hhf.technology/hhf.technoloy/32/68_2.png) [@hhf.technoloy](https://forum.hhf.technology/u/hhf.technoloy)\
**Post date:** [June 18, 2024, 6:30pm UTC](https://forum.hhf.technology/t/complete-zrok-setup-and-usage-guide-for-raspberry-pi/281/1 "2024-06-18T18:30:00Z")

</div>

# Complete zrok Setup and Usage Guide for Raspberry Pi

## Table of Contents

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Initial Setup](#initial-setup)
4. [Running zrok as a Service](#running-zrok-as-a-service)
5. [Usage](#usage)
6. [Connecting from a Client](#connecting-from-a-client)
7. [Security Considerations](#security-considerations)
8. [Troubleshooting](#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:

```bash
(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](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:

```bash
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:

```bash
sudo nano /etc/systemd/system/zrok.service

```

1. Add the following content:

```auto
[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:

```bash
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:

```bash
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](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:

```bash
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](http://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:

```bash
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](http://api.zrok.io) is sensitive information. Treat it like a password and do not share it publicly.

## Troubleshooting

- View zrok logs:

```bash
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](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](http://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](http://api.zrok.io) dashboard for the most current share code.

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