Proxy

If the webPDF server needs to retrieve external contents, it normally does so directly. However, there are cases in which webPDF is run on a server that does not have access to external resources or URLs, meaning that it cannot retrieve any content from other servers or from the Internet. However, this access is required, for instance, in order to convert various file formats (e.g., e-mails) when they reference external resources.

In order to make it possible to have this access, you can configure the use of a proxy in webPDF, in which case webPDF will attempt to run all external requests through this proxy in order to retrieve the necessary content.

The proxy's use is configured at the server level, i.e., it applies to the entire server and all web services.

The easiest way to configure the proxy is to do so in the Admin Portal, in the "Proxy" section.

Optionally, you can also configure the proxy directly in the application.xml file.

Configuration Options

webPDF provides two ways to configure proxy settings:

1. Manual proxy configuration - Define specific proxy servers in the configuration file
2. System proxy configuration - Use proxy settings from the operating system

Manual Proxy Configuration

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<server xmlns="http://schema.webpdf.de/1.0/configuration/application">
<!-- ... -->
<proxies useSystemProxies="false">
    <proxy enabled="true" host="proxy-server.example.com" port="8080" scheme="http"
           userName="" password="" bypassProxyOnLocal="true">
        <nonProxyHost host="no-proxy.com"/>
        <nonProxyHost host="any.no-proxy.com"/>
    </proxy>
    <proxy enabled="true" host="proxy-server.example.com" port="8443" scheme="https"
           userName="proxyuser" password="proxypassword" bypassProxyOnLocal="false">
        <nonProxyHost host="*.internal.com"/>
    </proxy>
</proxies>
<!-- ... -->
</server>

Proxies Element

The <proxies> element contains all proxy configurations:

• useSystemProxies (default: false) - When set to true, proxy settings are automatically read from the operating system instead of using manually configured proxies. When enabled, all manually configured <proxy> entries are ignored.

Proxy Element Attributes

Each <proxy> entry supports the following attributes:

• scheme (default: http) - The scheme to access the proxy server. Allowed values: http or https. This defines which protocol requests should use this proxy (e.g., a proxy with scheme="https" will be used for all HTTPS requests).

• host (required) - The address of the proxy server (without protocol prefix).

• port (default: 8080) - The port on which the proxy server listens.

• userName (optional) - The username required to authenticate with the proxy server. Leave empty if authentication is not required.

• password (optional) - The password required to authenticate with the proxy server. Leave empty if authentication is not required.

• bypassProxyOnLocal (default: true) - When enabled, the proxy will be bypassed for local addresses. This includes:

  • localhost
  • 127.* (IPv4 loopback addresses)
  • [::1] or ::1 (IPv6 loopback)
  • IPv6 link-local addresses (fe80::/10)
  • Addresses without a dot (e.g., intranet)

• enabled (default: true) - Enables or disables this proxy configuration. When disabled, the proxy will not be used even if configured. This is useful for testing or temporarily disabling a proxy without removing the configuration.

NonProxyHost Elements

You can specify multiple <nonProxyHost> entries to bypass the proxy for specific hosts:

<proxy ...>
    <nonProxyHost host="direct-access.example.com"/>
    <nonProxyHost host="*.internal.company.com"/>
    <nonProxyHost host="192.168.*"/>
</proxy>

• Wildcards (*) are supported for pattern matching
• Multiple entries can be defined per proxy
• These hosts will be accessed directly without using the proxy

System Proxy Configuration

<proxies useSystemProxies="true">
    <!-- Manual proxy entries are ignored when useSystemProxies is enabled -->
</proxies>

When useSystemProxies is set to true, webPDF automatically reads proxy settings from the operating system:

Supported Proxy Sources

Windows:

• System proxy settings from Windows Registry (Internet Settings)
• Registry path: HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings
• Important: Requires JVM option -Djava.net.useSystemProxies=true to read Windows registry settings

Linux:

• Environment variables: HTTP_PROXY, HTTPS_PROXY, NO_PROXY

All platforms:

• Java system properties (work without additional JVM options):
  • -Dhttp.proxyHost
  • -Dhttp.proxyPort
  • -Dhttps.proxyHost
  • -Dhttps.proxyPort
  • -Dhttp.nonProxyHosts

Important Limitations

• No authentication support: System proxies do not support authentication. The proxy must allow anonymous connections.
• PAC files not supported: Proxy Auto-Config (PAC) files are not supported.
• WPAD not supported: Web Proxy Auto-Discovery Protocol (WPAD) is not supported.
• Exclusive setting: When useSystemProxies is enabled, all manually configured <proxy> entries are completely ignored. Either system proxies OR manual proxies are used, not both.

Multiple Proxy Configurations

You can define separate proxy configurations for different schemes (protocols):

<proxies useSystemProxies="false">
    <proxy enabled="true" host="http-proxy.example.com" port="8080" scheme="http"/>
    <proxy enabled="true" host="https-proxy.example.com" port="8443" scheme="https"/>
</proxies>

webPDF will automatically select the appropriate proxy based on the target URL's scheme.

Server Restart Required

After you change the proxy configuration in application.xml, you must restart the webPDF server for the changes to take effect.