Sauce Connect Proxy Command-Line Quick Reference Guide

PAGE DEPRECATED: Updated content located here.

Sauce Connect Proxy provides several command-line arguments. The table below outlines all of the current flags you can use to specify Sauce Connect Proxy parameters.

Some command-line arguments can be passed through a config file or an environment variable. When the same argument is passed through multiple methods, the order of precedence is as follows: Command Line Argument > Environment Variable > Config File.

To ensure compatibility with these variables, make sure that you're using the most recent version of Sauce Connect Proxy (download here).

List of Sauce Connect Proxy Command-Line Arguments

Flag (Short)	Flag (Long)	Description
-u	`--user <username>`	Sauce Labs username. Instead of explicit `<username>,` you can also use the environment variable `SAUCE_USERNAME` on the command line. For more info, see Environment Variables Used by Sauce Connect Proxy and Best Practice: Use Environment Variables for Authentication Credentials.
`-k`	`--api-key <api-key>`	Sauce Labs API key. Instead of explicit `<api-key>`, you can also use the environment variable `SAUCE_ACCESS_KEY` on the command line. For more info, see Environment Variables Used by Sauce Connect Proxy and Best Practice: Use Environment Variables for Authentication Credentials.
-c	`--config-file <path>`	Included as part of the Sauce Connect Proxy download package (sc.exe) is the example configuration file config.yaml, to be used with the `--config-file` command-line option. This is the local path to a YAML file containing Sauce Connect Proxy configuration. Please refer to the sample YAML file for more information. Here is the order of precedence when the same argument is provided through multiple methods, with methods to the left having higher precedence: Command Line Argument > Environment Variable > Config File. In production environments, we recommend using a configuration file rather than command-line arguments for the following reasons: Ability to track configuration changes Easier to manage tunnel-domains and direct-domains options, which can get very long Secure Sauce Connect credentials with tighter access control over the config file
`-B`	`--no-ssl-bump-domains <...>`	Comma-separated list of domains. Requests, including hosts that match one of these domains, will not be SSL re-encrypted. See Sauce Connect Proxy and SSL Certificate Bumping for more information about scenarios in which you would want to use this command. For more info, see Formatting Domains guidelines. HTTP Header Injection is disabled for all HTTPS domains passed to `--no-ssl-bump-domains` argument.
`-N`	`--no-proxy-caching`	Disables caching in Sauce Connect Proxy. All requests will be sent through the tunnel.
`-D`	`--direct-domains <...>`	Comma-separated list of domains. Requests, including hosts that match one of these domains, will be relayed directly through the Internet instead of through the Sauce Connect tunnel. For more info, see Formatting Domains guidelines.
`-t`	`--tunnel-domains <...>`	Inverse of `--direct-domains`. Overrides `--direct-domains`. Only requests for domains in this list will be sent through the Sauce Connect Proxy tunnel. For more info, see Formatting Domains guidelines.
`-v`	`--verbose`	Enables verbose debugging. Use `-v` to output HTTP headers. You can also use the `-vv` (very verbose) option to output HTTP headers and KGP logs, however, it's meant for troubleshooting only. It's not for long-term use, nor should it be used in production. Running Sauce Connect Proxy with the very verbose `-vv` option is system-resource demanding and will adversely affect Sauce Connect Proxy performance.
`-F`	`--fast-fail-regexps <...>`	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 Sauce Connect Proxy FAQs > How Can I Use Sauce Connect Proxy to Test Graceful Degradation? for an example of using this command to test for application or site degradation based on missing assets or resources.
`-i`	`--tunnel-identifier <id>`	Assigns an `<id>` to a Sauce Connect Proxy tunnel. Future jobs will use this tunnel only when explicitly specified by the `tunnelIdentifier` Capability in a Selenium client. Note that `<id>` must be ASCII. For more information on using `--tunnel-identifier` to run multiple Sauce Connect tunnels simultaneously, see High Availability Sauce Connect Proxy Setup. For more information about the syntax for setting `tunnelIdentifier` as a capability, see Test Configuration Options.
`-l`	`--logfile <file>`	Capture the Sauce Connect Proxy logs in `<file>`. If a path is not specified in `<file>`, the default location of the `<file>` is the same location where the Sauce Connect executable can be found on your machine.
`-P`	`--se-port <port>`	Sets the port on which Sauce Connect's Selenium relay will listen for requests. Selenium commands reaching Sauce Connect on this port will be relayed to Sauce Labs securely and reliably through Sauce Connect's tunnel. This feature is disabled unless specified. NOTE: Effective with Sauce Connect Proxy version 4.6.0, this feature is no longer enabled by default.
`-p`	`--proxy <host:port>`	Proxy host and port that Sauce Connect Proxy should use to connect to the Sauce Labs REST API and test traffic. For more information about the `-p` option and configuring Sauce Connect with other proxies, see Sauce Connect Proxy Setup with Additional Proxies. As an alternative, you can also use environment variables `HTTP_PROXY, http_proxy, all_proxy, or ALL_PROXY` on the command line. For more information, see Environment Variables Used by Sauce Connect Proxy.
`-w`	`--proxy-userpwd <user:pwd>`	Username and password sent via basic authentication required to access the proxy configured with `-p (--proxy)`. For more information about the `-w` option and configuring Sauce Connect with other proxies, 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: Downloading Sauce Connect Proxy.
	`--pac <url>`	Proxy auto-configuration (PAC). Can be a http(s) or local file:// URL. For more information about the `-pac` option and configuring Sauce Connect with other proxies, see Sauce Connect Proxy Setup with Additional Proxies. Absolute paths are required when specifying a local PAC file (e.g., file:///Users/Andrew/Desktop/MyPac.pac).
	`--pac-auth <username:password@host:port>`	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. New Feature Option is only compatible with Sauce Connect Proxy client version 4.6.3+.
`-T`	`--proxy-tunnel`	Uses the proxy configured with `-p` for the tunnel connection. For more information about the `-T` option and configuring Sauce Connect with other proxies, see Sauce Connect Proxy Setup with Additional Proxies. You'll need to use this option if you use a PAC file that contains Sauce Labs DNS names.
`-s`	`--shared-tunnel`	Allows other users of the tunnel owner to use the tunnel. For more information, visit the Sharing Sauce Connect Proxy Tunnels - Extended Team Management page.
`-x`	`--rest-url <arg>`	By default, Sauce Connect Proxy connects to the US Virtual Device and Desktop Cloud (US-West-1). Use this option if you need to connect to a different Sauce Labs cloud (e.g., EU Virtual Device and Desktop Cloud or US Real Device Cloud). For a full list of Sauce Connect Proxy endpoints, see Data Center Endpoints.
`-f`	`--readyfile`	File that will be touched to indicate when the tunnel is ready.
`-a`	`--auth <host:port:user:pwd>`	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. Basic Authentication Only Sauce Connect'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, which means performing basic authentication in this way is disabled for all HTTPS domains passed to `--no-ssl-bump-domains` argument.
`-z`	`--log-stats <seconds>`	Logs statistics about HTTP traffic every `<seconds>`. Information includes bytes transmitted, requests made, and responses received.
	`--max-logsize <bytes>`	Rotates log file after reaching `<bytes>` size. Disabled by default.
	`--doctor`	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.
	`--no-autodetect`	Disables the auto-detection of proxy settings.
	`--version`	Displays version information and exit.
`-X`	`--scproxy-port <port>`	Sets port to use for the built-in HTTP proxy.
	`--cainfo <cainfo file>`	CA certificate bundle to use for verifying REST connections.
	`--capath <capath dir>`	Directory of CA certs to use for verifying REST connections.
	`--tunnel-cert public`	Requires that the certificates on the Sauce Labs internal tunnel Virtual Machine be signed by a Certificate Authority instead of self-signed certificates. See Sauce Connect Proxy Change Logs for details.
	`--tunnel-cainfo <cainfo file>`	CA certificate bundle to use for verifying tunnel connections.
	`--tunnel-capath <capath dir>`	Directory of CA certificates to use for verifying tunnel connections.
	`--scproxy-read-limit <X>`	Rates limit reads in scproxy to X bytes per second. This option can be used to adjust local network transfer rate in order not to overload the tunnel connection.
	`--scproxy-write-limit <X>`	Rates limit writes in scproxy to X bytes per second. This option can be used to adjust local network transfer rate in order not to overload the tunnel connection.
	`--dns <server[,server..]>`	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. Example: `--dns 8.8.8.8,8.8.4.4:53`.
	`--no-remove-colliding-tunnels`	By default, colliding tunnels will be removed when Sauce Connect is starting up. Use this option to prevent removal of identified tunnels with the same name or any other default tunnels. Jobs will be distributed across all tunnels, enabling load balancing and high availability.
`-d`	`--pidfile <file>`	Specifies the file in which to write the Sauce Connect Proxy process ID. When `--pidfile` is not explicitly specified, a randomly named pid file is generated (to avoid file name conflict). Sauce Connect Proxy makes a best effort but 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.
	`--metrics-address=address`	Defines host:port for the internal web server used to expose client side metrics (default is `localhost:8888`).
`-h`	`--help`	Displays the help text.
	`--extra-info '{"inject_job_id": true}'`	Injects 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. Header Injection is disabled for all HTTPS domains passed to `--no-ssl-bump-domains` argument.
	`--ocsp log-only`	OCSP tunnel certificate validation command that logs errors only; it will not stop Sauce Connect from connecting to a tunnel.
	`--ocsp attempt`	Sets an OCSP tunnel certificate validation "soft-fail" policy that allows Sauce Connect to run unless OCSP server returns a “revoked” status (e.g., timeouts, unknown status). It will not stop Sauce Connect from connecting to a tunnel. Connection to OCSP server will be set to time out after 5 seconds.
	`--ocsp strict`	Sets an OCSP tunnel certificate validation "hard-fail" policy that blocks Sauce Connect from running unless the OCSP server returns a “good” status (e.g., timeouts, revoked certificate, unknown status). It will stop Sauce Connect from connecting to a tunnel. Connection to OCSP server will be set to time out after 10 seconds.
	`--no-ocsp-verify`	OCSP tunnel certificate validation command that allows you to bypass OCSP checks.

NOTE: OCSP supports the following Sauce Connect 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 Commands

Here are some guidelines to follow when formatting domains within your commands:

Make sure your comma-separated list of domains doesn't include any spaces. For example, mydomain.com,saucelabs.com,mysite.com, instead of mydomain.com, saucelabs.com, mysite.com
Use only the domain name; no need to precede it with http: or https:
Prefix a domain name with "*." or simply "." to match all its subdomains. For 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 are not compatible with SSL bumping; you'll need to disable SSL Bumping for WebSocket domains

Developer-Only Command-Line Arguments

The following command-line arguments are only to be used when explicitly requested by our Support team.

Flag (Short)	Flag (Long)	Description
`-M`	`--max-missed-acks <...>`	Sets the maximum amount of keepalive ACKs that can be missed before the client will trigger a reconnect. The default is 30.
	`--no-cert-verify`	Disables certificate verification for tunnel/KGP connections.
	`--no-http-cert-verify`	Disables certificate verification for HTTP connections.
`-r`	`--reconnect=<boolean>`	If set false do not attempt to reconnect, and shut down.
	`--vm-version`	Requests a specific tunnel VM version.
`-o`	`--output-config`	Writes all configuration options as JSON to `stdout`. This flag is used by our Jenkins plugin and is not intended to be used by end users.

The Sauce Labs Cookbook

Sauce Headless

Front End Performance Testing

Insights

External Resources

More Info

Page tree

List of Sauce Connect Proxy Command-Line Arguments

Formatting Domains in Your Commands

Developer-Only Command-Line Arguments