Maven – Settings Reference
Maven – settings.xml file usage
In maven, general settings are declared using settings.xml
file which might live in two locations,
- In the Maven install location:
${maven.home}/conf/settings.xml
- In User’s home directory:
${user.home}/.m2/settings.xml
The former Mavensettings.xml
are also called global settings, the latter settings.xml
are referred to as user settings. If both files exists, their contents gets merged, with the user-specific settings.xml
being dominant.
Tip: If you need to create user-specific settings from scratch, it’s easiest to copy the global settings from your Maven installation to your ${user.home}/.m2
directory. Maven’s default settings.xml
is a template with comments and examples so you can quickly tweak it to match your needs.
Here is an overview of the elements under settings
:
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> <localRepository/> <interactiveMode/> <offline/> <pluginGroups/> <servers/> <mirrors/> <proxies/> <profiles/> <activeProfiles/> </settings>
Simple Settings details
- localRepository: This value is the path of local repository in our machine. The default value is
${user.home}/.m2/repository
. - interactiveMode: Defaults to
true
if Maven should attempt to interact with the user for input,false
if not. - offline:
true
if this build system should operate in offline mode, defaults tofalse
. This element is useful for build servers which cannot connect to a remote repository, either because of network setup or security reasons.
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> <localRepository>${user.home}/.m2/repository</localRepository> <interactiveMode>true</interactiveMode> <offline>false</offline> ... </settings>
Servers configuration
The repositories for download and deployment are defined by the repositories
and distributionManagement
elements of the POM. However, certain settings such as username
and password
should not be declared in pom.xml
. This type of information should exist on the build server in the settings.xml
.
Following parameters should be used while using server level settings in Maven,
- id: This is the ID of the server that Maven tries to connect to. This ID is unique for our understanding.
- username, password: These elements appear as a pair denoting the login and password required to authenticate to this server.
- privateKey, passphrase: Like the previous two elements, this pair specifies a path to a private key (default is
${user.home}/.ssh/id_dsa
) and apassphrase
, if required.
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> ... <servers> <server> <id>deploymentRepo</id> <username>repouser</username> <password>repopwd</password> </server> <server> <id>siteServer</id> <privateKey>/path/to/private/key</privateKey> <passphrase>optional; leave empty if not used.</passphrase> </server> </servers> ... </settings>
Mirrors configuration
Following parameters should be used while using mirror level settings in Maven,
- id, name: The unique identifier and user-friendly name of this mirror. The
id
is used to differentiate betweenmirror
elements and to pick the corresponding credentials from the<servers>
section when connecting to the mirror. - url: The base URL of this mirror. The build system will use this URL to connect to a repository rather than the original repository URL.
- mirrorOf: The
id
of the repository that this is a mirror of. For example, to point to a mirror of the Mavencentral
repository (https://repo.maven.apache.org/maven2/
), set this element tocentral
. This must not match the mirrorid
.
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> ... <mirrors> <mirror> <id>mirrorId</id> <mirrorOf>repositoryId</mirrorOf> <name>Human Readable Name for this Mirror.</name> <url>http://my.repository.com/repo/path</url> </mirror> </mirrors> ... </settings>
Proxies configuration
- id: The unique identifier for this proxy. This is used to differentiate between
proxy
elements. - active:
true
if this proxy is active. This is useful for declaring a set of proxies, but only one may be active at a time. - protocol, host, port: The
protocol://host:port
of the proxy, separated into discrete elements. - username, password: These elements appear as a pair denoting the login and password required to authenticate to this proxy server.
- nonProxyHosts: This is a list of hosts which should not be proxied. The delimiter of the list is the expected type of the proxy server; the example above is pipe delimited – comma delimited is also common.
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> ... <proxies> <proxy> <id>optional</id> <active>true</active> <protocol>http</protocol> <username>proxyuser</username> <password>proxypass</password> <host>proxy.host.net</host> <port>80</port> <nonProxyHosts>local.net|some.host.com</nonProxyHosts> </proxy> </proxies> ... </settings>
Properties configuration
Maven properties are value placeholder, like properties in Ant. Their values are accessible anywhere within a POM by using the notation ${X}
, where X
is the property. They come in five different styles, all accessible from the settings.xml
file:
env.X
: Prefixing a variable with “env.” will return the shell’s environment variable. For example,${env.PATH}
contains the $path environment variable (%PATH%
in Windows).project.x
: A dot (.) notated path in the POM will contain the corresponding element’s value. For example:<project><version>1.0</version></project>
is accessible via${project.version}
.settings.x
: A dot (.) notated path in thesettings.xml
will contain the corresponding element’s value. For example:<settings><offline>false</offline></settings>
is accessible via${settings.offline}
.- Java System Properties: All properties accessible via
java.lang.System.getProperties()
are available as POM properties, such as${java.home}
. x
: Set within a <properties /> element or an external files, the value may be used as${someVar}
.
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> ... <profiles> <profile> ... <properties> <user.install>${user.home}/our-project</user.install> </properties> ... </profile> </profiles> ... </settings>
Repositories
Repositories are remote collections of projects from which Maven uses to populate the local repository of the build system. It is from this local repository that Maven calls it plugins and dependencies. Different remote repositories may contain different projects, and under the active profile they may be searched for a matching release or snapshot artifact.
- releases, snapshots: These are the policies for each type of artifact, Release or snapshot. With these two sets, a POM has the power to alter the policies for each type independent of the other within a single repository. For example, one may decide to enable only snapshot downloads, possibly for development purposes.
- enabled:
true
orfalse
for whether this repository is enabled for the respective type (releases
orsnapshots
). - updatePolicy: This element specifies how often updates should attempt to occur. Maven will compare the local POM’s timestamp (stored in a repository’s maven-metadata file) to the remote. The choices are:
always
,daily
(default),interval:X
(where X is an integer in minutes) ornever
. - checksumPolicy: When Maven deploys files to the repository, it also deploys corresponding checksum files. Your options are to
ignore
,fail
, orwarn
on missing or incorrect checksums. - layout: In the above description of repositories, it was mentioned that they all follow a common layout. This is mostly correct. Maven 2 has a default layout for its repositories; however, Maven 1.x had a different layout. Use this element to specify which if it is
default
orlegacy
.
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> ... <profiles> <profile> ... <repositories> <repository> <id>codehausSnapshots</id> <name>Codehaus Snapshots</name> <releases> <enabled>false</enabled> <updatePolicy>always</updatePolicy> <checksumPolicy>warn</checksumPolicy> </releases> <snapshots> <enabled>true</enabled> <updatePolicy>never</updatePolicy> <checksumPolicy>fail</checksumPolicy> </snapshots> <url>http://snapshots.maven.codehaus.org/maven2</url> <layout>default</layout> </repository> </repositories> <pluginRepositories> ... </pluginRepositories> ... </profile> </profiles> ... </settings>
Active Profiles
The final piece of the settings.xml
puzzle is the activeProfiles
element. This contains a set of activeProfile
elements, which each have a value of a profile
id
. Any profile
id
defined as an activeProfile
will be active, regardless of any environment settings. If no matching profile is found nothing will happen. For example, if env-test
is an activeProfile
, a profile in a pom.xml
(or profile.xml
with a corresponding id
will be active. If no such profile is found then execution will continue as normal.
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> ... <activeProfiles> <activeProfile>env-test</activeProfile> </activeProfiles> </settings>
Conclusion
We had overview of Maven settings.xml file usage and its top elements configuration details.