The proxy: protocol

  1. Home
  2. Misc
  3. The proxy: protocol

The proxy: scheme

This is an advanced topic. It is not intended for casual FoxyProxy users.

What is it?

The FoxyProxy team has designed a URI (Uniform Resource Identifier) scheme to programmatically interact with proxy-related software such as FoxyProxy. The scheme is the proxy: scheme. Currently, FoxyProxy is the only software known to implement this scheme, but you are encouraged to support it in your software, too. Please contact us if you do so we can add your software to this page.

How to use it?

You can put proxy: links in webpages, web mail, or type them into the address bar to interact with FoxyProxy (proxy:// is also accepted but semantically incorrect). You can also leverage this ability to control FoxyProxy in a headless or batch environment such as Selenium. Commands to FoxyProxy are specified through URL query parameters–name/value pairs in the URL.

You can disable this feature with the ignoreProxyScheme hidden setting. To use: close firefox. In foxyproxy.xml, change the new ignoreProxyScheme attribute from its default of false to true.

Here are some proxy: scheme examples to get you started. All names and values are case-sensitive!

[proxy:host=foo.com&port=9999 File:16×16.gif] proxy:host=foo.com&port=9999
[proxy:host=foo.com&port=9999&foxyProxyMode=this&confirmation=https://getfoxyproxy.org/proxyservice/geoip/whatsmyip.html File:16×16.gif] [proxy:host=foo.com&port=9999&foxyProxyMode=this&confirmation=https://getfoxyproxy.org/proxyservice/geoip/whatsmyip.html proxy:host=foo.com&port=999&foxyProxyMode=this&confirmation=https://getfoxyproxy.org/proxyservice/geoip/whatsmyip.html]
[proxy:host=foo.com&port=1080&isSocks=true&enabled=false File:16×16.gif] proxy:host=foo.com&port=1080&isSocks=true&enabled=false
[proxy:url=http://foo.com/proxy.pac File:16×16.gif] proxy:url=http://foo.com/proxy.pac
[proxy:host=foo.com&port=999&action=deleteOne File:16×16.gif] proxy:host=foo.com&port=999&action=deleteOne

API Specification

Here is a complete list of supported parameters, values, and default values. All names and values are case-sensitive! Don’t forget FoxyProxy also has a more limited [faq.html#commandline command-line interface].

Name action
Description The action to perform with the specified proxy: info
Valid values update
add
updateOrAdd
deleteOne
deleteMultiple
Default if not specified updateOrAdd
Required? no
Examples proxy:host=foo.com&port=999
proxy:host=foo.com&port=999&action=add
proxy:host=foo.com&port=999&action=deleteMultiple
proxy:host=foo.com&port=999&name=Australia Proxy
proxy:host=bar.com&port=888&name=Australia Proxy&action=update
Notes updateOrAdd: if a proxy with the specified name exists, it is updated with the information specified in the proxy: URI. name is calculated by default if no name query parameter is specified. If no proxy with the specified name exists, FoxyProxy behaves as if action is specified as add. That is, a new proxy is added.

update: if a proxy with the specified name exists, it is updated with only the information specified in the proxy: URI. name is calculated by default if no name query parameter is specified. If no proxy with the specified name exists, no update is performed. If more than one proxy with the specified name exists, only the first is updated.

add: a new proxy with the specified name is added to FoxyProxy. name is calculated by default if no name query parameter is specified. Names need not be unique, so if an existing proxy with name already exists, the effect is that two proxies with the same name will exist.

deleteOne: if a proxy with the specified name exists, it is deleted. name is calculated by default if no name query parameter is specified. If FoxyProxy’s mode was set to use the deleted proxy for all URLs, FoxyProxy changes its mode to disabled to avoid a broken configuration. If no proxy with the specified name exists, no delete is performed. If more than one proxy with the specified name exists, only the first is deleted.

deleteMultiple: if a proxy with the specified name exists, it is deleted. name is calculated by default if no name query parameter is specified. If FoxyProxy’s mode was set to use the deleted proxy for all URLs, FoxyProxy changes its mode to disabled to avoid a broken configuration. If no proxy with the specified name exists, no delete is performed. If more than one proxy with the specified name exists, all of them are deleted.

 

Name foxyProxyMode
Description Changes FoxyProxy’s current mode images/proxyprotocol/mode.png screenshot
Valid values this
proxy name
patterns
previous
disabled
random (not supported)
roundrobin (not supported)
Default if not specified No default
Required? no
Examples proxy:host=foo.com&port=999&foxyProxyMode=this
proxy:foxyProxyMode=disabled
proxy:foxyProxyMode=Australia Proxy
proxy:host=foo.com&port=999&&name=UK Proxy&notes=London server&foxyProxyMode=French Proxy
Notes this: Sets FoxyProxy to Use Proxy XXXX for all URLs for the newly-added or updated proxy. If action is deleteOne or deleteMultiple, FoxyProxy’s mode remains unchanged.

proxy name: Sets FoxyProxy to Use Proxy XXXX for all URLs where XXXX is the proxy specified in place of proxy name. If more than one proxy with the same name exists, the first is selected. If no proxy with the specified name exists, FoxyProxy sets its mode to disabled.

patterns: Sets FoxyProxy to Use proxies based on their pre-defined patterns and priorities.

disabled: Sets FoxyProxy to disabled mode.

 

Name name
Description Name of the proxy being added/updated/deleted images/proxyprotocol/general-2.png screenshot
Default if not specified If host and port parameters are specified, and mode is manual, name defaults to host:port. If a url parameter is specified and mode is auto, name defaults to the value of url.
Required? no
Examples proxy:host=foo.com&port=999&name=Australia Proxy
proxy:name=Australia Proxy&enabled=false

 

Name mode
Description Mode of the proxy being added/updated
Valid values manual
auto
direct
system (not supported)
Default if not specified If host and port parameters are specified, mode defaults to manual. If url is specified but no host and port, mode defaults to auto. If host and port and url aren’t specified, mode defaults to direct.
Required? no, but (host and port or <code>url should be specified if name is not</code>
Examples proxy:name=Australia Proxy&mode=direct
proxy:name=Australia Proxy&mode=manual&host=localhost&port=8080&action=update
Notes manual: Sets this proxy to “Manual Proxy Configuration” [[images/proxyprotocol/proxy-details-1.png screenshot]]

auto: Sets this proxy to “Automatic proxy configuration URL” [[images/proxyprotocol/proxy-details-2.png screenshot]]

direct: Sets this proxy to “Direct internet connection (no proxy” [[images/proxyprotocol/proxy-details-3.png screenshot]]

 

Name host
Description Hostname or IP address of the proxy being added/updated/deleted images/proxyprotocol/proxy-details-4.png screenshot
Valid values Any hostname or IP address
Default if not specified No default
Required? no, but name should be specified if (host and port) or url are not
Examples proxy:host=foo.com&port=8888
proxy:host=localhost&port=999
proxy:host=192.168.1.1&port=1080

 

Name port
Description Port of the proxy being added/updated/deleted images/proxyprotocol/proxy-details-5.png screenshot
Valid values Any valid port number
Default if not specified No default
Required? no, but name should be specified if (host and port) or url are not
Examples proxy:host=foo.com&port=8888
proxy:host=localhost&port=999
proxy:host=192.168.1.1&port=1080&name=MyProxy

 

Name isSocks
Description true or false depending on if the proxy being added/updated is a SOCKS proxy server images/proxyprotocol/proxy-details-6.png screenshot
Valid values true or false
Default if not specified false
Required? no
Examples proxy:host=foo.com&port=1080&isSocks=true
proxy:host=localhost&port=1080&isSocks=true&socksversion=4
proxy:host=localhost&port=1080&isSocks=false&action=update

 

Name socksversion
Description The version of the SOCKS server implemented by the proxy server being added/updated images/proxyprotocol/proxy-details-7.png screenshot
Valid values 5
4a
4
Default if not specified 5
Required? no
Examples proxy:host=foo.com&port=1080&isSocks=true&socksversion=4a
proxy:host=localhost&port=1080&isSocks=false&socksversion=4

 

Name url
Description URL to a PAC file images/proxyprotocol/proxy-details-8.png screenshot
Valid values Any URL accepted by FoxyProxy, including relative://, file://, http://, ftp://, https://
Default if not specified No default
Required? no
Examples proxy:url=http://google.com/proxy.pac
proxy:host=localhost&port=1080&pac=http://foo.com/mypac.txt&mode=auto

 

Name autoReload
Description true or false depending on if the PAC file should be automatically reloaded periodically images/proxyprotocol/proxy-details-9.png screenshot
Valid values true or false
Default if not specified false
Required? no
Examples proxy:url=http://foobar.com/pac.txt&autoReload=true&reloadFreqMins=10
proxy:url=http://foobar.com:8080/pac.txt&autoReload=false

 

Name reloadFreqMins
Description Number of minutes after which the PAC file is reloaded images/proxyprotocol/proxy-details-10.png screenshot
Valid values Any positive integer
Default if not specified 60
Required? no
Examples proxy:url=http://foobar.com/pac.txt&autoReload=true&reloadFreqMins=10

 

Name loadNotification
Description Whether or not pop-up notifications should be shown when the PAC file fails to load images/proxyprotocol/proxy-details-11.png screenshot
Valid values true or false
Default if not specified <code>true</code>
Required? no
Examples proxy:url=http://foobar.com/pac.txt&autoReload=true&reloadFreqMins=10&loadNotification=false

 

Name errorNotification
Description Whether or not pop-up notifications should be shown when the PAC file contains errors images/proxyprotocol/proxy-details-12.png screenshot
Valid values true or false
Default if not specified <code>true</code>
Required? no
Examples proxy:url=http://foobar.com/pac.txt&errorNotification=false&loadNotification=false
Name errorNotification
Description Whether or not pop-up notifications should be shown when the PAC file contains errors images/proxyprotocol/proxy-details-12.png screenshot
Valid values true or false
Default if not specified <code>true</code>
Required? no
Examples proxy:url=http://foobar.com/pac.txt&errorNotification=false&loadNotification=false

 

Name disableOnBadPAC
Description Whether or not this proxy should switch its mode to disabled if its PAC file can’t load or has errors.
Valid values true or false
Default if not specified true
Required? no
Examples >proxy:url=http://foobar.com:8080/mypac.pac&disableOnBadPAC=false

 

Name enabled
Description Whether or not the proxy being added/updated is to be enabled/disabled images/proxyprotocol/general-1.png screenshot
Valid values true or false
Default if not specified <code>true</code>
Required? no
Examples proxy:host=foo.com&port=8080&enabled=false
proxy:name=Work Proxy&enabled=true

 

Name notes
Description Notes for the proxy being added/updated is to be enabled/disabled images/proxyprotocol/general-3.png screenshot
Default if not specified No default
Required? no
Examples proxy:host=foo.com&port=8080&notes=This is my home proxy
proxy:name=Work Proxy&notes=This is my work proxy&enabled=false

 

Name animatedIcons
Description Whether or not the icon for the proxy being added/updated should animate when in use images/proxyprotocol/general-4.png screenshot
Valid values true or false
Default if not specified true
Required? no
Examples proxy:host=foo.com&port=8080&animatedIcons=false

 

Name includeInCycle
Description Whether or not the proxy being added/updated should be included in proxy cycling images/proxyprotocol/general-5.png screenshot
Valid values true or false
Default if not specified true
Required? no
Examples proxy:host=foo.com&port=8080&includeInCycle=false

 

Name proxyDNS
Description Whether or not the proxy being added/updated should send DNS requests through the proxy server images/proxyprotocol/general-6.png screenshot
Valid values true or false
Default if not specified true
Required? no
Examples proxy:host=localhost&port=1080&isSocks=true&proxyDNS=false

 

Name color
Description Hex color code that the FoxyProxy icon should change to when this proxy is in use images/proxyprotocol/general-7.png screenshot
Valid values Any 6-digit hex color code. Be sure to precede the code with a hash/pound symbol
Default if not specified #65BAD7
Required? no
Examples proxy:host=localhost&port=8888&color=#8765D6

 

Name selectedTabIndex
Description The tab that should be focused when the user opens the proxy details page in FoxyProxy. Tabs are zero-indexed.
Valid values FoxyProxy Basic and Standard: 0, 1, 2 FoxyProxy Plus: 0, 1, 2, 3
Default if not specified 1
Required? no
Examples proxy:host=localhost&port=8888&selectedTabIndex=0

 

Name confirmation
Description Show confirmation message after all proxy: configuration changes are complete
Valid values popup or any compete URL
Required? no
Examples proxy:host=localhost&port=8888&confirmation=popup
proxy:host=localhost&port=8888&confirmation=http://getfoxyproxy.org/whatsmyip.html
Notes popup: Displays a popup confirmating that the proxy has been added/updated/deleted [[images/proxyprotocol/popup.png screenshot]]

URL: Redirects the browser to the specified URL after the proxy has been added/updated/deleted. This URL must start with a scheme/protocol (example: http://). If the URL includes query parameters of its own, confirmation must be the final query parameter in the proxy: URI.

 

Name username
Description The username to use for HTTP(S) proxy authentication (SOCKS authentication not supported)
Default if not specified No default
Required? no
Examples proxy:host=localhost&port=8888&username=jonathan
Notes This is only available with [/fpplus/index.html FoxyProxy Plus].

 

Name password
Description The password to use for HTTP(S) proxy authentication (SOCKS authentication not supported)
Default if not specified No default
Required? no
Examples proxy:host=localhost&port=8888&username=jonathan&password=foobar
Notes This is only available with [/fpplus/index.html FoxyProxy Plus].

 

Name domain
Description The NTLM domain to use for HTTP(S) proxy authentication (SOCKS authentication not supported)
Default if not specified No default
Required? no
Examples proxy:host=localhost&port=8888&username=jonathan&password=foobar&domain=cicero
Notes This is only available with [/fpplus/index.html FoxyProxy Plus].