Skip to end of metadata
Go to start of metadata

The Situation

Sauce Connect includes options that let you start multiple "default," unnamed tunnels, or multiple tunnels with the same tunnel-identifier. We call this a Sauce Connect pool. From an end user or test runner perspective, a pool is the same as a single Sauce Connect instance. The pool allows for redundancy should one of the tunnels in the pool shut down or disconnect, as newly started tests will be assigned to an active tunnel in the pool.

This feature is useful if you:

  • Use high concurrency (run more than 200 jobs in parallel), since tunnel resource usage (memory, CPU) is limited on the Sauce Labs side
  • Would like to implement a highly available Sauce Connect setup, where a Sauce Connect instance on your side or a tunnel VM instance on the Sauce Labs side going down does not affect your tests
  • Would like to implement rolling restarts of Sauce Connect. In this case, you can start a new tunnel instance which new tests will start using, and shut down your "old" Sauce Connect instance without interruptions.

Network Diagram

On the Sauce Labs side, there are three major components: The Sauce Test VM, the Sauce Connect tunnel VM, and the Tunnel pool. When leveraging HA, the logic flow is:

  1. Test framework makes a request for a new Sauce Test VM, which specifies the tunnel ID of the pool (or uses an unnamed, "default" pool).
  2. A service in Sauce Labs chooses a tunnel from the existing pool at random.
  3. The resulting Tunnel from step #3 is assigned to the new test VM.

This diagram illustrates the basic setup leveraging high availability for Sauce Connect.

Rolling Restarts

Rolling restarts means Sauce Connect tunnels can be restarted and this action will be transparent to end users. For example, should a tunnel in a pool be sent a shutdown command, the tunnel will stay open until all tests associated with it have completed. At the same time, once the shutdown command has been sent, the tunnel is marked inactive in the eyes of the pool, and no new jobs will use it.

Multiple Network Routes

In this diagram, we see a setup that allows for multiple network routes when reaching the site(s) under test. There are variations to this of course, for example some of the Sauce Connect instances could be in the same network infrastructure as the site(s) under test. You can also imagine leveraging different virtual routes inside the same physical network. What is gained by setting up tunnels in this manner is redundancy for Sauce Connect tests should one network route fail.

 

Different Machine, But Same Network

The most important thing to understand about setting up Sauce Connect is that while it doesn't need to be set up on the same machine as the site or application you're testing, it must be on the same network. What Not to Do: Dysfunctional Sauce Connect Proxy Network Configurations illustrates some examples of network architectures in which Sauce Connect will not be able to create a tunnel, or will be too slow to carry out effective testing.  

Sauce Connect IP and Virtual Machine Range

Sauce Connect Proxy makes outbound connections to Sauce Labs using the following IP ranges:
  • 162.222.72.0/21 (this is equivalent to the range 162.222.72.1 – 162.222.79.254)
  • 66.85.48.0/21 (this is equivalent to the range 66.85.48.0 - 66.85.55.255)
  • 185.94.24.0/22 (this is equivalent to the range 185.94.24.0 - 185.94.27.255)

For saucelabs.com certificate authentication, the server hosting Sauce Connect may need to connect to Online Certificate Status Protocol (OCSP) or Certificate Revocation List (CRL) services as well. Check out Sauce Connect Certificate Handling for more info.

Using Multiple Machines for Failover

If you're setting up Sauce Connect Proxy with multiple tunnels in the high availability configuration to provide failover functionality, you should make sure to set up each tunnel to run on a separate machine. This way, if there is an issue with port availability or machine failure, you will still have active tunnels. If using the same machine for multiple tunnels, please ensure you've familiarized yourself with the setup instructions here for start Sauce Connect Proxy with unique ports for the selenium listener and scproxy, and file for the log and pid.


IP Ranges and Data Center Endpoints
Sauce Labs has data centers in both the US and EU. You can access Sauce Labs services from either location by providing the appropriate URL endpoints, and whitelisting their associated IP ranges. 

 US Data Center

Virtual Device Cloud: https://ondemand.saucelabs.com/wd/hub
Sauce Connect Proxy: https://saucelabs.com/rest
REST API:  https://saucelabs.com/rest/v1
IP Ranges:

162.222.72.0/21 (this is equivalent to the range 162.222.72.1 – 162.222.79.254)
66.85.48.0/21 (this is equivalent to the range 66.85.48.0 - 66.85.55.255)

Prerequisites

Setting Up Sauce Connect

  1. Download the appropriate version of Sauce Connect for your operating system. 

    Latest Stable Release

    4.5.2

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.5.2 for Mac OS 10.8+
    04d3aed5dd2391dba5ffb4ef7c07ebed2da0720d
    Download Sauce Connect v4.5.2 for Windows 7+
    03f8106ad947ecfa187ca31d355b55c89ae92d42
    Download Sauce Connect v4.5.2 for Linux
    2a923ca09bab5d8096844ace36f4a89994364482
    Download Sauce Connect v4.5.2 for Linux 32-bit
    57dba5324515157f0954ef47871a9963b2f5fc8e
     Click here to download past stable releases of Sauce Connect Proxy...

    4.5.1

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.5.1 for Mac OS 10.8+
    adb6c71c091a970a7126ccfa4157218a0e608174
    Download Sauce Connect v4.5.1 for Windows 7+
    a74d632a8f90763a98759e82200c9f8dca08e45b
    Download Sauce Connect v4.5.1 for Linux
    5ca9328724c5ff16b12ea49e7a748d44f7305be5
    Download Sauce Connect v4.5.1 for Linux 32-bit
    ad0359956e1cbb6fd45ad691d050b50534bff765

    4.5.0

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.5.0 for Mac OS 10.8+
    24913e3b442af323d62b94fbdd7ad218cec58534
    Download Sauce Connect v4.5.0 for Windows 7+
    f4668b9a4b7834c3aedf73a930695e3b9f492d06
    Download Sauce Connect v4.5.0 for Linux
    06e52acbbde3668a8effbf0dc970b40e32763fa6
    Download Sauce Connect v4.5.0 for Linux 32-bit
    2473df68b567098e14ac2199d14813c2be389867

    4.4.11

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.4.11 for OS X 10.12+
    9b8fe1342b94518b9a4e3bc7933cf93873461910
    Note: Contains a major bug on OS X 10.11 and below, please use SC 4.4.12 instead. 
    Download Sauce Connect v4.4.11 for Windows 7+
    c6e9f3f2a99411da00e22147918d50360af5f989
    Download Sauce Connect v4.4.11 for Linux
    4a70c3a559913274a35b056a6e5d274cdbe4fdec
    Download Sauce Connect v4.4.11 for Linux 32-bit
    d9c8bfefeecf9244eb0f543b60496d9a0f007437

    4.4.10

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.4.10 for OS X 10.8+
    d02832aa7879ee44722d6f65a7c7730696a41d09
    Download Sauce Connect v4.4.10 for Windows 7+
    7da842be68ac8391697d3dee8b231a6caf372a76
    Download Sauce Connect v4.4.10 for Linux
    dc0210fbc99a609f01c1a50a9fb6e77c2293cfd8
    Download Sauce Connect v4.4.10 for Linux 32-bit
    7da842be68ac8391697d3dee8b231a6caf372a76

    4.4.9

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.4.9 for OS X 10.8+
    80720ce6640a000d6d0fa84e8f4d692b90918f91
    Download Sauce Connect v4.4.9 for Windows 7+
    4ecdacbb8b25f62308a4a39c624bf1e1dc3fde45
    Download Sauce Connect v4.4.9 for Linux
    733745d519cde6def195878140340ecb806cdf21
    Download Sauce Connect v4.4.9 for Linux 32-bit
    7add5bee0fce38a008909cdc75522063e6f45f0b

    4.4.8

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.4.8 for OS X 10.8+
    8964dde5a902842f1f26e3a2e47094a9146b06e2
    Download Sauce Connect v4.4.8 for Windows 7+
    ab61fc041f5d418eb9f3f75b4495f38cacfb35fd
    Download Sauce Connect v4.4.8 for Linux
    e0ec01aba8bd523838349af54582a2674b107dbb
    Download Sauce Connect v4.4.8 for Linux 32-bit
    779552aa573a675629bf42a9410454dc3286e958

    4.4.7

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.4.7 for OS X 10.8+
    6f3e693135294e536cd99fc9f9d3b55532c68172
    Download Sauce Connect v4.4.7 for Windows 7+
    2ada3428a1f291c7c669f96009295582d2d7438b
    Download Sauce Connect v4.4.7 for Linux
    edb6816c873cc4cdf1d099e1534778d35f184942
    Download Sauce Connect v4.4.7 for Linux 32-bit
    adf56c6e098e9512179f0cc03848e948e5f9dbc2

    4.4.6

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.4.6 for OS X 10.8+
    b0a2307391e5606018437d9ec7aca41a48c8f6f0
    Download Sauce Connect v4.4.6 for Windows 7+
    6e8523b674b01618098a89cde38a6eb127191b27
    Download Sauce Connect v4.4.6 for Linux
    9c47e879ad504442a9a050f2bc1fca104d82b4da
    Download Sauce Connect v4.4.6 for Linux 32-bit
    98a52ab215b62b649e0455b75a9cc598d0024812


    4.4.5

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.4.5 for OS X 10.8+

    49829d719e46a398504deda77dc3a13ac8b31dd9

    Download Sauce Connect v4.4.5 for Windows 7+

    e8f84a1ec4ce1acabdbd489e22d577949dbfb61c

    Download Sauce Connect v4.4.5 for Linux

    ee0f6d4a52975d55c4c005d9730f0bef533d1878

    Download Sauce Connect v4.4.5 for Linux 32-bit aa42f7d16a59474efd950c604f996bdcc2d45544

    4.4.4

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.4.4 for OS X 10.8+

    71e4961900f7ad19c33ad59b543051a7524611da

    Download Sauce Connect v4.4.4 for Windows 7+

    f6f258439cf86f5c54d1a990fecb6b5197eb073e

    Download Sauce Connect v4.4.4 for Linux

    d0992449388560c89b25f996cc163a3ffd09922a

    Download Sauce Connect v4.4.4 for Linux 32-bit

    ede12d6c95ef8b90bbba34ee2ab98d467cc229da

    4.4.3

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.4.3 for OS X 10.8+

    f5d6d0a8727e0b91225d3af03555092bd72a70a3

    Download Sauce Connect v4.4.3 for Windows 7+

    4b4445c95d722e43c09c41eac5fa6659cacd2b45

    Download Sauce Connect v4.4.3 for Linux

    c675da6d59da873502f87dfdfa76a528bd702d92

    Download Sauce Connect v4.4.3 for Linux 32-bit

    fa668557a672200df86f4dc8e85d573fce5dc7c0


    4.4.2

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.4.2 for OS X 10.8+
    a7e04143c3150975e72ae8fef38067d2752dec8f
    Download Sauce Connect v4.4.2 for Windows 7+
    697646350a7ea0a446ac4c55853aa20514a7984c
    Download Sauce Connect v4.4.2 for Linux
    57a07a14c5d95d72b6606ba34fceaf5bf76c2865
    Download Sauce Connect v4.4.2 for Linux 32-bit
    d45a7befba6355767d5ca868137ee9332628a790

    4.4.1

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.4.1 for OS X 10.8+
    7962a635b66a7a015c7a5f62d6f36bca7c923062
    Download Sauce Connect v4.4.1 for Windows 7+
    4942e4d4e050e218043f81f877034bbddf87f9dd
    Download Sauce Connect v4.4.1 for Linux
    eb15689b0a3e23bee9737e36d6d925a77ae16989
    Download Sauce Connect v4.4.1 for Linux 32-bit
    6542956db84eae9bcbe604a9054aa9079923fdad

  2. On the machine where you want to install Sauce Connect, open outbound port 443 for sending Selenium commands from Sauce Connect to the Sauce Labs virtual machine, and inbound port 4445 for receiving Selenium commands (inbound port 4445 only needs to be open for connections within your network from the machine where your test scripts are running, and only if you use Sauce Connect's Selenium Relay, which by default listens on port 4445).
  3. After extracting the Sauce Connect files onto your machine, go to the install directory and run the -u and -k commands to authenticate against your Sauce Labs account and establish the Sauce Connect tunnel.

    When running in Mac or Linux:
    bin/sc -u YOUR_USERNAME -k YOUR_ACCESS_KEY
    When running in Windows:
    bin\sc.exe -u YOUR_USERNAME -k YOUR_ACCESS_KEY
    Defining the datacenter with -x command
    bin/sc -u YOUR_USERNAME -k YOUR_ACCESS_KEY -x https://saucelabs.com/rest/v1

    Finding Your Username and Access Key

    You can find your Sauce Labs username and access key in the User Profile > User Settings section of your Sauce Labs dashboard. You should also check out our topic on setting your username and access key as environment variables.
  4. When you see connectedlog in to your Sauce Labs account and click the Tunnels dashboard link.
    Under Active Tunnels, you should see the tunnel you just started.  

Using the tunnelIdentifier Option for Automated Tests

Once you have launched a Sauce Connect Proxy tunnel, you need to use the tunnelIdentifier option in the desired capabilities of your automated tests to run your tests through that tunnel.  For example, if your tunnel is named myTunnel01, you would need to set this option as "tunnelIdentifier": "myTunnel01". If you are starting and stopping Sauce Connect Proxy programmatically, you can make sure your tunnel always launches with the same name by passing the identifier flag, -i, with your authentication credentials, for example: bin/sc -u YOUR_USERNAME -k YOUR_ACCESS_KEY -i myTunnelO1

High Availability Settings

CommandDescription

--no-remove-colliding-tunnels

Don't remove identified tunnels with the same name, or any other default tunnels if this is a default tunnel. Jobs will be distributed between these tunnels, enabling load balancing and high availability. By default, colliding tunnels will be removed when Sauce Connect is starting up.

Starting another tunnel with the same identifier as an existing pool and not adding --no-remove-colliding-tunnels will result in the new tunnel being established but all tunnels in the pre-existing pool will be closed.

After Setting Up Sauce Connect

Command Line Example

Sauce Connect can be started from the command line with these commands to set up Sauce Connect with High Availability. You need to run this command on each machine that you want to have access to the tunnel pool. 

#On Linux or Mac OSX you would use the following
>./sc -u YOUR_USERNAME -k YOUR_ACCESS_KEY --tunnel-identifier myTunnel --no-remove-colliding-tunnels

#On windows you would use the following
>sc.exe -u YOUR_USERNAME -k YOUR_ACCESS_KEY --tunnel-identifier myTunnel --no-remove-colliding-tunnels

Starting Sauce Connect Programmatically

To start Sauce Connect programmatically, there are many options, such as launching it via Maven when using Java. The Sauce Connect Maven plugin will do this for you automatically, and you can also check out an example of how to set this up in a testing script.  and an exmaple of using it can be found here.

 

  • No labels