diff --git a/docs/secure-connections/sauce-connect-5.md b/docs/secure-connections/sauce-connect-5.md index a8f5625817..806368994b 100644 --- a/docs/secure-connections/sauce-connect-5.md +++ b/docs/secure-connections/sauce-connect-5.md @@ -8,15 +8,19 @@ sidebar_label: Overview Sauce Connect Proxy 5 release is currently in the Alpha stage, some changes in CLI are expected. ::: -Sauce Connect Proxy 5 is a complete rewrite of Sauce Connect Proxy 4.x.x that aims to improve user experience and, also, provides a strong foundation for future improvements. +Sauce Connect Proxy 5 is a complete rewrite of Sauce Connect Proxy 4.x.x that aims to improve observability, performance, user experience and provide a strong foundation for future improvements. ## What You'll Need - If you're new to Sauce Connect, we recommend reviewing the [Sauce Connect Proxy overview](/secure-connections/sauce-connect) documentation. -## What's New In Sauce Connect Proxy 5 +## What's New In Sauce Connect Proxy 5? -1. Simplified onboarding and integration due to the secure connection (tunnel) protocol change. +:::caution +The Sauce Connect Proxy version 5 major release introduces CLI changes. Please refer to [Sauce Connect Proxy 5 CLI Reference](/dev/cli/sauce-connect-5/run/) for details. +::: + +1. Improved onboarding and integration due to the secure connection (tunnel) protocol change. The previous generation of Sauce Connect Proxy (version 4) used a custom [KGP](/secure-connections/sauce-connect/advanced/kgp/) protocol. The Sauce Connect Proxy version 5 uses HTTP/2 to establish a secure connection to Sauce Labs. Using standard well-documented protocol that is widely used in the industry simplifies Sauce Connect Proxy integration in secure CI/CD environments. 2. Performance improvement. @@ -26,6 +30,26 @@ Sauce Connect Proxy 5 utilizes much less memory and CPU resources which makes it 4. Observability improvement. Sauce Connect Proxy 5 comes with Prometheus metrics and a sample Grafana dashboard. + +### Major changes + +Sauce Connect Proxy 5 major changes are listed below. + +- The [Selenium Relay](/secure-connections/sauce-connect/proxy-tunnels/#using-the-selenium-relay) feature is not supported. +- Tunnels must be named, `--tunnel-name` flag is no longer optional. It's done to improve security and usability - tests that use Sauce Connect must explicitly specify the [tunnel name](/dev/test-configuration-options/#tunnelname). +- There is no default Sauce Labs region value, `--region` is required to ensure that the correct region is explicitly specified. +- Proxy auto-detection is not supported, all proxies must be specified with explicit flags - `--proxy` or `--pac` for SUT requests and `--proxy-sauce` for Sauce Labs REST API and tunnel connections. +- URL path matching with `--deny-domains` (`--fast-fail-regexps` in SC-4.x.x) is not supported + +The following flags are renamed to conform with the CLI naming scheme: + +- `--fast-fail-regexps` to `--deny-domains` +- `--no-ssl-bump-domains` to `--tls-passthrough-domains` + - `--tls-resign-domains` flag will be added shortly +- `--status-address` to `--api-address` +- `--dns` to `--dns-server` +- `--cainfo` to `--cacert-file` + ## Getting Started With Sauce Connect Proxy 5 Sauce Connect Proxy 5 network requirements are very similar to the previous generation of Sauce Connect Proxy (version 4). The main difference is that Sauce Connect Proxy 5 doesn't initiate non-HTTP connections. diff --git a/docs/secure-connections/sauce-connect-5/installation.md b/docs/secure-connections/sauce-connect-5/installation.md index 5a5830ab76..86f468a6f2 100644 --- a/docs/secure-connections/sauce-connect-5/installation.md +++ b/docs/secure-connections/sauce-connect-5/installation.md @@ -29,56 +29,56 @@ This topic describes where and how to download Sauce Connect Proxy to your local Linux x86_64 - sauce-connect-5.0.0-alpha7_linux.x86_64.tar.gz + sauce-connect-5.0.0-alpha8_linux.x86_64.tar.gz - sauce-connect_5.0.0-alpha7.linux_amd64.deb + sauce-connect_5.0.0-alpha8.linux_amd64.deb - sauce-connect-5.0.0-alpha7_linux.x86_64.rpm + sauce-connect-5.0.0-alpha8_linux.x86_64.rpm Linux arm64 - sauce-connect-5.0.0-alpha7_linux.aarch64.tar.gz + sauce-connect-5.0.0-alpha8_linux.aarch64.tar.gz - sauce-connect_5.0.0-alpha7.linux_arm64.deb + sauce-connect_5.0.0-alpha8.linux_arm64.deb - sauce-connect-5.0.0-alpha7_linux.aarch64.rpm + sauce-connect-5.0.0-alpha8_linux.aarch64.rpm Windows x86_64 - sauce-connect-5.0.0-alpha7_windows.x86_64.zip + sauce-connect-5.0.0-alpha8_windows.x86_64.zip Windows arm64 - sauce-connect-5.0.0-alpha7_windows.aarch64.zip + sauce-connect-5.0.0-alpha8_windows.aarch64.zip macOS - sauce-connect-5.0.0-alpha7_darwin.all.zip + sauce-connect-5.0.0-alpha8_darwin.all.zip -SHA256 checksums are [here](https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha7/checksums). +SHA256 checksums are [here](https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha8/checksums). 2. Install Sauce Connect Proxy @@ -95,37 +95,41 @@ SHA256 checksums are [here](https://saucelabs.com/downloads/sauce-connect-5.0.0- ```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-alpha7/sauce-connect-5.0.0-alpha7_linux.x86_64.tar.gz - tar xzf sauce-connect-5.0.0-alpha7_linux.x86_64.tar.gz + curl -sLO https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha8/sauce-connect-5.0.0-alpha8_linux.x86_64.tar.gz + tar xzf sauce-connect-5.0.0-alpha8_linux.x86_64.tar.gz ``` -
What's in the folder? - ```bash - $ tree . - ├── LICENSE - ├── LICENSE.3RD_PARTY - ├── completions - │   ├── sc.bash - │   ├── sc.fish - │   └── sc.zsh - └── sc - ``` -
+
What's in the folder? + + + ```bash + tree . + ├── LICENSE + ├── LICENSE.3RD_PARTY + ├── completions + │   ├── sc.bash + │   ├── sc.fish + │   └── sc.zsh + └── sc + ``` + +
+ ```bash cd /tmp - curl -sLO https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha7/sauce-connect_5.0.0-alpha7.linux_amd64.deb - sudo dpkg --skip-same-version --install sauce-connect_5.0.0-alpha7.linux_amd64.deb + curl -sLO https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha8/sauce-connect_5.0.0-alpha8.linux_amd64.deb + sudo dpkg --skip-same-version --install sauce-connect_5.0.0-alpha8.linux_amd64.deb ``` ```bash - sudo rpm -i https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha7/sauce-connect-5.0.0-alpha7_linux.x86_64.rpm + sudo rpm -i https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha8/sauce-connect-5.0.0-alpha8_linux.x86_64.rpm ``` @@ -139,15 +143,15 @@ SHA256 checksums are [here](https://saucelabs.com/downloads/sauce-connect-5.0.0- ```bash - sudo rpm -i https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha7/sauce-connect-5.0.0-alpha7_linux.x86_64.rpm + sudo rpm -i https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha8/sauce-connect-5.0.0-alpha8_linux.x86_64.rpm ``` ```bash title="Using Powershell (Windows)" - Invoke-RestMethod -Uri https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha7/sauce-connect-5.0.0-alpha7_windows.x86_64.zip -OutFile sauce-connect-5.0.0-alpha7.zip - Expand-Archive -Force -Path ./sauce-connect-5.0.0-alpha7.zip + Invoke-RestMethod -Uri https://saucelabs.com/downloads/sauce-connect-5.0.0-alpha8/sauce-connect-5.0.0-alpha8_windows.x86_64.zip -OutFile sauce-connect-5.0.0-alpha8.zip + Expand-Archive -Force -Path ./sauce-connect-5.0.0-alpha8.zip ``` @@ -157,7 +161,7 @@ SHA256 checksums are [here](https://saucelabs.com/downloads/sauce-connect-5.0.0- As an alternative to downloading the client, you can use the Sauce Connect Proxy Docker image to run it in a Docker container. ```bash -docker pull saucelabs/sauce-connect:5.0.0-alpha7 +docker pull saucelabs/sauce-connect:5.0.0-alpha8 ``` To learn more, see [Sauce Connect Docker Container Setup](/secure-connections/sauce-connect/setup-configuration/docker/). diff --git a/docs/secure-connections/sauce-connect-5/operation.md b/docs/secure-connections/sauce-connect-5/operation.md new file mode 100644 index 0000000000..8e21a930c0 --- /dev/null +++ b/docs/secure-connections/sauce-connect-5/operation.md @@ -0,0 +1,112 @@ +--- +id: operation +title: Sauce Connect Proxy 5 operations and administration +sidebar_label: Operations and Administration +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## What You'll Need + +- If you haven't already, make sure you can access the website or mobile app that you'll be testing from the Sauce Connect Proxy host. +- Check to see if you have any proxies that are required to access the public Internet. + +## Best Practice for Using Tunnels + +We recommend using a single Sauce Connect Proxy tunnel or tunnel pool for each test suite or build, and tearing it down at the end of your test. Your test automation framework should launch Sauce Connect Proxy before the test suite is triggered and shut it down when the suite finishes. + +### Security Considerations + +We recommend using a [YAML config file](/secure-connections/sauce-connect/setup-configuration/yaml-config/) or [setting environment variables](/secure-connections/sauce-connect/setup-configuration/environment-variables/) to hide sensitive information like your password ([--access-key](/dev/cli/sauce-connect-5/run/#--access-key)) and proxy credentials. This way, they won't be visible in the list of running processes. + +### Shared Tunnels + +Sauce Connect Proxy tunnel can be shared between multiple accounts in the same organization. To share a tunnel, start Sauce Connect Proxy with the [`--shared-tunnel`](/dev/cli/sauce-connect-proxy/#--shared-tunnel) flag. +For most Sauce Labs customers, your access to shared tunnels is determined by the permissions of the user who creates them. +Organization admins can create tunnels that any user on any team can use. +Team admins can create tunnels that any member of their team can use. Team members cannot share tunnels they create with any other team member. + +For more information about user roles and permissions, see [User Roles](/basics/acct-team-mgmt/managing-user-info). + +In order to use a tunnel that an admin or team member shares with you, you'll need to add [`tunnelOwner`](https://docs.saucelabs.com/dev/test-configuration-options/#tunnelowner) to your test capabilities and specify that person's username. + +## Installing Sauce Connect Proxy + +See the [installation instructions](/secure-connections/sauce-connect-5/installation/) + +## Starting Sauce Connect Proxy + +Every Sauce Connect Proxy tunnel spins up a fresh virtual machine (VM) that is used only for your tests. Once the tunnel is closed, VMs are destroyed. + +1. Make sure that the directory containing the `sc` binary is in the `$PATH`. Otherwise, you will have to specify the path to the binary in the command line, `/path/to/sc` +2. Define environment variables containing the required values: your user name, access key and Sauce Labs region + +```bash +SAUCE_USER= +SAUCE_ACCESS_KEY= +SAUCE_REGION= +``` + +:::note +If you don't define environment variables, you can specify the command line options or you can add all values to the configuration file. +::: + +3. Start Sauce Connect Proxy + + + + + +```bash +sc run --tunnel-name $SAUCE_TUNNEL_NAME +``` + +Or without environment variables: + +```bash +sc run --user --access-key --region --tunnel-name $SAUCE_TUNNEL_NAME +``` + + + + +```bash +sc run --tunnel-name $SAUCE_TUNNEL_NAME +``` + +Or without environment variables: + +```bash +sc run --user --access-key --region --tunnel-name $SAUCE_TUNNEL_NAME +``` + + + + +## Monitoring Tunnels + +### Web UI + +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. | +| 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. | + +## More Information + +- [Sauce Connect Proxy Overview](/secure-connections/sauce-connect/) +- [Sauce Connect Proxy 5 CLI Reference](/dev/cli/sauce-connect-5/run/)