SnowCD (Connectivity Diagnostic Tool)¶
SnowCD (i.e. Snowflake Connectivity Diagnostic Tool) helps users to diagnose and troubleshoot their network connection to Snowflake.
In this Topic:
SnowCD leverages the Snowflake hostname IP addresses and ports listed by either the
SYSTEM$WHITELIST_PRIVATELINK() functions to run a series of connection checks to evaluate and help troubleshoot the network connection to Snowflake.
If your Snowflake account uses private connectivity to the Snowflake service, execute the SYSTEM$WHITELIST_PRIVATELINK function to obtain the Snowflake hostname IP address and ports to evaluate and troubleshoot network connections to Snowflake.
For more information, see:
SnowCD returns one of the following:
All checks passedto indicate a healthy network connection.
A message to state that one or more checks failed with a troubleshooting suggestion.
Users can leverage SnowCD to evaluate the network connection to Snowflake at any time to verify the required configuration settings are correct. For example, users can integrate SnowCD into these use cases:
Automated deployment scripts.
A prerequisite check before deploying a service that connects to Snowflake.
Environment checks while starting a new machine.
Periodic checks on running machines.
SnowCD works with either direct connections or connections through proxy servers.
SnowCD checks access to the Snowflake database and to stages used to temporarily store data (for example, for loading).
SnowCD verifies that an HTTP response was returned from the HTTP host. This can detect problems such as the following:
No HTTP server is running at the specified IP address and port.
There was a DNS (Domain Name System) lookup failure.
A Man-In-The-Middle attack occurred and used an invalid certificate to impersonate the desired service.
Certain types of other network failures below the HTTP level.
SnowCD does not detect all possible problems. The known limitations include:
Stages require additional authentication information that SnowCD does not have. Although SnowCD verifies basic access to a stage, SnowCD does not perform a strict check on the HTTP response code from the stage. Therefore, SnowCD does not detect problems such as:
Access policy denial for Amazon S3 Bucket, Azure Blob storage, or Google Cloud Storage for stages.
There is a problem connecting to the customer’s proxy server, for example the proxy server returns an HTTP 403 error.
Because SnowCD does not detect all possible problems, Snowflake recommends that after you successfully verify access to a stage through SnowCD, you follow up by running a PUT command to load a file to the stage. The simplest way to run a PUT command is usually through SnowSQL.
Troubleshooting one or more network connection issues is challenging. Depending on the environment, it may be necessary to use SnowCD with other troubleshooting approaches. For example, if SnowCD returns information on an OCSP issue, consult the OCSP sections on this page.
Step 2: Download and Install SnowCD¶
To download and install SnowCD on Linux, complete the following steps:
Download the latest version of the SnowCD from the SnowCD Download page.
Open the Linux Terminal application and navigate to the directory where you downloaded the file.
Verify the SHA256 checksum matches.
$ sha256sum <filename>
Extract the file.
$ gunzip <filename>
Make the file executable.
$ chmod +x <filename>
Rename the executable to
$ mv <filename> snowcd
Linux users running RHEL or CentOS can install SnowCD using yum while Debian users can install using apt.
To download and install SnowCD on macOS, complete the following steps:
Download the latest version of the notarized SnowCD
pkgfile from the SnowCD Download page.
The pkg files use the following naming convention:
Open the Terminal application and navigate to the directory where you downloaded the file.
Verify the SHA256 checksum matches.
To get the checksum of the file, execute the command:
$ shasum -a 256 <filename>
Compare the checksum of the file to the checksum shown at the download site.
Open the Finder application and navigate to the directory where you downloaded the pkg file.
Extract and install SnowCD by double clicking on the pkg file.
The files, including the snowcd executable, are installed in the /opt/snowflake/snowcd directory.
Step 3: Run SnowCD¶
Before running SnowCD in macOS and Linux environments, you can add its directory to your
$PATH. In Windows environments, you can add SnowCD to your Environment Variables.
In macOS or Linux environments, you can run the snowcd executable from the command line by executing
snowcd <path_to_allowlist.json> [flags].
In Windows environments, execute
snowcd.exe <path_to_allowlist.json> [flags].
For a full description on the flags
snowcd supports, execute
If all checks are valid, SnowCD returns the number of checks on the number of hosts with the message
All checks passed as follows.
Performing 30 checks on 12 hosts All checks passed
If you try to run SnowCD without passing in the JSON allow list information from SELECT SYSTEM$WHITELIST(), the following error message displays as a reminder to include the file, with the list of currently supported flags, their data type where applicable, and a brief description of the flag.
Error: please provide whitelist generated by SYSTEM$WHITELIST() Usage: ./snowcd <path to input json file> [flags] Examples: ./snowcd test.json Flags: -h, --help help for ./snowcd --logLevel string log level (panic, fatal[default], error, warning, info, debug, trace) (default "fatal") --logPath string Output directory for log. When not specified, no log is generated --proxyHost string host for http proxy. (When not specified, does not use proxy at all) --proxyIsHTTPS Is connection to proxy secure, i.e. https. (default false) --proxyPassword string password for http proxy.(default empty) --proxyPort int port for http proxy.(default 8080) (default 8080) --proxyUser string user name for http proxy.(default empty) -t, --timeout int timeout for each hostname's checks in seconds (default 5) (default 5) --version version for ./snowcd
If SnowCD detects an incorrect setting or configuration, information on the failed check(s) displays with a troubleshooting suggestion. For example, the response below indicates an invalid hostname.
Check for 1 hosts failed, display as follow: ============================================== Host: www.google1.com Port: 443 Type: SNOWFLAKE_DEPLOYMENT Failed Check: DNS Check Error: lookup www.google1.com: no such host Suggestion: Check your configuration on DNS server
Using SnowCD with an HTTP Proxy¶
SnowCD can be run against an HTTP proxy to determine its connectivity status.
Currently, Snowflake does not support SSL-terminating proxy servers.
During the configuration of your firewall and proxy allow list, use SSL pass through (i.e. bypass SSL decryption).
Using Linux as a representative example, execute the following command to run SnowCD against a proxy, replacing the flag values where necessary.
snowcd allowlist.json \ --proxyHost <hostname> \ --proxyPort <port_number> \ --proxyUser <username> \ --proxyPassword <password>
Logging is optional and you can add the two logging flags to the proxy command. It is important to include a path to the log file to ensure logging occurs when running the command.
snowcd allowlist.json \ --proxyHost <hostname> \ --proxyPort <port_number> \ --proxyUser <username> \ --proxyPassword <password> \ --logLevel trace \ --logPath test.log
After executing this command, you can view the trace in the