mirror of
https://github.com/openziti/zrok.git
synced 2025-06-27 13:11:27 +02:00
document the linux agent service
This commit is contained in:
parent
1a01232123
commit
b57c51ec89
@ -3,15 +3,15 @@
|
|||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -sSLf https://get.openziti.io/install.bash \
|
curl -sSLf https://get.openziti.io/install.bash \
|
||||||
| sudo bash -s zrok-share
|
| sudo bash -s zrok-agent
|
||||||
```
|
```
|
||||||
|
|
||||||
1. If you set up the repository by following the guide, then also install the `zrok-share` package. This package provides the systemd service.
|
1. If you set up the repository by following the guide, then also install the `zrok-agent` package. This package provides the systemd service.
|
||||||
|
|
||||||
```bash title="Ubuntu, Debian"
|
```bash title="Ubuntu, Debian"
|
||||||
sudo apt install zrok-share
|
sudo apt install zrok-agent
|
||||||
```
|
```
|
||||||
|
|
||||||
```bash title="Fedora, Rocky"
|
```bash title="Fedora, Rocky"
|
||||||
sudo dnf install zrok-share
|
sudo dnf install zrok-agent
|
||||||
```
|
```
|
||||||
|
87
docs/guides/agent.mdx
Normal file
87
docs/guides/agent.mdx
Normal file
@ -0,0 +1,87 @@
|
|||||||
|
---
|
||||||
|
title: Agent
|
||||||
|
sidebar_position: 20
|
||||||
|
---
|
||||||
|
|
||||||
|
The zrok agent centralizes management of your public and private zrok shares and private frontends for accessing [private shares](/concepts/sharing-private.mdx). It provides a web-based console interface and changes how the `zrok share` and `zrok access` commands behave.
|
||||||
|
|
||||||
|
## Tutorial
|
||||||
|
|
||||||
|
Run the agent in the foreground.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
zrok agent
|
||||||
|
```
|
||||||
|
|
||||||
|
In another terminal, open the console.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
zrok agent console
|
||||||
|
```
|
||||||
|
|
||||||
|
You should see the agent UI in your default web browser.
|
||||||
|
|
||||||
|
Start sharing a public share with the agent.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
zrok share public 8080
|
||||||
|
```
|
||||||
|
|
||||||
|
```buttonless title="Output"
|
||||||
|
token:"zje5x8p0k9pi" frontendEndpoints:"https://zje5x8p0k9pi.share.zrok.io"
|
||||||
|
```
|
||||||
|
|
||||||
|
You will see the new public share in the agent UI and you can access it at the public share URL.
|
||||||
|
|
||||||
|
Reserve a private share for the agent to share.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
zrok reserve private 8080 --closed --unique-name "myshare"
|
||||||
|
```
|
||||||
|
```buttonless title="Output"
|
||||||
|
[ 1.883] INFO main.(*reserveCommand).run: your reserved share token is 'myshare'
|
||||||
|
```
|
||||||
|
|
||||||
|
Start sharing the reserved share with the agent.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
zrok share reserved "myshare"
|
||||||
|
```
|
||||||
|
```buttonless title="Output"
|
||||||
|
[ 0.001] INFO main.(*shareReservedCommand).shareAgent: starting
|
||||||
|
token:"myshare" backendMode:"proxy" shareMode:"private" target:"http://127.0.0.1:8080"
|
||||||
|
```
|
||||||
|
|
||||||
|
You will see the new reserved share in the agent UI and you can access it by running `zrok access "myshare"` on another device where you have enabled the same zrok account, since the share was reserved with closed permission mode.
|
||||||
|
|
||||||
|
### Running the Agent in the background
|
||||||
|
|
||||||
|
On Linux, you can [install the Linux package `zrok-agent`](/guides/linux-agent-service.mdx) to keep the agent running in the background after each reboot.
|
||||||
|
|
||||||
|
## How the Agent Works
|
||||||
|
|
||||||
|
### Centralized Management
|
||||||
|
|
||||||
|
Without the agent running, each time you execute a `zrok share` or `zrok access` command, a separate process is created to handle that specific share or access.
|
||||||
|
|
||||||
|
When the agent is running:
|
||||||
|
|
||||||
|
- All shares and accesses are managed by a single agent process
|
||||||
|
- The agent provides a web UI for monitoring and managing your shares and accesses
|
||||||
|
- New `zrok share` and `zrok access` commands delegate their operations to the running agent
|
||||||
|
- You can stop and restart individual shares/accesses without terminating the agent
|
||||||
|
|
||||||
|
### Agent Console
|
||||||
|
|
||||||
|
The agent provides a web-based console interface that can be accessed with:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
zrok agent console
|
||||||
|
```
|
||||||
|
|
||||||
|
This command opens your default web browser to the agent's UI, where you can:
|
||||||
|
|
||||||
|
- View the status of all your active shares and accesses
|
||||||
|
- Create new shares and accesses using simple UI widgets
|
||||||
|
- Stop or restart existing shares and accesses
|
||||||
|
- Monitor traffic and connection statistics
|
42
docs/guides/linux-agent-service.mdx
Normal file
42
docs/guides/linux-agent-service.mdx
Normal file
@ -0,0 +1,42 @@
|
|||||||
|
---
|
||||||
|
title: Linux Agent Service
|
||||||
|
sidebar_position: 40
|
||||||
|
---
|
||||||
|
|
||||||
|
import LinuxShareInstall from '/../docs/guides/_linux-share-install.mdx'
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Run the zrok agent as a `systemd --user` service under your Linux user account.
|
||||||
|
|
||||||
|
## Install the Package
|
||||||
|
|
||||||
|
The package provides the `zrok` executable and the `zrok-agent.service` unit.
|
||||||
|
|
||||||
|
<LinuxShareInstall />
|
||||||
|
|
||||||
|
## Enable your Account
|
||||||
|
|
||||||
|
This creates a `~/.zrok` directory enabled for your zrok account.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
zrok enable <your_account_token>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Start the Service
|
||||||
|
|
||||||
|
```bash
|
||||||
|
systemctl --user enable --now zrok-agent.service
|
||||||
|
```
|
||||||
|
|
||||||
|
## Use the agent
|
||||||
|
|
||||||
|
Learn more about using the zrok agent in the [agent guide](/guides/agent.mdx).
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Check the User Service Log
|
||||||
|
|
||||||
|
```bash
|
||||||
|
journalctl --user -lfu zrok-agent.service
|
||||||
|
```
|
@ -1,8 +0,0 @@
|
|||||||
{
|
|
||||||
"label": "Linux User Share",
|
|
||||||
"position": 40,
|
|
||||||
"link": {
|
|
||||||
"type": "doc",
|
|
||||||
"id": "guides/linux-user-share/index"
|
|
||||||
}
|
|
||||||
}
|
|
@ -1,44 +0,0 @@
|
|||||||
---
|
|
||||||
title: Linux User Share
|
|
||||||
---
|
|
||||||
|
|
||||||
import LinuxShareInstall from '/../docs/guides/_linux-share-install.mdx'
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
You can run any number of zrok share services as `systemd --user` units with your Linux user's zrok environment in `~/.zrok`. This is like [zrok frontdoor](/guides/frontdoor.mdx) except that frontdoor is a system service managed by root separately from your user's login. Linux user shares, Linux system services, and Docker shares all use the same configuration environment variables.
|
|
||||||
|
|
||||||
## Install the Linux Package
|
|
||||||
|
|
||||||
The package provides the `zrok` executable and service unit template.
|
|
||||||
|
|
||||||
<LinuxShareInstall />
|
|
||||||
|
|
||||||
## Create a User Share Configuration File
|
|
||||||
|
|
||||||
Substitute a name for your instance in place of `my-instance` in the following example. To avoid character escaping problems, use only letters, numbers, hyphens, and underscores in the instance name, not spaces or other special characters.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ZROK_INSTANCE="my-instance"
|
|
||||||
cp /opt/openziti/etc/zrok/zrok-share.env ~/.zrok/zrok-share@${ZROK_INSTANCE}.env
|
|
||||||
```
|
|
||||||
|
|
||||||
## Edit the User Share Configuration File
|
|
||||||
|
|
||||||
Edit the configuration file in `~/.zrok/zrok-share@${ZROK_INSTANCE}.env` as you would for [zrok frontdoor](/guides/frontdoor.mdx), except ignore the first section "ZROK ENVIRONMENT" because user shares re-use `~/.zrok` and do not need a separate zrok environment.
|
|
||||||
|
|
||||||
## Start the User Share Service
|
|
||||||
|
|
||||||
```bash
|
|
||||||
systemctl --user enable --now zrok-share@${ZROK_INSTANCE}.service
|
|
||||||
```
|
|
||||||
|
|
||||||
## Check the User Share Journal
|
|
||||||
|
|
||||||
```bash
|
|
||||||
journalctl --user -lfu zrok-share@${ZROK_INSTANCE}.service
|
|
||||||
```
|
|
||||||
|
|
||||||
## Add Another User Share
|
|
||||||
|
|
||||||
To create another user share, choose another instance name, copy the `zrok-share.env` file, edit the configuration file, and start the service.
|
|
Loading…
x
Reference in New Issue
Block a user