Documenting Sauce Connect debian and systemd (#2456)

saucelabs · Sep 26, 2023 · d7a1c0b · d7a1c0b
1 parent 7575ad7
commit d7a1c0b
Show file tree

Hide file tree

Showing 2 changed files with 133 additions and 39 deletions.
diff --git a/docs/secure-connections/sauce-connect-5/installation.md b/docs/secure-connections/sauce-connect-5/installation.md
@@ -88,20 +88,20 @@ SHA256 checksums are available [here](https://saucelabs.com/downloads/sauce-conn
 
 <Tabs
 defaultValue="Linux/macOS"
-   values={[
-     {label: 'Linux/macOS Binary', value: 'Linux/macOS'},
-     {label: 'Linux Debian', value: 'Debian'},
-     {label: 'Linux RPM', value: 'RPM'},
-     {label: 'macOS brew', value: 'brew'},
-     {label: 'Windows (Powershell)', value: 'Windows'},
-   ]}>
-  <TabItem value="Linux/macOS">
+  values={[
+    {label: 'Linux/macOS Binary', value: 'Linux/macOS'},
+    {label: 'Linux Debian', value: 'Debian'},
+    {label: 'Linux RPM', value: 'RPM'},
+    {label: 'macOS brew', value: 'brew'},
+    {label: 'Windows (Powershell)', value: 'Windows'},
+  ]}>
+<TabItem value="Linux/macOS">
 
-  ```bash
-  mkdir $HOME/sauce-connect-5.0.0-alpha && cd $HOME/sauce-connect-5.0.0-alpha
-  curl -sLO https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha9/sauce-connect-5.0.0-alpha9_linux.x86_64.tar.gz
-  tar xzf sauce-connect-5.0.0-alpha9_linux.x86_64.tar.gz
-  ```
+```bash
+mkdir $HOME/sauce-connect-5.0.0-alpha && cd $HOME/sauce-connect-5.0.0-alpha
+curl -sLO https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha9/sauce-connect-5.0.0-alpha9_linux.x86_64.tar.gz
+tar xzf sauce-connect-5.0.0-alpha9_linux.x86_64.tar.gz
+```
 
 <details><summary>What's in the folder?</summary>
 
@@ -123,43 +123,69 @@ defaultValue="Linux/macOS"
 
   <TabItem value="Debian">
 
+```bash
+arch=$(dpkg --print-architecture)
+sc_version=5.0.0-alpha9
+curl -sLO https://saucelabs.com/downloads/sauce-connect-${sc_version}/sauce-connect_${sc_version}.linux_${arch}.deb
+sudo dpkg --skip-same-version --install sauce-connect_${sc_version}.linux_${arch}.deb
+rm sauce-connect_${sc_version}.linux_${arch}.deb
+```
+
+<details><summary>What does the Sauce Connect Debian package install</summary>
+
+- Sauce Connect Proxy binary is in `/usr/bin/sc`
+- The enviroment variables file template is in `/etc/default/sauce-connect`. The file may be modified to include your configuration, , see [Running systemd service on Debian-based Linux](/secure-connections/sauce-connect-5/operation/#running-systemd-service-on-debian-based-linux)
   ```bash
-  arch=$(dpkg --print-architecture)
-  sc_version=5.0.0-alpha9
-  curl -sLO https://saucelabs.com/downloads/sauce-connect-${sc_version}/sauce-connect_${sc_version}.linux_${arch}.deb
-  sudo dpkg --skip-same-version --install sauce-connect_${sc_version}.linux_${arch}.deb
-  rm sauce-connect_${sc_version}.linux_${arch}.deb
+  cat /etc/default/sauce-connect
+  # Default values for Sauce Connect Proxy
+  #SAUCE_CONFIG_FILE=/etc/sauce-connect/config.yaml
+  # Required values
+  #SAUCE_USER=
+  #SAUCE_ACCESS_KEY=
+  #SAUCE_REGION=
+  #SAUCE_TUNNEL_NAME=
+  # Options
+  #SAUCE_SHARED_TUNNEL=
+  #SAUCE_TUNNEL_POOL=
+  # See https://docs.saucelabs.com/dev/cli/sauce-connect-5/ for all environment variable values
   ```
+- Systemd service is enabled, see [Running systemd service on Debian-based Linux](/secure-connections/sauce-connect-5/operation/#running-systemd-service-on-debian-based-linux)
+
+</details>
+
   </TabItem>
 
   <TabItem value="RPM">
 
-  ```bash
-  sudo rpm -i https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha9/sauce-connect-5.0.0-alpha9_linux.x86_64.rpm
-  ```
+```bash
+sudo rpm -i https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha9/sauce-connect-5.0.0-alpha9_linux.x86_64.rpm
+```
+
   </TabItem>
 
   <TabItem value="brew">
 
-  :::caution
-  To be updated
-  :::
+:::caution
+To be updated
+:::
 
   </TabItem>
 
   <TabItem value="RPM">
 
-  ```bash
-  sudo rpm -i https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha9/sauce-connect-5.0.0-alpha9_linux.x86_64.rpm
-  ```
+```bash
+sudo rpm -i https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha9/sauce-connect-5.0.0-alpha9_linux.x86_64.rpm
+```
+
   </TabItem>
 
   <TabItem value="Windows">
 
-  ```bash title="Using Powershell (Windows)"
-  Invoke-RestMethod -Uri https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha9/sauce-connect-5.0.0-alpha9_windows.x86_64.zip -OutFile sauce-connect-5.0.0-alpha9.zip
-  Expand-Archive -Force -Path ./sauce-connect-5.0.0-alpha9.zip
-  ```
+```bash title="Using Powershell (Windows)"
+Invoke-RestMethod -Uri https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha9/sauce-connect-5.0.0-alpha9_windows.x86_64.zip -OutFile sauce-connect-5.0.0-alpha9.zip
+Expand-Archive -Force -Path ./sauce-connect-5.0.0-alpha9.zip
+```
+
   </TabItem>
 </Tabs>
 

diff --git a/docs/secure-connections/sauce-connect-5/operation.md b/docs/secure-connections/sauce-connect-5/operation.md
@@ -96,15 +96,83 @@ sc run --user <your user> --access-key <your access key> --region <us-west|eu-ce
 
 You can manage and monitor all Sauce Connect Proxy tunnel activity from the Sauce Labs [**Tunnels**](https://app.saucelabs.com/tunnels) page, which displays useful information, such as the number of active tunnels, tunnel status, and specific attributes for each tunnel. You can also check the health of an individual tunnel by running a test on it.
 
-| Column          | Description                                                                                                                                           |
-| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Type            | The icon shows whether the tunnel is a Sauce Connect Proxy, or an IPSec Proxy.                                                            |
-| State           | The icon shows whether the tunnel is running or stopped.                                                                                              |
+| Column          | Description                                                                                                                                     |
+| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Type            | The icon shows whether the tunnel is a Sauce Connect Proxy, or an IPSec Proxy.                                                                  |
+| State           | The icon shows whether the tunnel is running or stopped.                                                                                        |
 | Tunnel Name     | The name of the tunnel. This is the [`--tunnel-name`](/dev/cli/sauce-connect-5/run/#--tunnel-name) used when starting the Sauce Connect tunnel. |
-| Client Hostname | The name of the machine where the Sauce Connect Proxy client is running.                                                                              |
-| Owner           | The name of the account that is running the tunnel.                                                                                                   |
-| Sharing         | Indicates whether or not the tunnel is shared.                                                                                                        |
-| Duration        | The amount of time the tunnel has been running.                                                                                                       |
+| Client Hostname | The name of the machine where the Sauce Connect Proxy client is running.                                                                        |
+| Owner           | The name of the account that is running the tunnel.                                                                                             |
+| Sharing         | Indicates whether or not the tunnel is shared.                                                                                                  |
+| Duration        | The amount of time the tunnel has been running.                                                                                                 |
+
+## Service Management Tools
+
+Running Sauce Connect Proxy as a service is recommended when your tests often require an active secure connection and, operationally, it's complicated to set up a tunnel just before each test suite.
+The following options are available:
+
+- [Running a containerized Sauce Connect Proxy](/secure-connections/sauce-connect/setup-configuration/docker/#running-the-sauce-connect-proxy-container-indefinitely-in-kubernetes)
+- Running a systemd service
+
+### Running systemd service on Debian-based Linux
+
+1. [Install](/secure-connections/sauce-connect-5/installation/) Debian package
+2. Create your Sauce Connect configuration file
+
+- Sauce Connect Proxy YAML config file
+- Create an env file containing `SAUCE_CONFIG_FILE` for the systemd service to be able to locate your YAML configuration file
+
+```bash
+mkdir /etc/sauce-connect
+cat <<EOF >> /etc/sauce-connect/env
+SAUCE_CONFIG_FILE=/etc/sauce-connect/sc.yaml
+EOF
+```
+
+- Create a configuration file containing your Sauce Connect Proxy configuration
+
+```bash
+cat <<EOF >> /etc/sauce-connect/sc.yaml
+region=us-west
+user=xxx
+access-key=xxx
+tunnel-name=my-systemd-sc
+EOF
+```
+
+3. Customize the systemd unit file
+
+- Running `systemctl edit sauce-connect` will open an editor that allows adding overrides
+- Add your overrides (that systemd will save in `/etc/systemd/system/sauce-connect.service.d/override.conf`)
+
+```bash
+[Service]
+EnvironmentFile=/etc/sauce-connect/env
+```
+
+4. Validate your systemd overrides
+
+```bash
+systemctl cat sauce-connect
+  # /lib/systemd/system/sauce-connect.service
+  [Unit]
+  Description=Sauce Connect Proxy Service
+  After=network-online.target
+
+  [Service]
+  EnvironmentFile=/etc/default/sauce-connect
+  …
+
+  # /etc/systemd/system/sauce-connect.service.d/override.conf
+  [Service]
+  EnvironmentFile=/etc/sauce-connect/env
+```
+
+5. Start the service
+
+```bash
+systemctl start sauce-connect
+```
 
 ## More Information