Skip to main content
Version: Next

Proxy

By default, coursier relies on java.net.HttpURLConnection to handle HTTP requests. java.net.HttpURLConnection automatically picks up proxy related properties.

Properties​

The following Java system properties control proxy behaviour:

PropertyDescription
https.proxyHostHostname of the proxy for HTTPS connections
https.proxyPortPort of the proxy for HTTPS connections (default: 443)
https.proxyUserUsername for proxy authentication (HTTPS)
https.proxyPasswordPassword for proxy authentication (HTTPS)
http.proxyHostHostname of the proxy for HTTP connections
http.proxyPortPort of the proxy for HTTP connections (default: 80)
http.proxyUserUsername for proxy authentication (HTTP)
http.proxyPasswordPassword for proxy authentication (HTTP)
http.nonProxyHostsPipe-separated list of host patterns that bypass the proxy (e.g. localhost|*.internal.example.com)

Basic authentication for HTTPS proxy tunnels​

Since 8u111, the JDK refuses to send Basic credentials when tunneling HTTPS connections through a proxy (Basic is listed in the jdk.http.auth.tunneling.disabledSchemes property, in $JAVA_HOME/conf/net.properties).

When proxy credentials are configured (via the http.proxyUser / https.proxyUser properties, the <username> of a proxy in Maven settings.xml, or the proxy user of the Scala CLI configuration), coursier removes Basic from the jdk.http.auth.tunneling.disabledSchemes property, so that authenticated proxies work. This setting applies to the whole JVM. coursier leaves the property alone when no proxy credentials are configured, or when the property was already set, like with

$ java -Djdk.http.auth.tunneling.disabledSchemes=Basic …

which keeps Basic authentication disabled for proxy tunnels.

Maven settings.xml​

Coursier automatically reads proxy settings from the Maven settings.xml file. It looks for settings.xml in the following locations, in order:

  1. The directory given by the CS_MAVEN_HOME environment variable
  2. The directory given by the MAVEN_HOME environment variable
  3. The directory given by the cs.maven.home Java property
  4. The directory given by the maven.home Java property
  5. ~/.m2 (the Maven default)

If the file is found, coursier reads any <proxy> entries whose <active> element is true (or absent) and configures the corresponding Java system properties automatically.

Example ~/.m2/settings.xml:

<settings>
<proxies>
<proxy>
<id>my-proxy</id>
<active>true</active>
<protocol>https</protocol>
<host>proxy.example.com</host>
<port>3128</port>
<username>proxyuser</username>
<password>proxypass</password>
<nonProxyHosts>localhost|*.internal.example.com</nonProxyHosts>
</proxy>
</proxies>
</settings>

The <protocol> element specifies whether the proxy itself communicates over HTTP or HTTPS (it does not filter which target URLs go through the proxy). If <protocol> is omitted, https is assumed.

CLI​

To set proxy properties directly, run the CLI with -D flags:

$ java -Dhttps.proxyHost=… -Dhttps.proxyPort=… \
-jar $(which coursier) [args]

instead of coursier [args]. Alternatively, recent versions of coursier should accept those options prefixed with -J, like

$ coursier -J-Dhttps.proxyHost=… -J-Dhttps.proxyPort=… [args]

sbt​

Set those properties when starting sbt, like

$ sbt -Dhttps.proxyHost=… -Dhttps.proxyPort=… [args]

Alternatively, pass those by setting JAVA_OPTS in the environment.

API​

Ensure the right Java properties are set when running your application, either from the command line when running your application, via

$ java -Dhttps.proxyHost=… -Dhttps.proxyPort=… [args]

or by setting them yourself before anything coursier is run, like

System.setProperty("https.proxyHost", "…")
System.setProperty("https.proxyPort", "…")

If you want coursier to read proxy settings from ~/.m2/settings.xml automatically (the same way the CLI does), call SetupProxy.setup() early in your application:

import coursier.proxy.SetupProxy;

SetupProxy.setup(); // reads ~/.m2/settings.xml and registers a proxy Authenticator

SetupProxy.setup() both configures the proxy system properties (https.proxyHost, etc.) from the Maven settings file and registers a java.net.Authenticator so that authenticated proxies work correctly. If proxy credentials are configured, it also enables Basic authentication for HTTPS proxy tunnels, see above.