extern/zrok
1
1
Fork 0
mirror of https://github.com/openziti/zrok.git synced 2024-12-22 14:50:55 +01:00
Code Issues Packages Projects Releases Wiki Activity

refine service guide

Browse Source
This commit is contained in:
Kenneth Bingham 2023-11-15 22:10:37 -05:00
parent 258f994127
commit cebe0bcd63
No known key found for this signature in database
GPG Key ID: 31709281860130B6
1 changed files with 20 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
docs/guides/linux-service.md
View File

@ -5,11 +5,11 @@ sidebar_position: 40
## Goal ## 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 ## 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 ## 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: When the service starts it will:
1. enable the zrok environment unless an `environment.json` file already exists 1. enable the zrok environment unless `/var/lib/zrok-share/.zrok/environment.json` exists
1. reserve a public subdomain for the service unless `reserved.json` exists 1. reserve a public subdomain for the service unless `/var/lib/zrok-share/.zrok/reserved.json` exists
1. start sharing the target that was specified in the configuration file when the reservation was made 1. start sharing the target specified in the configuration file
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 ## Installation
`install.bash` scripts [the manual procedure](https://openziti.io/docs/downloads/?os=Linux).
1. Download the OpenZiti install script. 1. Download the OpenZiti install script.
```bash ```bash
@ -51,47 +47,39 @@ With the service running, the administrator can see the reserved subdomain for t
## Enable ## 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" ZROK_ENABLE_TOKEN="14cbfca9772f"
``` ```
## Use Cases ## 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 ### 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 title="/opt/openziti/etc/zrok/zrok-share.env"
```bash
ZROK_TARGET="http://127.0.0.1:3000" ZROK_TARGET="http://127.0.0.1:3000"
ZROK_BACKEND_MODE="proxy" ZROK_BACKEND_MODE="proxy"
``` ```
### Serve Static Files ### 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" ```bash title="/opt/openziti/etc/zrok/zrok-share.env"
ZROK_TARGET="/var/www/html" ZROK_TARGET="/var/www/html"
ZROK_BACKEND_MODE="web" 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 ### 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" ```bash title="/opt/openziti/etc/zrok/zrok-share.env"
ZROK_TARGET="/usr/share/doc" ZROK_TARGET="/usr/share/doc"
@ -100,7 +88,7 @@ ZROK_BACKEND_MODE="drive"
### Caddy Server ### 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" ```bash title="/opt/openziti/etc/zrok/zrok-share.env"
ZROK_TARGET="/opt/openziti/etc/zrok/multiple_upstream.Caddyfile" 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. Start the service, and check the zrok console or the service log for the reserved subdomain.
```bash ```bash
# run now and at startup
sudo systemctl enable --now zrok-share.service sudo systemctl enable --now zrok-share.service
# or
# run now
sudo systemctl restart zrok-share.service
``` ```
```bash ```bash