Documentation » Configuration » Login Dialog » Advanced » Connection »

The Proxy Page (Advanced Site Settings dialog)

The Proxy page on the Advanced Site Settings dialog allows you to configure WinSCP to use various types of proxy in order to make its network connections.

Note that unlike some software (such as web browsers), WinSCP does not attempt to automatically determine whether to use a proxy and (if so) which one to use for a given destination. If you need to use a proxy, it must always be explicitly configured.1

When using an SSH tunneling, the proxy settings are used for a tunnel session, not for a main session.

Advertisement

Refer to documentation of page sections:

Advertisement

Setting the Proxy Type

First, select what type of proxy you want WinSCP to use for its network connections. The default setting is None. In this mode no proxy is used for the connection.

Selecting HTTP allows you to proxy your connections through a web server supporting the HTTP CONNECT command, as documented in RFC 2817.

Selecting SOCKS4 or SOCKS5 allows you to proxy your connections through a SOCKS server.

Many firewalls implement a less formal type of proxy in which a user can make a Telnet or TCP connection directly to the firewall machine and enter a command such as connect myhost.com 22 to connect through to an external host. Selecting Telnet allows you to tell WinSCP to use this type of proxy, with the precise command specified. This type of proxy is not supported for FTP, WebDAV and S3 protocols.

Selecting Local allows you to specify an arbitrary command on the local machine to act as a proxy. When the session is started, instead of creating a TCP connection, WinSCP runs the specified command, and uses its standard input and output streams. This type of proxy is not supported for FTP, WebDAV and S3 protocols.

This could be used, for instance, to talk to some kind of network proxy that WinSCP does not natively support; or you could tunnel a connection over something other than TCP/IP entirely.

For FTP protocol set of methods to connect over FTP proxies is supported. The methods differ by sequence of commands needed to instruct the proxy to connect to target host. The most typical method is USER %user@%host.

Use Autodetect button to autodetect proxy settings. Works for HTTP proxy only.

Username and Password

You can enter a username and a password in the User name and Password boxes, which will be used if your proxy requires authentication.

If WinSCP discovers that it needs a proxy username or password and you have not specified one here, WinSCP will prompt for it interactively in the terminal window.

Authentication is not fully supported for all forms of proxy:

  • Username and password authentication is supported for HTTP proxies and SOCKS5 proxies.
    • With SOCKS5, authentication is via CHAP if the proxy supports it, otherwise the password is sent to the proxy in plain text.
    • With HTTP proxying, authentication is via “HTTP Digest” if possible, or “HTTP Basic”. In the latter case, the password is sent to the proxy in plain text.
  • SOCKS4 can use the User name field, but does not support passwords.
  • You can specify a way to include a username and password in the Telnet/Local proxy command.
    If you do so, and don’t also specify the actual username and/or password in the configuration, WinSCP will interactively prompt for them.
  • Most FTP proxy methods do require authentication.

Telnet/Local Proxy Command

If you are using the Telnet proxy type, the usual command required by the firewall’s Telnet server is connect, followed by a host name and a port number. If your proxy needs a different command, you can enter an alternative in the Telnet command box.

Advertisement

If you are using the Local proxy type, the local command to run is specified in the Local Proxy Command.

In this string, you can use \n to represent a new-line, \r to represent a carriage return, \t to represent a tab character, and \x followed by two hex digits to represent any other character. \\ is used to encode the \ character itself.

Also, the special strings %host and %port will be replaced by the host name and port number you want to connect to. The strings %user and %pass will be replaced by the proxy username and password (which, if not specified in the configuration, will be prompted for). To get a literal % sign, enter %%.

If a Telnet proxy server prompts for a username and password before commands can be sent, you can use a command such as:

%user\n%pass\nconnect %host %port\n

This will send your username and password as the first two lines to the proxy, followed by a command to connect to the desired host and port. Note that if you do not include the %user or %pass tokens in the Telnet command, then anything specified in Username and Password configuration fields will be ignored.

You can use PuTTY plink as local proxy command to implement two hop tunnel.

These options are not available for FTP protocol.

Name Resolution When Using a Proxy

If you are using a proxy to access a private network, it can make a difference whether DNS name resolution is performed by WinSCP itself (on the client machine) or performed by the proxy.

The Do DNS name lookup at proxy end configuration option allows you to control this. If you set it to No, WinSCP will always do its own DNS, and will always pass an IP address to the proxy. If you set it to Yes, WinSCP will always pass host names straight to the proxy without trying to look them up first.

If you set this option to Auto (the default), WinSCP will do something it considers appropriate for each type of proxy. Most types of proxy (HTTP, SOCK5, Telnet, and local) will have host names passed straight to them; SOCKS4 proxies will not.

The original SOCKS4 protocol does not support proxy-side DNS. There is a protocol extension (SOCKS4A) which does support it, but not all SOCKS4 servers provide this extension. If you enable proxy DNS and your SOCKS4 server cannot deal with it, this might be why.

If you want to avoid WinSCP making any DNS query related to your destination host name (for example, because your local DNS resolver is very slow to return a negative response in that situation), then as well as setting this control to Yes, you may also need to turn off GSSAPI authentication and GSSAPI key exchange in SSH. This is because GSSAPI setup also involves a DNS query for the destination host name, and that query is performed by the separate GSSAPI library, so WinSCP can’t override or reconfigure it.

These options are not available for FTP protocol.

Proxying Local Host Connections

Connections to the local host (the host name localhost, and any loopback IP address) are not proxied by default. It is very unlikely that this behavior would ever cause problems, but if it does you can change it by enabling Consider proxying local host connections.1

Advertisement

This option is not available for FTP protocol.

Further Reading

Read more about Login dialog and Advanced Site Settings dialog.

  1. The text is copy of PuTTY User Manual or was inspired by it.Back

Last modified: by martin