Skip to end of metadata
Go to start of metadata

The Situation

The Sauce Connect proxy setup is for situations in which there is a proxy server between the Internet and the machine hosting Sauce Connect, or between the machine hosting Sauce Connect and the machine hosting the website you want to test. In these cases you will want to use the Sauce Connect proxy commands to configure the proxy host and port that Sauce Connect can use to either reach the Internet or the site you want to test. 

Network Diagrams

Sauce Connect and MitM Proxies

If you use a Man-in-the-Middle proxy to monitor network traffic, it must be configured to allow the TLS connection and proprietary protocol that Sauce Connect uses to communicate with the Sauce Labs virtual machines that are running your tests. If it will allow only HTTP or HTTPS sessions, it will drop the inbound Sauce Connect connection. Check out Sauce Connect Start Up and Tear Down Process for more information about how Sauce Connect starts up and maintains the connection with the Sauce Labs browser cloud.  

Internet Control/Transaction Monitoring with a Proxy Configuration

You may have a network configuration in which you use a proxy to control the flow of traffic from your internal network to the external Internet, either as a means of adding security to your network, or whitelisting or blacklisting certain sites. In this situation you could set up Sauce Connect behind a proxy like BrowserMob, which records all traffic that passes through it, and which can later provide a history of that traffic. 

Proxied Site Under Test (SUT)

In this configuration the SUT is behind a proxy, to allow even more control over traffic before it reaches the SUT.  Typical this setup is used to control access to the SUT by means of IP whitelisting, or requiring a username and password to access the proxy.

Diagram Legend
ShorthandLonghand
SC HostMachine in your network that the Sauce Connect application is running on.
SUTSite Under Test, the site that you're testing.
Tunnel VM

The virtual machine that hosts Sauce Connect on the Sauce Labs side.

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.

Prerequisites

Sauce Connect Launcher for Firefox

Sauce Connect Launcher is an add-on for Firefox that lets you start up a Sauce Connect tunnel from within your browser by entering your Sauce Labs authentication credentials. You can get it from the add-on marketplace, and check out Using Sauce Connect Proxy Launcher for more information.

Setting Up Sauce Connect

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

    Latest Stable Release

    4.4.12

    Download LinkSHA1 Checksum
    Download Sauce Connect v4.4.12 for Mac OS 10.8+
    9ae0fb092dccab4eba9ce2e98fd679009a742607
    Download Sauce Connect v4.4.12 for Windows 7+
    38c978b01b8c794e53ea88558971e36a998ec779
    Download Sauce Connect v4.4.12 for Linux
    3a1f9ec4fc187f73d884e6f1cc0ef2d80de43c1f
    Download Sauce Connect v4.4.12 for Linux 32-bit
    d133eed8d50290313fdd053a3ad0e96a9f00645f
     Click here to download past stable releases of Sauce Connect Proxy...

    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 -u YOUR_USERNAME -k YOUR_ACCESS_KEY

    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.  

You now have three options for proxy configuration:

Automatic Proxy Configuration

As of Sauce Connect 4.3.1, proxies and PAC settings are autoconfigured based on the settings of the operating system on the machine where it is installed.

  • On Windows, Sauce Connect will use the proxy settings for Internet Explorer, as well as the system-wide proxy settings that set in the Control Panel.
  • On Mac OS X, Sauce Connect will use the proxy settings in Preferences/Network. Both proxy and PAC settings are supported.
  • On Linux, Sauce Connect looks for these variables, in this order:
    • http_proxy
    • HTTP_PROXY
    • all_proxy
    • ALL_PROXY. They can be in the form http://host.name:port or host.name:port.

You can disable automatic proxy detection with the command line option  ./sc -z --no-autodetect.

Command Line Configuration

If automatic proxy configuration fails, you need to override the settings, or you need to enable proxies through a test script, there are several command-line options that you can use to configure proxies manually

  • -p
  • --proxy <host:port>
  • -w
  • --proxy-userpwd <user:pwd>
  • -T
  • --proxy-tunnel
  • --pac <url>

Why are there -p, --proxy and a -T, --proxy-tunnel options?

Fundamentally, Sauce Connect makes two separate outbound connections for two separate purposes. The first, which -p, --proxy <host:port> uses, is a lightweight connection to our REST API that simply tells our servers basic information about the status of Sauce Connect's status (for example, starting up, ready, stopping).

The second connection is to the actual tunnel virtual machine (VM) created for your Sauce Connect instance. Enabling the -T, --proxy-tunnel flag will cause some proxy specified with -p, --proxy to be used for this connection as well. You should try to avoid using a proxy for this connection, since it is already TLS secured, and a large volume of data tends to go over this connection. Adding another step in the middle, in the form of a proxy, can hinder test performance.

Ideally you should only need to use -p, --proxy <host:port> (and perhaps -w, --proxy-userpwd <user:pwd> for credentials), but -T, --proxy-tunnel is available if your network doesn't allow outgoing connections on port 443. If your tests are slow, you may want to ask your network administrator about making an exception for this connection.

BrowserMob Proxy Configuration

You can use BrowserMob Proxy with Sauce Connect 4.2 and higher by using the Sauce Connect PAC feature. 

Since BrowserMob bumps SSL connections, and Sauce Connect 4 verifies the certificate when connecting to the REST API, that means the --proxy option can't be used with a BrowserMob proxy. Sauce Connect will complain that the certificate received from the REST endpoint is invalid.

To choose a proxy in a dynamic fashion, however, you can create a PAC file that matches the REST and tunnel VM hostnames, and uses the local BrowserMob proxy for everything else.

  1. Start BrowserMob Proxy.

    $ ./browsermob-proxy --port 9000

     

  2. Start another terminal and create a proxy instance in BrowserMob.

    $ curl -X POST http://localhost:9000/proxy
    {"port":9091}

     

  3. Create a file, browsermob.js, with this content. 
    This is what you will pass into Sauce Connect 4.

    function FindProxyForURL(url, host) {
        if (shExpMatch(host, "*.miso.saucelabs.com") ||
            shExpMatch(host, "saucelabs.com")) {
            // KGP and REST connections. Another proxy can also be specified.
            return "DIRECT";
        }
    
        // Test HTTP traffic, route it through the local BrowserMob proxy.
        return "PROXY localhost:9091";
    }

     

  4. Copy the file to the same directory as Sauce Connect 4, and start Sauce Connect 4.

    $ ./sc -v --pac file://$(pwd)/browsermob.js

    Sauce Connect 4 will print the proxy used for REST and the tunnel VM connection, which should be Using no proxy for connecting to Sauce Labs REST API and Using no proxy for connecting to tunnel VM if their hostnames are configured with DIRECT access.

WonderProxy

You can use WonderProxy for GeoIP website testing with Sauce Connect. Check out the step-by-step setup guide on the WonderProxy website.

After Setting Up Sauce Connect

Command Line Examples

In its simplest form, Sauce Connect can be started from the command line with these commands.

#On Linux or Mac OSX you would use the following
>./sc -u YOUR_USERNAME -k YOUR_ACCESS_KEY --proxy host:port --proxy-tunnel
 
#On windows you would use the following
>sc.exe -u YOUR_USERNAME -k YOUR_ACCESS_KEY --proxy host:port --proxy-tunnel

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.

 

  • No labels