mirror of
https://github.com/openziti/zrok.git
synced 2025-06-27 05:01:26 +02:00
document the linux agent service
This commit is contained in:
Kenneth Bingham
parent
1a01232123
commit
b57c51ec89
@ -3,15 +3,15 @@
|
||||
|
||||
```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"
|
||||
sudo apt install zrok-share
|
||||
sudo apt install zrok-agent
|
||||
```
|
||||
|
||||
```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