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)
Getting startedBefore you begin 1. Make sure port 443 is not proxied and can be opened for outbound connections. Install 2. Get Sauce Connect v4:
- Download Sauce Connect for OS X
- Download Sauce Connect for Windows
- Download Sauce Connect for Linux
- (If you're looking for Sauce Connect v3, you download it here.)
5. Go to the install directory and start sc:
6. When you see "connected", you are ready to go! Next steps: 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.
Setup processThe 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.
Teardown processOnce 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.
System requirementsThese vary depending on the number of parallel tests you plan to run. Here are some samples based on simultaneous test volume:
|10 tests (Use your dev machine)||4gb||4GHz|
+ use a dedicated Connect server
+ ulimit -n 8192
sccommand line program accepts the following parameters:
Usage: ./sc -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 identifier. -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 Labs support. -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 every <seconds>. -h, --help Display this help text.
Managing multiple tunnelsIn 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 --tunnel-identifier flag (or -i) 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.
Please note that in order to run multiple Sauce Connect instances on the same machine, it's necessary to provide additional flags to configure independent log files, pid files, and ports for each instant. Here's an example of how to configure all of these settings for a second instance:
sc --pidfile /tmp/sc2.pid --logfile /tmp/sc2.log --scproxy-port 29999 --se-port 4446 -i my-tun2
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"
FAQsWhat 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. Can I access applications on localhost? Sauce Connect proxies these commonly-used localhost ports:
$ crontab -e 00 00 * * * killall sc
80, 443, 888, 2000, 2001, 2020, 2109, 2222, 2310, 3000, 3001, 3030, 3210, 3333, 4000, 4001, 4040, 4321, 4502, 4503, 4567, 5000, 5001, 5050, 5555, 5432, 6000, 6001, 6060, 6666, 6543, 7000, 7070, 7774, 7777, 8000, 8001, 8003, 8031, 8080, 8081, 8765, 8777, 8888, 9000, 9001, 9080, 9090, 9876, 9877, 9999, 49221, 55001
So when you use Connect, your local web apps are available to test at localhost URLs, just as if the Sauce Labs cloud were your local machine. Easy!
Do you need a different port? Please let us know! We do our best to support ports that will be useful for many customers, such as those used by popular frameworks.
Please note that because an additional proxy is required for localhost URLs, tests may perform better when using a locally-defined domain name (which can be set in your hosts file) rather than localhost. Using a locally-defined domain name also allows access to applications on any port.