This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new 24b09327 Replace the Wagon HTTP guide with the current Wagon HTTP
configuration reference
24b09327 is described below
commit 24b09327ed920293d7e159543f5970f49ec5d31d
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Oct 31 20:03:19 2026 +0000
Replace the Wagon HTTP guide with the current Wagon HTTP configuration
reference
---
.../markdown/guides/mini/guide-http-settings.md | 671 +++++++++++++--------
1 file changed, 412 insertions(+), 259 deletions(-)
diff --git a/content/markdown/guides/mini/guide-http-settings.md
b/content/markdown/guides/mini/guide-http-settings.md
index 237ffaed..57906f9e 100644
--- a/content/markdown/guides/mini/guide-http-settings.md
+++ b/content/markdown/guides/mini/guide-http-settings.md
@@ -23,343 +23,496 @@ under the License.
<!-- MACRO{toc} -->
-You can use the default wagon implementation for a given protocol, or you can
select an alternative wagon `provider` on a per-protocol basis. For more
information, see the [Guide to Wagon Providers](./guide-wagon-providers.html)
[3]. The default wagon http(s) is the HttpClient based on [Apache Http Client
4.5](https://hc.apache.org/httpcomponents-client-4.5.x/). HTTP connection
pooling prevents reopening new connections to the same server for each request.
This pool feature is configurab [...]
+You can use the default wagon implementation for a given protocol, or select
an alternative wagon provider on a per-protocol basis; see the [Guide to Wagon
Providers](./guide-wagon-providers.html). With Maven 3.9.0 and later, Wagon is
used when you select it with `-Dmaven.resolver.transport=wagon`. The native
HTTP transport reads only the `<all>` block of `httpConfiguration` (`get`,
`head` and `put` are ignored) and warns about the deprecation, so the
per-method configuration below appli [...]
-- http(s) connection pool: default to 20.
-- readTimeout: default to 1800000 (~30 minutes) (see section `Read time out`
below)
-- default Preemptive Authentication only with PUT (GET doesn't use anymore
default Preemptive Authentication)
+This page documents the `<configuration>` block that
+[wagon-http](https://maven.apache.org/wagon/wagon-providers/wagon-http/) reads
— headers, request parameters,
+timeouts, preemptive authentication and authentication scope — and how each
setting
+maps onto Apache HttpClient 4.5. It describes Wagon 3.5.3, the version Maven
3.9.x and
+3.10.x ship with. Four behaviours marked "Wagon 3.5.3" below change in later
Wagon
+releases, so check the release notes of the Wagon version you use.
-## Introduction
+Everything here comes from `AbstractHttpClientWagon` in `wagon-http-shared`,
so it
+applies equally to
[wagon-webdav-jackrabbit](https://maven.apache.org/wagon/wagon-providers/wagon-webdav-jackrabbit/),
+which extends the same class. It does **not** apply to
+[wagon-http-lightweight](https://maven.apache.org/wagon/wagon-providers/wagon-http-lightweight/),
which is a
+different implementation built on `java.net.HttpURLConnection`.
-The HttpClient-based HTTP wagon offers more control over the configuration
used to access HTTP-based Maven repositories. For starters, you have
fine-grained control over what HTTP headers are used when resolving artifacts.
In addition, you can also configure a wide range of parameters to control the
behavior of HttpClient itself. Best of all, you have the ability to control
these headers and parameters for all requests, or individual request types
(GET, HEAD, and PUT).
+Settings that are global rather than per-server are exposed as system
properties
+instead; see [System properties](#System_properties) at the end.
-## The Basics
+## Where configuration goes
-Without any special configuration, Maven's HTTP wagon uses some default HTTP
headers and client parameters when managing artifacts. The default headers are:
+In a Maven build, per-server configuration lives in `settings.xml`, inside the
+`<server>` whose `<id>` matches the repository or `distributionManagement` id:
-```
-Cache-control: no-cache
-Cache-store: no-store
-Pragma: no-cache
-Expires: 0
-Accept-Encoding: gzip
+```xml
+<settings>
+ <servers>
+ <server>
+ <id>my-repository</id>
+ <username>deploy</username>
+ <password>secret</password>
+ <configuration>
+ <!-- everything on this page goes here -->
+ </configuration>
+ </server>
+ </servers>
+</settings>
```
-In addition, PUT requests made with the HTTP wagon use the following
HttpClient parameter:
+The elements inside `<configuration>` are mapped onto the Wagon instance as
Plexus
+component configuration: element names correspond to the fields and setters of
the
+provider class. Programmatically the same settings are the
`setHttpConfiguration`,
+`setHttpHeaders`, `setBasicAuthScope`, `setProxyBasicAuthScope` and
+`setInitialBackoffSeconds` methods of `AbstractHttpClientWagon`.
+
+## `httpConfiguration`
+
+`httpConfiguration` is the main entry point. It is an
+[`HttpConfiguration`](https://maven.apache.org/wagon/apidocs/org/apache/maven/wagon/shared/http/HttpConfiguration.html)
+with five optional children, one for "every method" plus one per HTTP method
the
+providers issue:
+
+| Element | Applies to |
+| --- | --- |
+| `all` | every request |
+| `get` | `GET` — downloads |
+| `put` | `PUT` — uploads |
+| `head` | `HEAD` — `resourceExists` |
+| `mkcol` | `MKCOL` — WebDAV collection creation |
+
+Each is an
+[`HttpMethodConfiguration`](https://maven.apache.org/wagon/apidocs/org/apache/maven/wagon/shared/http/HttpMethodConfiguration.html)
+with the same six properties:
+
+| Property | Type | Default |
+| --- | --- | --- |
+| `useDefaultHeaders` | boolean | `true` |
+| `headers` | `Properties` | empty |
+| `params` | `Properties` | empty |
+| `connectionTimeout` | int, milliseconds | 60000 |
+| `readTimeout` | int, milliseconds | 1800000, or the value of the
`maven.wagon.rto` system property |
+| `usePreemptive` | boolean | `false` |
-```
-http.protocol.expect-continue=true
+```xml
+<configuration>
+ <httpConfiguration>
+ <all>
+ <connectionTimeout>10000</connectionTimeout>
+ <readTimeout>60000</readTimeout>
+ <headers>
+ <User-Agent>my-build/1.0</User-Agent>
+ </headers>
+ <params>
+ <http.protocol.max-redirects>5</http.protocol.max-redirects>
+ </params>
+ </all>
+ <put>
+ <readTimeout>600000</readTimeout>
+ </put>
+ </httpConfiguration>
+</configuration>
```
-From the HttpClient documentation[2], this parameter provides the following
functionality:
+### How `all` and the per-method block are combined
-```
-Activates 'Expect: 100-Continue' handshake for the entity enclosing methods.
-The 'Expect: 100-Continue' handshake allows a client that is sending a request
-message with a request body to determine if the origin server is willing to
-accept the request (based on the request headers) before the client sends the
-request body.
-
-The use of the 'Expect: 100-continue' handshake can result in noticeable
performance
-improvement for entity enclosing requests (such as POST and PUT) that require
-the target server's authentication.
-
-'Expect: 100-continue' handshake should be used with caution, as it may cause
-problems with HTTP servers and proxies that do not support HTTP/1.1 protocol.
-```
+For each request, `HttpConfiguration.getMethodConfiguration(HttpUriRequest)`
looks at
+the method name and merges `all` with the matching block. Anything that is not
`GET`,
+`PUT`, `HEAD` or `MKCOL` gets `all` alone.
-Without this setting, PUT requests that require authentication transfer their
entire payload to the server before that server issues an authentication
challenge. In order to complete the PUT request, the client must then re-send
the payload with the proper credentials specified in the HTTP headers. This
results in twice the bandwidth usage, and twice the time to transfer each
artifact.
+The merge, in `ConfigurationUtils.merge(base, local)`:
-Another option to avoid this double transfer is what's known as preemptive
authentication, which involves sending the authentication headers along with
the original PUT request. However, there are a few potential issues with this
approach. For one thing, in the event you have an unused `<server>` entry that
specifies an invalid username/password combination, some servers may respond
with a `401 Unauthorized` even if the server doesn't actually require any
authentication for the request. [...]
+- if only one of the two is present, it is used as-is;
+- otherwise `all` is copied and then the per-method block is layered on top:
+ `headers` and `params` are merged key by key (the per-method value wins);
+ `useDefaultHeaders` is taken from the per-method block if it was set
explicitly;
+ `connectionTimeout` and `readTimeout` are taken from the per-method block
only if
+ they differ from `Wagon.DEFAULT_CONNECTION_TIMEOUT` and
`Wagon.DEFAULT_READ_TIMEOUT`
+ respectively.
-We'll discuss preemptive authentication in another example, below.
+That last rule has a consequence worth knowing in Wagon 3.5.3: you cannot use
a per-method block to
+set a timeout *back* to the default value. Writing
`<readTimeout>1800000</readTimeout>`
+inside `<get>` is indistinguishable from not writing it at all, and the value
from
+`<all>` survives.
-## Configuring GET, HEAD, PUT, or All of the Above
+**Wagon 3.5.3: `usePreemptive` is not carried through the merge at all.** The
copy step does not
+copy it and the merge step does not apply it, so if both `<all>` and the block
for
+the method in question are present, the effective `usePreemptive` is always
`false`.
+Set it in `<all>` and leave that method's own block out, or set it only in the
+method block and leave `<all>` out. This is what
+`HttpWagonPreemptiveTest` does — it configures nothing but
+`setAll(new HttpMethodConfiguration().setUsePreemptive(true))`.
-**Starting with Maven 3.9.0 native HTTP transport will pick up the "all"
settings only (get, head, put are neglected!)" but it will WARN about its
deprecation. For users sticking with Wagon nothing changes.**
+### Writing `headers` and `params`
-In all of the examples below, it's important to understand that you can
configure the HTTP settings for all requests made to a given server, or for
only one method. To configure all methods for a server, use the following
section of the `settings.xml` file:
+Both are `java.util.Properties`, and Plexus accepts two spellings for those.
The
+short form uses the key as the element name:
```xml
-<settings>
- [...]
- <servers>
- <server>
- <id>the-server</id>
- <configuration>
- <httpConfiguration>
- <all>
- [ Your configuration here. ]
- </all>
- </httpConfiguration>
- </configuration>
- </server>
- </servers>
-</settings>
+<headers>
+ <User-Agent>my-build/1.0</User-Agent>
+</headers>
```
-On the other hand, if you can live with the default configuration for most
requests — say, HEAD and GET requests, which are used to check for the
existence of a file and retrieve a file respectively — maybe you only need to
configure the PUT method:
+The long form spells out each entry and works with every Plexus component
+configurator:
```xml
-<settings>
- [...]
- <servers>
- <server>
- <id>the-server</id>
- <configuration>
- <httpConfiguration>
- <put>
- [ Your configuration here. ]
- </put>
- </httpConfiguration>
- </configuration>
- </server>
- </servers>
-</settings>
+<headers>
+ <property>
+ <name>User-Agent</name>
+ <value>my-build/1.0</value>
+ </property>
+</headers>
```
-For clarity, the other two sections are `<get>` for GET requests, and `<head>`
for HEAD requests. I know that's going to be hard to remember...
+Use the long form for keys that are not valid XML element names — most of the
`params`
+keys below contain dots, which is fine, but nothing stops a header name from
+containing characters that are not.
+
+### `headers`
-## Taking Control of Your HTTP Headers
+Headers from the configuration are applied with `setHeader`, so they replace
any
+header of the same name that the provider had already added.
-As you may have noticed above, the default HTTP headers do have the potential
to cause problems. For instance, some websites set the encoding for downloading
GZipped files as `gzip`, in spite of the fact that the HTTP request itself
isn't being sent using GZip compression. If the client is using the
`Accept-Encoding: gzip` header, this can result in the client itself
decompressing the GZipped file _during the transfer_ and writing the
decompressed file to the local disk with the original [...]
+`User-Agent` gets special handling: `getUserAgent(HttpUriRequest)` looks it up
in
+`httpHeaders` first, then in the merged method configuration's `headers`, and
the
+result is set on the request. If nothing supplies one, no `User-Agent` is
added by
+Wagon.
-To turn off this default behavior, simply disable the default headers. Then,
respecify the other headers that you are still interested in, like this:
+### `useDefaultHeaders`
+
+When `true` — the default — every request gets
+
+```
+Cache-control: no-cache
+Pragma: no-cache
+```
+
+before your own headers are applied. Set it to `false` to suppress them.
+
+### `params`
+
+`<params>` is an escape hatch onto HttpClient's `RequestConfig`. Only the keys
below
+are recognised; anything else is silently ignored. Values may optionally be
prefixed
+with a legacy type coercion of the form `%type,value` — for example
+`%Integer,3` — in which case only the part after the comma is used.
+
+| Parameter | `RequestConfig` setting |
+| --- | --- |
+| `http.socket.timeout` | `setSocketTimeout(int)` |
+| `http.connection.timeout` | `setConnectTimeout(int)` |
+| `http.connection.stalecheck` | `setStaleConnectionCheckEnabled(boolean)` |
+| `http.conn-manager.timeout` | `setConnectionRequestTimeout(int)` |
+| `http.protocol.expect-continue` | `setExpectContinueEnabled(boolean)` |
+| `http.protocol.handle-authentication` | `setAuthenticationEnabled(boolean)` |
+| `http.protocol.handle-redirects` | `setRedirectsEnabled(boolean)` |
+| `http.protocol.max-redirects` | `setMaxRedirects(int)` |
+| `http.protocol.allow-circular-redirects` |
`setCircularRedirectsAllowed(boolean)` |
+| `http.protocol.reject-relative-redirect` |
`setRelativeRedirectsAllowed(!value)` |
+| `http.protocol.handle-content-compression` |
`setContentCompressionEnabled(boolean)` |
+| `http.protocol.handle-uri-normalization` | `setNormalizeUri(boolean)` |
+| `http.protocol.cookie-policy` | `setCookieSpec(String)` |
+| `http.route.default-proxy` | `setProxy(HttpHost.create(value))` |
+| `http.route.local-address` | `setLocalAddress(InetAddress)`; an unresolvable
name is ignored |
+| `http.auth.target-scheme-pref` | `setTargetPreferredAuthSchemes(...)`,
comma-separated |
+| `http.auth.proxy-scheme-pref` | `setProxyPreferredAuthSchemes(...)`,
comma-separated |
+
+Two of these interact with settings applied elsewhere. `params` are applied
*after*
+the request has already been given the Wagon's own connect and read timeouts,
so
+`http.socket.timeout` and `http.connection.timeout` take precedence over
+`connectionTimeout`/`readTimeout` and over `setTimeout`/`setReadTimeout`.
Also, the
+cookie policy is set to `CookieSpecs.BROWSER_COMPATIBILITY` before `params` are
+applied, so `http.protocol.cookie-policy` overrides that default.
+
+`Expect: 100-continue` is enabled unconditionally for `PUT` requests, before
`params`
+are applied; `http.protocol.expect-continue` can therefore turn it off. It is
+deliberately not enabled for `MKCOL`, which has no body.
+
+### Ignoring cookies
+
+Some repositories send session cookies, often by mistake, alongside HTTP
redirection. The
+cookie's `Path` can then disagree with the path the client uses, and requests
fail. If you
+know you do not need the session cookie, ignore cookies for the server:
```xml
-<settings>
- [...]
- <servers>
- <server>
- <id>openssl</id>
- <configuration>
- <httpConfiguration>
- <put>
- <useDefaultHeaders>false</useDefaultHeaders>
- <headers>
- <property>
- <name>Cache-control</name>
- <value>no-cache</value>
- </property>
- <property>
- <name>Cache-store</name>
- <value>no-store</value>
- </property>
- <property>
- <name>Pragma</name>
- <value>no-cache</value>
- </property>
- <property>
- <name>Expires</name>
- <value>0</value>
- </property>
- <property>
- <name>Accept-Encoding</name>
- <value>*</value>
- </property>
- </headers>
- </put>
- </httpConfiguration>
- </configuration>
- </server>
- [...]
- </servers>
- [...]
-</settings>
+<configuration>
+ <httpConfiguration>
+ <all>
+ <params>
+ <http.protocol.cookie-policy>ignore</http.protocol.cookie-policy>
+ </params>
+ </all>
+ </httpConfiguration>
+</configuration>
```
-## Fine-Tuning HttpClient Parameters
+## Authentication
-Going beyond the power of HTTP request parameters, HttpClient provides a host
of other configuration options. In most cases, you won't need to customize
these. But in case you do, Maven provides access to specify your own
fine-grained configuration for HttpClient. Again, you can specify these
parameter customizations per-method (HEAD, GET, or PUT), or for all methods of
interacting with a given server. For a complete list of supported parameters,
see the link[2] in Resources section below.
+### Target server credentials
-### Non-String Parameter Values
+At `connect` time, if the `AuthenticationInfo` has a non-empty user name *and*
a
+non-empty password, a `UsernamePasswordCredentials` is registered in the
+`CredentialsProvider` under an `AuthScope` derived from the repository's host
and
+port. A user name without a password registers nothing.
-Many of the configuration parameters for HttpClient have simple string values;
however, there are important exceptions to this. In some cases, you may need to
specify boolean, integer, or long values. In others, you may even need to
specify a collection of string values. You can specify these using a simple
formatting syntax, as follows:
+The client is built with an auth scheme registry containing exactly three
schemes:
-1. **booleans:** `%b,<value>`
-2. **integer:** `%i,<value>`
-3. **long:** `%l,<value>` (yes, that's an 'L', not a '1')
-4. **double:** `%d,<value>`
-5. **collection of strings:** `%c,<value1>,<value2>,<value3>,...`, which could
also be specified as:
+| Scheme | Factory |
+| --- | --- |
+| Basic | `BasicSchemeFactory`, UTF-8 |
+| Digest | `DigestSchemeFactory`, UTF-8 |
+| NTLM | `NTLMSchemeFactory` |
- ```
- %c,
- <value1>,
- <value2>,
- <value3>,
- ...
- ```
+Basic and Digest both work against the target server with a plain user name and
+password, negotiated in response to the server's challenge. Use
+`http.auth.target-scheme-pref` if you need to force the order in which schemes
are
+tried.
-As you may have noticed, this syntax is similar to the format-and-data
strategy used by functions like `sprintf()` in many languages. The syntax has
been chosen with this similarity in mind, to make it a little more intuitive to
use.
+**NTLM against the target server is not supported.** The target credentials are
+always `UsernamePasswordCredentials`, never `NTCredentials`, so the registered
NTLM
+scheme has nothing usable to offer. NTLM is only wired up for proxies — see
below.
-#### Example: Using Preemptive Authentication
+### Preemptive authentication
-Using the above syntax, you can configure preemptive authentication for PUT
requests using the boolean HttpClient parameter
`http.authentication.preemptive`, like this:
+By default HttpClient waits for a `401` challenge before sending credentials.
With
+`usePreemptive` set, a `BasicScheme` is placed in the `AuthCache` for the
target host
+before the request goes out, provided credentials for that scope exist — so
the first
+request already carries an `Authorization: Basic` header:
```xml
-<settings>
- <servers>
- <server>
- <id>my-server</id>
- <configuration>
- <httpConfiguration>
- <put>
- <params>
- <property>
- <name>http.authentication.preemptive</name>
- <value>%b,true</value>
- </property>
- </params>
- </put>
- </httpConfiguration>
- </configuration>
- </server>
- </servers>
-</settings>
+<configuration>
+ <httpConfiguration>
+ <all>
+ <usePreemptive>true</usePreemptive>
+ </all>
+ </httpConfiguration>
+</configuration>
```
-Another option is to make write it like this:
+Note the merge caveat above: adding a `<get>` block alongside this would switch
+preemptive authentication back off.
-```xml
-<settings>
- <servers>
- <server>
- <id>my-server</id>
- <configuration>
- <httpConfiguration>
- <put>
- <usePreemptive>true</usePreemptive>
- </put>
- </httpConfiguration>
- </configuration>
- </server>
- </servers>
-</settings>
-```
+Without `Expect: 100-continue`, a `PUT` that needs authentication would send
its whole payload before the server issues the challenge, and then send it
again with credentials: twice the bandwidth and time per artifact. Preemptive
authentication avoids that by sending the credentials with the first request,
at a price. An unused `<server>` entry with a wrong user name or password can
make some servers answer `401 Unauthorized` even for requests that need no
authentication, and sending cre [...]
-### Example: Lifting auth scope restriction for external authentication systems
+Preemptive Basic authentication is only ever Basic — the cache entry is a
+`BasicScheme`. It has no effect on Digest or NTLM.
-Maven Wagon by default limits supplied credentials to the host:port
combination scope, ignoring any other target servers. When the target server
delegates authentication to an external system, you need to deliberately lift
that scope limitation. Configure your server element to pass authentication to
all target servers which challenge the client. +---+ _settings_ _servers_
_server_ _id_my-server_/id_ _configuration_ _basicAuthScope_ _host_ANY_/host_
_port_ANY_/port_ _!-- or even 443 to f [...]
+`PUT` is a special case in Wagon 3.5.3: `AbstractHttpClientWagon.put` primes
the `AuthCache` with a
+`BasicScheme` for the target host whenever credentials exist, regardless of
+`usePreemptive`. Uploads are therefore preemptively authenticated by default.
The
+source marks this as a known wart ("FIXME Perform only when preemptive has been
+configured").
-### Ignoring Cookies
+### `basicAuth` and `proxyAuth` — overriding the authentication scope
-Like the example above, telling the HttpClient to ignore cookies for all
methods of request is a simple matter of configuring the
`http.protocol.cookie-policy` parameter (it uses a regular string value, so no
special syntax is required):
+By default the `AuthScope` for the target is built from the repository's own
host and
+port with `AuthScope.ANY_REALM`, and a port of `-1` becomes
`AuthScope.ANY_PORT`.
+[`BasicAuthScope`](https://maven.apache.org/wagon/apidocs/org/apache/maven/wagon/shared/http/BasicAuthScope.html)
+lets you override `host`, `port` and `realm`.
-```xml
-<settings>
- <servers>
- <server>
- <id>my-server</id>
- <configuration>
- <httpConfiguration>
- <all>
- <params>
- <param>
- <name>http.protocol.cookie-policy</name>
- <value>ignore</value>
- </param>
- </params>
- </all>
- </httpConfiguration>
- </configuration>
- </server>
- </servers>
-</settings>
-```
+`host` and `port` accept the literal string `ANY` to mean "match anything", and
+setting `host`, `port` and `realm` all to `ANY` yields `AuthScope.ANY`.
-The configuration above can be useful in cases where the repository is using
cookies - like the session cookies that are often mistakenly turned on or left
on in appservers - alongside HTTP redirection. In these cases, it becomes far
more likely that the cookie issued by the appserver uses a `Path` that is
inconsistent with the one used by the client to access the server. If you have
this problem, and know that you don't need to use this session cookie, you can
ignore cookies from this s [...]
+`realm` does not work that way, and it is worth being explicit about it
because the
+asymmetry is easy to trip over in Wagon 3.5.3. Omitting `realm` gives you
`AuthScope.ANY_REALM`,
+which is what "match any realm" means. Setting it to any value — *including*
`ANY`,
+unless `host` and `port` are `ANY` too — matches that string verbatim, so
+`<realm>ANY</realm>` on its own produces a scope that only matches a server
whose
+realm is literally `ANY`. Leave `realm` out unless you mean to pin it.
-## Support for General-Wagon Configuration Standards
+This is the setting to reach for when credentials are not being sent because
the
+server's realm or port does not match what Wagon derived from the URL — for
instance
+a repository fronted by a redirect to another host, or one that delegates
authentication
+to an external system that challenges from a different host.
-It should be noted that configuration options previously available in the
HttpClient-driven HTTP wagon are still supported in addition to this new,
fine-grained approach. These include the configuration of HTTP headers and
connection timeouts. Let's examine each of these briefly:
+The two scopes are held in fields named `basicAuth` (for the target) and
`proxyAuth`
+(for the proxy), reachable through `setBasicAuthScope` and
`setProxyBasicAuthScope`.
-### HTTP Headers
+```xml
+<configuration>
+ <basicAuth>
+ <host>ANY</host>
+ <port>ANY</port>
+ <realm>ANY</realm>
+ </basicAuth>
+</configuration>
+```
-In all HTTP Wagon implementations, you can add your own HTTP headers like this:
+That is the all-`ANY` case, which short-circuits to `AuthScope.ANY` and so
does match
+any realm. To widen only the host and port, omit `realm` rather than setting
it to
+`ANY`:
```xml
-<settings>
- <servers>
- <server>
- <id>my-server</id>
- <configuration>
- <httpHeaders>
- <property>
- <name>Foo</name>
- <value>Bar</value>
- </property>
- </httpHeaders>
- </configuration>
- </server>
- </servers>
-</settings>
+<configuration>
+ <basicAuth>
+ <host>ANY</host>
+ <port>ANY</port>
+ </basicAuth>
+</configuration>
```
-It's important to understand that the above approach doesn't allow you to turn
off all of the default HTTP headers; nor does it allow you to specify headers
on a per-method basis. However, this configuration remains available in both
the lightweight and httpclient-based Wagon implementations.
+## Proxies
+
+Proxy settings come from Maven's `<proxy>` configuration rather than from
+`<server><configuration>`; Wagon receives them as a
+[`ProxyInfo`](https://maven.apache.org/wagon/apidocs/org/apache/maven/wagon/proxy/ProxyInfo.html).
What the HTTP
+provider does with them:
+
+- The proxy is only used when the `ProxyInfo`'s `type` matches the repository's
+ protocol and the target host does not match `nonProxyHosts`. See
+ [Configuring a proxy](./guide-proxies.html).
+- If the `ProxyInfo` carries a user name and a password, credentials are
registered
+ under a scope derived from the proxy host and port, overridable through
`proxyAuth`
+ exactly as `basicAuth` overrides the target scope.
+- **NTLM.** If either `ntlmHost` or `ntlmDomain` is set on the `ProxyInfo`,
the proxy
+ credentials become `NTCredentials(username, password, ntlmHost, ntlmDomain)`
+ instead of `UsernamePasswordCredentials`, and the registered
`NTLMSchemeFactory`
+ handles the challenge. Use `http.auth.proxy-scheme-pref` to control which
scheme is
+ preferred when the proxy offers several.
+- Proxy authentication is always primed preemptively: whenever proxy
credentials
+ exist, a `BasicScheme` with `ChallengeState.PROXY` is put in the `AuthCache`
for the
+ proxy host.
+
+## Connection timeout
+
+Every Wagon that extends `AbstractWagon` (SCP, HTTP, FTP and others) accepts a
flat
+connection timeout in milliseconds, which applies to all methods:
-### Connection Timeouts
+```xml
+<configuration>
+ <timeout>6000</timeout>
+</configuration>
+```
-All wagon implementations that extend the `AbstractWagon` class, including
those for SCP, HTTP, FTP, and more, allow the configuration of a connection
timeout, to allow the user to tell Maven how long to wait before giving up on a
connection that has not responded. This option is preserved in the
HttpClient-based wagon, but this wagon also provides a fine-grained alternative
configuration that can allow you to specify timeouts per-method for a given
server. The old configuration option - [...]
+`connectionTimeout` inside `httpConfiguration` is the per-method alternative.
The `params`
+`http.socket.timeout` and `http.connection.timeout` still take precedence over
both.
+
+## Deprecated: `httpHeaders`
```xml
-<settings>
- <servers>
- <server>
- <id>my-server</id>
- <configuration>
- <timeout>6000</timeout> <!-- milliseconds -->
- </configuration>
- </server>
- </servers>
-</settings>
+<configuration>
+ <httpHeaders>
+ <property>
+ <name>User-Agent</name>
+ <value>my-build/1.0</value>
+ </property>
+ </httpHeaders>
+</configuration>
```
-...while the new configuration option looks more like this:
+`httpHeaders` is a flat `Properties` of headers applied to every request. It
predates
+`httpConfiguration` and is marked deprecated in the source in favour of it. It
is
+still honoured, and it is applied *before* the `httpConfiguration` headers, so
a
+header set in both places takes its value from `httpConfiguration`. The one
exception
+is `User-Agent` lookup, which consults `httpHeaders` first.
+
+## Backoff on 429
+
+When the server answers `429 Too Many Requests`, the provider sleeps and
retries,
+doubling the wait each time until it would reach the maximum, at which point it
+throws `TransferFailedException`. The initial wait is 5 seconds and the
maximum is
+180 seconds; both are system properties (below), and the initial value is also
+settable per server:
```xml
-<settings>
- <servers>
- <server>
- <id>my-server</id>
- <configuration>
- <httpConfiguration>
- <put>
- <connectionTimeout>10000</connectionTimeout> <!-- milliseconds -->
- </put>
- </httpConfiguration>
- </configuration>
- </server>
- </servers>
-</settings>
+<configuration>
+ <initialBackoffSeconds>10</initialBackoffSeconds>
+</configuration>
```
-If all you need is a per-server timeout configuration, you still have the
option to use the old `<timeout>` parameter. If you need to separate timeout
preferences according to HTTP method, you can use one more like that specified
directly above.
+## System properties
+
+These are JVM-wide, not per-server. Several are read into `static final`
fields when
+`AbstractHttpClientWagon` is first loaded, so they must be set before any
transfer
+starts — on the command line, or in `MAVEN_OPTS`.
+
+### Connection pool
+
+| Property | Default | Effect |
+| --- | --- | --- |
+| `maven.wagon.http.pool` | `true` | enable the pooling connection manager;
when `false`, total connections are capped at 1 and idle connections are closed
on disconnect |
+| `maven.wagon.httpconnectionManager.maxPerRoute` | `20` | max connections per
route |
+| `maven.wagon.httpconnectionManager.maxTotal` | `40` | max connections
overall |
+| `maven.wagon.httpconnectionManager.ttlSeconds` | `300` | connection
time-to-live; `-1` keeps connections indefinitely |
+
+### Timeouts
+
+| Property | Default | Effect |
+| --- | --- | --- |
+| `maven.wagon.rto` | `1800000` | default read timeout in milliseconds |
+
+### TLS
+
+| Property | Default | Effect |
+| --- | --- | --- |
+| `maven.wagon.http.ssl.insecure` | `false` | accept any certificate chain
whose dates are valid |
+| `maven.wagon.http.ssl.allowall` | `false` | with `insecure`, skip hostname
verification |
+| `maven.wagon.http.ssl.ignore.validity.dates` | `false` | with `insecure`,
also ignore certificate dates |
+| `https.protocols` | — | comma-separated list of enabled TLS protocols |
+| `https.cipherSuites` | — | comma-separated list of enabled cipher suites |
-### Read time out
+Without `maven.wagon.http.ssl.insecure`, the default JSSE socket factory is
used with
+HttpClient's browser-compatible hostname verifier.
-The default timeout is 30 minutes. If you want to change this value, you can
add the following setup in your settings:
+### Retries
+
+| Property | Default | Effect |
+| --- | --- | --- |
+| `maven.wagon.http.retryHandler.class` | `standard` | `default`, `standard`,
or a fully qualified `HttpRequestRetryHandler` with a no-arg constructor |
+| `maven.wagon.http.retryHandler.requestSentEnabled` | `false` | retry
requests that were already sent (`default` and `standard` only) |
+| `maven.wagon.http.retryHandler.count` | `3` | retry count (`default` and
`standard` only) |
+| `maven.wagon.http.retryHandler.nonRetryableClasses` | — | comma-separated
exception class names to never retry (`default` only) |
+| `maven.wagon.http.serviceUnavailableRetryStrategy.class` | `none` | `none`,
`default`, `standard`, or a fully qualified `ServiceUnavailableRetryStrategy`
with a no-arg constructor |
+| `maven.wagon.http.serviceUnavailableRetryStrategy.retryInterval` | `1000` |
milliseconds between retries |
+| `maven.wagon.http.serviceUnavailableRetryStrategy.maxRetries` | `5` |
maximum retries |
+
+A retry handler only reacts to failures while sending the request and reading
the
+response head. It cannot recover a response body that fails part-way through.
+
+### Backoff
+
+| Property | Default | Effect |
+| --- | --- | --- |
+| `maven.wagon.httpconnectionManager.backoffSeconds` | `5` | initial wait
after a `429` |
+| `maven.wagon.httpconnectionManager.maxBackoffSeconds` | `180` | give up once
the next wait would reach this |
+
+## Worked example
+
+A server that needs preemptive Basic authentication, a custom user agent, no
+redirects, and a generous read timeout for uploads:
```xml
-<settings>
- <servers>
- <server>
- <id>my-server</id>
- <configuration>
- <httpConfiguration>
- <put>
- <readTimeout>120000</readTimeout> <!-- milliseconds -->
- </put>
- </httpConfiguration>
- </configuration>
- </server>
- </servers>
-</settings>
+<server>
+ <id>internal-releases</id>
+ <username>deploy</username>
+ <password>secret</password>
+ <configuration>
+ <httpConfiguration>
+ <all>
+ <usePreemptive>true</usePreemptive>
+ <connectionTimeout>10000</connectionTimeout>
+ <headers>
+ <User-Agent>acme-build/2.1</User-Agent>
+ </headers>
+ <params>
+
<http.protocol.handle-redirects>false</http.protocol.handle-redirects>
+ <http.socket.timeout>600000</http.socket.timeout>
+ </params>
+ </all>
+ </httpConfiguration>
+ </configuration>
+</server>
```
+Everything is in `<all>` on purpose: adding a `<get>` or `<put>` block would
drop
+`usePreemptive`. Where a per-method setting is unavoidable, use `params` —
those do
+merge correctly.
+
## Resources
1. [HttpClient website](https://hc.apache.org/httpcomponents-client-4.5.x/)
2. [HttpClient preference architecture and configuration
guide](https://hc.apache.org/httpclient-3.x/preference-api.html)
3. [Guide to Wagon Providers](./guide-wagon-providers.html)
-4. [Wagon Http](/wagon/wagon-providers/wagon-http/)
-
+4. [Wagon HTTP
provider](https://maven.apache.org/wagon/wagon-providers/wagon-http/)