Merge pull request #818 from openziti/systemd-user-unit-instance-template

add systemd user unit instance template

.goreleaser-linux-amd64.yml

@@ -109,6 +109,9 @@ nfpms:
       - dst: /lib/systemd/system/
         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
 

.goreleaser-linux-arm64.yml

@@ -113,6 +113,9 @@ nfpms:
       - dst: /lib/systemd/system/
         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
 

.goreleaser-linux-armel.yml

@@ -117,6 +117,9 @@ nfpms:
       - dst: /lib/systemd/system/
         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
 

.goreleaser-linux-armhf.yml

@@ -115,6 +115,9 @@ nfpms:
       - dst: /lib/systemd/system/
         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,9 +4,11 @@
 
 FIX: Docker share examples had incorrect default path for zrok environment mountpoint
 
+FIX: Clarify how to use DNS providers like Route53 with the zrok Docker instance sample.
+
 CHANGE: Use port 80 for the default Ziti API endpoint in the zrok Docker instance sample (https://github.com/openziti/zrok/issues/793).
 
-FIX: Clarify how to use DNS providers like Route53 with the zrok Docker instance sample.
+FEATURE: Linux service template for systemd user units (https://github.com/openziti/zrok/pull/818)
 
 ## v0.4.45
 

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.
+<LinuxShareInstall />
-
-    ```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
-    ```
 
 <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,6 +46,24 @@ 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.
 
+## 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 account 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.

nfpm/zrok-share.bash

@@ -36,28 +36,20 @@ fi
 echo "DEBUG: zrok state directory is ${HOME}/.zrok"
 
 : "${ZROK_SHARE_RESERVED:=true}"
-
 echo "DEBUG: ZROK_SHARE_RESERVED=${ZROK_SHARE_RESERVED}"
 
-if (( $# )); then
+while (( $# )); do
-  if [[ -s "$1" ]]; then
+  if [[ "${1:0:1}" == @ ]]; then
+    ZROK_INSTANCE="${1:1}"
+    shift
+  elif [[ -s "$1" ]]; then
     echo "INFO: reading share configuration from $1"
     source "$1"
     shift
-  else
-    echo "ERROR: '$1' is empty or not readable" >&2
-    exit 1
   fi
-else
+done
-  # TODO: consider defining a default environment file
+
-  # if [[ -s /opt/openziti/etc/zrok.env ]]; then
+ZROK_RESERVATION_FILE="${HOME}/.zrok/reserved${ZROK_INSTANCE:+@${ZROK_INSTANCE}}.json"
-  #   source /opt/openziti/etc/zrok.env
-  # else
-  #   echo "ERROR: need /opt/openziti/etc/zrok.env or filename argument to read share configuration" >&2
-  #   exit 1
-  # fi
-  echo "INFO: reading share configuration from environment variables"
-fi
 
 [[ -n "${ZROK_TARGET:-}" ]] || {
   echo "ERROR: ZROK_TARGET is not defined." >&2
@@ -70,14 +62,14 @@ if [[ "${ZROK_FRONTEND_MODE:-}" == temp-public ]]; then
   ZROK_CMD="share public"
 elif [[ "${ZROK_FRONTEND_MODE:-}" == temp-private ]]; then
   ZROK_CMD="share private"
-elif [[ -s ~/.zrok/reserved.json ]]; then
+elif [[ -s "${ZROK_RESERVATION_FILE}" ]]; then
-  ZROK_RESERVED_TOKEN="$(jq -r '.token' ~/.zrok/reserved.json 2>/dev/null)"
+  ZROK_RESERVATION_TOKEN="$(jq -r '.token' "${ZROK_RESERVATION_FILE}" 2>/dev/null)"
-  if [[ -z "${ZROK_RESERVED_TOKEN}" || "${ZROK_RESERVED_TOKEN}" == null ]]; then
+  if [[ -z "${ZROK_RESERVATION_TOKEN}" || "${ZROK_RESERVATION_TOKEN}" == null ]]; then
-    echo "ERROR: invalid reserved.json: '$(jq -c . ~/.zrok/reserved.json)'" >&2
+    echo "ERROR: invalid reservation file: '$(jq -c . "${ZROK_RESERVATION_FILE}")'" >&2
     exit 1
   else
-    echo "INFO: zrok backend is already reserved: ${ZROK_RESERVED_TOKEN}"
+    echo "INFO: zrok backend is already reserved: ${ZROK_RESERVATION_TOKEN}"
-    ZROK_CMD="${ZROK_RESERVED_TOKEN} ${ZROK_TARGET}"
+    ZROK_CMD="${ZROK_RESERVATION_TOKEN} ${ZROK_TARGET}"
     if [[ "${ZROK_SHARE_RESERVED}" == true ]]; then
       exec_share_reserved ${ZROK_CMD}
     else
@@ -208,30 +200,30 @@ if [[ "${ZROK_FRONTEND_MODE:-}" =~ ^temp- ]]; then
   exec_with_common_opts ${ZROK_CMD}
 else
   # reserve and continue
-  zrok ${ZROK_CMD} > ~/.zrok/reserved.json
+  zrok ${ZROK_CMD} > "${ZROK_RESERVATION_FILE}"
   # share the reserved backend target until exit
-  if ! [[ -s ~/.zrok/reserved.json ]]; then
+  if ! [[ -s "${ZROK_RESERVATION_FILE}" ]]; then
-    echo "ERROR: empty or missing $(realpath ~/.zrok)/reserved.json" >&2
+    echo "ERROR: empty or missing $(realpath "${ZROK_RESERVATION_FILE}")" >&2
     exit 1
-  elif ! jq . < ~/.zrok/reserved.json &>/dev/null; then
+  elif ! jq . < "${ZROK_RESERVATION_FILE}" &>/dev/null; then
-    echo "ERROR: invalid JSON in $(realpath ~/.zrok)/reserved.json" >&2
+    echo "ERROR: invalid JSON in $(realpath "${ZROK_RESERVATION_FILE}")" >&2
     exit 1
   else
     if [[ "${ZROK_FRONTEND_MODE:-}" == reserved-public ]]; then
-      ZROK_PUBLIC_URLS=$(jq -cr '.frontend_endpoints' ~/.zrok/reserved.json 2>/dev/null)
+      ZROK_PUBLIC_URLS=$(jq -cr '.frontend_endpoints' "${ZROK_RESERVATION_FILE}" 2>/dev/null)
       if [[ -z "${ZROK_PUBLIC_URLS}" || "${ZROK_PUBLIC_URLS}" == null ]]; then
-        echo "ERROR: frontend endpoints not defined in $(realpath ~/.zrok)/reserved.json" >&2
+        echo "ERROR: frontend endpoints not defined in $(realpath "${ZROK_RESERVATION_FILE}")" >&2
         exit 1
       else
         echo "INFO: zrok public URLs: ${ZROK_PUBLIC_URLS}"
       fi
     fi
-    ZROK_RESERVED_TOKEN=$(jq -r '.token' ~/.zrok/reserved.json 2>/dev/null)
+    ZROK_RESERVATION_TOKEN=$(jq -r '.token' "${ZROK_RESERVATION_FILE}" 2>/dev/null)
-    if [[ -z "${ZROK_RESERVED_TOKEN}" || "${ZROK_RESERVED_TOKEN}" == null ]]; then
+    if [[ -z "${ZROK_RESERVATION_TOKEN}" || "${ZROK_RESERVATION_TOKEN}" == null ]]; then
-      echo "ERROR: zrok reservation token not defined in $(realpath ~/.zrok)/reserved.json" >&2
+      echo "ERROR: zrok reservation token not defined in $(realpath "${ZROK_RESERVATION_FILE}")" >&2
       exit 1
     fi
-    ZROK_CMD="${ZROK_RESERVED_TOKEN} ${ZROK_TARGET}"
+    ZROK_CMD="${ZROK_RESERVATION_TOKEN} ${ZROK_TARGET}"
     if [[ "${ZROK_SHARE_RESERVED}" == true ]]; then
       exec_share_reserved ${ZROK_CMD}
     else

nfpm/zrok-share.env

@@ -3,8 +3,10 @@
 #
 ## ZROK ENVIRONMENT
 #
-# You MUST enable a zrok environment by setting the environment enable token here. This file must be readable by
+# The variables in this section are not used by user units, i.e., systemctl --user, because it is assumed the user's
-# 'other'.  Obtain the enable token from the zrok console after accepting your invitation and creating a password.
+# environment in ~/.zrok is already enabled. The variables in this section are required by system-wide service units.
+# For system services, you MUST enable a zrok environment by setting the account token here.  This file must
+# be readable by 'other'. Obtain the account token from the zrok console.
 #
 # WARNING: changing these values has no effect if /var/lib/zrok-share/.zrok/environment.json exists. Remove that file to
 # enable a new environment and /var/lib/zrok-share/.zrok/reserved.json to provision a new frontend URL for the specified

nfpm/zrok-share.service

@@ -1,5 +1,5 @@
 [Unit]
-Description=zrok reserved public share service
+Description=zrok share service 
 After=network-online.target
 
 [Service]
@@ -7,8 +7,9 @@ Type=simple
 DynamicUser=yes
 StateDirectory=zrok-share
 UMask=0007
-ExecStartPre=/opt/openziti/bin/zrok-enable.bash /opt/openziti/etc/zrok/zrok-share.env
+EnvironmentFile=/opt/openziti/etc/zrok/zrok-share.env
-ExecStart=/opt/openziti/bin/zrok-share.bash /opt/openziti/etc/zrok/zrok-share.env
+ExecStartPre=/opt/openziti/bin/zrok-enable.bash
+ExecStart=/opt/openziti/bin/zrok-share.bash
 Restart=always
 RestartSec=3
 

nfpm/zrok-share.service.override.conf

@@ -6,5 +6,3 @@
 
 # allow adding tun device and IP routes and iptables rules; required when ZROK_BACKEND_MODE=vpn
 # AmbientCapabilities=CAP_NET_ADMIN
-
-# you must run 'systemctl daemon-reload' after modifying this file

nfpm/zrok-share@.service

@@ -0,0 +1,17 @@
+
+# /usr/lib/systemd/user/zrok-share@.service
+
+[Unit]
+Description=zrok share user service unit @%i
+After=network-online.target
+
+[Service]
+Type=simple
+UMask=0007
+EnvironmentFile=%h/.zrok/zrok-share@%i.env
+ExecStart=/opt/openziti/bin/zrok-share.bash @%i
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target