From 7923dec9f597374f4ad121baa0ae03b29d578e9c Mon Sep 17 00:00:00 2001
From: boenshao <65853605+boenshao@users.noreply.github.com>
Date: Fri, 7 Jul 2023 18:57:26 +0800
Subject: [PATCH] docs: non root user with systemd (#269)

* doc: remove 'DynamicUser=yes', so the service can read config file with permission 600

* doc: add example for non-root systemd service

* fix(doc): should be 'app2.toml'
---
 examples/systemd/README.md         | 51 ++++++++++++++++++++++++++----
 examples/systemd/rathole@.service  |  7 ++--
 examples/systemd/ratholec.service  |  7 ++--
 examples/systemd/ratholec@.service |  7 ++--
 examples/systemd/ratholes.service  |  7 ++--
 examples/systemd/ratholes@.service |  7 ++--
 6 files changed, 70 insertions(+), 16 deletions(-)

diff --git a/examples/systemd/README.md b/examples/systemd/README.md
index c3fb285..030d29c 100644
--- a/examples/systemd/README.md
+++ b/examples/systemd/README.md
@@ -2,12 +2,16 @@
 
 The directory lists some systemd unit files for example, which can be used to run `rathole` as a service on Linux.
 
-[The `@` symbol in name of unit files](https://superuser.com/questions/393423/the-symbol-and-systemctl-and-vsftpd) such as
+[The `@` symbol in the name of unit files](https://superuser.com/questions/393423/the-symbol-and-systemctl-and-vsftpd) such as
 `rathole@.service` facilitates the management of multiple instances of `rathole`.
 
 For the naming of the example, `ratholes` stands for `rathole --server`, and `ratholec` stands for `rathole --client`, `rathole` is just `rathole`.
 
-Assuming that `rathole` is installed in `/usr/bin/rathole`, and the configuration file is in `/etc/rathole/app1.toml`, the following steps shows how to run an instance of `rathole --server`.
+For security, it is suggested to store configuration files with permission `600`, that is, only the owner can read the file, preventing arbitrary users on the system from accessing the secret tokens.
+
+### With root privilege
+
+Assuming that `rathole` is installed in `/usr/bin/rathole`, and the configuration file is in `/etc/rathole/app1.toml`, the following steps show how to run an instance of `rathole --server` with root.
 
 1. Create a service file.
 
@@ -22,14 +26,49 @@ sudo mkdir -p /etc/rathole
 # And create the configuration file named `app1.toml` inside /etc/rathole
 ```
 
-3. Enable and start the service
+3. Enable and start the service.
 
 ```bash
 sudo systemctl daemon-reload # Make sure systemd find the new unit
 sudo systemctl enable ratholes@app1 --now
 ```
 
-And if there's another configuration named `app2.toml` in `/etc/rathole`, then
-`sudo systemctl enable ratholes@app2 --now` can start an instance for that configuration.
+### Without root privilege
 
-The same applies to `rathole --client` and `rathole`.
+Assuming that `rathole` is installed in `~/.local/bin/rathole`, and the configuration file is in `~/.local/etc/rathole/app1.toml`, the following steps show how to run an instance of `rathole --server` without root.
+
+1. Edit the example service file as...
+
+```txt
+# with root
+# ExecStart=/usr/bin/rathole -s /etc/rathole/%i.toml
+# without root
+ExecStart=%h/.local/bin/rathole -s %h/.local/etc/rathole/%i.toml
+```
+
+2. Create a service file.
+
+```bash
+mkdir -p ~/.config/systemd/user
+cp ratholes@.service ~/.config/systemd/user/
+```
+
+3. Create the configuration file `app1.toml`.
+
+```bash
+mkdir -p ~/.local/etc/rathole
+# And create the configuration file named `app1.toml` inside ~/.local/etc/rathole
+```
+
+4. Enable and start the service.
+
+```bash
+systemctl --user daemon-reload # Make sure systemd find the new unit
+systemctl --user enable ratholes@app1 --now
+```
+
+### Run multiple services
+
+To run multiple services at once, simply add another configuration, say `app2.toml` under `/etc/rathole` (`~/.local/etc/rathole` for non-root), then run `sudo systemctl enable ratholes@app2 --now` (`systemctl --user enable ratholes@app2 --now` for non-root) to start an instance for that configuration.
+
+The same applies to `ratholec@.service` for `rathole --client` and `rathole@.service` for `rathole`.
diff --git a/examples/systemd/rathole@.service b/examples/systemd/rathole@.service
index 508ba32..001d9e9 100644
--- a/examples/systemd/rathole@.service
+++ b/examples/systemd/rathole@.service
@@ -4,11 +4,14 @@ After=network.target
 
 [Service]
 Type=simple
-DynamicUser=yes
 Restart=on-failure
 RestartSec=5s
-ExecStart=/usr/bin/rathole /etc/rathole/%i.toml
 LimitNOFILE=1048576
 
+# with root
+ExecStart=/usr/bin/rathole /etc/rathole/%i.toml
+# without root
+# ExecStart=%h/.local/bin/rathole %h/.local/etc/rathole/%i.toml
+
 [Install]
 WantedBy=multi-user.target
diff --git a/examples/systemd/ratholec.service b/examples/systemd/ratholec.service
index 742c750..5a532e3 100644
--- a/examples/systemd/ratholec.service
+++ b/examples/systemd/ratholec.service
@@ -4,11 +4,14 @@ After=network.target
 
 [Service]
 Type=simple
-DynamicUser=yes
 Restart=on-failure
 RestartSec=5s
-ExecStart=/usr/bin/rathole -c /etc/rathole/rathole.toml
 LimitNOFILE=1048576
 
+# with root
+ExecStart=/usr/bin/rathole -c /etc/rathole/rathole.toml
+# without root
+# ExecStart=%h/.local/bin/rathole -c %h/.local/etc/rathole/rathole.toml
+
 [Install]
 WantedBy=multi-user.target
diff --git a/examples/systemd/ratholec@.service b/examples/systemd/ratholec@.service
index 472a02e..c3a42d3 100644
--- a/examples/systemd/ratholec@.service
+++ b/examples/systemd/ratholec@.service
@@ -4,11 +4,14 @@ After=network.target
 
 [Service]
 Type=simple
-DynamicUser=yes
 Restart=on-failure
 RestartSec=5s
-ExecStart=/usr/bin/rathole -c /etc/rathole/%i.toml
 LimitNOFILE=1048576
 
+# with root
+ExecStart=/usr/bin/rathole -c /etc/rathole/%i.toml
+# without root
+# ExecStart=%h/.local/bin/rathole -c %h/.local/etc/rathole/%i.toml
+
 [Install]
 WantedBy=multi-user.target
diff --git a/examples/systemd/ratholes.service b/examples/systemd/ratholes.service
index 62e5031..333928a 100644
--- a/examples/systemd/ratholes.service
+++ b/examples/systemd/ratholes.service
@@ -4,11 +4,14 @@ After=network.target
 
 [Service]
 Type=simple
-DynamicUser=yes
 Restart=on-failure
 RestartSec=5s
-ExecStart=/usr/bin/rathole -s /etc/rathole/rathole.toml
 LimitNOFILE=1048576
 
+# with root
+ExecStart=/usr/bin/rathole -s /etc/rathole/rathole.toml
+# without root
+# ExecStart=%h/.local/bin/rathole -s %h/.local/etc/rathole/rathole.toml
+
 [Install]
 WantedBy=multi-user.target
diff --git a/examples/systemd/ratholes@.service b/examples/systemd/ratholes@.service
index c101612..b6834a6 100644
--- a/examples/systemd/ratholes@.service
+++ b/examples/systemd/ratholes@.service
@@ -4,11 +4,14 @@ After=network.target
 
 [Service]
 Type=simple
-DynamicUser=yes
 Restart=on-failure
 RestartSec=5s
-ExecStart=/usr/bin/rathole -s /etc/rathole/%i.toml
 LimitNOFILE=1048576
 
+# with root
+ExecStart=/usr/bin/rathole -s /etc/rathole/%i.toml
+# without root
+# ExecStart=%h/.local/bin/rathole -s %h/.local/etc/rathole/%i.toml
+
 [Install]
 WantedBy=multi-user.target