diff --git a/scripts/boringproxy-client@.service b/scripts/boringproxy-client@.service new file mode 100644 index 0000000..2b18565 --- /dev/null +++ b/scripts/boringproxy-client@.service @@ -0,0 +1,13 @@ +[Unit] +Description=BoringProxy Client (%I client) +After=network.target + +[Service] +PrivateTmp=true +Type=simple +User=root +Group=root +ExecStart=/usr/local/bin/boringproxy client -server bp.example.com -token your-bp-server-token -client-name %i + +[Install] +WantedBy=multi-user.target \ No newline at end of file diff --git a/scripts/boringproxy-server.service b/scripts/boringproxy-server.service new file mode 100644 index 0000000..7692e23 --- /dev/null +++ b/scripts/boringproxy-server.service @@ -0,0 +1,14 @@ +[Unit] +Description=BoringProxy Server +After=network.target + +[Service] +PrivateTmp=true +Type=simple +User=root +Group=root +WorkingDirectory=/root/ +ExecStart=/usr/local/bin/boringproxy server -admin-domain bp.example.com + +[Install] +WantedBy=multi-user.target diff --git a/systemd-integration.md b/systemd-integration.md new file mode 100644 index 0000000..6719aea --- /dev/null +++ b/systemd-integration.md @@ -0,0 +1,91 @@ +# Systemd Integration + +These instructions assume that you have followed the [Installation instruction](https://boringproxy.io/#installation) and installed the boringproxy binary to `/usr/local/bin/` + +If you install the binary to a different path you will need to update the path in the service files. + +--- + +## BoringProxy Server Service +This service file along with the assumptions above assumes that you will run the initial launch of the server from the `/root` directory as the `root` user. + +Download the boringproxy-server.service file +```bash +# with wget +sudo wget https://raw.githubusercontent.com/boringproxy/boringproxy/master/scripts/boringproxy-server.service -O /etc/systemd/system/boringproxy-server.service + +# or with curl +sudo curl https://raw.githubusercontent.com/boringproxy/boringproxy/master/scripts/build.sh --output /etc/systemd/system/boringproxy-server.service +``` + +Edit `/etc/systemd/system/boringproxy-server.service` and replace the admin domain `bp.example.com` with the domain that the server will be available at. EX: `-admin-domain proxy.bpuser.me` + +Enable and start the boringproxy server service with the following command +```bash +sudo systemctl enable --now boringproxy-server.service +``` + +This will make sure that boringproxy server will always start backup if the host is restarted. + +--- + +## BoringProxy Client Service + +Download the boringproxy-client@.service file +```bash +# with wget +sudo wget https://raw.githubusercontent.com/boringproxy/boringproxy/master/scripts/boringproxy-client%40.service -O "/etc/systemd/system/boringproxy-client@.service" + +# or with curl +sudo curl https://raw.githubusercontent.com/boringproxy/boringproxy/master/scripts/boringproxy-client%40.service --output "/etc/systemd/system/boringproxy-client@.service" +``` + +Edit `/etc/systemd/system/boringproxy-client@.service` and replace the server address `bp.example.com` with the domain that the server is located at. EX: `-server proxy.bpuser.me` + +also edit the token value `your-bp-server-token` with the token from when you installed the server. EX: `-token rt42g.......3fn` + +Enable and start the boringproxy server service with the following command +```bash +# the value after the @ symbol in the service name is what will determine the name of the client in the Admin UI +sudo systemctl enable --now boringproxy-client@default.service +``` + +This will make sure that boringproxy client will always start backup and reconnect to the boringclient server if the host is restarted or goes down for some reason. + +### Notes + +This systemd service file is a template service which allows you to spawn multiple clients with a specified name. + +If you do not need/want the ability to launch multiple clients with a single service file and do not want to have to specify `boringproxy-client@.service` when interacting with the service, rename the service file to `boringproxy-client.service` and remove the `%I` from the `Description` field and replace the `%i` after `-client-name` with the name you want the client to have. after those modifications you can use the service as `boringproxy-client.service` + +--- + +## Using a user other than root + +As good practice tells us we really should not run services as the root user. If you would like to follow these best practices the service file `User`, `Group`, and `WorkingDirectory` values will need to be updated. + +The below commands will setup and fix the service file to use a user besides root +```bash +# create the system users homedir - This is needed as you need a place to store the `boringproxy_db.json` file +sudo mkdir -pv /opt/boringproxy + +# create the system user - We are using a system user as we don't want regular user permissions assigned since all it is going to be doing is running boringproxy for us. We also specify the shell as /bin/false so that nothing can login as this user just incase. +sudo useradd -d /opt/boringproxy -m --system --shell /bin/false boringproxy + +# If you have already launched the boringproxy server you need to move the db file to keep your settings +# mv /root/boringproxy_db.json /opt/boringproxy/boringproxy_db.json + +# Set the permissions just to make sure especially if you have moved the db file into the directory. +sudo chown boringproxy:boringproxy -R /opt/boringproxy +# You can also lock down the directory even further with the following if your somewhat paranoid +# chmod 700 /opt/boringproxy + +# update the service files to use the new user, group, and user home directory +# Server Service +sed -i "s/^User=.*/User=boringproxy/" /etc/systemd/system/boringproxy-server.service +sed -i "s/^Group=.*/Group=boringproxy/" /etc/systemd/system/boringproxy-server.service +sed -i "s/^WorkingDirectory=.*/WorkingDirectory=/opt/boringproxy/" /etc/systemd/system/boringproxy-server.service +# Client Service +sed -i "s/^User=.*/User=boringproxy/" /etc/systemd/system/boringproxy-client\@.service +sed -i "s/^Group=.*/Group=boringproxy/" /etc/systemd/system/boringproxy-client\@.service +``` \ No newline at end of file