From af0367e36b584660cfe0e89cd33338b8110d16a4 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Thu, 2 Jan 2025 01:52:50 -0500 Subject: [PATCH] document and announce Linux user shares --- .goreleaser-linux-armel.yml | 3 -- CHANGELOG.md | 4 +- docs/guides/_frontdoor-linux.mdx | 36 +--------------- docs/guides/_linux-share-install.mdx | 17 ++++++++ docs/guides/linux-user-share/_category_.json | 8 ++++ docs/guides/linux-user-share/index.mdx | 44 ++++++++++++++++++++ 6 files changed, 74 insertions(+), 38 deletions(-) create mode 100644 docs/guides/_linux-share-install.mdx create mode 100644 docs/guides/linux-user-share/_category_.json create mode 100644 docs/guides/linux-user-share/index.mdx diff --git a/.goreleaser-linux-armel.yml b/.goreleaser-linux-armel.yml index 748360dd..86526dec 100644 --- a/.goreleaser-linux-armel.yml +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 74ff2044..3f997524 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/guides/_frontdoor-linux.mdx b/docs/guides/_frontdoor-linux.mdx index 23977db9..ac3b6fe7 100644 --- a/docs/guides/_frontdoor-linux.mdx +++ b/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 - ``` +
Ansible Playbook diff --git a/docs/guides/_linux-share-install.mdx b/docs/guides/_linux-share-install.mdx new file mode 100644 index 00000000..acea45b2 --- /dev/null +++ b/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 + ``` diff --git a/docs/guides/linux-user-share/_category_.json b/docs/guides/linux-user-share/_category_.json new file mode 100644 index 00000000..16892730 --- /dev/null +++ b/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" + } +} diff --git a/docs/guides/linux-user-share/index.mdx b/docs/guides/linux-user-share/index.mdx new file mode 100644 index 00000000..6b9679e2 --- /dev/null +++ b/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. + + + +## 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.