Sauce Connect is a secure tunneling app which allows you to execute tests securely when testing behind firewalls via a secure connection between Sauce Labs’ client cloud and your environment.
When should I use Sauce Connect?
You should use Sauce Connect whenever you’re testing an app behind a firewall. Sauce Connect is not required to execute scripts on Sauce.
You can also use Sauce Connect:
- · as an alternative to whitelisting
- · as a means of filtering traffic in your records (e.g. for Google Analytics)
- · as a means of monitoring network traffic
- · as a way to stabilize network connections (detecting/re-sending dropped packets)
Before you begin
1. Make sure port 443 is not proxied and can be opened for outbound connections.
2. Get Sauce Connect v4:
3. Unzip (or untar).
4. Open a command prompt.
5. Go to the install directory and start sc:
6. When you see "connected", you are ready to go!
7. Read our take on security: Security best practices
bin/sc -u YOUR-SAUCE-USERNAME -k YOUR-SAUCE-API-KEY
How is Sauce Connect secured?
Though starting up a tunnel using Sauce Connect may take a few seconds, our tunneling method allows for the highest possible security. We spin up a secure tunnel sandbox environment for each tunnel connection in order to provide greater tunnel security and isolation from other customers.
Data transmitted by Sauce Connect is encrypted through industry-standard TLS, using the AES-256 cipher. SC also uses a caching web proxy to minimize data transfer. To read more about security on Sauce, read our security white paper.
Within your infrastructure, Sauce Connect needs access to the application under test, but can be firewalled from the rest of your internal network. We recommend running Sauce Connect in a firewall DMZ, on a dedicated machine, and setting up firewall rules to restrict access from that DMZ to your internal network.
The initial outbound connect created by Sauce Connect is over port 443 to *.saucelabs.com. The response to this request contains instructions which Sauce Connect will use to establish a secure tunnel between Sauce Connect and Sauce Labs client cloud. Now that Connect has it’s instructions it will create another outbound connect to *.saucelabs.com also over 443. Once the connection is established all traffic between Sauce Labs and Sauce Connect will be multiplexed over a single encrypted TLS connection.
Once Sauce Connect is asked terminated (typically via ctrl-c), a call will be made from Sauce Connect to the REST API with instructions to terminate the tunnel VM. Sauce Connect will continue to poll the REST API until the tunnel VM has been halted and deleted.
These vary depending on the number of parallel tests you plan to run. Here are some samples based on
simultaneous test volume:
For increased reliability and security, use a dedicated server.
|30 tests (Use your dev machine)
|100 tests+ use a dedicated Connect server+ set uLimit to 8192
sc command line program accepts the following parameters:
-u, --user <username> The environment variable
SAUCE_USERNAME can also be used.
-k, --api-key <api-key> The environment variable
SAUCE_ACCESS_KEY can also be used.
-B, --no-ssl-bump-domains <...> Comma-separated list of domains.
Requests whose host matches one of
these will not be SSL re-encrypted.
-D, --direct-domains <...> Comma-separated list of domains.
Requests whose host matches one of
these will be relayed directly
through the internet, instead of
through the tunnel.
-v, --verbose Enable verbose debugging.
-F, --fast-fail-regexps <...> Comma-separated list of regular
expressions. Requests matching one
of these will get dropped instantly
and will not go through the tunnel.
-i, --tunnel-identifier <id> Don't automatically assign jobs to
this tunnel. Jobs will use it only
by explicitly providing the right
-l, --logfile <file>
-P, --se-port <port> Port on which Sauce Connect's
Selenium relay will listen for
requests. Selenium commands
reaching Connect on this port will
be relayed to Sauce Labs securely
and reliably through Connect's
tunnel. Defaults to 4445.
-p, --proxy <host:port> Proxy host and port that Sauce
Connect should use to connect
to the Sauce Labs cloud.
-w, --proxy-userpwd <user:pwd> Username and password required to
access the proxy configured with -p.
-T, --proxy-tunnel Use the proxy configured with -p
for the tunnel connection.
-s, --shared-tunnel Let sub-accounts of the tunnel
owner use the tunnel if requested.
-x, --rest-url <arg> Advanced feature: Connect to Sauce
REST API at alternative URL. Use
only if directed to do so by Sauce
-f, --readyfile <file> File that will be touched to signal
when tunnel is ready.
-a, --auth <host:port:user:pwd> Perform basic authentication when
an URL on <host:port> asks for a
username and password. This option
can be used multiple times.
-z, --log-stats <seconds> Log statistics about HTTP traffic
-h, --help Display this help text.
Managing multiple tunnels
In its default mode of execution, one Connect instance will suffice all your needs and will require no efforts to make cloud browsers driven by your tests navigate through the tunnel.
Just start Connect, all traffic from jobs under the same account will use it transparently. Stop that tunnel, all jobs will stop to do so and attempt to find your web servers through the open internet.
Using identified tunnels, you can start multiple instances of Connect that will not collide with each other and will not make your tests' traffic transparently tunnel through.
This allows you to test different localhost servers or access different networks from different tests (a common requirement when running tests on TravisCI.)
To use this feature, simply start Sauce Connect using the -i flag (or --tunnel-identifier) and provide your own unique identifier string. Once the tunnel is up and running, any tests that you want going through this tunnel will need to provide the correct identifier using the tunnel-identifier desired capability.
Can I reuse a tunnel between multiple accounts?
Tunnels started by an account can be reused by its sub-accounts. To reuse a tunnel, start Sauce Connect with the special --shared-tunnel parameter from the main account in your account tree. For example:
Once the tunnel is running, provide the special "parent-tunnel" desired capability on a per-job basis. The value of this capability should be the username of the parent account that owns the shared Connect tunnel as a string. Here's an example (this test should can run using Auth credentials for any sub-account of "parentAccount"):
sc --shared-tunnel parentAccount parentAccountsAccessKey
That's it! We'll take care of the rest by making the jobs that request this capability route all their traffic through the tunnel created using your parent account (parentAccount, following our example).
capabilities['parent-tunnel'] = "parentAccount"
What firewall rules do I need?
Sauce Connect needs to make a direct, outbound connection to *.saucelabs.com on port 443 for the primary
tunnel connection to the Sauce's cloud.
How do I keep Sauce Connect fresh?
Connect handles a lot of traffic for heavy testers. Here is one way to keep it 'fresh' to avoid leakages and freezes.
First write a loop that will make sure of starting Sauce Connect every time it gets killed or crashes:
Then write a cron task that will kill Sauce Connect on a regular basis:
$ while :; do killall sc; sleep 30; sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY; done
This will kill Sauce Connect every day at 12am, but can be modified to behave differently depending on your requirements.
$ crontab -e
00 00 * * * killall sc