Merge branch 'main' into agent_restart_persistence

.github/workflows/promote-downstreams.yml

@@ -63,6 +63,7 @@ jobs:
         package_name:
           - zrok
           - zrok-share
+          - zrok-agent
         arch:
           - deb: amd64
             rpm: x86_64

.github/workflows/release.yml

@@ -103,7 +103,7 @@ jobs:
           else
             SEMVER_PRE=${SEMVER#*-}
           fi
-          for PAX in zrok{,-share}; do
+          for PAX in zrok{,-share,-agent}; do
             _pattern="./dist/${PAX}-${SEMVER_CORE}${SEMVER_PRE:+~${SEMVER_PRE}}*.${ARCH}.rpm"
             if ! compgen -G "$_pattern" > /dev/null; then
               echo "ERROR: No RPM files found matching pattern '${_pattern}'" >&2
@@ -139,7 +139,7 @@ jobs:
           else
             SEMVER_PRE=${SEMVER#*-}
           fi
-          for PAX in zrok{,-share}; do
+          for PAX in zrok{,-share,-agent}; do
             _pattern="./dist/${PAX}_${SEMVER_CORE}${SEMVER_PRE:+~${SEMVER_PRE}}*_${ARCH}.deb"
             if ! compgen -G "$_pattern" > /dev/null; then
               echo "ERROR: No DEB files found matching pattern '${_pattern}'" >&2

.goreleaser-linux-amd64.yml

@@ -23,7 +23,7 @@ nfpms:
     license: Apache 2.0
 
     # Build IDs for the builds you want to create NFPM packages for.
-    builds:
+    ids:
       - zrok-amd64
 
     # Formats to be generated.
@@ -137,3 +137,56 @@ nfpms:
       - dst: /opt/openziti/etc/zrok/
         src: ./etc/caddy/multiple_upstream.Caddyfile
         type: config|noreplace
+
+  - package_name: zrok-agent
+    id: zrok-agent
+    vendor: NetFoundry
+    homepage: https://zrok.io/
+    maintainer: support@zrok.io
+    description: |
+      This package provides zrok-agent.service. Enable your zrok account on this device with "zrok enable". Run 
+      "systemctl enable --user --now zrok-agent.service" to enable the service for the current user and visit the agent 
+      UI by running "zrok agent console".
+    license: Apache 2.0
+
+    # do not bundle the built binaries, only supporting files
+    meta: true
+
+    # Formats to be generated.
+    formats:
+      - deb
+      - rpm
+
+    # {{ .ConventionalFileName }} satisfies the RPM name convention.
+    file_name_template: "{{ .ConventionalFileName }}"
+
+    # Umask to be used on files without explicit mode set. (overridable)
+    umask: 0o002
+
+    # Package version within this release version.
+    release: 1
+
+    # Section.
+    section: default
+
+    # Priority.
+    priority: optional
+
+    # GoReleaser will automatically add the binaries here
+    dependencies:
+      - zrok
+
+    # this allows users to satisfy the requirement for jq another way, not with the package manager, e.g.
+    # apt install --no-recommends zrok-share
+    recommends: []
+
+    overrides:
+      # yum and dnf do not automatically install "weak deps" aka "recommends", so we need to add them as a dependency
+      rpm:
+        dependencies:
+          - zrok
+
+    # Contents to add to the package.
+    contents:
+      - dst: /usr/lib/systemd/user/
+        src: ./nfpm/zrok-agent.service

.goreleaser-linux-arm64.yml

@@ -27,7 +27,7 @@ nfpms:
     license: Apache 2.0
 
     # Build IDs for the builds you want to create NFPM packages for.
-    builds:
+    ids:
       - zrok-armv8
 
     # Formats to be generated.
@@ -141,3 +141,56 @@ nfpms:
       - dst: /opt/openziti/etc/zrok/
         src: ./etc/caddy/multiple_upstream.Caddyfile
         type: config|noreplace
+
+  - package_name: zrok-agent
+    id: zrok-agent
+    vendor: NetFoundry
+    homepage: https://zrok.io/
+    maintainer: support@zrok.io
+    description: |
+      This package provides zrok-agent.service. Enable your zrok account on this device with "zrok enable". Run 
+      "systemctl enable --user --now zrok-agent.service" to enable the service for the current user and visit the agent 
+      UI by running "zrok agent console".
+    license: Apache 2.0
+
+    # do not bundle the built binaries, only supporting files
+    meta: true
+
+    # Formats to be generated.
+    formats:
+      - deb
+      - rpm
+
+    # {{ .ConventionalFileName }} satisfies the RPM name convention.
+    file_name_template: "{{ .ConventionalFileName }}"
+
+    # Umask to be used on files without explicit mode set. (overridable)
+    umask: 0o002
+
+    # Package version within this release version.
+    release: 1
+
+    # Section.
+    section: default
+
+    # Priority.
+    priority: optional
+
+    # GoReleaser will automatically add the binaries here
+    dependencies:
+      - zrok
+
+    # this allows users to satisfy the requirement for jq another way, not with the package manager, e.g.
+    # apt install --no-recommends zrok-share
+    recommends: []
+
+    overrides:
+      # yum and dnf do not automatically install "weak deps" aka "recommends", so we need to add them as a dependency
+      rpm:
+        dependencies:
+          - zrok
+
+    # Contents to add to the package.
+    contents:
+      - dst: /usr/lib/systemd/user/
+        src: ./nfpm/zrok-agent.service

.goreleaser-linux-armel.yml

@@ -31,7 +31,7 @@ nfpms:
     license: Apache 2.0
 
     # Build IDs for the builds you want to create NFPM packages for.
-    builds:
+    ids:
       - zrok-armel
 
     # Formats to be generated.
@@ -145,3 +145,56 @@ nfpms:
       - dst: /opt/openziti/etc/zrok/
         src: ./etc/caddy/multiple_upstream.Caddyfile
         type: config|noreplace
+
+  - package_name: zrok-agent
+    id: zrok-agent
+    vendor: NetFoundry
+    homepage: https://zrok.io/
+    maintainer: support@zrok.io
+    description: |
+      This package provides zrok-agent.service. Enable your zrok account on this device with "zrok enable". Run 
+      "systemctl enable --user --now zrok-agent.service" to enable the service for the current user and visit the agent 
+      UI by running "zrok agent console".
+    license: Apache 2.0
+
+    # do not bundle the built binaries, only supporting files
+    meta: true
+
+    # Formats to be generated.
+    formats:
+      - deb
+      - rpm
+
+    # {{ .ConventionalFileName }} satisfies the RPM name convention.
+    file_name_template: "{{ .ConventionalFileName }}"
+
+    # Umask to be used on files without explicit mode set. (overridable)
+    umask: 0o002
+
+    # Package version within this release version.
+    release: 1
+
+    # Section.
+    section: default
+
+    # Priority.
+    priority: optional
+
+    # GoReleaser will automatically add the binaries here
+    dependencies:
+      - zrok
+
+    # this allows users to satisfy the requirement for jq another way, not with the package manager, e.g.
+    # apt install --no-recommends zrok-share
+    recommends: []
+
+    overrides:
+      # yum and dnf do not automatically install "weak deps" aka "recommends", so we need to add them as a dependency
+      rpm:
+        dependencies:
+          - zrok
+
+    # Contents to add to the package.
+    contents:
+      - dst: /usr/lib/systemd/user/
+        src: ./nfpm/zrok-agent.service

.goreleaser-linux-armhf.yml

@@ -29,7 +29,7 @@ nfpms:
     license: Apache 2.0
 
     # Build IDs for the builds you want to create NFPM packages for.
-    builds:
+    ids:
       - zrok-armhf
 
     # Formats to be generated.
@@ -143,3 +143,56 @@ nfpms:
       - dst: /opt/openziti/etc/zrok/
         src: ./etc/caddy/multiple_upstream.Caddyfile
         type: config|noreplace
+
+  - package_name: zrok-agent
+    id: zrok-agent
+    vendor: NetFoundry
+    homepage: https://zrok.io/
+    maintainer: support@zrok.io
+    description: |
+      This package provides zrok-agent.service. Enable your zrok account on this device with "zrok enable". Run 
+      "systemctl enable --user --now zrok-agent.service" to enable the service for the current user and visit the agent 
+      UI by running "zrok agent console".
+    license: Apache 2.0
+
+    # do not bundle the built binaries, only supporting files
+    meta: true
+
+    # Formats to be generated.
+    formats:
+      - deb
+      - rpm
+
+    # {{ .ConventionalFileName }} satisfies the RPM name convention.
+    file_name_template: "{{ .ConventionalFileName }}"
+
+    # Umask to be used on files without explicit mode set. (overridable)
+    umask: 0o002
+
+    # Package version within this release version.
+    release: 1
+
+    # Section.
+    section: default
+
+    # Priority.
+    priority: optional
+
+    # GoReleaser will automatically add the binaries here
+    dependencies:
+      - zrok
+
+    # this allows users to satisfy the requirement for jq another way, not with the package manager, e.g.
+    # apt install --no-recommends zrok-share
+    recommends: []
+
+    overrides:
+      # yum and dnf do not automatically install "weak deps" aka "recommends", so we need to add them as a dependency
+      rpm:
+        dependencies:
+          - zrok
+
+    # Contents to add to the package.
+    contents:
+      - dst: /usr/lib/systemd/user/
+        src: ./nfpm/zrok-agent.service

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 FEATURE: The zrok Agent now persists private accesses and reserved shares between executions. Any `zrok access private` instances or `zrok share reserved` instances created using the agent are now persisted to a registry stored in `${HOME}/.zrok`. When restarting the agent these accesses and reserved shares are re-created from the data in this registry (https://github.com/openziti/zrok/pull/922)
 
+FEATURE: zrok-agent Linux package runs the agent as a user service (https://github.com/openziti/zrok/issues/883)
+
 CHANGE: let the Docker instance set the Caddy HTTPS port (https://github.com/openziti/zrok/pull/920)
 
 CHANGE: Add Traefik option for TLS termination in the Docker instance (https://github.com/openziti/zrok/issues/808)

docs/guides/_linux-agent-install.mdx

@@ -0,0 +1,17 @@
+
+1. Set up `zrok`'s Linux package repository by following [the Linux install guide](/guides/install/linux.mdx#install-zrok-from-the-repository), or run this one-liner to complete the repo setup and install packages.
+
+    ```bash
+    curl -sSLf https://get.openziti.io/install.bash \
+    | sudo bash -s zrok-agent
+    ```
+
+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-agent
+    ```
+
+    ```bash title="Fedora, Rocky"
+    sudo dnf install zrok-agent
+    ```

docs/guides/agent/_category_.json

@@ -2,6 +2,7 @@
   "label": "The zrok Agent",
   "position": 15,
   "link": {
-    "type": "generated-index"
+    "type": "doc",
+    "id": "guides/agent/index"
   }
 }

docs/guides/agent/index.mdx

@@ -0,0 +1,109 @@
+---
+title: Agent
+sidebar_position: 20
+---
+
+The zrok Agent centralizes management of your zrok shares and accesses. It provides both web-based and command-line interfaces, 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.
+
+Check the status of the Agent's shares and accesses.
+
+```bash
+zrok agent status
+```
+
+```buttonless title="Output"
+ FRONTEND TOKEN  TOKEN  BIND ADDRESS
+0 accesses in agent
+
+ TOKEN         RESERVED  SHARE MODE  BACKEND MODE  TARGET
+ myshare       true      private     tcpTunnel     127.0.0.1:8080
+1 share in agent
+```
+
+### Running the Agent in the background
+
+You can keep the Agent running reliably in the background by installing the Agent service in Windows or Linux.
+
+- Windows - [set up the Windows system service](/guides/agent/windows-service/index.mdx)
+- Linux - [install the Linux package `zrok-agent`](/guides/agent/linux-service.mdx)
+
+## 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.
+- The `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.
+- The Agent will remember and automatically restart your shares started with `share reserved`, and any accesses started with `access private`.
+- The Agent will not restart regular, ephemeral shares started with `share private` or `share public`.
+
+### 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 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

docs/guides/agent/linux-service.mdx

@@ -0,0 +1,42 @@
+---
+title: Linux Agent Service
+sidebar_position: 40
+---
+
+import LinuxAgentInstall from '/../docs/guides/_linux-agent-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.
+
+<LinuxAgentInstall />
+
+## 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/index.mdx).
+
+## Troubleshooting
+
+### Check the User Service Log
+
+```bash
+journalctl --user -lfu zrok-agent.service
+```

docs/guides/agent/windows-service/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: Configuring a Windows Service
+sidebar_label: Windows Agent Service
 ---
 
 In Windows environments, it can be useful to run the zrok Agent as a service, allowing it to automatically restart with your system.

docs/guides/linux-user-share/_category_.json

@@ -1,8 +0,0 @@
-{
-  "label": "Linux User Share",
-  "position": 40,
-  "link": {
-    "type": "doc",
-    "id": "guides/linux-user-share/index"
-  }
-}

docs/guides/linux-user-share/index.mdx

@@ -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.

nfpm/zrok-agent.service

@@ -0,0 +1,16 @@
+# /usr/lib/systemd/user/zrok-agent.service
+
+[Unit]
+Description=zrok agent user service unit
+After=network-online.target
+
+[Service]
+Type=simple
+UMask=0007
+ExecStartPre=/usr/bin/env rm --force %h/.zrok/agent.socket
+ExecStart=/opt/openziti/bin/zrok agent start
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=default.target

nfpm/zrok-share@.service

@@ -14,4 +14,4 @@ Restart=always
 RestartSec=3
 
 [Install]
-WantedBy=multi-user.target
+WantedBy=default.target