Skip to main content

sc run

caution

Sauce Connect Proxy 5 release is currently in the Alpha stage, some changes in CLI are expected.

The sc run command is a main Sauce Connect Proxy 5 command that allows provisioning a Sauce Connect Proxy server and establishing a secure connection between the Sauce Connect Proxy client and the server.

Usage​

SAUCE_USER=<username> SAUCE_ACCESS_KEY=<access key> sc run --region <region> [OPTIONS]

Options​

Main​

--user​

| REQUIRED | STRING | stable |

Description: Sets your Sauce Labs username.
Environment variable: SAUCE_USER
Shorthand: -u

note

For additional security, we recommend setting this as an environment variable.

--access-key​

| REQUIRED | STRING | stable |

Description: Sets your Sauce Labs access key. This will be the same as your Access Key.
Environment variable: SAUCE_ACCESS_KEY
Shorthand: -k

note

For additional security, we recommend setting this as an environment variable.

--region​

| REQUIRED | STRING | stable |

Description: Sets your Sauce Labs data center endpoint (for example, us-west or eu-central).
Environment variable: SAUCE_REGION
Shorthand: -r

--tunnel-name​

| REQUIRED | STRING | stable |

Description: Assigns a name to a Sauce Connect Proxy tunnel. It can also assign a name to a group of tunnels in the same High Availability pool, when used with --tunnel-pool. Must be in ASCII format.
Environment variable: SAUCE_TUNNEL_NAME
Shorthand: -i

note

You can run tests using this tunnel by specifying the tunnelName in your test capabilities. To learn about the syntax for setting this as a capability, see Test Configuration Options.

--config-file​

| OPTIONAL | STRING | stable |

Description: Defines the local path to a YAML file containing a Sauce Connect Proxy configuration.
Environment variable: n/a
Shorthand: -c

note

The following precedence order of configuration sources is used: command flags, environment variables, config file, default values.

--rest-url​

| OPTIONAL | STRING | stable |

Description: Sets the URL for the data center endpoint of the location where the device you're testing on is hosted.
Environment variable: SAUCE_REST_URL
Shorthand: n/a

note

This flag is an alternative to the recommended --region. It's not shown in the CLI usage message.

--metadata​

| OPTIONAL | STRING | alpha |

Description: Sets custom metadata, expects key=value pairs. Can be repeated multiple times.
Environment variable: SAUCE_METADATA
Shorthand: -M

note

This flag is, primarily, used by Sauce Labs to assign custom properties to the tunnel info for reporting purposes.

--metadata "runner=jenkins" --metadata "group=qa"

Tunnel Mode Configuration​

--shared-tunnel​

| OPTIONAL | STRING | deprecated |

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

note

This flag will change in the stable release of Sauce Connect Proxy 5.0.0.

--tunnel-pool​

| OPTIONAL | STRING | stable |

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

Proxy Configuration​

--pac​

| OPTIONAL | STRING | stable |

Description: Proxy Auto-Configuration file to use for upstream proxy selection. It can be a local file or a URL, you can also use '-' to read from stdin. For more information, see Sauce Connect Proxy Setup with Additional Proxies.
Environment variable: SAUCE_PAC
Shorthand: -p

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

--auth​

| OPTIONAL | STRING | stable |

Description: Site or upstream proxy basic authentication credentials in the format username:password@host:port. The host and port can be set to "*" to match all. The flag can be specified multiple times to add multiple credentials.
Environment variable: SAUCE_PAC_AUTH
Shorthand: -a

--header​

| OPTIONAL | STRING | stable |

Description: Add or remove HTTP request headers. Use the format "name: value" to add a header, "name;" to set the header to empty value, "-name" to remove the header, "-name*" to remove headers by prefix. The header name will be normalized to canonical form. The header value should not contain any newlines or carriage returns. The flag can be specified multiple times.
Environment variable: SAUCE_HEADER
Shorthand: -H

-H "Host: example.com" -H "-User-Agent" -H "-X-*"

--proxy​

| OPTIONAL | STRING | stable |

Description: Defines an upstream proxy [protocol://]host:port where you want to route your test session traffic. For example, the traffic from a Firefox desktop test.
The supported protocols are: http, https, socks, socks5. No protocol specified will be treated as HTTP proxy. The basic authentication username and password can be specified in the host string e.g. user:pass@host:port. Alternatively, you can use the -a, --auth flag to specify the credentials. Environment variable: SAUCE_PROXY
Shorthand: -x

note

This flag configures the proxy for SUT traffic only. Use the --proxy-sauce flag to configure a proxy for the Sauce Labs REST API and Sauce Connect Server traffic.

--proxy-sauce​

| OPTIONAL | STRING | stable |

Description: Defines external proxy host:port where you want to route Sauce Labs REST API and Sauce Connect Server traffic.
Environment variable: SAUCE_PROXY_SAUCE
Shorthand: n/a

note

This flag configures the proxy for the Sauce Labs REST API and Sauce Connect Server traffic only. Use the --proxy flag to configure a proxy for SUT traffic proxy.

--proxy-localhost​

| OPTIONAL | STRING | stable |

Description: One of allow, deny, direct. Setting this to allow supports sending requests to localhost through the upstream proxy. This includes scenarios where an upstream proxy is hosted on localhost. Setting this to direct sends requests to localhost directly without using the upstream proxy. By default, requests to localhost are denied.
Environment variable: SAUCE_PROXY_LOCALHOST
Shorthand: n/a

--response-header​

| OPTIONAL | STRING | stable |

Description: Add or remove HTTP headers on the received response before sending it to the client. See the documentation for the -H, --header flag for more details on the format.
Environment variable: SAUCE_RESPONSE_HEADER
Shorthand: -R

Tunnel Traffic Configuration​

--direct-domains​

| OPTIONAL | STRING | alpha |

Description: Sets domain(s) that are requested through the public internet instead of the Sauce Connect Proxy tunnel. Can be repeated multiple times. This is the inverse of --tunnel-domains. See Tuning Sauce Connect Proxy Traffic for more information.
Environment variable: SAUCE_DIRECT_DOMAINS
Shorthand: -D

--tls-passthrough-domains​

| OPTIONAL | STRING | alpha |

Description: Sets domain(s) that do not require TLS resigning. Matching requests will not be TLS re-encrypted. Can be repeated multiple times. See SSL Certificate Bumping for more information about scenarios in which might want to use this command.
Environment variable: SAUCE_TLS_PASSTHROUGH_DOMAINS
Shorthand: -B

--deny-domains​

| OPTIONAL | STRING | alpha |

Description: Allows you to set a deny-list of domain patterns. Matching requests will get dropped instantly and will not go through the tunnel. Tests for app 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.
Environment variable: SAUCE_DENY_DOMAINS
Shorthand: -F

--tunnel-domains​

| OPTIONAL | STRING | alpha |

Description: Sets domain(s) that are requested through the Sauce Connect Proxy tunnel. This is the inverse of --direct-domains. Can be repeated multiple times. See Tuning Sauce Connect Proxy Traffic for more information.
Environment variable: SAUCE_TUNNEL_DOMAINS
Shorthand: -t

Client Configuration​

--address​

| OPTIONAL | STRING | alpha |

Description: Optional address for the built-in HTTP proxy.
Environment variable: SAUCE_ADDRESS
Shorthand: n/a

--api-address​

| OPTIONAL | STRING | stable |

Description: Use this option to define the host:port for the internal web server used to expose the Sauce Connect Proxy runtime info. Disabled by default.
Environment variable: SAUCE_API_ADDRESS
Shorthand: n/a

--api-basic-auth​

| OPTIONAL | STRING | stable |

Description: Basic authentication username:password credentials to protect the server. Username and password are URL decoded. This allows you to pass in special characters such as @ by using %40 or pass in a colon with %3a.
Environment variable: SAUCE_API_BASIC_AUTH
Shorthand: n/a

Networking and Security​

--cacert-file​

| OPTIONAL | STRING | stable |

Description: CA certificate bundle in PEM format to use in addition to the system root certificates. Can be a path to a file or "data:" followed by base64 encoded certificate. Use this flag multiple times to specify multiple CA certificate files.
Environment variable: SAUCE_CACERT_FILE
Shorthand: n/a

--dns-server​

| OPTIONAL | STRING | stable |

Description: DNS server(s) to use instead of system default. There are two execution policies, when more then one server is specified. Fallback: the first server in a list is used as primary, the rest are used as fallbacks. Round robin: the servers are used in a round-robin fashion. The port is optional, if not specified the default port is 53.
Environment variable: SAUCE_DNS
Shorthand: -n

sc run --dns-server 8.8.8.8 --dns-server 8.8.4.4:53

Logging​

--log-file​

| OPTIONAL | STRING | stable |

Description: Captures the Sauce Connect Proxy logs in a file. If a path is not specified, logs to stdout.
Environment variable: SAUCE_LOG_FILE
Shorthand: n/a

--log-http​

| OPTIONAL | STRING | alpha |

Description: HTTP request and response logging mode, one of none, short-url, url, headers, body, errors. HTTP request and response logging mode. By default, request line and headers are logged if response status code is greater than or equal to 500. Setting this to none disables logging. The short-url mode logs [scheme://]host[/path] instead of the full URL.
Environment variable: SAUCE_LOG_HTTP
Shorthand: n/a

--log-level​

| OPTIONAL | STRING | stable |

Description: Log level, one of error, info, debug. The default is info.
Environment variable: SAUCE_LOG_LEVEL
Shorthand: n/a

note

Setting the SAUCE_LOG_LEVEL environment variable to 1 is equivalent to -v and 2 is equivalent to -vv.

Formatting Domains​

Here are some guidelines to follow when formatting domain regular expressions:

  • 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 a dot . to match all its subdomains.
    • Example: You could refer to docs.saucelabs.com and my.saucelabs.com as .saucelabs.com.

Additional Resources​