Skip to main content

Sauce Connect Proxy CLI Reference

Below is a list of flags to use on your Sauce Connect Proxy command line to specify parameters.

What You'll Need#

tip

You can view the entire list of CLI options by running the --help flag.


Main#


--user#

| REQUIRED | STRING |

Description: Sets your Sauce Labs username. For additional security, you can set this as an environment variable.
Shorthand: -u


--api-key#

| REQUIRED | STRING |

Description: Sets your Sauce Labs API key. This will be the same as your Access Key. For additional security, you can set this as an environment variable.
Shorthand: -k

Description: defines the local path to a YAML file containing a Sauce Connect Proxy configuration.
Shorthand: -c


--config-file#

| REQUIRED | STRING |

For YAML Configuration Files ONLY

This is required only if you're using a YAML file to configure your tunnels.

Description: Defines the local path to a YAML file containing a Sauce Connect Proxy configuration. For instructions, Configuring Tunnels with a YAML File.
Shorthand: -c


--region#

| OPTIONAL | STRING |

Description: Sets your Sauce Labs region data center. Strongly recommended for best performance. Possible values are us-west, eu-central, us-east, and apac-southeast. For more information, see Data Center Endpoints.
Default: If you don't specify a Data Center at all, Sauce Connect will default to us-west.
Shorthand: -r

caution

We recommend using this flag over its predecessor, --rest-url, which will eventually be deprecated. Not compatible with versions below 4.7.0.


--shared-tunnel#

| OPTIONAL |

Description: changes tunnel sharing permissions so that all users in an organization can use Sauce Connect Proxy tunnels, rather than just the tunnel owner (admin). For more information, see Sharing Sauce Connect Proxy Tunnels.
Shorthand: -s


--tunnel-name#

| OPTIONAL | STRING |

Description: Assigns a name to a Sauce Connect Proxy tunnel. Strongly recommended for best performance. It can also assign a name to a group of tunnels in the same [High Availability pool]((/secure-connections/sauce-connect/setup-configuration/high-availability), when used with --tunnel-pool. Must be in ASCII format.

Future jobs will use this tunnel only when explicitly specified by the tunnelName in your test capabilities. To learn about the syntax for setting this as a capability, see Test Configuration Options.
Shorthand: n/a

Tunnel Configuration#


--tunnel-pool#

| OPTIONAL | STRING |

Description: Launches a high availability tunnel pool along with the --tunnel-name flag. For more info, see High Availability Setup.
Shorthand: n/a


--tunnel-pool#

| OPTIONAL | STRING |

Description: Launches a high availability tunnel pool along with the --tunnel-name flag. For more info, see High Availability Setup.
Shorthand: n/a


--rest-url#

| OPTIONAL | STRING |

caution

Effective with Sauce Connect Proxy version 4.7.0, we recommend using --region instead. --rest-url will eventually be deprecated. Download the latest SC version here.

Description: Sets your Sauce Labs regional data center REST API URL (e.g., EU-Central, US-West).
Shorthand: -x


--no-remove-colliding-tunnels#

DEPRECATED

Description: Effective with Sauce Connect Proxy version 4.7.0, this flag was deprecated and replaced by --tunnel-pool. Download the latest SC version here.


--tunnel-identifier#

DEPRECATED

Description: Effective with version 4.7.0, this flag was deprecated and replaced by --tunnel-name. Download the latest SC version here. Shorthand: -i for --tunnel-identifier


--tunnel-identifier#

DEPRECATED

Description: Effective with version 4.7.0, this flag was deprecated and replaced by --tunnel-name. Download the latest SC version here. Shorthand: -i for --tunnel-identifier


--direct-domains#

| OPTIONAL | STRING |

Description: Sets domain(s) that you want to relay directly through the internet instead of through the Sauce Connect Proxy tunnel. When adding multiple domains, format as a comma-separated list.
Shorthand: -D


--no-ssl-bump-domains#

| OPTIONAL | STRING |

Description: Sets domain(s) that do not require SSL resigning. Requests that include hosts matching one of these domains will not be SSL re-encrypted. When adding multiple domains, format as a comma-separated list. See SSL Certificate Bumping for more information about scenarios in which might want to use this command.
Shorthand: -B

note

HTTP Header Injection is disabled for all HTTPS domains passed to --no-ssl-bump-domains argument.


--fast-fail-regexps#

| OPTIONAL | STRING |

Description: Allows you to set a deny-list of URL patterns. Requests with URLs matching one of these will get dropped instantly and will not go through the tunnel. Tests for application and site degradation based on missing assets or resources. 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. See the Sauce Connect Proxy FAQ for an example.
Shorthand: -F


--tunnel-domains#

| OPTIONAL | STRING |

Description: Sets domain(s) that need to be sent through the Sauce Connect Proxy tunnel. This is the inverse of --direct-domains. When adding multiple domains, format as a comma-separated list. Be sure to format your domains as a comma-separated list (see Formatting Domains guidelines).
Shorthand: -t

External Proxy Configuration#


--no-autodetect#

Description: Disables the auto-detection of system proxy settings. See also Automatic Proxy Auto-Configuration.
Shorthand: n/a


--pac#

| OPTIONAL | STRING |

Description: Defines external proxy auto-configuration (PAC) URI. You can input 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

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

--pac-auth#

| OPTIONAL | STRING |

Description: Supplies PAC authentication in the format username:password@host:port. This option can be used multiple times for each authenticated host in the PAC file.
Shorthand: n/a


--proxy#

| OPTIONAL | STRING |

Description: Defines external proxy host:port where you want to route Sauce Labs REST API bound traffic.
Shorthand: -p


--proxy-localhost#

| OPTIONAL | BOOLEAN |

Description: Setting this to true supports proxying upstream requests to localhost. By default, it is false.
Shorthand: n/a


--proxy-tunnel#

Description: Routes all tunnel traffic through the external proxy specified by --proxy. Uses the proxy configured with --proxy or --pac for the tunnel connection. For more information about the -T option and configuring Sauce Connect Proxy with other proxies, see Set Up with Additional Proxies. You'll need to use this option if you have a PAC file that contains Sauce Labs DNS names.
Shorthand: -T


--proxy-userpwd#

| OPTIONAL | STRING |

Description: Sets username and password (sent via basic authentication) to access the proxy configured with --proxy. For more information, see Set Up with Additional Proxies.
Shorthand: -w

Client Configuration#


--logfile#

| OPTIONAL | STRING |

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


--max-logsize#

| OPTIONAL | NUMBER |

Description: Rotates logfile after reaching the max bytes size. It creates a new log and appends an order number to the previous log. Disabled by default.
Shorthand: n/a


--pidfile#

| OPTIONAL | STRING |

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


--readyfile#

| OPTIONAL | STRING |

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


--scproxy-port#

| OPTIONAL | NUMBER |

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


--se-port#

| OPTIONAL | NUMBER |

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. For more information, see Using the Selenium Relay.
Shorthand: -P

Networking and Security#


--auth#

| OPTIONAL | STRING |

Description: Performs basic authentication when a URL on host:port asks for a username and password (host:port:username:password format). This option can be used multiple times. For examples, see Authentication Using --auth.

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

--auth mysite.com:80:awesometester:supersekrit

--cainfo#

| OPTIONAL | STRING |

Description: CA certificate bundle to use for verifying connections to Sauce Labs REST API. Default: /private/etc/ssl/cert.pem.
Shorthand: n/a


--dns#

| OPTIONAL | STRING |

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

--dns 8.8.8.8,8.8.4.4:53

--tunnel-cainfo#

| OPTIONAL | STRING |

Description: CA certificate bundle to use for verifying tunnel connections.
Shorthand: n/a


--ocsp#

| OPTIONAL | STRING |

Description: OCSP verification mode. Options are: strict, log-only, and disable. The default is log-only.

note

--ocsp strict may fail if a certificate in the chain does not support OCSP. It's recommended to leave it to the default "log-only" mode.

Shorthand: n/a


--tunnel-capath#

DEPRECATED

Description: Directory of CA certificates to use for verifying tunnel connections. Effective with Sauce Connect Proxy version 4.7.0, --tunnel-capath was deprecated. Download the latest SC version here.


--capath#

DEPRECATED

Description: Defines a directory of CA certs to use for verifying connections to Sauce Labs REST API. Effective with Sauce Connect Proxy version 4.7.0, --capath was deprecated. Download the latest SC version here.

Troubleshooting and Debugging#


--log-stats#

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


--metrics-address#

| OPTIONAL | STRING |

caution

Effective with Sauce Connect Proxy version 4.7.0, the metrics server is disabled by default.

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 for versions prior to 4.7.0.
Shorthand: n/a


--verbose#

Description: Enables verbose debugging. Use this to log HTTP headers or debug Sauce Connect connection.
Shorthand: -v

note

You can also use -vv (very verbose), which outputs HTTP headers and KGP logs, although it's recommended for troubleshooting purposes only because it's system-resource demanding and can adversely affect Sauce Connect Proxy performance.

Other Options#


--scproxy-read-limit#

| OPTIONAL | NUMBER |

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#

| OPTIONAL | NUMBER |

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


--extra-info#

Description: JSON string that contains an advanced tunnel configuration.

OptionDescriptionExample
inject-forwarded-forDo not remove X-FORWARDED-FOR header from the proxied HTTP requests.--extra-info '{"inject-forwarded-for": true}'
reply_body_max_sizeSet limit to the reply body size (unlimited by default).--extra-info '{"reply_body_max_size": "30 MB"}'

You can specify a combination of several options. For example:

--extra-info '{"inject-forwarded-for": true, "reply_body_max_size": "300 MB"}'

Shorthand: n/a

Data Center Endpoints#

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.

For Sauce Connect Proxy version 4.7.0+:

To connect to the US-West Data Center, add the region name and place an -r immediately before it. Here's a full example that includes all required options, plus the US-West Data Center:

./sc -u {SAUCE_USERNAME} -k {SAUCE_ACCESS_KEY} -r us-west

For Sauce Connect Proxy versions below 4.7.0:

Add the endpoint URL and place an -x immediately before it. Here's a full example that includes all required options, plus the US-West Data Center endpoint:

./sc -u {SAUCE_USERNAME} -k {SAUCE_ACCESS_KEY} -x https://api.us-west-1.saucelabs.com/rest/v1

Formatting Domains in the Command Line#

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 docs.saucelabs.com and my.saucelabs.com as "*.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 those.

Additional Resources#