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. See Basic Setup for Sauce Connect Proxy for detailed setup instructions and use cases.

tip

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

Main#


--api-key#

| OPTIONAL | STRING |

Description: Sets your Sauce Labs API key.
Shorthand: -k


--config-file#

| OPTIONAL | STRING |

Description: Sets the local path to a YAML file containing a Sauce Connect Proxy configuration. 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


--tunnel-pool or --no-remove-colliding-tunnels#

| OPTIONAL | STRING |

caution

Effective with Sauce Connect Proxy version 4.7.0, --no-remove-colliding-tunnels has been deprecated and replaced by --tunnel-pool.

Description: The tunnel is a part of the High Availability Sauce Connect Proxy Tunnel Pool. For more info, see High Availability Setup.
Shorthand: n/a


--region#

| OPTIONAL | STRING |

caution

Effective with Sauce Connect Proxy version 4.7.0, we recommend using --region over --rest-url.

Description: Sauce Labs data center region (e.g., EU-Central, US-West). For a full list, see Data Center Endpoints. Not compatible with Sauce Connect Proxy versions below 4.7.0.
Default: us-west
Shorthand: -r


--rest-url#

| OPTIONAL | STRING |

caution

Effective with Sauce Connect Proxy version 4.7.0, we recommend using --region over --rest-url.

Description: Sauce Labs regional data center REST API URL (e.g., EU-Central, US-West). For a full list, see Data Center Endpoints.
Default: https://saucelabs.com/rest/v1
Shorthand: -x


--shared-tunnel#

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


--tunnel-name or --tunnel-identifier#

| OPTIONAL | STRING |

caution

Effective with version 4.7.0, --tunnel-identifier has been deprecated and replaced by --tunnel-name.

Description: Assigns an ID to a Sauce Connect Proxy tunnel. While not required, this option is strongly recommended. Future jobs will use this tunnel only when explicitly specified by the tunnelIdentifier in the desired capabilities of your automated tests.

To learn about the syntax for setting this as a capability, see Test Configuration Options. For information on using this option in the tunnel pool, see High Availability Setup.

note

Your ID must be ASCII.

Shorthand: -i for --tunnel-identifier; n/a for --tunnel-name


--user#

| OPTIONAL | STRING |

Description: Sets your Sauce Labs username.
Shorthand: -u

Tunnel Configuration#


--direct-domains#

| OPTIONAL | STRING |

Description: Comma-separated list of domains (see Formatting Domains guidelines) that you want to be relayed directly through the internet instead of through the Sauce Connect Proxy tunnel.
Shorthand: -D


--fast-fail-regexps#

| OPTIONAL | STRING |

Description: 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. Requests with URLs matching one of these will get dropped instantly and will not go through the tunnel. See the Sauce Connect Proxy FAQ for an example.
Shorthand: -F


--tunnel-domains#

| OPTIONAL | STRING |

Description: Performs the inverse of --direct-domains; sends domains that you request through the Sauce Connect Proxy tunnel. Be sure to format your domains as a comma-separated list (see Formatting Domains guidelines).
Shorthand: -t


--no-ssl-bump-domains#

| OPTIONAL | STRING |

Description: Comma-separated list of domains (see Formatting Domains guidelines). Requests that include hosts matching one of these domains, will not be SSL re-encrypted. See SSL Certificate Bumping for more information about scenarios in which you would want to use this command.

note

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

Shorthand: -B

External Proxy Configuration#


--no-autodetect#

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


--pac#

| OPTIONAL | STRING |

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

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

--pac-auth#

| OPTIONAL | STRING |

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. Not compatible with Sauce Connect Proxy versions below 4.6.3.
Shorthand: n/a


--proxy#

| OPTIONAL | STRING |

Description: Proxy host and port that Sauce Connect should use to connect to the Sauce Labs REST API.
Shorthand: -p


--proxy-tunnel#

Description: 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: Requires username and password to be sent via basic authentication to access the proxy configured with -p (--proxy). For more information, see Set Up with Additional Proxies.

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

Client Configuration#


--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


--logfile#

| OPTIONAL | STRING |

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


--max-logsize#

| OPTIONAL | NUMBER |

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


--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. 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.
Shorthand: n/a


--capath#

| OPTIONAL | STRING |

caution

Effective with Sauce Connect Proxy version 4.7.0, --capath has been deprecated.

Description: Directory of CA certs to use for verifying connections to Sauce Labs REST API.
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

--ocsp#

| OPTIONAL | STRING |

Description: OSCP verification mode. Options are strict, attempt, 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-cainfo#

| OPTIONAL | STRING |

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


--tunnel-capath#

| OPTIONAL | STRING |

caution

Effective with Sauce Connect Proxy version 4.7.0, --tunnel-capath has been deprecated.

Description: Directory of CA certificates to use for verifying tunnel connections.
Shorthand: n/a

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 -r us-west -u john.smith -k ab015c1e-xxxx-xxxx-xxxx-xxxxxxxxxxx

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 -x https://api.us-west-1.saucelabs.com/rest/v1 -u john.smith -k ab015c1e-xxxx-xxxx-xxxx-xxxxxxxxxxx

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#

For quickstart info, see the Tunnels page and Sauce Connect Proxy Basic Setup.