Explanation

If your XWiki installation is running behind a proxy server, it will likely fail to search for or install extensions, as the Extension Manager relies on remote repositories for this. As a result, you may see connection refused exceptions in the log files. 

Cause

This happens because XWiki, by default, cannot access the internet through the proxy without proper configuration.

Solution

To configure XWiki to work behind a proxy, you need to add the relevant proxy properties/settings to your system environment. XWiki uses the default Java proxy configuration via Apache HttpClient. For more details, refer to the Java Networking and Proxies documentation.

• If you installed XWiki using Tomcat 8+:
  1. Open the setenv.sh (for Linux/Unix) or setenv.bat (for Windows) file from your Tomcat installation’s bin directory  with an editor and add:
     • For Linux/Unix: CATALINA_OPTS="$CATALINA_OPTS -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=7777"
     • For Windows: set CATALINA_OPTS=%CATALINA_OPTS% -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=7777
  2. Restart Tomcat.
  For more tips and configuration options, see the RUNNING.txt / RUNNING.md file from the Tomcat distribution.
• If you installed a standalone (demo) distribution:
  1. Open the start_xwiki.bat (for Windows) or start_xwiki.sh (for Linux/Unix) with an editor and add:
     • For Linux/Unix: XWIKI_OPTS="$XWIKI_OPTS -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=7777" 
     • For Windows: set XWIKI_OPTS=%XWIKI_OPTS% -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 
  2. Restart XWiki.

FAQ

Why do some extensions fail to load when using a proxy that restricts Internet access?

If your proxy server only allows partial access to the Internet, XWiki’s Extension Manager may fail to retrieve available extensions. This happens because XWiki needs to connect to specific external repositories: store.xwiki.com, extensions.xwiki.org, nexus.xwiki.org. Note: one is .com, the others are .org. Make sure all three are accessible through your proxy.

What if my proxy server requires authentication?

You can provide proxy credentials using Java system properties in your startup script: -Dhttps.proxyUser and -Dhttps.proxyPassword (and the http alteratives).

Is XWiki configured properly to see my proxy?

If you still have errors, cannot download extensions with the Extension Manager, or simply want to check whether the proxy settings were applied, you can debug proxy configuration.

More

To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.

Related

• Multiple Instances of XWiki in the Same Container.
• SSL Certificate Error.
• "File Path too Long" on Windows when Unzipping.