Network Preferences

../_images/network-preferences.png

If Canopy is having trouble connecting to the internet (e.g. logging in, or using the Package Manager or Documentation Browser), you can test your network settings with the Test connection setup button. If this test fails, you can change Canopy’s network settings as described below.

After changing these settings, you must again use Test connection setup, otherwise your changes will be discarded when the OK button is pressed.

After changing and successfully testing and accepting the network proxy settings, please restart the IPython kernel, the Package Manager, and the Documentation Browser, if they were already active before the change, so that the new settings are properly propagated to these components.

Proxy Setup

The primary use of the Network Preferences tab is to test and configure Canopy’s network proxy settings.

A network proxy firewall is a computer that sits between your local computer and the internet. It is typically set up by your IT staff. In order for a program to connect to the internet, it must go through the proxy.

If an http/https proxy is configured on your system, Canopy will attempt to detect and use the current settings. However this is not always possible, so you might need to manually set custom proxy settings in the Network tab.

Common options for proxy setup are discussed in the next sections. For more information and troubleshooting, please refer to “Using Canopy 2 Behind a Proxy Firewall” in the Enthought Support Knowledge Base.

System settings

When the System settings option is selected (the default), Canopy will look for proxy settings in the current environment variables, and will query the OS for proxy information.

The environment variables that are considered for Canopy’s proxy setup are:

  • HTTP_PROXY and/or HTTPS_PROXY – the proxy server URL, formatted as:

    http://[proxy_username[:proxy_password]@]proxy.host:port[/]
    
  • NO_PROXY (optional) – a comma-separated list of domains and IPs that should not be accessed through the proxy server.

  • REQUESTS_CA_BUNDLE (optional) – the full path of a file containing a set of SSL certificate bundles, that may be needed by Python to verify the identity of your network’s proxy servers.

If the HTTP_PROXY and HTTPS_PROXY environment variables are not set, then Canopy will query the operating system’s proxy configuration. Proxy information that is discovered will be shown in the network preferences tab.

Note

  • To test the connection status, please click the Test connection setup button. If the settings are correct, then the test should succeed.
  • Querying the operating system proxy configuration is currently only supported for Microsoft Windows (from the Windows registry) and Mac OS.
  • If necessary, additional domains and IPs, such as DNS domains, that should not be accessed through the proxy server, can be specified in Skip domains as a list of domains and IPs separated by semicolon (;) characters. These will be combined with any entries in the NO_PROXY environment variable, in addition to 127.0.0.1 and localhost, which are automatically included in this list.

Custom settings

If Canopy was not able to correctly detect the proxy setting, you will need to manually provide the necessary information. The first step is to ask your IT staff for the authentication credentials for your proxy firewall. At a minimum, this will require a proxy server URL such as http://ourproxy.company.com and a port number, and it might include a user name and password.

With that information, go to to the Network preferences tab and select Custom settings. The following proxy settings fields are now shown and can be filled in:

  • host – the proxy host domain name or IP.
  • port – the port where the proxy server listens for connections.
  • username – (optional) username to connect to proxy server.
  • password – (optional) password to authorize access to the proxy server.
  • skip domains – (optional) a list of domains and IPs, separated by semicolon (;) characters, that should not be accessed through the proxy server. This setting, even if empty, supersedes any domains listed in the NO_PROXY environment variable. In addition, 127.0.0.1 and localhost will automatically be included in this list.

Note

  • To test the connection status, please click the Test connection setup button. If the settings are correct, then the test should succeed.
  • If there is no proxy server information detected or provided by the user, then the skip domain server value is ignored.

No Proxy

In most cases, using System settings, Canopy should be able to adapt to and work between proxy and no-proxy network environments (e.g. company and home networks). However, when this auto-detection fails, and you need to connect to the internet through a no-proxy network, you can manually select the No proxy option to temporarily deactivate your system or custom proxy settings.

SSL Certificates

By default, the Verify SSL Certificates option is set, and Canopy will use HTTPS requests and try to verify the chain of SSL certificates returned by the various servers on the web, just like a web browser.

However, your system’s default list of certificates might not include the certificate for the proxy server (if one is set up); in this case, Canopy will not be able to connect to the internet, so utilities like the Package Manager will fail with a connection error.

To fix this, so that Canopy can verify the identity of the proxy server and connect to the internet, you will need to locate an additional SSL certificate file. Set the SSL Certificate Bundle option to point to that file. Alternatively, you could set the REQUESTS_CA_BUNDLE environment variable to point to the file.

Note

  • Check with your IT staff to obtain the necessary SSL certificate file.
  • The SSL Certificate Bundle option in Network preferences will override any value that is set in the REQUESTS_CA_BUNDLE environment variable.
  • Disabling Verify SSL Certificates is not recommended. This option should mainly be used temporarily, for debugging network issues.

Troubleshooting

If connection problems persist after trying both System and Custom Settings, you can use the Detailed Network Access Tests button to produce a network test report, which you can copy to clipboard to examine, report to your IT staff, or report to Enthought Support.

Propagate to Terminal and IPython

If your machine is behind a proxy firewall and your own Python code or command line utilities like edm or pip need to access the internet, then they will also need to use the same proxy settings as Canopy.

The Propagate to Terminal and IPython setting, in the Network preferences tab, controls whether your Custom Proxy settings are passed to Canopy Terminal and to Canopy’s IPython panel. By default, these will be passed unless a proxy password is specified.

The SSL certificate bundle information will be always propagated to Terminal and IPython if a proxy is used, so that networking tools that depend on the requests python package are aware of the alternative set of SSL certificates that need to be used.

For details, please refer to “Using Canopy 2 Behind a Proxy Firewall” in the Enthought Support Knowledge Base.