The Sauce Labs Cookbook

Sauce Headless

Front End Performance Testing

Analytics

External Resources

More Info


Page tree
Skip to end of metadata
Go to start of metadata

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.

Effective with Sauce Connect Proxy version 4.5.0, 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 > Config File > Environment Variable

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.

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

-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 > Config File > Environment Variable.

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

Supported with Sauce Connect Proxy version 4.5.0 and above.

-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 Troubleshooting > SSL Bumping Enabled by Default for more information about scenarios in which you would want to use this command.

For more info, see Formatting Domains guidelines at the bottom of this page.

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

-N
 --no-proxy-caching

Disable caching in Sauce Connect Proxy. All requests will be sent through the tunnel.

-M
 --max-missed-acks <...>

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

-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 at the bottom of this page.

-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 at the bottom of this page.

-v
 --verbose

Enable verbose debugging. -vv will output HTTP headers and KGP logs. Effective with Sauce Connect Proxy version 4.4.3, -v will also output HTTP headers.

Running Sauce Connect Proxy with the very verbose -vv option is system-resource demanding and will adversely affect Sauce Connect Proxy performance. This option is meant for troubleshooting only, not for long-term use and should not be used in production.


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

Assign <id> to this Sauce Connect Proxy instance. Future jobs will use this tunnel only when explicitly specified by the tunnel-identifier DesiredCapability in a Selenium client. For more information on using --tunnel-identifier to run multiple Sauce Connect tunnels simultaneously, see High Availability Sauce Connect Proxy Setup. Test Configuration Options contains more information about the syntax for setting tunnel-identifier as a DesiredCapability. Note that <id> must be ASCII.

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

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: This feature is deprecated in Sauce Connect 4.6 and will be removed in a future version.

-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 using Sauce Connect with multiple internal 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 or all proxies used on a PAC file. For more information about using Sauce Connect with proxies, see Sauce Connect Proxy Setup with Additional Proxies.


 --pac <url>

Proxy auto-configuration (PAC). Can be a http(s) or local file:// URL. For more information about using Sauce Connect with 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).

-T
 --proxy-tunnel

Use the proxy configured with -p for the tunnel connection. For more information about using Sauce Connect with proxies, see Sauce Connect Proxy Setup with Additional Proxies.

For Sauce Connect Proxy version 4.5.3 and above, you must use this option if you use a PAC file that has 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 "US virtual desktop and device cloud." Use this option if you need to connect to a different Sauce Labs cloud.

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

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


 --no-autodetect

Disables the auto-detection of proxy settings.


 --version

Displays version information and exit.

-X
 --scproxy-port <port>

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 (under version 4.5.4) for details.

Supported in Sauce Connect Proxy versions 4.5.4 and above.


--tunnel-cainfo <cainfo file>

CA certificate bundle to use for verifying tunnel connections.

Supported in Sauce Connect Proxy versions 4.5.4 and above.


--tunnel-capath <capath dir>

Directory of CA certs to use for verifying tunnel connections.

Supported in Sauce Connect Proxy versions 4.5.4 and above.


--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>
Rate 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..]>

Use 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

Don't remove identified tunnels with the same name, or any other default tunnels, if this is a default tunnel. Jobs will be distributed across these tunnels, enabling load balancing and high availability. By default, colliding tunnels will be removed when Sauce Connect is starting up.

-d

--pidfile <file>

File to write the Sauce Connect Proxy process ID into. Useful for programmatically stopping Sauce Connect.

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

host:port for the internal web server used to expose client side metrics (default: 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.

Developer-Only Command-Line Arguments

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

Flag (Short)Flag (Long)

Description


 --no-cert-verify

Disables certificate verification for tunnel/KGP connections.



 --no-http-cert-verify


Disables certificate verification for HTTP connections.

-r
 --reconnect <seconds>

Maximum time in seconds to wait between tunnel reconnect attempts.


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

Formatting Domains

Here are some guidelines to follow when formatting domains within command-lines:

  • 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