From 95d319a4bc2dbd8a696aca98ab18358787cb9ef5 Mon Sep 17 00:00:00 2001 From: Willem Grobler <40760504+WGrobler@users.noreply.github.com> Date: Sat, 12 Feb 2022 09:23:19 +0200 Subject: [PATCH 1/5] Create README.md --- systemd/README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 systemd/README.md diff --git a/systemd/README.md b/systemd/README.md new file mode 100644 index 0000000..bc3a7a4 --- /dev/null +++ b/systemd/README.md @@ -0,0 +1,77 @@ +# Installing Service + +## Server + +The folling steps assume that boringproxy is already installed on the server. If you haven't installed the server, follow [installation](https://boringproxy.io/installation/) instructions in the documentation. + +boringproxy needs to be installed in **/usr/local/bin/boringproxy** for the default service file to work, this location can be changed in the service file + +### Create boringproxy user & group +The service will be run as user 'boringproxy'. Runnning the service as root is not recomended. + +Add user "boringproxy" +```bash +useradd -M boringproxy +``` + +Add group "boringproxy" +```bash +groupadd boringproxy; +``` + +Add user "boringproxy" to group "boringproxy" +```bash +usermod -a -G boringproxy boringproxy +``` + +### Download & edit service file + +Copy service file from GitHub +```bash +wget https://raw.githubusercontent.com/WGrobler/boringproxy/master/systemd/boringproxy-server.service +``` + +Edit service file to include your setup information + +Default working directory is ***"/opt/boringproxy/"***, you can change this in the service file to another directory. +Make sure the directory exists, otherwise create WorkingDirectory +```bash +mkdir -p /opt/boringproxy/ +``` + +Default location for your boringproxy executable file is ***"/usr/local/bin/boringproxy"***, you can change this in the service file to another path. +Make sure the file exists, otherwise move file from the current directory to ***"/usr/local/bin/boringproxy"*** +```bash +mv ./boringproxy /usr/local/bin/boringproxy +``` + +Reload the service files to include the new service. +```bash +systemctl daemon-reload +``` + +Start your service +```bash +systemctl start boringproxy-server.service +``` + +To check the status of your service +```bash +systemctl status boringproxy-server.service +``` + +To enable your service on every reboot +```bash +systemctl enable boringproxy-server.service +``` + +To disable your service on every reboot +```bash +systemctl disable boringproxy-server.service +``` + +## Client + +```bash +./boringproxy client -server bpdemo.brng.pro -token fKFIjefKDFLEFijKDFJKELJF -client-name demo-client -user demo-user +``` From a520d486ddc8ad12c0f42c8b5f1ae206530d82c6 Mon Sep 17 00:00:00 2001 From: Willem Grobler <40760504+WGrobler@users.noreply.github.com> Date: Sat, 12 Feb 2022 11:03:24 +0200 Subject: [PATCH 2/5] Update README.md --- systemd/README.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/systemd/README.md b/systemd/README.md index bc3a7a4..9502c52 100644 --- a/systemd/README.md +++ b/systemd/README.md @@ -11,7 +11,7 @@ The service will be run as user 'boringproxy'. Runnning the service as root is n Add user "boringproxy" ```bash -useradd -M boringproxy +useradd -s /bin/bash -d /home/boringproxy/ -m boringproxy; ``` Add group "boringproxy" @@ -24,6 +24,11 @@ Add user "boringproxy" to group "boringproxy" usermod -a -G boringproxy boringproxy ``` +Create SSH folder for user. BoringProxy assumes the folder already exists. If it does not exist, the program will fail to add tunnels. +```bash +mkdir /home/boringproxy/.ssh +``` + ### Download & edit service file Copy service file from GitHub @@ -45,11 +50,41 @@ Make sure the file exists, otherwise move file from the current directory to *** mv ./boringproxy /usr/local/bin/boringproxy ``` +### Install service file to systemd + +Copy service file to "/etc/systemd/system/" +```bash +mv ./boringproxy-server.service /etc/systemd/system/ +``` Reload the service files to include the new service. ```bash systemctl daemon-reload ``` +### Manual start (once off only) +When boringproxy start for the first time, it requires a manual input of your email address. This email address will be used when registering Certificates with Let's Encrypt. +By stating the server manually, you can enter the required information and ensure the server is starting correctly under the new user. + +To start the server, you will need to change the current directory to your WorkingDirectory (as indicated in your service file) and then run the ExecStart command (as indicated in your service file). If you made changes to the default WorkingDirectory or boringproxy executable file path, change the command below accordingly. +Change the admin-domain in the command below to your admin-domain and enter your email address when prompted +```bash +runuser -l boringproxy -c 'cd /opt/boringproxy; /usr/local/bin/boringproxy server -admin-domain bp.example.com' +``` + +If your server was successfully started, close the running process and start it again using the service. Since the process was started as a different user, you will have to kill the foreground process (***Ctrl + C***) as well as close the process started as user boringproxy. To kill all running processes for user boringproxy, use the command below: +```bash +pkill -u boringproxy +``` + +To check if boringproxy is still running, you can look if a process is listening on port 443 using: +```bash +netstat -tulpn | grep LISTEN | grep 443 +``` +If nothing is returned, no process is currently using port 443. Alternatively you will receive a result like: +***tcp6 0 0 :::443 :::* LISTEN 9461/boringproxy *** + +### Service commands + Start your service ```bash systemctl start boringproxy-server.service From 6783bba782b806f464ff4eff6f1b31641dd1ef4c Mon Sep 17 00:00:00 2001 From: Willem Grobler <40760504+WGrobler@users.noreply.github.com> Date: Sat, 12 Feb 2022 11:05:26 +0200 Subject: [PATCH 3/5] Update README.md --- systemd/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/systemd/README.md b/systemd/README.md index 9502c52..16af8e6 100644 --- a/systemd/README.md +++ b/systemd/README.md @@ -81,7 +81,7 @@ To check if boringproxy is still running, you can look if a process is listening netstat -tulpn | grep LISTEN | grep 443 ``` If nothing is returned, no process is currently using port 443. Alternatively you will receive a result like: -***tcp6 0 0 :::443 :::* LISTEN 9461/boringproxy *** +*tcp6 0 0 :::443 :::* LISTEN 9461/boringproxy* ### Service commands From b3d16e18a177255847fa2aa2d82010c50fc37adf Mon Sep 17 00:00:00 2001 From: Willem Grobler <40760504+WGrobler@users.noreply.github.com> Date: Sat, 12 Feb 2022 11:21:45 +0200 Subject: [PATCH 4/5] Update README.md --- systemd/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/systemd/README.md b/systemd/README.md index 16af8e6..12850e6 100644 --- a/systemd/README.md +++ b/systemd/README.md @@ -27,6 +27,7 @@ usermod -a -G boringproxy boringproxy Create SSH folder for user. BoringProxy assumes the folder already exists. If it does not exist, the program will fail to add tunnels. ```bash mkdir /home/boringproxy/.ssh +chown boringproxy:boringproxy /home/boringproxy/.ssh ``` ### Download & edit service file From e140bee71848ac9941198ac6a82fc5ce94e17fda Mon Sep 17 00:00:00 2001 From: "Willem@105.pve1.lan" Date: Sat, 12 Feb 2022 12:41:21 +0200 Subject: [PATCH 5/5] pre merge req changes --- systemd/README.md | 143 ++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 119 insertions(+), 24 deletions(-) diff --git a/systemd/README.md b/systemd/README.md index 12850e6..3e609a4 100644 --- a/systemd/README.md +++ b/systemd/README.md @@ -1,25 +1,30 @@ # Installing Service -## Server +A service is a program that runs in the background outside the interactive control of system users. Services can also be automatically started on boot. -The folling steps assume that boringproxy is already installed on the server. If you haven't installed the server, follow [installation](https://boringproxy.io/installation/) instructions in the documentation. +*The systemd service instructions were writen for Linux* -boringproxy needs to be installed in **/usr/local/bin/boringproxy** for the default service file to work, this location can be changed in the service file +# Prerequisites -### Create boringproxy user & group -The service will be run as user 'boringproxy'. Runnning the service as root is not recomended. +## Install boringproxy +The folling steps assume that boringproxy is already installed. If you haven't installed the server, follow [installation](https://boringproxy.io/installation/) instructions in the documentation. -Add user "boringproxy" +Boringproxy needs to be installed in **/usr/local/bin/boringproxy** for the default service file to work. If you want to use another path, this can be changed in the service file. + +## Create boringproxy user & group +The service will be run as user *boringproxy*. Runnning the service as *root* is not recomended. + +Add user *boringproxy* ```bash useradd -s /bin/bash -d /home/boringproxy/ -m boringproxy; ``` -Add group "boringproxy" +Add group *boringproxy* ```bash groupadd boringproxy; ``` -Add user "boringproxy" to group "boringproxy" +Add user *boringproxy* to group *boringproxy* ```bash usermod -a -G boringproxy boringproxy ``` @@ -30,30 +35,44 @@ mkdir /home/boringproxy/.ssh chown boringproxy:boringproxy /home/boringproxy/.ssh ``` -### Download & edit service file +## Server + +Installing the service on a boringproxy server + +### Download service file Copy service file from GitHub ```bash -wget https://raw.githubusercontent.com/WGrobler/boringproxy/master/systemd/boringproxy-server.service +wget https://raw.githubusercontent.com/boringproxy/boringproxy/master/systemd/boringproxy-server.service ``` -Edit service file to include your setup information +### Edit service file to include your setup information -Default working directory is ***"/opt/boringproxy/"***, you can change this in the service file to another directory. -Make sure the directory exists, otherwise create WorkingDirectory +#### Working Directory + +Default working directory is */opt/boringproxy/*, you can change this in the service file to another directory. + +Create the directory if it does not alreay exists ```bash mkdir -p /opt/boringproxy/ ``` +#### Boringproxy executable file path -Default location for your boringproxy executable file is ***"/usr/local/bin/boringproxy"***, you can change this in the service file to another path. -Make sure the file exists, otherwise move file from the current directory to ***"/usr/local/bin/boringproxy"*** +Default location for your boringproxy executable file is */usr/local/bin/boringproxy*, you can change this in the service file to another path. + +Move file from the downloaded directory to */usr/local/bin/boringproxy* ```bash mv ./boringproxy /usr/local/bin/boringproxy ``` +#### ExecStart + +Edit the service file and change *bp.example.com* to your admin-domain (the main domain configured in DNS). + + ### Install service file to systemd -Copy service file to "/etc/systemd/system/" +Copy service file to */etc/systemd/system/* ```bash mv ./boringproxy-server.service /etc/systemd/system/ ``` @@ -64,28 +83,37 @@ systemctl daemon-reload ### Manual start (once off only) When boringproxy start for the first time, it requires a manual input of your email address. This email address will be used when registering Certificates with Let's Encrypt. -By stating the server manually, you can enter the required information and ensure the server is starting correctly under the new user. -To start the server, you will need to change the current directory to your WorkingDirectory (as indicated in your service file) and then run the ExecStart command (as indicated in your service file). If you made changes to the default WorkingDirectory or boringproxy executable file path, change the command below accordingly. -Change the admin-domain in the command below to your admin-domain and enter your email address when prompted +By stating the server manually, you can enter the required information and ensure the server is starting correctly under the new user. + +To start the server, you will need to change the current directory to your WorkingDirectory (as indicated in your service file) and then run the ExecStart command (as indicated in your service file). If you made changes to the default WorkingDirectory or boringproxy executable file path, change the command below accordingly. + +If no changes were made to the default paths, change the *admin-domain* in the command below to your *admin-domain* and enter your email address when prompted ```bash runuser -l boringproxy -c 'cd /opt/boringproxy; /usr/local/bin/boringproxy server -admin-domain bp.example.com' ``` -If your server was successfully started, close the running process and start it again using the service. Since the process was started as a different user, you will have to kill the foreground process (***Ctrl + C***) as well as close the process started as user boringproxy. To kill all running processes for user boringproxy, use the command below: +If your server was successfully started, close the running process and start it again using the service. + +Since the process was started as a different user, you will have to kill the foreground process (***Ctrl + C***) as well as close the process started as user *boringproxy*. + +To kill all running processes for user *boringproxy*, use the command below: ```bash pkill -u boringproxy ``` -To check if boringproxy is still running, you can look if a process is listening on port 443 using: +To check if **boringproxy** is still running, you can look if a process is listening on port 443 using: ```bash netstat -tulpn | grep LISTEN | grep 443 ``` If nothing is returned, no process is currently using port 443. Alternatively you will receive a result like: -*tcp6 0 0 :::443 :::* LISTEN 9461/boringproxy* + +*tcp6 0 0 :::443 ::: LISTEN 9461/boringproxy* ### Service commands +After the above steps are completed, you can execute the service by using the commands below. + Start your service ```bash systemctl start boringproxy-server.service @@ -103,11 +131,78 @@ systemctl enable boringproxy-server.service To disable your service on every reboot ```bash -systemctl disable boringproxy-server.service +systemctl disable boringproxy-server.service ``` ## Client +Installing the service on a boringproxy client + +### Download service file + +Copy service file from GitHub ```bash -./boringproxy client -server bpdemo.brng.pro -token fKFIjefKDFLEFijKDFJKELJF -client-name demo-client -user demo-user +wget https://raw.githubusercontent.com/boringproxy/boringproxy/master/systemd/boringproxy-client%40.service ``` + +### Edit service file to include your setup information + +#### Working Directory + +Default working directory is */opt/boringproxy/*, you can change this in the service file to another directory. + +Create the directory if it does not alreay exists +```bash +mkdir -p /opt/boringproxy/ +``` +#### Boringproxy executable file path + +Default location for your boringproxy executable file is */usr/local/bin/boringproxy*, you can change this in the service file to another path. + +Move file from the downloaded directory to */usr/local/bin/boringproxy* +```bash +mv ./boringproxy /usr/local/bin/boringproxy +``` + +#### ExecStart + +Edit the service file and change the folowing: +- **bp.example.com** to your *admin-domain* +- **your-bp-server-token** to your user token + + +### Install service file to systemd + +Copy service file to */etc/systemd/system/* +*You can change your-server-name to any name you want to identify the server. This is usefull when connecting your client device to multiple servers using different client services.* +```bash +mv ./boringproxy-client@.service /etc/systemd/system/boringproxy-client@your-server-name.service +``` +Reload the service files to include the new service. +```bash +systemctl daemon-reload +``` + +### Service commands + +After the above steps are completed, you can execute the service by using the commands below. + +Start your service +```bash +systemctl start boringproxy-client@your-server-name.service +``` + +To check the status of your service +```bash +systemctl status boringproxy-client@your-server-name.service +``` + +To enable your service on every reboot +```bash +systemctl enable boringproxy-client@your-server-name.service +``` + +To disable your service on every reboot +```bash +systemctl disable boringproxy-client@your-server-name.service +``` \ No newline at end of file