From b57c51ec890725616aed5de60548000740f5b6dc Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Thu, 20 Mar 2025 21:40:00 -0400 Subject: [PATCH] document the linux agent service --- docs/guides/_linux-share-install.mdx | 8 +- docs/guides/agent.mdx | 87 ++++++++++++++++++++ docs/guides/linux-agent-service.mdx | 42 ++++++++++ docs/guides/linux-user-share/_category_.json | 8 -- docs/guides/linux-user-share/index.mdx | 44 ---------- 5 files changed, 133 insertions(+), 56 deletions(-) create mode 100644 docs/guides/agent.mdx create mode 100644 docs/guides/linux-agent-service.mdx delete mode 100644 docs/guides/linux-user-share/_category_.json delete mode 100644 docs/guides/linux-user-share/index.mdx diff --git a/docs/guides/_linux-share-install.mdx b/docs/guides/_linux-share-install.mdx index acea45b2..088dc04e 100644 --- a/docs/guides/_linux-share-install.mdx +++ b/docs/guides/_linux-share-install.mdx @@ -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 ``` diff --git a/docs/guides/agent.mdx b/docs/guides/agent.mdx new file mode 100644 index 00000000..4baf6a4a --- /dev/null +++ b/docs/guides/agent.mdx @@ -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 diff --git a/docs/guides/linux-agent-service.mdx b/docs/guides/linux-agent-service.mdx new file mode 100644 index 00000000..fe728be1 --- /dev/null +++ b/docs/guides/linux-agent-service.mdx @@ -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. + + + +## Enable your Account + +This creates a `~/.zrok` directory enabled for your zrok account. + +```bash +zrok enable +``` + +## 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 +``` diff --git a/docs/guides/linux-user-share/_category_.json b/docs/guides/linux-user-share/_category_.json deleted file mode 100644 index 16892730..00000000 --- a/docs/guides/linux-user-share/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Linux User Share", - "position": 40, - "link": { - "type": "doc", - "id": "guides/linux-user-share/index" - } -} diff --git a/docs/guides/linux-user-share/index.mdx b/docs/guides/linux-user-share/index.mdx deleted file mode 100644 index 6b9679e2..00000000 --- a/docs/guides/linux-user-share/index.mdx +++ /dev/null @@ -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. - - - -## 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.