Thursday, October 18, 2007

Hudsuckr: Advanced Windows proxy configuration from the command line

Windows stores proxy configuration settings in the registry, in HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings. However, the settings there like "ProxyServer" "ProxyEnable" can be somewhat misleading, and certain advanced settings (like the setting to "Automatically detect settings" using WPAD) aren't available as separate registry keys.

In IE4, proxy settings were stored in the "Internet Settings" key as simple strings (REG_SZ) and ints (REG_DWORD), but since IE5 it has been possible to set proxy configurations separately for each Internet connection. For example, you could set up your computer to use a proxy when you're using a VPN, use WPAD when you're on dial-up, and to go directly to the Internet when you're corrected directly using the LAN. These "per connections" settings are stored in the "Internet Settings\Connections" key; unfortunately, they're stored there in REG_BINARY blobs that are not meant to be edited directly. (When you use the "Internet Options" Control Panel, it automatically updates both the REG_BINARY blobs and the regular registry settings in "Internet Settings" automatically.)

That makes it difficult to configure "per connection" settings (like WPAD) using command line tools, including proxycfg.exe and others. We needed to be able to automatically enable/disable WPAD in Selenium RC, so I've coded up a simple command-line executable called "hudsuckr" that lets you do it. (It's named after the classic 1994 Coen brothers movie The Hudsucker Proxy. "Hudsuckr" contains no "e" because that makes it easier to Google and because it makes it more Web 2.0. ;-)

Here's the usage documentation that you get when you run "hudsuckr --help" from the command line:

    Hudsuckr Windows Proxy Configuration Tool: "You know, for kids!"
    
    Windows manages Internet proxy connection information in the registry;
    each Internet "connection" can have its own separate proxy
    configuration.  These settings correspond to settings in the "Internet
    Options" Control Panel, under the "Connections" tab.
    
    Run "hudsuckr" without arguments to print out the current proxy
    configuration details.  We print out the name of the current active
    connection, the four connection flags (DIRECT, PROXY, AUTO_PROXY_URL,
    AUTO_DETECT), and three strings: PROXY_SERVER, PROXY_BYPASS, and
    AUTOCONFIG_URL. The seven settings are described in MS documentation
    available here: http://msdn2.microsoft.com/en-us/library/aa385145.aspx
    
    Run "hudsuckr" with exactly eight arguments to set the proxy
    configuration, like this:
      hudsuckr (null) true true true true "localhost:4444" "" "file://c:/proxy.pac"
    
    Specify the name of the connection first (or use the LAN settings by
    specifying "(null)"), then set the four flags using "true" and
    "false", then the proxy server (with a colon to specify the port), the
    list of servers to bypass delimited by semi-colons (with "" as
    a special string that bypasses local addresses), and finally the URL
    to a proxy PAC autoconfiguration file.  Use "" or "(null)" to leave
    string settings blank/empty.
    
    If you're still confused about the flags, look at the proxy settings
    in the "Internet Options" Control Panel. See how you can check those
    checkboxes independently of one another? The flags correspond to those
    checkboxes.  If AUTO_DETECT is true, IE will try to use WPAD; if
    successful, WPAD will override the specified AUTOCONFIG_URL. If an
    AUTOCONFIG_URL is detected (by AUTO_DETECT) or specified directly
    (AUTO_PROXY_URL is enabled), IE will use the autoconfig script as a
    proxy PAC file.  If no AUTOCONFIG_URL was specified or detected, IE
    will attempt to use the server specified in PROXY_SERVER if the PROXY
    flag is enabled; it will bypass the proxy for the list of servers
    specified in PROXY_BYPASS. Finally, if PROXY, AUTO_DETECT and
    AUTO_PROXY_URL are all set to false, IE will attempt to contact the
    web server directly.  Note that the DIRECT flag always appears to be
    true, even if the PROXY flag is true; we recommend you leave it that
    way, too.

Here's what you might see if you run hudsuckr without command line arguments:

    > hudsuckr.exe
    ACTIVE_CONNECTION=(null)
    PROXY_TYPE_DIRECT=true
    PROXY_TYPE_PROXY=false
    PROXY_TYPE_AUTO_PROXY_URL=false
    PROXY_TYPE_AUTO_DETECT=false
    INTERNET_PER_CONN_PROXY_SERVER=(null)
    INTERNET_PER_CONN_PROXY_BYPASS=(null)
    INTERNET_PER_CONN_AUTOCONFIG_URL=(null)

Or, after you've configured lots of proxy settings:

    > hudsuckr.exe (null) true true true true "localhost:4444" "" "file://c:/proxy.pac"
    ACTIVE_CONNECTION=(null)
    PROXY_TYPE_DIRECT=true
    PROXY_TYPE_PROXY=true
    PROXY_TYPE_AUTO_PROXY_URL=true
    PROXY_TYPE_AUTO_DETECT=true
    INTERNET_PER_CONN_PROXY_SERVER=localhost:4444
    INTERNET_PER_CONN_PROXY_BYPASS=
    INTERNET_PER_CONN_AUTOCONFIG_URL=file://c:/proxy.pac

To turn off all proxies for the LAN connection, you might run a command like this:

    > hudsuckr (null) true false false false (null) (null) (null)
    ACTIVE_CONNECTION=(null)
    PROXY_TYPE_DIRECT=true
    PROXY_TYPE_PROXY=false
    PROXY_TYPE_AUTO_PROXY_URL=false
    PROXY_TYPE_AUTO_DETECT=false
    INTERNET_PER_CONN_PROXY_SERVER=(null)
    INTERNET_PER_CONN_PROXY_BYPASS=(null)
    INTERNET_PER_CONN_AUTOCONFIG_URL=(null)

Download hudsuckr.exe
Hudsuckr source code