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:

Overview

SnowCD leverages the Snowflake hostname IP addresses and ports listed by either the SYSTEM$WHITELIST() or SYSTEM$WHITELIST_PRIVATELINK() functions to run a series of connection checks to evaluate and help troubleshoot the network connection to Snowflake.

Important

If your Snowflake account uses AWS PrivateLink or Azure Private Link, 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 AWS PrivateLink & Snowflake and Azure Private Link & Snowflake.

SnowCD returns one of the following:

  1. All checks passed to indicate a healthy network connection.

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

  1. Automated deployment scripts.

  2. A prerequisite check before deploying a service that connects to Snowflake.

  3. Environment checks while starting a new machine.

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

Attention

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.

Using SnowCD

Step 2: Download and Install SnowCD

Linux

To download and install SnowCD on Linux, complete the following steps:

  1. Download the latest version of the SnowCD (i.e. snowcd) for your Linux operating system.

  2. Open the Linux Terminal application and navigate to the directory where you downloaded the file.

  3. Verify the SHA256 checksum matches.

    $ sha256sum <filename>
    
  4. Extract the file.

    $ gunzip <filename>
    
  5. Make the file executable.

    $ chmod +x <filename>
    
  6. Rename the executable to snowcd.

    $ mv <filename> snowcd
    

Note

Linux users running RHEL or CentOS can install SnowCD using yum while Debian users can install using apt.

macOS

To download and install SnowCD on macOS, complete the following steps:

  1. Download the latest version of the notarized SnowCD pkg file for your Apple (i.e. mac64) operating system.

    The pkg files use the following naming convention:

    snowcd-<version_number>-darwin_x86_64.pkg

    For example:

    snowcd-1.0.5-darwin_x86_64.pkg

  2. Open the Terminal application and navigate to the directory where you downloaded the file.

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

  4. Open the Finder application and navigate to the directory where you downloaded the pkg file.

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

Windows

To download and install SnowCD on Windows, complete the following steps:

  1. Download the latest version of the SnowCD (i.e. snowcd) for your Windows (i.e. win64) operating system.

  2. Run the MSI file using the Windows Installer.

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.

  1. In macOS or Linux environments, you can run the snowcd executable from the command line by executing snowcd <path_to_allowlist.json> [flags].

  2. In Windows environments, execute snowcd.exe <path_to_allowlist.json> [flags].

Tip

For a full description on the flags snowcd supports, execute snowcd -h.

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.

Important

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 test.log file.