From f5ba90283982fd983d5b3a3c7d462bdb3a3389e6 Mon Sep 17 00:00:00 2001 From: Hubert Grochowski Date: Tue, 26 Mar 2024 12:35:35 +0100 Subject: [PATCH] sc5: move cli docs to secure connections section This patch is a foundation to auto generated SC5 CLI docs. This moves all sc5 docs to one place. It has several advantages: - centralized information/unified structure: Users often look for all relevant documentation in one place. Having CLI docs next to other related docs reduces the need to navigate through different sections of the site, providing a smoother and more intuitive user experience. - consistent context/cross-referencing ease: Keeping related documents together helps maintain context for the user, as they can browse quickly through the sidebar. - discoverability: Users might not always know what they are looking for. By having CLI docs in the same location as other SC content, you increase the chances of users discovering useful commands and features they weren't initially aware of. - SEO benefits: From a web presence perspective, having a consolidated section with comprehensive coverage of a topic can improve search engine visibility. The SC5 CLI section will remain and point to new cli directory. --- docs/dev/cli.md | 2 +- docs/dev/cli/sauce-connect-5.md | 90 +--- docs/dev/cli/sauce-connect-5/completion.md | 86 +--- docs/dev/cli/sauce-connect-5/sc_legacy.md | 255 +----------- docs/dev/cli/sauce-connect-5/sc_run.md | 382 +---------------- docs/dev/cli/sauce-connect-proxy.md | 2 +- docs/secure-connections/sauce-connect-5.md | 16 +- .../sauce-connect-5/cli/sc.md | 33 ++ .../sauce-connect-5/cli/sc_legacy.md | 258 ++++++++++++ .../sauce-connect-5/cli/sc_run.md | 385 ++++++++++++++++++ .../sauce-connect-5/installation/docker.md | 2 +- .../installation/kubernetes.md | 2 +- .../sauce-connect-5/installation/linux.md | 6 +- .../sauce-connect-5/installation/macos.md | 4 +- .../sauce-connect-5/installation/windows.md | 2 +- .../sauce-connect-5/migrating.md | 2 +- .../sauce-connect-5/operation/api-server.md | 6 +- .../operation/configuration.md | 40 +- .../sauce-connect-5/operation/monitoring.md | 4 +- .../sauce-connect-5/operation/overview.md | 6 +- .../sauce-connect-5/operation/proxies.md | 26 +- .../sauce-connect-5/quickstart.md | 6 +- sidebars.js | 25 +- 23 files changed, 773 insertions(+), 867 deletions(-) create mode 100644 docs/secure-connections/sauce-connect-5/cli/sc.md create mode 100644 docs/secure-connections/sauce-connect-5/cli/sc_legacy.md create mode 100644 docs/secure-connections/sauce-connect-5/cli/sc_run.md diff --git a/docs/dev/cli.md b/docs/dev/cli.md index 97fa677b26..bcba46f9ca 100644 --- a/docs/dev/cli.md +++ b/docs/dev/cli.md @@ -17,7 +17,7 @@ hide_table_of_contents: true
-

Sauce Connect Proxy 5 CLI

+

Sauce Connect Proxy 5 CLI

The CLI tool for deploying Sauce Connect Proxy 5 tunnels.

diff --git a/docs/dev/cli/sauce-connect-5.md b/docs/dev/cli/sauce-connect-5.md index 897accde46..87a1cec883 100644 --- a/docs/dev/cli/sauce-connect-5.md +++ b/docs/dev/cli/sauce-connect-5.md @@ -1,85 +1,23 @@ --- id: sauce-connect-5 -title: Sauce Connect Proxy 5 CLI Reference -sidebar_label: sc +title: Sauce Connect 5 CLI --- -import useBaseUrl from '@docusaurus/useBaseUrl'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +# Sauce Connect 5 CLI Documentation Has Moved -Below is a list of commands available with your Sauce Connect Proxy application. +The documentation you're looking for has been moved to a new location. Please use the links below to access the Sauce Connect 5 CLI documentation directly. -## What You'll Need +## Quick Links to New Documentation -- Make sure you're using the latest [Sauce Connect Proxy version](/secure-connections/sauce-connect-5/installation/). Otherwise, some commands may not work. -- See [Sauce Connect Quickstart](/secure-connections/sauce-connect-5/quickstart/) for setup instructions and use cases. +- **Sauce Connect 5 CLI Overview**: [Visit Here](/secure-connections/sauce-connect-5/cli/sc) +- **Running Sauce Connect Proxy**: [sc run Documentation](/secure-connections/sauce-connect-5/cli/run) +- **Compatibility Mode (Legacy)**: [sc legacy Documentation](/secure-connections/sauce-connect-5/cli/legacy) +- **Command Line Autocompletion**: Learn more about sc completion: + - [linux](/secure-connections/sauce-connect-5/installation/linux/#add-bash-completion) + - [macOS](/secure-connections/sauce-connect-5/installation/macos/#add-completion) + - [windows](/secure-connections/sauce-connect-5/installation/windows/#add-completion) +- **Additional Resources**: For setup and configuration, see the [installation guide](/secure-connections/sauce-connect-5/installation) and [configuration guide](/secure-connections/sauce-connect-5/operation/configuration/). -
+For any additional help or questions, please contact our support team. -## Commands - -- [sc run](/dev/cli/sauce-connect-5/run/) -- [sc legacy](/dev/cli/sauce-connect-5/legacy/) -- [sc completion](/dev/cli/sauce-connect-5/completion/) -- `sc version` -- `sc help` - -### `sc run` - -The [sc run](/dev/cli/sauce-connect-5/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. - -### `sc legacy` - -The [sc legacy](/dev/cli/sauce-connect-5/legacy/) command runs Sauce Connect Proxy 5 in compatibility mode with Sauce Connect Proxy 4. - -### `sc completion` - -The [sc completion](/dev/cli/sauce-connect-5/completion/) command generates an autocompletion script for `bash`, `zsh`, `fish` and `powershell` shells. See each sub-command's help for details on how to use the generated script. - -### `sc version` - -The `sc version` command output detailed version info. - -```bash -sc version - Version: 5.0.0 - Build time: 2023-10-31T21:11:37Z - Git commit: 9eb9a377aaa791765f74aace37e83d8ac1d000e2 - Go Arch: arm64 - Go OS: darwin - Go Version: go1.21.3 -``` - -### `sc help` - -The `sc help` command allows getting usage for other commands - -```bash -sc help -Sauce Connect Proxy CLI opens a secure connection between Sauce Labs and a locally hosted applications. You can learn -more at https://docs.saucelabs.com/secure-connections/sauce-connect-5/. - -Commands: - run Run Sauce Connect Proxy - -Other Commands: - completion Generate the autocompletion script for the specified shell - version Print version information - -The following options can be passed to any subcommand: - -Other: - -c, --config-file (env SAUCE_CONFIG_FILE) - Configuration file to load options from. The supported formats are: JSON, YAML, TOML, HCL, and Java - properties. The file format is determined by the file extension, if not specified the default format is YAML. - The following precedence order of configuration sources is used: command flags, environment variables, config - file, default values. - -Use "sc --help" for more information about a given command. -``` - -## Additional Resources - -- [Sauce Connect Proxy Basic Setup](/secure-connections/sauce-connect-5/installation/). -- [Sauce Connect Proxy Environment Variables](/secure-connections/sauce-connect-5/operation/configuration/#environment-variables/). +Thank you for using Sauce Connect! diff --git a/docs/dev/cli/sauce-connect-5/completion.md b/docs/dev/cli/sauce-connect-5/completion.md index 04eed8877e..8b1985ec3f 100644 --- a/docs/dev/cli/sauce-connect-5/completion.md +++ b/docs/dev/cli/sauce-connect-5/completion.md @@ -1,89 +1,7 @@ --- id: completion title: sc completion -sidebar_label: sc completion --- -Generate an autocompletion script for `bash`, `zsh`, `fish` and `powershell` shells. See each sub-command's help for details on how to use the generated script. - -## Usage - -```bash -$ sc completion [OPTIONS] -``` - -## Options - -### bash - -
- -#### Linux - -``` -sc completion bash > /etc/bash_completion.d/sc -``` - -#### macOS - -``` -sc completion bash > /usr/local/etc/bash_completion.d/sc -``` - -
- -### zsh - -
- -1. If shell completion is not already enabled in your environment, enable it by executing the following once: - -``` -echo "autoload -U compinit; compinit" >> ~/.zshrc -``` - -2. To load completions for each session, execute once: - -``` -sc completion zsh > "${fpath[1]}/_sc" -``` - -3. Start a new shell to apply this setup. - -
- -### fish - -
- -``` -sc completion fish | source -``` - -To load completions for each session, execute once: - -``` -sc completion fish > ~/.config/fish/completions/sc.fish -``` - -
- -### Powershell - -
- -``` -sc completion powershell | Out-String | Invoke-Expression -``` - -To load completions for every new session, run the following and then source this file from your Powershell profile: - -``` -sc completion powershell > sc.ps1 -``` - -
- -## Additional Resources - -- [Sauce Connect Proxy Basic Setup](/secure-connections/sauce-connect-5/installation/). +# This page has been moved +See [Sauce Connect 5 CLI completion documentation](/secure-connections/sauce-connect-5/cli/sc/#command-line-autocompletion). diff --git a/docs/dev/cli/sauce-connect-5/sc_legacy.md b/docs/dev/cli/sauce-connect-5/sc_legacy.md index 3e8126eae8..e5d4d4135f 100644 --- a/docs/dev/cli/sauce-connect-5/sc_legacy.md +++ b/docs/dev/cli/sauce-connect-5/sc_legacy.md @@ -3,256 +3,5 @@ id: legacy title: sc legacy --- -# Sc Legacy - -Usage: `sc legacy [flags]` - -Run Sauce Connect Proxy in compatibility mode with Sauce Connect 4.9.X - -**Note:** You can also specify the options as YAML, JSON or TOML file using `--config-file` flag. -You can generate a config file by running `sc legacy config-file` command. - - -## Required - -### `-r, --region` {#region} - -* Environment variable: `SAUCE_REGION` -* Value Format: `` - -Sauce Labs datacenter region. -Default: us-west. - -### `-i, --tunnel-name` {#tunnel-name} - -* Environment variable: `SAUCE_TUNNEL_NAME` -* Value Format: `` - -Tunnel name used for this tunnel or the tunnels in the same HA pool. - -### `-u, --user` {#user} - -* Environment variable: `SAUCE_USER` -* Value Format: `` - -Sauce Labs username. - -## Options - -### `-s, --shared-tunnel` {#shared-tunnel} - -* Environment variable: `SAUCE_SHARED_TUNNEL` -* Value Format: `` -* Default value: `false` - -Share the tunnels within the same organization. - -### `--tunnel-pool` {#tunnel-pool} - -* Environment variable: `SAUCE_TUNNEL_POOL` -* Value Format: `` -* Default value: `false` - -Denotes a tunnel as part of a high availability tunnel pool. - -## Tunnel traffic - -### `-D, --direct-domains` {#direct-domains} - -* Environment variable: `SAUCE_DIRECT_DOMAINS` -* Value Format: `` - -Domains that do not require tunneling. - -### `-t, --tunnel-domains` {#tunnel-domains} - -* Environment variable: `SAUCE_TUNNEL_DOMAINS` -* Value Format: `` - -Domains that require tunneling. -Inverse of '--direct-domains'. - -## Proxy - -### `-a, --auth` {#auth} - -* Environment variable: `SAUCE_AUTH` -* Value Format: `` - -Basic authentication for URL in host:port:username:password format. - -### `-T, --proxy-tunnel` {#proxy-tunnel} - -* Environment variable: `SAUCE_PROXY_TUNNEL` -* Value Format: `` -* Default value: `false` - -Route all tunnel traffic through the external proxy specified in --proxy. - -## DNS - -### `--dns` {#dns} - -* Environment variable: `SAUCE_DNS` -* Value Format: `` - -Use the specified name server. -Example: --dns 8.8.8.8,8.8.4.4:53 - -## API server - -### `-k, --api-key` {#api-key} - -* Environment variable: `SAUCE_API_KEY` -* Value Format: `` - -Sauce Labs API Access Key. - -## Logging - -### `-z, --log-stats` {#log-stats} - -* Environment variable: `SAUCE_LOG_STATS` -* Value Format: `` -* Default value: `0` - -seconds Log statistics about HTTP traffic every ``. - -## Other - -### `--autodetect` {#autodetect} - -* Environment variable: `SAUCE_AUTODETECT` -* Value Format: `` -* Default value: `true` - -Detect the system proxy settings. -Inverse of '--no-autodetect'. -Default: true. - -### `--cainfo` {#cainfo} - -* Environment variable: `SAUCE_CAINFO` -* Value Format: `` -* Default value: `/etc/ssl/certs/ca-certificates.crt` - -CA certificate for verifying REST API. - -### `-c, --config-file` {#config-file} - -* Environment variable: `SAUCE_CONFIG_FILE` -* Value Format: `` - -Path to YAML config file. - -### `--experimental` {#experimental} - -* Environment variable: `SAUCE_EXPERIMENTAL` -* Value Format: `` - -Enable or disable experimental features. - -### `--extra-info` {#extra-info} - -* Environment variable: `SAUCE_EXTRA_INFO` -* Value Format: `` -* Default value: `{}` - -JSON string that contains an advanced tunnel configuration. - -### `-F, --fast-fail-regexps` {#fast-fail-regexps} - -* Environment variable: `SAUCE_FAST_FAIL_REGEXPS` -* Value Format: `` - -Deny-list URL patterns. - -### `--no-autodetect` {#no-autodetect} - -* Environment variable: `SAUCE_NO_AUTODETECT` -* Value Format: `` -* Default value: `false` - -Disable detection of the system proxy settings. -Default: false. - -### `-B, --no-ssl-bump-domains` {#no-ssl-bump-domains} - -* Environment variable: `SAUCE_NO_SSL_BUMP_DOMAINS` -* Value Format: `` - -Domains that do not require SSL resigning. - -### `--ocsp` {#ocsp} - -* Environment variable: `SAUCE_OCSP` -* Value Format: `` -* Default value: `log-only` - -Cert revocation check. -One of: strict, log-only, disable. -Default: log-only. - -### `--output-config-file` {#output-config-file} - -* Environment variable: `SAUCE_OUTPUT_CONFIG_FILE` -* Value Format: `` - -Write the new Sauce Connect 5 run command configuration to the specified file. - - If set the run command will not be executed. - - -### `-d, --pidfile` {#pidfile} - -* Environment variable: `SAUCE_PIDFILE` -* Value Format: `` - -File containing the process ID (PID). -Default: temp file. - -### `-f, --readyfile` {#readyfile} - -* Environment variable: `SAUCE_READYFILE` -* Value Format: `` - -File containing JSON formatted metadata. -Created when the tunnel is ready. - -### `-x, --rest-url` {#rest-url} - -* Environment variable: `SAUCE_REST_URL` -* Value Format: `` - -Sauce REST API URL. -An alternative to the recommended flag '--region'. - -### `-P, --se-port` {#se-port} - -* Environment variable: `SAUCE_SE_PORT` -* Value Format: `` -* Default value: `-1` - -Port on which Sauce Connect's Selenium relay will listen for requests. - -### `--status-address` {#status-address} - -* Environment variable: `SAUCE_STATUS_ADDRESS` -* Value Format: `` - -Status server address in host:port format. -Default: disabled. - -### `--tunnel-cainfo` {#tunnel-cainfo} - -* Environment variable: `SAUCE_TUNNEL_CAINFO` -* Value Format: `` -* Default value: `/etc/ssl/certs/ca-certificates.crt` - -CA certificate bundle to use for verifying tunnel connections. - -## Additional Resources - -- [Sauce Connect Proxy Basic Setup](/secure-connections/sauce-connect-5/installation/). -- [Sauce Connect Proxy 5 Migration Guide](/secure-connections/sauce-connect-5/migrating/). -- [Sauce Connect Proxy 4 CLI Reference](/dev/cli/sauce-connect-proxy). +# This page has been moved +See [Sauce Connect 5 CLI legacy documentation](/secure-connections/sauce-connect-5/cli/sc/#compatibility-mode-legacy). diff --git a/docs/dev/cli/sauce-connect-5/sc_run.md b/docs/dev/cli/sauce-connect-5/sc_run.md index 72dd569b6e..ef09d29fd8 100644 --- a/docs/dev/cli/sauce-connect-5/sc_run.md +++ b/docs/dev/cli/sauce-connect-5/sc_run.md @@ -3,383 +3,5 @@ id: run title: sc run --- -# Sc Run - -Usage: `sc run --username --access-key --region --tunnel-name [flags]` - -Run Sauce Connect Proxy - -**Note:** You can also specify the options as YAML, JSON or TOML file using `--config-file` flag. -You can generate a config file by running `sc run config-file` command. - - -## Required - -### `-k, --access-key` {#access-key} - -* Environment variable: `SAUCE_ACCESS_KEY` -* Value Format: `` - -Sauce Labs Access Key, you can get it from the [User Settings page](https://app.saucelabs.com/user-settings). -For additional security, we recommend setting this as an environment variable. - -### `-r, --region` {#region} - -* Environment variable: `SAUCE_REGION` -* Value Format: `` - -Sauce Labs region name, ex. -us-west or eu-central. -More details [here](/basics/data-center-endpoints). - -### `-i, --tunnel-name` {#tunnel-name} - -* Environment variable: `SAUCE_TUNNEL_NAME` -* Value Format: `` - -Name of the tunnel or tunnel pool. -You can run tests using this tunnel by specifying the tunnelName value in your test capabilities, see [here](/dev/test-configuration-options/). -It can also assign a name to a group of tunnels in the same high availability pool, see [here](/secure-connections/sauce-connect/setup-configuration/high-availability/). - -### `-u, --username` {#username} - -* Environment variable: `SAUCE_USERNAME` -* Value Format: `` - -Sauce Labs username. -For additional security, we recommend setting this as an environment variable. - -## Options - -### `-M, --metadata` {#metadata} - -* Environment variable: `SAUCE_METADATA` -* Value Format: `,...` - -Custom metadata key-value pairs. -This flag is, primarily, used by Sauce Labs to assign custom properties to the tunnel for reporting purposes. - -### `-s, --shared` {#shared} - -* Environment variable: `SAUCE_SHARED` -* Value Format: `` - -Share the tunnel within the same org unit. -Only the 'all' option is currently supported. -See [here](/basics/acct-team-mgmt/sauce-connect-proxy-tunnels/). - -### `-t, --tunnel-pool` {#tunnel-pool} - -* Environment variable: `SAUCE_TUNNEL_POOL` -* Value Format: `` -* Default value: `false` - -Denotes a tunnel as part of a high availability tunnel pool. -See [here](/secure-connections/sauce-connect/setup-configuration/high-availability/). - - -## Tunnel traffic - -### `-F, --deny-domains` {#deny-domains} - -* Environment variable: `SAUCE_DENY_DOMAINS` -* Value Format: `[-],...` - -Deny requests to the matching domains. -Prefix domains with '-' to exclude requests from being denied. - -The following example denies requests to *.example.com and *.google.com. - -``` ---deny-domains .*\.example\.com,.*\.google\.com -``` - -### `-D, --direct-domains` {#direct-domains} - -* Environment variable: `SAUCE_DIRECT_DOMAINS` -* Value Format: `[-],...` - -Forward matching requests to their origin server over the public internet. -Requests that don't match "direct domains" will be forwarded to customer-side over the Sauce Connect Proxy connection. -You can specify --direct-domains or --tunnel-domains, but not both. -Prefix domains with '-' to exclude requests from being forwarded directly. -Note that direct domains are automatically excluded from being resigned. - -The following example sends requests to *.example.com and *.google.com directly. -It would tunnel all other domains. - -``` ---direct-domains .*\.example\.com,.*\.google\.com -``` - -### `-B, --tls-passthrough-domains` {#tls-passthrough-domains} - -* Environment variable: `SAUCE_TLS_PASSTHROUGH_DOMAINS` -* Value Format: `[-],...` - -Pass matching requests to their origin server without SSL/TLS re-encryption. -You can specify --tls-passthrough-domains or --tls-resign-domains, but not both. -Prefix domains with '-' to exclude requests from being passed through. -Note that direct domains will always be passed through. - -The following example passes requests to *.example.com and *.google.com through without SSL/TLS re-encryption. - -``` ---tls-passthrough-domains .*\.example\.com,.*\.google\.com -``` - -### `-b, --tls-resign-domains` {#tls-resign-domains} - -* Environment variable: `SAUCE_TLS_RESIGN_DOMAINS` -* Value Format: `[-],...` - -Resign SSL/TLS certificates for matching requests. -You can specify --tls-resign-domains or --tls-passthrough-domains, but not both. -Prefix domains with '-' to exclude requests from being resigned. -Note that direct domains will never be resigned. - -The following example resigns SSL/TLS certificates for all requests to *.myorg.dev, except abc.myorg.dev. - -``` ---tls-resign-domains .*\.myorg\.dev,-abc\.myorg\.dev -``` - -### `-T, --tunnel-domains` {#tunnel-domains} - -* Environment variable: `SAUCE_TUNNEL_DOMAINS` -* Value Format: `[-],...` - -Forward matching requests over the Sauce Connect Proxy connection. -Requests not matching "tunnel domains" will be forwarded to their origin server over the public internet. -This is the recommended option for the best performance since it minimizes the expensive tunnelled traffic and uses it only for internal domains that are not publicly available. -You can specify --tunnel-domains or --direct-domains, but not both. -Prefix domains with '-' to exclude requests from being forwarded over the SC Proxy connection. - -The following example tunnels all requests to *.myorg.dev, except abc.myorg.com. - -``` ---tunnel-domains .*\.myorg\.dev,-abc\.myorg\.com -``` - -## Proxy - -### `-a, --auth` {#auth} - -* Environment variable: `SAUCE_AUTH` -* Value Format: `` - -Site or upstream proxy basic authentication credentials. -The host and port can be set to "*" to match all hosts and ports respectively. -The flag can be specified multiple times to add multiple credentials. -Note: Requests to these hosts will be automatically resigned as if there were specified in --tls-resign-domains flag. -Example: -``` ---proxy myproxy.org:3128 --proxy-sauce https://external.com:443 --auth user1:pass1@myproxy.org:3128,user2:pass2@external.com:* -``` - -### `-H, --header` {#header} - -* Environment variable: `SAUCE_HEADER` -* Value Format: `
` - -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. -Example: -H "Host: example.com" -H "-User-Agent" -H "-X-*". - -### `-p, --pac` {#pac} - -* Environment variable: `SAUCE_PAC` -* Value Format: `` - -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. -The data URI scheme is supported, the format is `data:base64,`. - -### `-x, --proxy` {#proxy} - -* Environment variable: `SAUCE_PROXY` -* Value Format: `[protocol://]host[:port]` - -Upstream proxy to use for requests received from the Sauce Connect Server only. -The supported protocols are: http, https, socks, socks5. -No protocol specified will be interpreted as an HTTP proxy. -If the port number is not specified, it is assumed to be 1080. -The basic authentication username and password can be specified in the host string, e.g. -user:pass@host:port. -Alternatively, you can specify the credentials using the -a, --auth flag. - -### `--proxy-localhost` {#proxy-localhost} - -* Environment variable: `SAUCE_PROXY_LOCALHOST` -* Value Format: `` -* Default value: `deny` - -Setting this to allow enables sending requests to localhost through the upstream proxy. -Setting this to direct sends requests to localhost directly without using the upstream proxy. -By default, requests to localhost are denied. - -### `--proxy-sauce` {#proxy-sauce} - -* Environment variable: `SAUCE_PROXY_SAUCE` -* Value Format: `[protocol://]host[:port]` - -Proxy for requests to Sauce Labs REST API and Sauce Connect servers only. -See the -x, --proxy flag for more details on the format. - -## DNS - -### `--dns-round-robin` {#dns-round-robin} - -* Environment variable: `SAUCE_DNS_ROUND_ROBIN` -* Value Format: `` -* Default value: `false` - -If more than one DNS server is specified with the --dns-server flag, passing this flag will enable round-robin selection. - - -### `-n, --dns-server` {#dns-server} - -* Environment variable: `SAUCE_DNS_SERVER` -* Value Format: `[:]` - -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. - -### `--dns-timeout` {#dns-timeout} - -* Environment variable: `SAUCE_DNS_TIMEOUT` -* Value Format: `` -* Default value: `5s` - -Timeout for dialing DNS servers. -Only used if DNS servers are specified. - - -## HTTP client - -### `--cacert-file` {#cacert-file} - -* Environment variable: `SAUCE_CACERT_FILE` -* Value Format: `` - -Add your own CA certificates to verify against. -The system root certificates will be used in addition to any certificates in this list. -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. - -### `--http-dial-timeout` {#http-dial-timeout} - -* Environment variable: `SAUCE_HTTP_DIAL_TIMEOUT` -* Value Format: `` -* Default value: `30s` - -The maximum amount of time a dial will wait for a connect to complete. -With or without a timeout, the operating system may impose its own earlier timeout. -For instance, TCP timeouts are often around 3 minutes. - - -### `--http-idle-conn-timeout` {#http-idle-conn-timeout} - -* Environment variable: `SAUCE_HTTP_IDLE_CONN_TIMEOUT` -* Value Format: `` -* Default value: `1m30s` - -The maximum amount of time an idle (keep-alive) connection will remain idle before closing itself. -Zero means no limit. - - -### `--http-response-header-timeout` {#http-response-header-timeout} - -* Environment variable: `SAUCE_HTTP_RESPONSE_HEADER_TIMEOUT` -* Value Format: `` -* Default value: `0s` - -The amount of time to wait for a server's response headers after fully writing the request (including its body, if any).This time does not include the time to read the response body. -Zero means no limit. - - -### `--http-tls-handshake-timeout` {#http-tls-handshake-timeout} - -* Environment variable: `SAUCE_HTTP_TLS_HANDSHAKE_TIMEOUT` -* Value Format: `` -* Default value: `10s` - -The maximum amount of time waiting to wait for a TLS handshake. -Zero means no limit. - -## API server - -### `--api-address` {#api-address} - -* Environment variable: `SAUCE_API_ADDRESS` -* Value Format: `` - -The server address to listen on. -If the host is empty, the server will listen on all available interfaces. - -### `--api-basic-auth` {#api-basic-auth} - -* Environment variable: `SAUCE_API_BASIC_AUTH` -* Value Format: `` - -Basic authentication credentials to protect the server. - -### `--api-idle-timeout` {#api-idle-timeout} - -* Environment variable: `SAUCE_API_IDLE_TIMEOUT` -* Value Format: `` -* Default value: `1h0m0s` - -The maximum amount of time to wait for the next request before closing connection. - -## Logging - -### `--log-file` {#log-file} - -* Environment variable: `SAUCE_LOG_FILE` -* Value Format: `` - -Path to the log file, if empty, logs to stdout. - -### `--log-http` {#log-http} - -* Environment variable: `SAUCE_LOG_HTTP` -* Value Format: `[api|proxy|control:],...` - -HTTP request and response logging mode. -Setting this to none disables logging. -The short-url mode logs [scheme://]host[/path] instead of the full URL. -The error mode logs request line and headers if status code is greater than or equal to 500. - -### `--log-level` {#log-level} - -* Environment variable: `SAUCE_LOG_LEVEL` -* Value Format: `` -* Default value: `info` - -Log level. - -## 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` -- Domains flags can be repeated multiple times - - Example, `--direct-domains mydomain\.com,saucelabs\.com --direct-domains mysite\.com` -- Prefix domain names with `.*` to match all its subdomains. - - Example: You could refer to `docs\.saucelabs\.com` and `my\.saucelabs\.com` as `.*saucelabs\.com`. -- Escape special characters, such as `.` to ensure they are not parsed - - Not escaping dot character doesn't result in error, dot matches every single character except a newline. For example, `example.com` will match `example.com` and also `examplescom`, while `example\.com` will match `example.com` only. - -## Additional Resources - -- [Sauce Connect Proxy Installation](/secure-connections/sauce-connect-5/installation/). +# This page has been moved +See [Sauce Connect 5 CLI run documentation](/secure-connections/sauce-connect-5/cli/run). diff --git a/docs/dev/cli/sauce-connect-proxy.md b/docs/dev/cli/sauce-connect-proxy.md index f52bbd7a5e..fd06b894a0 100644 --- a/docs/dev/cli/sauce-connect-proxy.md +++ b/docs/dev/cli/sauce-connect-proxy.md @@ -12,7 +12,7 @@ Below is a list of flags to use on your Sauce Connect Proxy v4.x.x command line :::note This is Sauce Connect Version 4 CLI documentation. -The Sauce Connect Proxy version 5 major release introduced breaking CLI changes. Please refer to [Sauce Connect Proxy 5 CLI Reference](/dev/cli/sauce-connect-5/run/) for details. +The Sauce Connect Proxy version 5 major release introduced breaking CLI changes. Please refer to [Sauce Connect Proxy 5 CLI Reference](/secure-connections/sauce-connect-5/cli/sc/) for details. ::: ## What You'll Need diff --git a/docs/secure-connections/sauce-connect-5.md b/docs/secure-connections/sauce-connect-5.md index cdd07f2b23..6d949d1f6e 100644 --- a/docs/secure-connections/sauce-connect-5.md +++ b/docs/secure-connections/sauce-connect-5.md @@ -13,8 +13,8 @@ Sauce Connect Proxy 5 is a complete rewrite of Sauce Connect Proxy 4.x.x that ai ## What's New In Sauce Connect Proxy 5? :::caution -The Sauce Connect Proxy version 5 major release introduces CLI changes. Please refer to [Sauce Connect Proxy 5 CLI Reference](/dev/cli/sauce-connect-5/run/) for details. -An [`sc legacy`](/dev/cli/sauce-connect-5/legacy/) command is introduced to help users transition from version 4.x.x to 5.0.x. +The Sauce Connect Proxy version 5 major release introduces CLI changes. Please refer to [Sauce Connect Proxy 5 CLI Reference](/secure-connections/sauce-connect-5/cli/sc/) for details. +An [`sc legacy`](/secure-connections/sauce-connect-5/cli/legacy/) command is introduced to help users transition from version 4.x.x to 5.0.x. ::: 1. Improved onboarding and integration due to the secure connection (tunnel) protocol change. @@ -34,13 +34,13 @@ An [`sc legacy`](/dev/cli/sauce-connect-5/legacy/) command is introduced to help Sauce Connect Proxy 5 major changes are listed below. -- Tunnels must be named, the [`--tunnel-name`](/dev/cli/sauce-connect-5/run/#--tunnel-name) flag is no longer optional. It's done to improve security and usability - tests that use Sauce Connect must explicitly specify the [tunnel name](/dev/test-configuration-options/#tunnelname). -- There is no default Sauce Labs region value, [`--region`](/dev/cli/sauce-connect-5/run/#--region) is required to ensure that the correct region is explicitly specified. +- Tunnels must be named, the [`--tunnel-name`](/secure-connections/sauce-connect-5/cli/run/#--tunnel-name) flag is no longer optional. It's done to improve security and usability - tests that use Sauce Connect must explicitly specify the [tunnel name](/dev/test-configuration-options/#tunnelname). +- There is no default Sauce Labs region value, [`--region`](/secure-connections/sauce-connect-5/cli/run/#--region) is required to ensure that the correct region is explicitly specified. - [SSL Certificate Bumping](/secure-connections/sauce-connect/security-authentication#ssl-certificate-bumping) is not enabled for all domains, by default. - [SSL Certificate Bumping](/secure-connections/sauce-connect/security-authentication#ssl-certificate-bumping) is fully supported and additional flags are added to fine-tune the configuration. -- Proxy auto-detection is not supported, all proxies must be specified with explicit flags - [`--proxy`](/dev/cli/sauce-connect-5/run/#--proxy) or [`--pac`](/dev/cli/sauce-connect-5/run/#--pac) for SUT requests and [`--proxy-sauce`](/dev/cli/sauce-connect-5/run/#--proxy-sauce) for Sauce Labs REST API and tunnel connections. -- Domain flags ([`--tunnel-domains`](/dev/cli/sauce-connect-5/run/#--tunnel-domains), [`--direct-domains`](/dev/cli/sauce-connect-5/run/#--direct-domains), etc) accept regular expressions only. -- [Subcommands](/dev/cli/sauce-connect-5/) are introduced to support multiple CLI changes and future capabilities. +- Proxy auto-detection is not supported, all proxies must be specified with explicit flags - [`--proxy`](/secure-connections/sauce-connect-5/cli/run/#--proxy) or [`--pac`](/secure-connections/sauce-connect-5/cli/run/#--pac) for SUT requests and [`--proxy-sauce`](/secure-connections/sauce-connect-5/cli/run/#--proxy-sauce) for Sauce Labs REST API and tunnel connections. +- Domain flags ([`--tunnel-domains`](/secure-connections/sauce-connect-5/cli/run/#--tunnel-domains), [`--direct-domains`](/secure-connections/sauce-connect-5/cli/run/#--direct-domains), etc) accept regular expressions only. +- [Subcommands](/secure-connections/sauce-connect-5/cli/sc) are introduced to support multiple CLI changes and future capabilities. - The [Selenium Relay](/secure-connections/sauce-connect/proxy-tunnels/#using-the-selenium-relay) feature is not supported. - Log administration capabilities (such as log-rotate) are not supported. Log management is better left to specialized tools. @@ -54,4 +54,4 @@ If you already use Sauce Connect Proxy 4, please refer to [Sauce Connect Proxy 5 - [Sauce Connect Proxy 5 Quickstart Guide](/secure-connections/sauce-connect-5/quickstart/) - [Sauce Connect Proxy 5 Migration Guide](/secure-connections/sauce-connect-5/migrating/) -- [Sauce Connect Proxy 5 CLI Reference](/dev/cli/sauce-connect-5/) +- [Sauce Connect Proxy 5 CLI Reference](/secure-connections/sauce-connect-5/cli/sc) diff --git a/docs/secure-connections/sauce-connect-5/cli/sc.md b/docs/secure-connections/sauce-connect-5/cli/sc.md new file mode 100644 index 0000000000..93abb62adb --- /dev/null +++ b/docs/secure-connections/sauce-connect-5/cli/sc.md @@ -0,0 +1,33 @@ +--- +id: sc +title: sc +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +# Sauce Connect 5 CLI + +## Commands + +### Running Sauce Connect Proxy + +See [sc run Documentation](/secure-connections/sauce-connect-5/cli/run). + +### Compatibility Mode (Legacy) + +See [sc legacy Documentation](/secure-connections/sauce-connect-5/cli/legacy). + +### Command Line Autocompletion: + +Learn more about sc completion: + - [linux](/secure-connections/sauce-connect-5/installation/linux/#add-bash-completion) + - [macOS](/secure-connections/sauce-connect-5/installation/macos/#add-completion) + - [windows](/secure-connections/sauce-connect-5/installation/windows/#add-completion) + +## Additional Resources + +For setup and configuration, see the [installation guide](/secure-connections/sauce-connect-5/installation) and [configuration guide](/secure-connections/sauce-connect-5/operation/configuration/). + +For any additional help or questions, please contact our support team. + +Thank you for using Sauce Connect! diff --git a/docs/secure-connections/sauce-connect-5/cli/sc_legacy.md b/docs/secure-connections/sauce-connect-5/cli/sc_legacy.md new file mode 100644 index 0000000000..3e8126eae8 --- /dev/null +++ b/docs/secure-connections/sauce-connect-5/cli/sc_legacy.md @@ -0,0 +1,258 @@ +--- +id: legacy +title: sc legacy +--- + +# Sc Legacy + +Usage: `sc legacy [flags]` + +Run Sauce Connect Proxy in compatibility mode with Sauce Connect 4.9.X + +**Note:** You can also specify the options as YAML, JSON or TOML file using `--config-file` flag. +You can generate a config file by running `sc legacy config-file` command. + + +## Required + +### `-r, --region` {#region} + +* Environment variable: `SAUCE_REGION` +* Value Format: `` + +Sauce Labs datacenter region. +Default: us-west. + +### `-i, --tunnel-name` {#tunnel-name} + +* Environment variable: `SAUCE_TUNNEL_NAME` +* Value Format: `` + +Tunnel name used for this tunnel or the tunnels in the same HA pool. + +### `-u, --user` {#user} + +* Environment variable: `SAUCE_USER` +* Value Format: `` + +Sauce Labs username. + +## Options + +### `-s, --shared-tunnel` {#shared-tunnel} + +* Environment variable: `SAUCE_SHARED_TUNNEL` +* Value Format: `` +* Default value: `false` + +Share the tunnels within the same organization. + +### `--tunnel-pool` {#tunnel-pool} + +* Environment variable: `SAUCE_TUNNEL_POOL` +* Value Format: `` +* Default value: `false` + +Denotes a tunnel as part of a high availability tunnel pool. + +## Tunnel traffic + +### `-D, --direct-domains` {#direct-domains} + +* Environment variable: `SAUCE_DIRECT_DOMAINS` +* Value Format: `` + +Domains that do not require tunneling. + +### `-t, --tunnel-domains` {#tunnel-domains} + +* Environment variable: `SAUCE_TUNNEL_DOMAINS` +* Value Format: `` + +Domains that require tunneling. +Inverse of '--direct-domains'. + +## Proxy + +### `-a, --auth` {#auth} + +* Environment variable: `SAUCE_AUTH` +* Value Format: `` + +Basic authentication for URL in host:port:username:password format. + +### `-T, --proxy-tunnel` {#proxy-tunnel} + +* Environment variable: `SAUCE_PROXY_TUNNEL` +* Value Format: `` +* Default value: `false` + +Route all tunnel traffic through the external proxy specified in --proxy. + +## DNS + +### `--dns` {#dns} + +* Environment variable: `SAUCE_DNS` +* Value Format: `` + +Use the specified name server. +Example: --dns 8.8.8.8,8.8.4.4:53 + +## API server + +### `-k, --api-key` {#api-key} + +* Environment variable: `SAUCE_API_KEY` +* Value Format: `` + +Sauce Labs API Access Key. + +## Logging + +### `-z, --log-stats` {#log-stats} + +* Environment variable: `SAUCE_LOG_STATS` +* Value Format: `` +* Default value: `0` + +seconds Log statistics about HTTP traffic every ``. + +## Other + +### `--autodetect` {#autodetect} + +* Environment variable: `SAUCE_AUTODETECT` +* Value Format: `` +* Default value: `true` + +Detect the system proxy settings. +Inverse of '--no-autodetect'. +Default: true. + +### `--cainfo` {#cainfo} + +* Environment variable: `SAUCE_CAINFO` +* Value Format: `` +* Default value: `/etc/ssl/certs/ca-certificates.crt` + +CA certificate for verifying REST API. + +### `-c, --config-file` {#config-file} + +* Environment variable: `SAUCE_CONFIG_FILE` +* Value Format: `` + +Path to YAML config file. + +### `--experimental` {#experimental} + +* Environment variable: `SAUCE_EXPERIMENTAL` +* Value Format: `` + +Enable or disable experimental features. + +### `--extra-info` {#extra-info} + +* Environment variable: `SAUCE_EXTRA_INFO` +* Value Format: `` +* Default value: `{}` + +JSON string that contains an advanced tunnel configuration. + +### `-F, --fast-fail-regexps` {#fast-fail-regexps} + +* Environment variable: `SAUCE_FAST_FAIL_REGEXPS` +* Value Format: `` + +Deny-list URL patterns. + +### `--no-autodetect` {#no-autodetect} + +* Environment variable: `SAUCE_NO_AUTODETECT` +* Value Format: `` +* Default value: `false` + +Disable detection of the system proxy settings. +Default: false. + +### `-B, --no-ssl-bump-domains` {#no-ssl-bump-domains} + +* Environment variable: `SAUCE_NO_SSL_BUMP_DOMAINS` +* Value Format: `` + +Domains that do not require SSL resigning. + +### `--ocsp` {#ocsp} + +* Environment variable: `SAUCE_OCSP` +* Value Format: `` +* Default value: `log-only` + +Cert revocation check. +One of: strict, log-only, disable. +Default: log-only. + +### `--output-config-file` {#output-config-file} + +* Environment variable: `SAUCE_OUTPUT_CONFIG_FILE` +* Value Format: `` + +Write the new Sauce Connect 5 run command configuration to the specified file. + + If set the run command will not be executed. + + +### `-d, --pidfile` {#pidfile} + +* Environment variable: `SAUCE_PIDFILE` +* Value Format: `` + +File containing the process ID (PID). +Default: temp file. + +### `-f, --readyfile` {#readyfile} + +* Environment variable: `SAUCE_READYFILE` +* Value Format: `` + +File containing JSON formatted metadata. +Created when the tunnel is ready. + +### `-x, --rest-url` {#rest-url} + +* Environment variable: `SAUCE_REST_URL` +* Value Format: `` + +Sauce REST API URL. +An alternative to the recommended flag '--region'. + +### `-P, --se-port` {#se-port} + +* Environment variable: `SAUCE_SE_PORT` +* Value Format: `` +* Default value: `-1` + +Port on which Sauce Connect's Selenium relay will listen for requests. + +### `--status-address` {#status-address} + +* Environment variable: `SAUCE_STATUS_ADDRESS` +* Value Format: `` + +Status server address in host:port format. +Default: disabled. + +### `--tunnel-cainfo` {#tunnel-cainfo} + +* Environment variable: `SAUCE_TUNNEL_CAINFO` +* Value Format: `` +* Default value: `/etc/ssl/certs/ca-certificates.crt` + +CA certificate bundle to use for verifying tunnel connections. + +## Additional Resources + +- [Sauce Connect Proxy Basic Setup](/secure-connections/sauce-connect-5/installation/). +- [Sauce Connect Proxy 5 Migration Guide](/secure-connections/sauce-connect-5/migrating/). +- [Sauce Connect Proxy 4 CLI Reference](/dev/cli/sauce-connect-proxy). diff --git a/docs/secure-connections/sauce-connect-5/cli/sc_run.md b/docs/secure-connections/sauce-connect-5/cli/sc_run.md new file mode 100644 index 0000000000..72dd569b6e --- /dev/null +++ b/docs/secure-connections/sauce-connect-5/cli/sc_run.md @@ -0,0 +1,385 @@ +--- +id: run +title: sc run +--- + +# Sc Run + +Usage: `sc run --username --access-key --region --tunnel-name [flags]` + +Run Sauce Connect Proxy + +**Note:** You can also specify the options as YAML, JSON or TOML file using `--config-file` flag. +You can generate a config file by running `sc run config-file` command. + + +## Required + +### `-k, --access-key` {#access-key} + +* Environment variable: `SAUCE_ACCESS_KEY` +* Value Format: `` + +Sauce Labs Access Key, you can get it from the [User Settings page](https://app.saucelabs.com/user-settings). +For additional security, we recommend setting this as an environment variable. + +### `-r, --region` {#region} + +* Environment variable: `SAUCE_REGION` +* Value Format: `` + +Sauce Labs region name, ex. +us-west or eu-central. +More details [here](/basics/data-center-endpoints). + +### `-i, --tunnel-name` {#tunnel-name} + +* Environment variable: `SAUCE_TUNNEL_NAME` +* Value Format: `` + +Name of the tunnel or tunnel pool. +You can run tests using this tunnel by specifying the tunnelName value in your test capabilities, see [here](/dev/test-configuration-options/). +It can also assign a name to a group of tunnels in the same high availability pool, see [here](/secure-connections/sauce-connect/setup-configuration/high-availability/). + +### `-u, --username` {#username} + +* Environment variable: `SAUCE_USERNAME` +* Value Format: `` + +Sauce Labs username. +For additional security, we recommend setting this as an environment variable. + +## Options + +### `-M, --metadata` {#metadata} + +* Environment variable: `SAUCE_METADATA` +* Value Format: `,...` + +Custom metadata key-value pairs. +This flag is, primarily, used by Sauce Labs to assign custom properties to the tunnel for reporting purposes. + +### `-s, --shared` {#shared} + +* Environment variable: `SAUCE_SHARED` +* Value Format: `` + +Share the tunnel within the same org unit. +Only the 'all' option is currently supported. +See [here](/basics/acct-team-mgmt/sauce-connect-proxy-tunnels/). + +### `-t, --tunnel-pool` {#tunnel-pool} + +* Environment variable: `SAUCE_TUNNEL_POOL` +* Value Format: `` +* Default value: `false` + +Denotes a tunnel as part of a high availability tunnel pool. +See [here](/secure-connections/sauce-connect/setup-configuration/high-availability/). + + +## Tunnel traffic + +### `-F, --deny-domains` {#deny-domains} + +* Environment variable: `SAUCE_DENY_DOMAINS` +* Value Format: `[-],...` + +Deny requests to the matching domains. +Prefix domains with '-' to exclude requests from being denied. + +The following example denies requests to *.example.com and *.google.com. + +``` +--deny-domains .*\.example\.com,.*\.google\.com +``` + +### `-D, --direct-domains` {#direct-domains} + +* Environment variable: `SAUCE_DIRECT_DOMAINS` +* Value Format: `[-],...` + +Forward matching requests to their origin server over the public internet. +Requests that don't match "direct domains" will be forwarded to customer-side over the Sauce Connect Proxy connection. +You can specify --direct-domains or --tunnel-domains, but not both. +Prefix domains with '-' to exclude requests from being forwarded directly. +Note that direct domains are automatically excluded from being resigned. + +The following example sends requests to *.example.com and *.google.com directly. +It would tunnel all other domains. + +``` +--direct-domains .*\.example\.com,.*\.google\.com +``` + +### `-B, --tls-passthrough-domains` {#tls-passthrough-domains} + +* Environment variable: `SAUCE_TLS_PASSTHROUGH_DOMAINS` +* Value Format: `[-],...` + +Pass matching requests to their origin server without SSL/TLS re-encryption. +You can specify --tls-passthrough-domains or --tls-resign-domains, but not both. +Prefix domains with '-' to exclude requests from being passed through. +Note that direct domains will always be passed through. + +The following example passes requests to *.example.com and *.google.com through without SSL/TLS re-encryption. + +``` +--tls-passthrough-domains .*\.example\.com,.*\.google\.com +``` + +### `-b, --tls-resign-domains` {#tls-resign-domains} + +* Environment variable: `SAUCE_TLS_RESIGN_DOMAINS` +* Value Format: `[-],...` + +Resign SSL/TLS certificates for matching requests. +You can specify --tls-resign-domains or --tls-passthrough-domains, but not both. +Prefix domains with '-' to exclude requests from being resigned. +Note that direct domains will never be resigned. + +The following example resigns SSL/TLS certificates for all requests to *.myorg.dev, except abc.myorg.dev. + +``` +--tls-resign-domains .*\.myorg\.dev,-abc\.myorg\.dev +``` + +### `-T, --tunnel-domains` {#tunnel-domains} + +* Environment variable: `SAUCE_TUNNEL_DOMAINS` +* Value Format: `[-],...` + +Forward matching requests over the Sauce Connect Proxy connection. +Requests not matching "tunnel domains" will be forwarded to their origin server over the public internet. +This is the recommended option for the best performance since it minimizes the expensive tunnelled traffic and uses it only for internal domains that are not publicly available. +You can specify --tunnel-domains or --direct-domains, but not both. +Prefix domains with '-' to exclude requests from being forwarded over the SC Proxy connection. + +The following example tunnels all requests to *.myorg.dev, except abc.myorg.com. + +``` +--tunnel-domains .*\.myorg\.dev,-abc\.myorg\.com +``` + +## Proxy + +### `-a, --auth` {#auth} + +* Environment variable: `SAUCE_AUTH` +* Value Format: `` + +Site or upstream proxy basic authentication credentials. +The host and port can be set to "*" to match all hosts and ports respectively. +The flag can be specified multiple times to add multiple credentials. +Note: Requests to these hosts will be automatically resigned as if there were specified in --tls-resign-domains flag. +Example: +``` +--proxy myproxy.org:3128 --proxy-sauce https://external.com:443 --auth user1:pass1@myproxy.org:3128,user2:pass2@external.com:* +``` + +### `-H, --header` {#header} + +* Environment variable: `SAUCE_HEADER` +* Value Format: `
` + +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. +Example: -H "Host: example.com" -H "-User-Agent" -H "-X-*". + +### `-p, --pac` {#pac} + +* Environment variable: `SAUCE_PAC` +* Value Format: `` + +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. +The data URI scheme is supported, the format is `data:base64,`. + +### `-x, --proxy` {#proxy} + +* Environment variable: `SAUCE_PROXY` +* Value Format: `[protocol://]host[:port]` + +Upstream proxy to use for requests received from the Sauce Connect Server only. +The supported protocols are: http, https, socks, socks5. +No protocol specified will be interpreted as an HTTP proxy. +If the port number is not specified, it is assumed to be 1080. +The basic authentication username and password can be specified in the host string, e.g. +user:pass@host:port. +Alternatively, you can specify the credentials using the -a, --auth flag. + +### `--proxy-localhost` {#proxy-localhost} + +* Environment variable: `SAUCE_PROXY_LOCALHOST` +* Value Format: `` +* Default value: `deny` + +Setting this to allow enables sending requests to localhost through the upstream proxy. +Setting this to direct sends requests to localhost directly without using the upstream proxy. +By default, requests to localhost are denied. + +### `--proxy-sauce` {#proxy-sauce} + +* Environment variable: `SAUCE_PROXY_SAUCE` +* Value Format: `[protocol://]host[:port]` + +Proxy for requests to Sauce Labs REST API and Sauce Connect servers only. +See the -x, --proxy flag for more details on the format. + +## DNS + +### `--dns-round-robin` {#dns-round-robin} + +* Environment variable: `SAUCE_DNS_ROUND_ROBIN` +* Value Format: `` +* Default value: `false` + +If more than one DNS server is specified with the --dns-server flag, passing this flag will enable round-robin selection. + + +### `-n, --dns-server` {#dns-server} + +* Environment variable: `SAUCE_DNS_SERVER` +* Value Format: `[:]` + +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. + +### `--dns-timeout` {#dns-timeout} + +* Environment variable: `SAUCE_DNS_TIMEOUT` +* Value Format: `` +* Default value: `5s` + +Timeout for dialing DNS servers. +Only used if DNS servers are specified. + + +## HTTP client + +### `--cacert-file` {#cacert-file} + +* Environment variable: `SAUCE_CACERT_FILE` +* Value Format: `` + +Add your own CA certificates to verify against. +The system root certificates will be used in addition to any certificates in this list. +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. + +### `--http-dial-timeout` {#http-dial-timeout} + +* Environment variable: `SAUCE_HTTP_DIAL_TIMEOUT` +* Value Format: `` +* Default value: `30s` + +The maximum amount of time a dial will wait for a connect to complete. +With or without a timeout, the operating system may impose its own earlier timeout. +For instance, TCP timeouts are often around 3 minutes. + + +### `--http-idle-conn-timeout` {#http-idle-conn-timeout} + +* Environment variable: `SAUCE_HTTP_IDLE_CONN_TIMEOUT` +* Value Format: `` +* Default value: `1m30s` + +The maximum amount of time an idle (keep-alive) connection will remain idle before closing itself. +Zero means no limit. + + +### `--http-response-header-timeout` {#http-response-header-timeout} + +* Environment variable: `SAUCE_HTTP_RESPONSE_HEADER_TIMEOUT` +* Value Format: `` +* Default value: `0s` + +The amount of time to wait for a server's response headers after fully writing the request (including its body, if any).This time does not include the time to read the response body. +Zero means no limit. + + +### `--http-tls-handshake-timeout` {#http-tls-handshake-timeout} + +* Environment variable: `SAUCE_HTTP_TLS_HANDSHAKE_TIMEOUT` +* Value Format: `` +* Default value: `10s` + +The maximum amount of time waiting to wait for a TLS handshake. +Zero means no limit. + +## API server + +### `--api-address` {#api-address} + +* Environment variable: `SAUCE_API_ADDRESS` +* Value Format: `` + +The server address to listen on. +If the host is empty, the server will listen on all available interfaces. + +### `--api-basic-auth` {#api-basic-auth} + +* Environment variable: `SAUCE_API_BASIC_AUTH` +* Value Format: `` + +Basic authentication credentials to protect the server. + +### `--api-idle-timeout` {#api-idle-timeout} + +* Environment variable: `SAUCE_API_IDLE_TIMEOUT` +* Value Format: `` +* Default value: `1h0m0s` + +The maximum amount of time to wait for the next request before closing connection. + +## Logging + +### `--log-file` {#log-file} + +* Environment variable: `SAUCE_LOG_FILE` +* Value Format: `` + +Path to the log file, if empty, logs to stdout. + +### `--log-http` {#log-http} + +* Environment variable: `SAUCE_LOG_HTTP` +* Value Format: `[api|proxy|control:],...` + +HTTP request and response logging mode. +Setting this to none disables logging. +The short-url mode logs [scheme://]host[/path] instead of the full URL. +The error mode logs request line and headers if status code is greater than or equal to 500. + +### `--log-level` {#log-level} + +* Environment variable: `SAUCE_LOG_LEVEL` +* Value Format: `` +* Default value: `info` + +Log level. + +## 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` +- Domains flags can be repeated multiple times + - Example, `--direct-domains mydomain\.com,saucelabs\.com --direct-domains mysite\.com` +- Prefix domain names with `.*` to match all its subdomains. + - Example: You could refer to `docs\.saucelabs\.com` and `my\.saucelabs\.com` as `.*saucelabs\.com`. +- Escape special characters, such as `.` to ensure they are not parsed + - Not escaping dot character doesn't result in error, dot matches every single character except a newline. For example, `example.com` will match `example.com` and also `examplescom`, while `example\.com` will match `example.com` only. + +## Additional Resources + +- [Sauce Connect Proxy Installation](/secure-connections/sauce-connect-5/installation/). diff --git a/docs/secure-connections/sauce-connect-5/installation/docker.md b/docs/secure-connections/sauce-connect-5/installation/docker.md index 54bc5e32eb..663ac6c821 100644 --- a/docs/secure-connections/sauce-connect-5/installation/docker.md +++ b/docs/secure-connections/sauce-connect-5/installation/docker.md @@ -43,7 +43,7 @@ Here are some benefits/use cases for using containerized Sauce Connect Proxy: --network="host" \ -it saucelabs/sauce-connect:5.0 ``` - If desired, you can specify any additional [`sc run` options](/dev/cli/sauce-connect-5/run/) as environment variables. + If desired, you can specify any additional [`sc run` options](/secure-connections/sauce-connect-5/cli/run/) as environment variables. Alternatively, you can also mount a config file to the container by adding the `-v` option to the `docker run` command. diff --git a/docs/secure-connections/sauce-connect-5/installation/kubernetes.md b/docs/secure-connections/sauce-connect-5/installation/kubernetes.md index 57b3d7b3d9..d223727b8f 100644 --- a/docs/secure-connections/sauce-connect-5/installation/kubernetes.md +++ b/docs/secure-connections/sauce-connect-5/installation/kubernetes.md @@ -37,7 +37,7 @@ config: #terminationGracePeriodSeconds: 600 ``` -For more information about the `config` values, see the [sc run command reference](https://docs.saucelabs.com/dev/cli/sauce-connect-5/run). +For more information about the `config` values, see the [sc run command reference](/secure-connections/sauce-connect-5/cli/run). #### Install the Helm chart diff --git a/docs/secure-connections/sauce-connect-5/installation/linux.md b/docs/secure-connections/sauce-connect-5/installation/linux.md index b162c7c8e1..c811f45212 100644 --- a/docs/secure-connections/sauce-connect-5/installation/linux.md +++ b/docs/secure-connections/sauce-connect-5/installation/linux.md @@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem'; ## Debian/Ubuntu -Sauce Connect provides `.deb` package with Systemd service for [Sauce Connect run](/dev/cli/sauce-connect-5/sc_run.md) command. +Sauce Connect provides `.deb` package with Systemd service for [Sauce Connect run](/secure-connections/sauce-connect-5/cli/run) command. Other commands are available as well, but you will need to start them manually. ### Install package @@ -60,7 +60,7 @@ sudo systemctl status sauce-connect ## RedHat/CentOS/Fedora -Sauce Connect provides `.rpm` package with Systemd service for [Sauce Connect run](/dev/cli/sauce-connect-5/sc_run.md) command. +Sauce Connect provides `.rpm` package with Systemd service for [Sauce Connect run](/secure-connections/sauce-connect-5/cli/run) command. Other commands are available as well, but you will need to start them manually. @@ -172,7 +172,7 @@ sudo ln -s /opt/sauce-connect/completions/sc.bash /etc/bash_completion.d/sc ### Edit config file This step is optional. You can use default configuration or configure Sauce Connect with flags or environment variables. -See [CLI reference](/dev/cli/sauce-connect-5/) for more details. +See [CLI reference](/secure-connections/sauce-connect-5/cli/run) for more details. ```bash diff --git a/docs/secure-connections/sauce-connect-5/installation/macos.md b/docs/secure-connections/sauce-connect-5/installation/macos.md index b7c15f96b2..5354ee4446 100644 --- a/docs/secure-connections/sauce-connect-5/installation/macos.md +++ b/docs/secure-connections/sauce-connect-5/installation/macos.md @@ -22,7 +22,7 @@ brew install sauce-connect ### Edit config file This step is optional. You can use default configuration or configure Sauce Connect with flags or environment variables. -See [CLI reference](/dev/cli/sauce-connect-5/) for more details. +See [CLI reference](/secure-connections/sauce-connect-5/cli/run) for more details. ```bash vim sauce-connect.yaml @@ -87,7 +87,7 @@ echo 'source <(sc completion bash)' >>~/.bash_profile ### Edit config file This step is optional. You can use default configuration or configure Sauce Connect with flags or environment variables. -See [CLI reference](/dev/cli/sauce-connect-5/) for more details. +See [CLI reference](/secure-connections/sauce-connect-5/cli/run) for more details. ```bash vim /opt/sauce-connect/sauce-connect.yaml diff --git a/docs/secure-connections/sauce-connect-5/installation/windows.md b/docs/secure-connections/sauce-connect-5/installation/windows.md index b0050a15a5..1e6bc9bae7 100644 --- a/docs/secure-connections/sauce-connect-5/installation/windows.md +++ b/docs/secure-connections/sauce-connect-5/installation/windows.md @@ -69,7 +69,7 @@ Add-Content -Path $PROFILE -Value ". C:\sauce-connect\completions\sc.ps1" ### Edit config file This step is optional. You can use default configuration or configure Sauce Connect with flags or environment variables. -See [CLI reference](/dev/cli/sauce-connect-5/) for more details. +See [CLI reference](/secure-connections/sauce-connect-5/cli/run) for more details. ```bash notepad C:\sauce-connect\sauce-connect.yaml diff --git a/docs/secure-connections/sauce-connect-5/migrating.md b/docs/secure-connections/sauce-connect-5/migrating.md index 7676838ac8..3ea37c01cb 100644 --- a/docs/secure-connections/sauce-connect-5/migrating.md +++ b/docs/secure-connections/sauce-connect-5/migrating.md @@ -33,7 +33,7 @@ You can now install or upgrade Sauce Connect version 5 with a package manager sy ## Quick Start using `sc legacy` -The [`sc legacy`](/dev/cli/sauce-connect-5/legacy/) command is used to translate SC4 configuration to SC5. +The [`sc legacy`](/secure-connections/sauce-connect-5/cli/legacy/) command is used to translate SC4 configuration to SC5. For a quick sanity check, you can start Sauce Connect with the legacy command: diff --git a/docs/secure-connections/sauce-connect-5/operation/api-server.md b/docs/secure-connections/sauce-connect-5/operation/api-server.md index ace18b8a6f..6508828fcc 100644 --- a/docs/secure-connections/sauce-connect-5/operation/api-server.md +++ b/docs/secure-connections/sauce-connect-5/operation/api-server.md @@ -9,7 +9,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; Sauce Connect Proxy, optionally, exposes an API server that allows obtain information about the local Sauce Connect Proxy instance. -The API interface is configured with the [`--api-address`](/dev/cli/sauce-connect-5/run/#--api-address) flag. +The API interface is configured with the [`--api-address`](/secure-connections/sauce-connect-5/cli/run/#--api-address) flag. ```bash --api-address :8080 # listens on all the interfaces' port 8080 @@ -28,7 +28,7 @@ The table below summarizes available endpoints. | `/info` | Returns runtime information about the tunnel instance. | | `/metrics` | Exposes [Prometheus](https://prometheus.io/) metrics. | | `/configz` | Returns the configuration values. | -| `/pac` | Returns the PAC content being configured with the [`--pac`](/dev/cli/sauce-connect-5/run/#--pac) flag. | +| `/pac` | Returns the PAC content being configured with the [`--pac`](/secure-connections/sauce-connect-5/cli/run/#--pac) flag. | | `/version` | Returns the Sauce Connect Proxy instance version and build info. | ### Info @@ -51,4 +51,4 @@ The `/readyz` response is used to determine when Sauce Connect Proxy is ready to ## More Information - [Sauce Connect Proxy Overview](/secure-connections/sauce-connect/) -- [Sauce Connect Proxy 5 CLI Reference](/dev/cli/sauce-connect-5/run/) +- [Sauce Connect Proxy 5 CLI Reference](/secure-connections/sauce-connect-5/cli/sc/) diff --git a/docs/secure-connections/sauce-connect-5/operation/configuration.md b/docs/secure-connections/sauce-connect-5/operation/configuration.md index 7a60f762c8..1cf85af43a 100644 --- a/docs/secure-connections/sauce-connect-5/operation/configuration.md +++ b/docs/secure-connections/sauce-connect-5/operation/configuration.md @@ -8,7 +8,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -The explicit way to launch a Sauce Connect Proxy tunnel is to run a single command line comprised of all [flags](/dev/cli/sauce-connect-5/run/) and any optional [flags](/dev/cli/sauce-connect-5/run/) you want to use to customize tunnel behavior. +The explicit way to launch a Sauce Connect Proxy tunnel is to run a single command line comprised of all [flags](/secure-connections/sauce-connect-5/cli/run/) and any optional [flags](/secure-connections/sauce-connect-5/cli/run/) you want to use to customize tunnel behavior. It's also possible to pass the same command-line arguments through a config file, and as environment variables. If you pass the same argument through multiple methods, the order of precedence is as follows (from highest to lowest): @@ -18,7 +18,7 @@ If you pass the same argument through multiple methods, the order of precedence ## Config File -The Sauce Connect Proxy [config file](/dev/cli/sauce-connect-5/run/#--config-file) may contain any CLI flag. +The Sauce Connect Proxy [config file](/secure-connections/sauce-connect-5/cli/run/#--config-file) may contain any CLI flag. It may also contain comments that could help make its content more readable, for example: ```yaml @@ -34,7 +34,7 @@ tunnel-name: 'my-macos' ### Config File Reference -[`sc run config-file`](/dev/cli/sauce-connect-5/run/#configuration-file) command's output below contains all the available options and their usage. +[`sc run config-file`](/secure-connections/sauce-connect-5/cli/run/#configuration-file) command's output below contains all the available options and their usage.
`sc run config-file` output @@ -281,7 +281,7 @@ To launch a tunnel using a **config.yml** file option. 1. Create Sauce Connect Proxy config file in any location, for example: `$HOME/sc/config.yml` (`%HOMEPATH%\sc\config.yml` for Windows). 2. Enter values for the properties you'd like to use. -3. Use the [--config-file](/dev/cli/sauce-connect-5/run/#--config-file) flag to run Sauce Connect Proxy with your configuration file. +3. Use the [--config-file](/secure-connections/sauce-connect-5/cli/run/#--config-file) flag to run Sauce Connect Proxy with your configuration file.