Sauce Connect Proxy CLI Reference

Below is a list of required and optional flags to use on your Sauce Connect command line to specify parameters. See Basic Setup for Sauce Connect Proxy for detailed setup instructions and use cases.

tip

View these options directly in the command line terminal by running the --help flag.

Required#

--user#

Description: Sets your Sauce Labs username. You can also use the SAUCE_USERNAME environment variable on the command line.

Shorthand: -u


--accessKey#

Description: Sets your Sauce Labs API key. You can also use the SAUCE_ACCESS_KEY environment variable on the command line.

Shorthand: -k


Data Center Endpoint#

Description: depending on the Data Center location of the device you're testing on (US or EU), you may need to add a Data Center Endpoint.

Examples:

No endpoint needed. Connection to the US Data Center occurs by default. So your only required options would be username and access key.

$ bin/sc -u john.smith -k ab015c1e-xxxx-xxxx-xxxx-xxxxxxxxxxx

Optional#

--tunnel-identifier [id]#

Description: assigns an ID to a Sauce Connect Proxy tunnel. While not required, this option is very strongly recommended. Future jobs will use this tunnel only when explicitly specified by the tunnelIdentifier Capability in a Selenium client.

For information on using --tunnel-identifier to run several Sauce Connect Proxy tunnels simultaneously, see High Availability Sauce Connect Proxy Setup. To learn about the syntax for setting --tunnelIdentifier as a capability, see Test Configuration Options.

Your ID must be ASCII.

Shorthand: -i

Example:

$ bin/sc -u john.smith -k ab015c1e-xxxx-xxxx-xxxx-xxxxxxxxxxx https://saucelabs.com/rest/v1/ -i your-tunnel-name

--config-file <path>#

Description: sets the local path to a YAML file containing a Sauce Connect Proxy configuration. Use this in conjunction with the --config-file option. An example YAML configuration file, config.yaml, is included for your reference as part of the Sauce Connect Proxy download package.

We recommend using a YAML configuration file in production environments, rather than command-line options, as it facilitates tracking configuration changes, managing tunnel-domains and direct-domains options (which can get very long), and securing Sauce Connect Proxy credentials with tighter access control over the config file.

Shorthand: -c


--no-ssl-bump-domains#

Description: disables SSL Bumping functionality. Specifying this option will prevent your tests from being interrupted with security warnings by automatically re-signing self-signed and invalid SSL certificates not trusted by stock browsers.

Use this option when you start Sauce Connect Proxy and specify the domains in comma-separated listthat you don't want bumped or SSL re-encrypted. You can also specify all, which prevents all domains passing through the tunnel from being bumped.

Shorthand: -B


--no-proxy-caching#

Description: disables caching in Sauce Connect Proxy. All requests will be sent through the tunnel.

Shorthand: -N


--max-missed-acks#

Description: sets the maximum amount of keepalive ACKs that can be missed before the client will trigger a reconnect. The default is 30.

Shorthand: -M


--direct-domains [...]#

Description: Use this option along with a comma-separated list of domains. that you want to be relayed directly through the Internet instead of through the Sauce Connect Proxy tunnel.

Shorthand: -D


--tunnel-domains [...]#

Description: does the inverse of --direct-domains; it sends domains that you request through the Sauce Connect Proxy tunnel. Be sure to format your domains as a comma-separated list.

Shorthand: -t


--verbose#

Description: enables verbose debugging. Use this to output HTTP headers.

NOTE: -vv (very verbose), which outputs HTTP headers and KGP logs, is meant for troubleshooting purposes only. It is system-resource demanding and adversely affects Sauce Connect Proxy performance.

Shorthand: -v


--fast-fail-regexps [...]#

Description: Tests for application and site degradation based on missing assets or resources. It can be used to simulate non-loading of scripts, styles, or other resources. Use this option followed by a comma-separated list of regular expressions. Requests with URLs matching one of these will get dropped instantly and will not go through the tunnel. See Using Sauce Connect Proxy to Test Graceful Degradation for an example.

Shorthand: -F


--logfile [file]#

Description: captures the Sauce Connect Proxy logs in a file. If a path is not specified in file, the file location will default to the location where the Sauce Connect Proxy executable can be found on your machine.

Shorthand: -l


--se-port [port]#

Description: sets the port on which Sauce Connect Proxy's Selenium relay will listen for requests. Selenium commands reaching Sauce Connect Proxy on this port will be relayed to Sauce Labs securely and reliably through Sauce Connect Proxy's tunnel. This feature is disabled unless specified.

Shorthand: -P


--proxy [host:port]#

Description: Sets the proxy host and port that Sauce Connect Proxy should use to connect to the Sauce Labs REST API and test traffic. For information about the -p option and configuring Sauce Connect Proxy with other proxies, see Sauce Connect Proxy Setup with Additional Proxies.

Alternatively, you can use corresponding environment variables HTTP_PROXY, http_proxy, all_proxy, or ALL_PROXY on the command line.

Shorthand: -p


--proxy-userpwd [user:pwd]#

Description: Requires username and password to be sent via basic authentication to access the proxy configured with -p (--proxy). For more information, see Sauce Connect Proxy Setup with Additional Proxies.

NOTE: Sauce Connect Proxy versions older than 4.6.1 do not support the -p option combined with --pac. Update to the latest version here.

Shorthand: -w


--pac [url]#

Description: Defines proxy auto-configuration (PAC) URL. You can input a http(s) or local file://URL. Absolute paths are required when specifying a local PAC file. For more information, see Sauce Connect Proxy Setup with Additional Proxies.

Shorthand: n/a

Example:

--pac file:///Users/JohnSmith/Desktop/MyPac.pac

--pac-auth#

Description: Supplies PAC authentication string in format username:password@host:port. This option can be used multiple times for each authenticated host in the PAC file. This option is compatible only with Sauce Connect Proxy versions 4.6.3 and higher.

Shorthand: n/a


--proxy-tunnel#

Description: Uses the proxy configured with -p for the tunnel connection. For more information about the -T option and configuring Sauce Connect Proxy with other proxies, see Sauce Connect Proxy Setup with Additional Proxies.

You'll need to use this option if you have a PAC file that contains Sauce Labs DNS names.

Shorthand: -T


--shared-tunnel#

Description: Allows other users of the tunnel owner to use the tunnel. For more information, see Sharing Sauce Connect Proxy Tunnels - Extended Team Management.

Shorthand: -s


--rest-url [arg]#

Description: Allows you to connect to a different Sauce Labs cloud (e.g., EU Virtual Device and Desktop Cloud or US Real Device Cloud) other than the default, US-West-1. For a full list of Sauce Connect Proxy endpoints, see Data Center Endpoints.

Shorthand: -x


--readyfile#

Description: Sets file that will be touched to indicate when the tunnel is ready.

Shorthand: -f


--auth [host:port:user:pwd]#

Description: Performs basic authentication when a URL on host:port asks for a username and password. This option can be used multiple times. For examples, see Using --auth with Sauce Connect Proxy.

Sauce Connect Proxy's --auth flag will only send the header Authorization with a type of 'Basic'. If a resource responds with the header WWW-Authenticate of a type any other than 'Basic,' your authentication will fail and return a non-200 HTTP response. HTTP Header Injection is disabled for SSL domains that are not re-encrypted by Sauce Connect Proxy, which means performing basic authentication in this way is disabled for all HTTPS domains passed to --no-ssl-bump-domains argument.

Shorthand: -a


--log-stats [seconds]#

Description: Logs statistics about HTTP traffic every seconds. Information includes bytes transmitted, requests made, and responses received.

Shorthand: -z


--max-logsize [bytes]#

Description: Rotates log file after reaching bytes size. Disabled by default.

Shorthand: n/a


--doctor#

Description: Performs checks to detect possible misconfiguration or problems. Check out Sauce Connect Proxy Debugging and Diagnostics with --doctor flag for more information about the errors that --doctor will detect and how to resolve them. Please note that when using the --doctor flag, place it at the end of your command for best results.

Shorthand: n/a


--no-autodetect#

Description: Disables the auto-detection of proxy settings.

Shorthand: n/a


--version#

Description: Displays version information and exit.

Shorthand: n/a


--scproxy-port [port]#

Description: Sets port to use for the built-in HTTP proxy.

Shorthand: -X


--cainfo [cainfo file]#

Description: CA certificate bundle to use for verifying REST connections.

Shorthand: n/a


--capath [capath dir]#

Description: Directory of CA certs to use for verifying REST connections.

Shorthand: n/a


--tunnel-cert public#

Description: Use this to require certificates on the Sauce Labs internal tunnel Virtual Machine to be signed by a Certificate Authority instead of self-signed certificates.

Shorthand: n/a


--tunnel-cainfo [cainfo file]#

Description: CA certificate bundle to use for verifying tunnel connections.

Shorthand: n/a


--tunnel-capath [capath dir]#

Description: Directory of CA certificates to use for verifying tunnel connections.

Shorthand: n/a


--scproxy-read-limit [bytes per second]#

Description: Rates limit reads in scproxy to the number of bytes per second that you specify. This option can be used to adjust local network transfer rate to prevent overloading the tunnel connection.

Shorthand: n/a


--scproxy-write-limit [bytes per second]#

Description: Rates limit writes in scproxy to the number of bytes per second that you specify. This option can be used to adjust local network transfer rate to prevent overloading the tunnel connection.

Shorthand: n/a


--dns [server[,server..]]#

Description: Uses specified name server. To specify multiple servers, separate them with a comma. Use IP addresses, optionally with a port number, the two separated by a colon.

Shorthand: n/a

Example:

--dns 8.8.8.8,8.8.4.4:53

--no-remove-colliding-tunnels#

Description: Use this option to prevent the removal of colliding tunnels, which would otherwise happen by default when Sauce Connect Proxy starts up. Colliding tunnels are tunnels with the same tunnel ID name. This includes unnamed (default) tunnels. Jobs will be distributed across all tunnels, enabling load balancing and high availability.

Shorthand: n/a


--pidfile [file]#

Description: specifies the file where you want the Sauce Connect Proxy process ID (pid) to be written. This is useful for programmatically stopping Sauce Connect Proxy. Although Sauce Connect Proxy makes a best effort, we cannot guarantee that the pidfile will be removed when shutting down Sauce Connect Proxy. With that in mind, relying on the pidfile as a means to monitor Sauce Connect Proxy is not supported.

Shorthand: -d


--metrics-address=address#

Description: Use this option to define the host:port for the internal web server used to expose client side metrics. The default is localhost:8888.

Shorthand: n/a


--help#

Description: Displays the Help text.

Shorthand: -h


--extra-info '["inject_job_id":true]'#

Description: Injects the job id and tunnel id as HTTP request headers. HTTP Header Injection is disabled for SSL domains that are not re-encrypted by Sauce Connect Proxy and all HTTPS domains passed to --no-ssl-bump-domains argument.

Shorthand: n/a


--ocsp log-only#

Description: Sets an OCSP tunnel certificate validation "log-only" policy, which specifically logs errors.

Shorthand: n/a


--ocsp attempt#

Description: Sets an OCSP tunnel certificate validation "soft-fail" policy that allows Sauce Connect Proxy to run unless OCSP server returns a “revoked” status (e.g., timeouts, unknown status). It will not stop Sauce Connect Proxy from connecting to a tunnel. Connection to OCSP server will be set to time out after 5 seconds.

Shorthand: n/a


--ocsp strict#

Description: Sets an OCSP tunnel certificate validation "hard-fail" policy that blocks Sauce Connect Proxy from running unless the OCSP server returns a “good” status (e.g., timeouts, revoked certificate, unknown status). It will stop Sauce Connect Proxy from connecting to a tunnel. Connection to OCSP server will be set to time out after 10 seconds.

Shorthand: n/a


--no-ocsp-verify#

Description: Sets an OCSP tunnel certificate validation "bypass" policy that allows you to skip OCSP checks.

Shorthand: n/a

NOTE: OCSP supports the following Sauce Connect Proxy flags: --kgp-host, --kgp-port, --proxy, --pac, --no-autodetect, --proxy-tunnel, --tunnel-cainfo, --tunnel-capath. More information: Sauce Connect Proxy Certificate Handling.


Formatting Domains in Your Command Lines#

Here are some guidelines to follow when formatting domains:

  • Use only the domain name. Do not precede it with http: or https:
    • Example: mydomain.com
  • Make sure your comma-separated list of domains doesn't include any spaces.
    • Example, mydomain.com,saucelabs.com,mysite.com
  • Prefix domain names with *. or simply . to match all its subdomains.
    • Example: You could refer to both wiki.saucelabs.com and my.saucelabs.com with "*.saucelabs.com" or ".saucelabs.com". Enclose the argument in quotes to prevent shell expansion of asterisk.
  • If you don't want any domains to be SSL re-encrypted, you can specify all with the argument (i.e., -B all or --no-ssl-bump-domains all)
  • WebSockets domains are not compatible with SSL bumping, so you'll need to disable SSL Bumping for them

Additional Resources#

Last updated on by Kim