Proxy

This document describes how proxy functionality works in JxBrowser. Here you can find how to configure proxy settings and handle proxy authentication requests.

By default JxBrowser uses system proxy settings.

System proxy

Windows

JxBrowser uses the same settings that Microsoft Edge uses.

macOS

JxBrowser uses the proxy settings listed under the Network Control Panel. These are the same settings as Safari uses.

Linux

JxBrowser uses either GNOME/KDE proxy settings, or will use certain environment variables. When you modify JxBrowser proxy settings you do not modify the system global proxy settings.

Configurations

If you do not want to use the system proxy settings, you can configure each Profile with its own proxy settings.

To configure proxy settings use the Proxy:

Java
Kotlin
Proxy proxy = profile.proxy();
val proxy = profile.proxy()

If you use the Engine.proxy() method you get the Proxy instance associated with the default profile.

If you want to tell the library to use the system proxy settings again, call:

Java
Kotlin
proxy.config(SystemProxyConfig.newInstance());
proxy.config(SystemProxyConfig.newInstance())

Proxy settings are stored in the User Data directory. So, if you configure Engine to use specific User Data directory, then the Engine will remember the proxy settings and restore them the next time you create it.

Direct

With this proxy configuration the connection will not use proxy server at all:

Java
Kotlin
proxy.config(DirectProxyConfig.newInstance());
proxy.config(DirectProxyConfig.newInstance())

Auto detect

With this proxy configuration the connection automatically detects proxy settings:

Java
Kotlin
proxy.config(AutoDetectProxyConfig.newInstance());
proxy.config(AutoDetectProxyConfig.newInstance())

Automatic proxy detection is a process by which a web proxy server is identified by the system. This feature is also known as Web Proxy Auto-Discovery (WPAD). When automatic proxy detection is enabled, the system attempts to locate a proxy configuration script (wpad.dat or proxy.pac) that is responsible for returning the set of proxies. If the proxy configuration script is found, the script is downloaded, compiled, and run on the local computer.

Custom

With this proxy configuration you can provide custom proxy settings for HTTP, HTTPS, and FTP protocols:

Java
Kotlin
String proxyRules = "http=foo:80;https=foo:80;ftp=foo:80;socks=foo:80";
String exceptions = "<local>";  // Bypass proxy server for local web pages.
proxy.config(CustomProxyConfig.newInstance(proxyRules, exceptions));
val proxyRules = "http=foo:80;https=foo:80;ftp=foo:80;socks=foo:80"
val exceptions = "<local>"  // Bypass proxy server for local web pages.
proxy.config(CustomProxyConfig.newInstance(proxyRules, exceptions))

Examples of the proxy rules:

http=foopy:80;ftp=foopy2 means use HTTP proxy foopy:80 for http:// URLs, and HTTP proxy foopy2:80 for ftp:// URLs.
foopy:80 means use HTTP proxy foopy:80 for all URLs.
socks4://foopy means use SOCKS v4 proxy foopy:1080 for all URLs.

The format of the exceptions can be any of the following:

[ URL_SCHEME "://" ] HOSTNAME_PATTERN [ ":" <port> ]

Examples:

foobar.com
*foobar.com
*.foobar.com
*foobar.com:99
https://x.*.y.com:99

"." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ]
Examples:
```
.google.com
.com
http://.google.com
```
[ SCHEME "://" ] IP_LITERAL [ ":" PORT ]
Examples:
```
127.0.1
[0:0::1]
[::1]
http://[::1]:99
```
IP_LITERAL "/" PREFIX_LENGHT_IN_BITS.
Examples:
```
192.168.1.1/16
fefe:13::abc/33
```
"<local>". Match local addresses. <local> means that the host matches one of: 127.0.0.1, ::1, localhost.

If you need to provide several exception rules, you can separate them using comma: *foobar.com,.google.com,<local>.

PAC

With this proxy configuration the connection uses the proxy settings received from the proxy auto-config (PAC) file. You must provide a valid URL of the required PAC file:

Java
Kotlin
proxy.config(UrlProxyConfig.newInstance("<pac-file-url>"));
proxy.config(UrlProxyConfig.newInstance("<pac-file-url>"))

URL to the PAC file must be a valid http:// address. You cannot provide a path to a *.pac file stored on local file system. The name of the PAC file must have the pac extension. For example, http://my-site.com/proxy.pac. On a web server the pac file must be served with the application/x-ns-proxy-autoconfig mime type.

Authentication

JxBrowser supports proxy authentication. Please see Authentication.

Chromium does not support password-based authentication for SOCKS proxies.