From 258f9941279279ecc234e777a8918a76e6463ce1 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Wed, 15 Nov 2023 18:55:21 -0500 Subject: [PATCH 1/5] add a Linux service guide --- docs/guides/linux-service.md | 141 +++++++++++++++++++++++ docs/guides/self-hosting/_category_.json | 2 +- 2 files changed, 142 insertions(+), 1 deletion(-) create mode 100644 docs/guides/linux-service.md diff --git a/docs/guides/linux-service.md b/docs/guides/linux-service.md new file mode 100644 index 00000000..6b123f52 --- /dev/null +++ b/docs/guides/linux-service.md @@ -0,0 +1,141 @@ +--- +title: Linux Service +sidebar_position: 40 +--- + +## Goal + +Connect a reserved subdomain to a backend target with a Linux systemd service. + +## Requirements + +The Linux distribution must have a package manager that understands the `.deb` or `.rpm` format and be running systemd v232 or newer. + +## 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 an `environment.json` file already exists +1. reserve a public subdomain for the service unless `reserved.json` exists +1. start sharing the target that was specified in the configuration file when the reservation was made + +With the service running, the administrator can see the reserved subdomain for their share in the zrok console or the service log, i.e. `journalctl -lfu zrok-share.service`. + +## Installation + +`install.bash` scripts [the manual procedure](https://openziti.io/docs/downloads/?os=Linux). + +1. Download the OpenZiti install script. + + ```bash + curl -sSo ./openziti-install.bash https://get.openziti.io/install.bash + ``` + +1. Inspect the script to ensure it is suitable to run as root on your system. + + ```bash + less ./openziti-install.bash + ``` + +1. Run the script as root to install the `zrok-share` package. + + ```bash + sudo bash ./openziti-install.bash zrok-share + ``` + +## Enable + +After installing the `zrok-share` package above, save the zrok environment enable token from the zrok console in the configuration file, `/opt/openziti/etc/zrok/zrok-share.env`. + +```bash +ZROK_ENABLE_TOKEN="14cbfca9772f" +``` + +## Use Cases + +You can change the share target by modifying the configuration file and restarting the service. This allows you to change the share target without having to reserve a new subdomain. + +You may switch between backend modes or change authentication options by deleting the `/var/lib/zrok-share/.zrok/reserved.json` file and restarting the service. A new subdomain will be reserved and the target will be shared using the new backend mode and authentication options. + +### Proxy a Web Server + +Sharing a web server means that zrok will provide a public subdomain for an existing web server. The web server could be on a private network or on the same host as zrok. + +This uses zrok in the default `proxy` backend mode. Specify the target URL in the configuration file, `/opt/openziti/etc/zrok/zrok-share.env`. + +```bash +ZROK_TARGET="http://127.0.0.1:3000" +ZROK_BACKEND_MODE="proxy" +``` + +### Serve Static Files + +This uses zrok's `web` backend mode, meaning that zrok will run an embedded web server that's configured to serve your files. If there's an `index.html` file in the directory then visitors will see the rendered page in their browser, otherwise they'll see the list of available files. The directory must be readable by 'other' users, i.e. `chmod o+rX /var/www/html`. + +```bash title="/opt/openziti/etc/zrok/zrok-share.env" +ZROK_TARGET="/var/www/html" +ZROK_BACKEND_MODE="web" +``` + +Start the service, and check the zrok console or the service log for the reserved subdomain. + +```bash +sudo systemctl enable --now zrok-share.service +``` + +### WebDAV Server + +This uses zrok's `drive` backend mode to serve a directory of static files as a WebDAV resource. The directory must be readable by 'other' users, i.e. `chmod o+rX /usr/share/doc`. Add the following to the configuration file. + +```bash title="/opt/openziti/etc/zrok/zrok-share.env" +ZROK_TARGET="/usr/share/doc" +ZROK_BACKEND_MODE="drive" +``` + +### Caddy Server + +Use zrok's built-in Caddy server to serve static files or as a reverse proxy to multiple web servers with various HTTP routes or as a load-balanced set, or both. A sample Caddyfile is provided. Set these in the configuration file. + +```bash title="/opt/openziti/etc/zrok/zrok-share.env" +ZROK_TARGET="/opt/openziti/etc/zrok/multiple_upstream.Caddyfile" +ZROK_BACKEND_MODE="caddy" +``` + +## Authentication + +You can require a password or OAuth email address suffix. + +### OAuth + +You can require that visitors authenticate with an email address that matches at least one of the suffixes you specify. Add the following to the configuration file. + +```bash title="/opt/openziti/etc/zrok/zrok-share.env" +ZROK_OAUTH_PROVIDER="github" # or google +ZROK_OAUTH_EMAILS="bob@example.com @acme.example.com" +``` + +### Password + +Enable HTTP basic authentication by adding the following to the configuration file. + +```bash title="/opt/openziti/etc/zrok/zrok-share.env" +ZROK_BASIC_AUTH="user:passwd" +``` + +## Start the Service + +Start the service, and check the zrok console or the service log for the reserved subdomain. + +```bash +sudo systemctl enable --now zrok-share.service +``` + +```bash +journalctl -u zrok-share.service +``` diff --git a/docs/guides/self-hosting/_category_.json b/docs/guides/self-hosting/_category_.json index 09bd9bb5..391aa9bb 100644 --- a/docs/guides/self-hosting/_category_.json +++ b/docs/guides/self-hosting/_category_.json @@ -1,6 +1,6 @@ { "label": "Self Hosting", - "position": 20, + "position": 80, "link": { "type": "generated-index" } From cebe0bcd638bf3fd398b6617b02bed414eea3e4a Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Wed, 15 Nov 2023 22:10:37 -0500 Subject: [PATCH 2/5] refine service guide --- docs/guides/linux-service.md | 46 ++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 26 deletions(-) diff --git a/docs/guides/linux-service.md b/docs/guides/linux-service.md index 6b123f52..eb9feadb 100644 --- a/docs/guides/linux-service.md +++ b/docs/guides/linux-service.md @@ -5,11 +5,11 @@ sidebar_position: 40 ## Goal -Connect a reserved subdomain to a backend target with a Linux systemd service. +Proxy a reserved public subdomain to a backend target with a Linux service. ## Requirements -The Linux distribution must have a package manager that understands the `.deb` or `.rpm` format and be running systemd v232 or newer. +The Linux distribution must have a package manager that understands the `.deb` or `.rpm` format and be running systemd v232 or newer. This includes Ubuntu 20+, ## How it Works @@ -21,16 +21,12 @@ The `zrok-share` package creates a `zrok-share.service` unit in systemd. The adm When the service starts it will: -1. enable the zrok environment unless an `environment.json` file already exists -1. reserve a public subdomain for the service unless `reserved.json` exists -1. start sharing the target that was specified in the configuration file when the reservation was made - -With the service running, the administrator can see the reserved subdomain for their share in the zrok console or the service log, i.e. `journalctl -lfu zrok-share.service`. +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 in the configuration file ## Installation -`install.bash` scripts [the manual procedure](https://openziti.io/docs/downloads/?os=Linux). - 1. Download the OpenZiti install script. ```bash @@ -51,47 +47,39 @@ With the service running, the administrator can see the reserved subdomain for t ## Enable -After installing the `zrok-share` package above, save the zrok environment enable token from the zrok console in the configuration file, `/opt/openziti/etc/zrok/zrok-share.env`. +Save the enable token from the zrok console in the configuration file. -```bash +```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_ENABLE_TOKEN="14cbfca9772f" ``` ## Use Cases -You can change the share target by modifying the configuration file and restarting the service. This allows you to change the share target without having to reserve a new subdomain. +You can change the share target by modifying the configuration file and restarting the service. Changing the target does not require reserving a new subdomain. -You may switch between backend modes or change authentication options by deleting the `/var/lib/zrok-share/.zrok/reserved.json` file and restarting the service. A new subdomain will be reserved and the target will be shared using the new backend mode and authentication options. +You may switch between backend modes or change authentication options by deleting the `/var/lib/zrok-share/.zrok/reserved.json` file and restarting the service. A new subdomain will be reserved. ### Proxy a Web Server -Sharing a web server means that zrok will provide a public subdomain for an existing web server. The web server could be on a private network or on the same host as zrok. +Proxy a reserved subdomain to an existing web server. The web server could be on a private network or on the same host as zrok. -This uses zrok in the default `proxy` backend mode. Specify the target URL in the configuration file, `/opt/openziti/etc/zrok/zrok-share.env`. - -```bash +```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_TARGET="http://127.0.0.1:3000" ZROK_BACKEND_MODE="proxy" ``` ### Serve Static Files -This uses zrok's `web` backend mode, meaning that zrok will run an embedded web server that's configured to serve your files. If there's an `index.html` file in the directory then visitors will see the rendered page in their browser, otherwise they'll see the list of available files. The directory must be readable by 'other' users, i.e. `chmod o+rX /var/www/html`. +Run zrok's embedded web server to serve the files in a directory. If there's an `index.html` file in the directory then visitors will see that web page in their browser, otherwise they'll see a generated index of the directory. The directory must be readable by 'other' users, i.e. `chmod o+rX /var/www/html`. ```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_TARGET="/var/www/html" ZROK_BACKEND_MODE="web" ``` -Start the service, and check the zrok console or the service log for the reserved subdomain. - -```bash -sudo systemctl enable --now zrok-share.service -``` - ### WebDAV Server -This uses zrok's `drive` backend mode to serve a directory of static files as a WebDAV resource. The directory must be readable by 'other' users, i.e. `chmod o+rX /usr/share/doc`. Add the following to the configuration file. +This uses zrok's `drive` backend mode to serve a directory of static files as a WebDAV resource. The directory must be readable by 'other' users, i.e. `chmod o+rX /usr/share/doc`. ```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_TARGET="/usr/share/doc" @@ -100,7 +88,7 @@ ZROK_BACKEND_MODE="drive" ### Caddy Server -Use zrok's built-in Caddy server to serve static files or as a reverse proxy to multiple web servers with various HTTP routes or as a load-balanced set, or both. A sample Caddyfile is provided. Set these in the configuration file. +Use zrok's built-in Caddy server to serve static files or as a reverse proxy to multiple web servers with various HTTP routes or as a load-balanced set. A sample Caddyfile template is provided. Set these in the configuration file. ```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_TARGET="/opt/openziti/etc/zrok/multiple_upstream.Caddyfile" @@ -133,7 +121,13 @@ ZROK_BASIC_AUTH="user:passwd" Start the service, and check the zrok console or the service log for the reserved subdomain. ```bash +# run now and at startup sudo systemctl enable --now zrok-share.service + +# or + +# run now +sudo systemctl restart zrok-share.service ``` ```bash From 16f0b7639d0c1941282cacab4148acbf60fb29dc Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Wed, 15 Nov 2023 23:02:37 -0500 Subject: [PATCH 3/5] add package and testing info --- docs/guides/linux-service.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/guides/linux-service.md b/docs/guides/linux-service.md index eb9feadb..9a45bf6a 100644 --- a/docs/guides/linux-service.md +++ b/docs/guides/linux-service.md @@ -9,7 +9,7 @@ Proxy a reserved public subdomain to a backend target with a Linux service. ## Requirements -The Linux distribution must have a package manager that understands the `.deb` or `.rpm` format and be running systemd v232 or newer. This includes Ubuntu 20+, +The Linux distribution must have a package manager that understands the `.deb` or `.rpm` format and be running systemd v232 or newer. The service was tested with Ubuntu 20-22, Debian 11-12, Rocky 8-9, and Fedora 37-38. ## How it Works @@ -55,9 +55,9 @@ ZROK_ENABLE_TOKEN="14cbfca9772f" ## Use Cases -You can change the share target by modifying the configuration file and restarting the service. Changing the target does not require reserving a new subdomain. +You may change the target for the current backend mode, e.g. `proxy`, by editing the configuration file and restarting the service. The reserved subdomain will remain the same. -You may switch between backend modes or change authentication options by deleting the `/var/lib/zrok-share/.zrok/reserved.json` file and restarting the service. A new subdomain will be reserved. +You may switch between backend modes or change authentication options by deleting `/var/lib/zrok-share/.zrok/reserved.json` and restarting the service. A new subdomain will be reserved. ### Proxy a Web Server @@ -120,16 +120,18 @@ ZROK_BASIC_AUTH="user:passwd" Start the service, and check the zrok console or the service log for the reserved subdomain. -```bash -# run now and at startup +```bash title="run now and at startup" sudo systemctl enable --now zrok-share.service +``` -# or - -# run now +```bash title="run now" sudo systemctl restart zrok-share.service ``` ```bash journalctl -u zrok-share.service ``` + +## Package Contents + +The files included in the `zrok-share` package are sourced [here in GitHub](https://github.com/openziti/zrok/tree/main/nfpm). From 51b4fb2a4505deb53df4834eb1dfc2537b3b3f06 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Wed, 15 Nov 2023 23:17:38 -0500 Subject: [PATCH 4/5] refine service guide --- docs/guides/linux-service.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/linux-service.md b/docs/guides/linux-service.md index 9a45bf6a..9dae82b3 100644 --- a/docs/guides/linux-service.md +++ b/docs/guides/linux-service.md @@ -70,7 +70,7 @@ ZROK_BACKEND_MODE="proxy" ### Serve Static Files -Run zrok's embedded web server to serve the files in a directory. If there's an `index.html` file in the directory then visitors will see that web page in their browser, otherwise they'll see a generated index of the directory. The directory must be readable by 'other' users, i.e. `chmod o+rX /var/www/html`. +Run zrok's embedded web server to serve the files in a directory. If there's an `index.html` file in the directory then visitors will see that web page in their browser, otherwise they'll see a generated index of the files. The directory must be readable by 'other', e.g. `chmod -R o+rX /var/www/html`. ```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_TARGET="/var/www/html" @@ -79,7 +79,7 @@ ZROK_BACKEND_MODE="web" ### WebDAV Server -This uses zrok's `drive` backend mode to serve a directory of static files as a WebDAV resource. The directory must be readable by 'other' users, i.e. `chmod o+rX /usr/share/doc`. +This uses zrok's `drive` backend mode to serve a directory of static files as a WebDAV resource. The directory must be readable by 'other', e.g. `chmod -R o+rX /usr/share/doc`. ```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_TARGET="/usr/share/doc" @@ -88,7 +88,7 @@ ZROK_BACKEND_MODE="drive" ### Caddy Server -Use zrok's built-in Caddy server to serve static files or as a reverse proxy to multiple web servers with various HTTP routes or as a load-balanced set. A sample Caddyfile template is provided. Set these in the configuration file. +Use zrok's built-in Caddy server to serve static files or as a reverse proxy to multiple web servers with various HTTP routes or as a load-balanced set. A sample Caddyfile is available in the path shown. ```bash title="/opt/openziti/etc/zrok/zrok-share.env" ZROK_TARGET="/opt/openziti/etc/zrok/multiple_upstream.Caddyfile" @@ -97,7 +97,7 @@ ZROK_BACKEND_MODE="caddy" ## Authentication -You can require a password or OAuth email address suffix. +You can limit access to certain email addresses with OAuth or require a password. ### OAuth From 04df0f1878f7e52af6f24841e11bcd313840b850 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Thu, 16 Nov 2023 12:51:35 -0500 Subject: [PATCH 5/5] organize the compatibility/requirements stuff at the bottom of the page --- docs/guides/linux-service.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/guides/linux-service.md b/docs/guides/linux-service.md index 9dae82b3..d759e144 100644 --- a/docs/guides/linux-service.md +++ b/docs/guides/linux-service.md @@ -7,10 +7,6 @@ sidebar_position: 40 Proxy a reserved public subdomain to a backend target with a Linux service. -## Requirements - -The Linux distribution must have a package manager that understands the `.deb` or `.rpm` format and be running systemd v232 or newer. The service was tested with Ubuntu 20-22, Debian 11-12, Rocky 8-9, and Fedora 37-38. - ## 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: @@ -132,6 +128,15 @@ sudo systemctl restart zrok-share.service journalctl -u zrok-share.service ``` +## Compatibility + +The Linux distribution must have a package manager that understands the `.deb` or `.rpm` format and be running systemd v232 or newer. The service was tested with: + +* Ubuntu 20.04, 22.04, 23.04 +* Debian 11 12 +* Rocky 8, 9 +* Fedora 37, 38 + ## Package Contents The files included in the `zrok-share` package are sourced [here in GitHub](https://github.com/openziti/zrok/tree/main/nfpm).