document and announce Linux user shares

.goreleaser-linux-armel.yml

@@ -120,9 +120,6 @@ nfpms:
       - dst: /usr/lib/systemd/user/
         src: ./nfpm/zrok-share@.service
 
-      - dst: /usr/lib/systemd/user/
-        src: ./nfpm/zrok-share@.service
-
       - dst: /etc/systemd/system/zrok-share.service.d/override.conf
         src: ./nfpm/zrok-share.service.override.conf
 

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 FIX: Docker share examples had incorrect default path for zrok environment mountpoint
 
+FEATURE: Linux service template for systemd user units (https://github.com/openziti/zrok/pull/818)
+
 ## v0.4.45
 
 FEATURE: Minimal support for "organizations". Site admin API endpoints provided to create, list, and delete "organizations". Site admin API endpoints provided to add, list, and remove "organization members" (zrok accounts) with the ability to mark accounts as a "organization admin". API endpoints provided for organization admins to list the members of their organizations, and to also see the overview (environments, shares, and accesses) for any account in their organization. API endpoint for end users to see which organizations their account is a member of (https://github.com/openziti/zrok/issues/537) 

docs/guides/_frontdoor-linux.mdx

@@ -1,42 +1,10 @@
+import LinuxShareInstall from './_linux-share-install.mdx'
 import AnsibleRepoSetup from './install/_ansible_repo_setup.yaml'
 import ConcatenateYamlSnippets from '@site/src/components/cat-yaml.jsx'
 
-## Goal
-
-Proxy a reserved public subdomain to a backend target with an always-on Linux system service.
-
-## How it Works
-
-The `zrok-share` package creates a `zrok-share.service` unit in systemd. The administrator edits the service's configuration file to specify the:
-
-1. zrok environment enable token
-1. target URL or files to be shared and backend mode, e.g. `proxy`
-1. authentication options, if wanted
-
-When the service starts it will:
-
-1. enable the zrok environment unless `/var/lib/zrok-share/.zrok/environment.json` exists
-1. reserve a public subdomain for the service unless `/var/lib/zrok-share/.zrok/reserved.json` exists
-1. start sharing the target specified as `ZROK_TARGET` in the environment file
-
 ## Installation
 
-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-share
-    ```
-
-1. If you set up the repository by following the guide, then also install the `zrok-share` package. This package provides the systemd service.
-
-    ```bash title="Ubuntu, Debian"
-    sudo apt install zrok-share
-    ```
-
-    ```bash title="Fedora, Rocky"
-    sudo dnf install zrok-share
-    ```
+<LinuxShareInstall />
 
 <Details>
 <summary>Ansible Playbook</summary>

docs/guides/_linux-share-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-share
+    ```
+
+1. If you set up the repository by following the guide, then also install the `zrok-share` package. This package provides the systemd service.
+
+    ```bash title="Ubuntu, Debian"
+    sudo apt install zrok-share
+    ```
+
+    ```bash title="Fedora, Rocky"
+    sudo dnf install zrok-share
+    ```

docs/guides/frontdoor.mdx

@@ -46,7 +46,25 @@ the detected OS of the visitor's browser */}
 
 On Linux, zrok frontdoor is implemented natively as a system service provided by the `zrok-share` DEB or RPM package.
 
-    <LinuxService/>
+## Goal
+
+Proxy a reserved public subdomain to a backend target with an always-on Linux system service.
+
+## How it Works
+
+The `zrok-share` package creates a `zrok-share.service` unit in systemd. The administrator edits the service's configuration file to specify the:
+
+1. zrok environment enable token
+1. target URL or files to be shared and backend mode, e.g. `proxy`
+1. authentication options, if wanted
+
+When the service starts it will:
+
+1. enable the zrok environment unless `/var/lib/zrok-share/.zrok/environment.json` exists
+1. reserve a public subdomain for the service unless `/var/lib/zrok-share/.zrok/reserved.json` exists
+1. start sharing the target specified as `ZROK_TARGET` in the environment file
+
+  <LinuxService/>
 
   </TabItem>
 

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

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

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

@@ -0,0 +1,44 @@
+---
+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.