Maven settings.xml File Examples

What is the Maven settings XML file?

A Maven settings.xml file defines values that configure Maven execution in various ways. Most commonly, it is used to define a local repository location, alternate remote repository servers, and authentication information for private repositories.

Maven settings.xml file contains configurations that are not specific to a project but are global in nature.

The same xml file can be used for multiple java projects to download maven dependencies from maven and other repositiries.

Configuring Maven

Project - most static configuration occurs in pom.xml
Installation - This is configuration added once for a Maven installation
User - this is configuration specific to a particular user
The separation is quite clear - the project defines the information that applies to the project, no matter who is building it, while the others both define settings for the current environment.

The installation and user configuration cannot be used to add shared project information.

For this, you should have your projects inherit from a company-wide parent pom.xml.

Location of Maven Settings File Maven can use 2 setting file location at the same time.

You can specify your user configuration in ${user.home}/.m2/settings.xml. it is user home derectory location.

Maven installation directory: $M2_HOME/conf/settings.xml

This section will show how to make some common configurations. Note that the file is not required - defaults will be used if it is not found.

Configuring your Local Repository

The location of your local repository can be changed in your user configuration. The default value is

${user.home}/.m2/repository/.

<settings>
  ...
  <localRepository> /path/to/local/repo/</localRepository>
  ...
</settings>
  

Maven can have two settings files working at a time

The Maven installation directory: $M2_HOME/conf/settings.xml [global settings] The user’s home directory: ${user.home}/.m2/settings.xml [user settings] Both files are optional. If both files are present, the values in the user home settings file overrides the values from global settings file

A quick view for setting.xml is

 <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
                          http://maven.apache.org/xsd/settings-1.0.0.xsd" >
       <localRepository/ >
       <interactiveMode/ >
       <usePluginRegistry/ >
       <offline/ >
       <pluginGroups/ >
       <servers/ >
       <mirrors/ >
       <proxies/ >
       <profiles/ >
       <activeProfiles/ >
 </settings >

default settings.xml file

The following is the default settings.xml file

 <?xml version="1.0" encoding="UTF-8"? >

 

 <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 http://maven.apache.org/xsd/settings-1.0.0.xsd" >
   <!-- localRepository
   | The path to the local repository maven will use to store artifacts.
   |
   | Default: ${user.home}/.m2/repository
   <localRepository >/path/to/local/repo </localRepository >
  -- >

   <!-- interactiveMode
   | This will determine whether maven prompts you when it needs input. If set to false,
   | maven will use a sensible default value, perhaps based on some other setting, for
   | the parameter in question.
   |
   | Default: true
   <interactiveMode >true </interactiveMode >
  -- >

   <!-- offline
   | Determines whether maven should attempt to connect to the network when executing a build.
   | This will have an effect on artifact downloads, artifact deployment, and others.
   |
   | Default: false
   <offline >false </offline >
  -- >

   <!-- pluginGroups
   | This is a list of additional group identifiers that will be searched when resolving plugins by their prefix, i.e.
   | when invoking a command line like "mvn prefix:goal". Maven will automatically add the group identifiers
   | "org.apache.maven.plugins" and "org.codehaus.mojo" if these are not already contained in the list.
   |-- >
   <pluginGroups >
     <!-- pluginGroup
     | Specifies a further group identifier to use for plugin lookup.
     <pluginGroup >com.your.plugins </pluginGroup >
    -- >
   </pluginGroups >

   <!-- proxies
   | This is a list of proxies which can be used on this machine to connect to the network.
   | Unless otherwise specified (by system property or command-line switch), the first proxy
   | specification in this list marked as active will be used.
   |-- >
   <proxies >
     <!-- proxy
     | Specification for one proxy, to be used in connecting to the network.
     |
     <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 >

   <!-- servers
   | This is a list of authentication profiles, keyed by the server-id used within the system.
   | Authentication profiles can be used whenever maven must make a connection to a remote server.
   |-- >
   <servers >
     <!-- server
     | Specifies the authentication information to use when connecting to a particular server, identified by
     | a unique name within the system (referred to by the 'id' attribute below).
     |
     | NOTE: You should either specify username/password OR privateKey/passphrase, since these pairings are
     |       used together.
     |
     <server >
       <id >deploymentRepo </id >
       <username >repouser </username >
       <password >repopwd </password >
     </server >
    -- >

     <!-- Another sample, using keys to authenticate.
     <server >
       <id >siteServer </id >
       <privateKey >/path/to/private/key </privateKey >
       <passphrase >optional; leave empty if not used. </passphrase >
     </server >
    -- >
   </servers >

   <!-- mirrors
   | This is a list of mirrors to be used in downloading artifacts from remote repositories.
   |
   | It works like this: a POM may declare a repository to use in resolving certain artifacts.
   | However, this repository may have problems with heavy traffic at times, so people have mirrored
   | it to several places.
   |
   | That repository definition will have a unique id, so we can create a mirror reference for that
   | repository, to be used as an alternate download site. The mirror site will be the preferred
   | server for that repository.
   |-- >
   <mirrors >
     <!-- mirror
     | Specifies a repository mirror site to use instead of a given repository. The repository that
     | this mirror serves has an ID that matches the mirrorOf element of this mirror. IDs are used
     | for inheritance and direct lookup purposes, and must be unique across the set of 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 >

   <!-- profiles
   | This is a list of profiles which can be activated in a variety of ways, and which can modify
   | the build process. Profiles provided in the settings.xml are intended to provide local machine-
   | specific paths and repository locations which allow the build to work in the local environment.
   |
   | For example, if you have an integration testing plugin - like cactus - that needs to know where
   | your Tomcat instance is installed, you can provide a variable here such that the variable is
   | dereferenced during the build process to configure the cactus plugin.
   |
   | As noted above, profiles can be activated in a variety of ways. One way - the activeProfiles
   | section of this document (settings.xml) - will be discussed later. Another way essentially
   | relies on the detection of a system property, either matching a particular value for the property,
   | or merely testing its existence. Profiles can also be activated by JDK version prefix, where a
   | value of '1.4' might activate a profile when the build is executed on a JDK version of '1.4.2_07'.
   | Finally, the list of active profiles can be specified directly from the command line.
   |
   | NOTE: For profiles defined in the settings.xml, you are restricted to specifying only artifact
   |       repositories, plugin repositories, and free-form properties to be used as configuration
   |       variables for plugins in the POM.
   |
   |-- >
   <profiles >
     <profile >
       <id >jdk-1.4 </id >

       <activation >
         <jdk >1.4 </jdk >
       </activation >

       <repositories >
         <repository >
           <id >jdk14 </id >
           <name >Repository for JDK 1.4 builds </name >
           <url >http://www.myhost.com/maven/jdk14 </url >
           <layout >default </layout >
           <snapshotPolicy >always </snapshotPolicy >
         </repository >
       </repositories >
     </profile >
    -- >

     <!--
     | Here is another profile, activated by the system property 'target-env' with a value of 'dev',
     | which provides a specific path to the Tomcat instance. To use this, your plugin configuration
     | might hypothetically look like:
     |
     | ...
     |  <plugin >
     |    <groupId >org.myco.myplugins </groupId >
     |    <artifactId >myplugin </artifactId >
     |
     |    <configuration >
     |      <tomcatLocation >${tomcatPath} </tomcatLocation >
     |    </configuration >
     |  </plugin >
     | ...
     |
     | NOTE: If you just wanted to inject this configuration whenever someone set 'target-env' to
     |       anything, you could just leave off the  <value/ > inside the activation-property.
     |
     <profile >
       <id >env-dev </id >

       <activation >
         <property >
           <name >target-env </name >
           <value >dev </value >
         </property >
       </activation >

       <properties >
         <tomcatPath >/path/to/tomcat/instance </tomcatPath >
       </properties >
     </profile >
    -- >
   </profiles >

   <!-- activeProfiles
   | List of profiles that are active for all builds.
   |
   <activeProfiles >
     <activeProfile >alwaysActiveProfile </activeProfile >
     <activeProfile >anotherAlwaysActiveProfile </activeProfile >
   </activeProfiles >
  -- >
 </settings >

the description of each property is given below.

Element Type Description

settings Root element of the user configuration file.

localRepository

The local repository. Default value is: ${user.home}/.m2/repository

interactiveMode boolean 

Whether Maven should attempt to interact with the user for input. The default value is: true.

usePluginRegistry boolean

 Whether Maven should use the plugin-registry.xml file to manage plugin versions. The default value is: false.

offline boolean

Indicate whether the maven should operate in offline mode full-time. The default value is: false.

proxies/proxy* List<Proxy> (Many) Configuration for different proxy profiles. Multiple proxy profiles might come in handy for anyone working from a notebook or other mobile platform, to enable easy switching of entire proxy configurations by simply specifying the profile id, again either from the command line or from the defaults section below. servers/server* List<Server> (Many) Configuration of server-specific settings, mainly authentication method. This allows configuration of authentication on a per-server basis. mirrors/mirror* List<Mirror> (Many) Configuration of download mirrors for repositories. profiles/profile* List<Profile> (Many) Configuration of build profiles for adjusting the build according to environmental parameters.

activeProfiles/activeProfile* List<String> (Many) List of manually-activated build profiles, specified in the order in which they should be applied. pluginGroups/pluginGroup* List<String> (Many) List of groupIds to search for a plugin when that plugin groupId is not explicitly provided.

proxy

 The element contains information required to proxy settings.

active boolean

Whether this proxy configuration is the active one. The default value is: true.

protocol String

The proxy protocol. The default value is http.

username String The proxy user. password String The proxy password.
port int The proxy port.
The default value is 8080.
host String The proxy host.
nonProxyHosts String The list of non-proxied hosts (delimited by |).
id String No description.
The default value is the default.

server The &ltserver&gt element contains information required for server settings. username String The username used to authenticate.
password String The password used in conjunction with the username to authenticate.
privateKey String The private key location used to authenticate.
passphrase String The passphrase used in conjunction with the private key to authenticate.
filePermissions String The permissions for files when they are created.
directoryPermissions String The permissions for directories when they are created.
configuration JUDGMENT Extra configuration for the transport layer.
id String No description.
The default value is the default.

mirror A download mirror for a given repository.

mirrorOf String

 The server ID of the repository being mirrored, e.g., "central". This MUST NOT match the mirror id. name String The optional name that describes the mirror.

url String

The URL of the mirror repository. url String The URL of the mirror repository. layout String The layout of the mirror repository. Since Maven 3.

 Default value is default.

mirrorOfLayouts String The layouts of repositories being mirrored. This value can be used to restrict the usage of the mirror to repositories with a matching layout (apart from a matching id). Since Maven 3. The default value is default,legacy.
id String No description. The default value is default.
profile Modifications to the build process which is keyed on some sort of environmental parameter.

activation Activation The conditional logic which will automatically trigger the inclusion of this profile. properties/key=value* Properties (Many) Extended configuration specific to this profile goes here. Contents take the form of <property.name>property.value</property.name> repositories/repository* List<Repository> (Many) The lists of the remote repositories. pluginRepositories/pluginRepository* List<Repository> (Many) The lists of the remote repositories for discovering plugins. id String No description. Default value is: default. activation

The conditions within the build runtime environment which will trigger the automatic inclusion of the parent build profile.

activeByDefault boolean Flag specifying whether this profile is active as a default. Default value is: false.

jdk String Specifies that this profile will be activated when a matching JDK is detected.

the ActivationOS Specifies that this profile will be activated when matching OS attributes are detected. property ActivationProperty Specifies that this profile will be activated when this System property is specified. file ActivationFile Specifies that this profile will be activated based on the existence of a file.
the This is an activator that will detect an operating system's attributes in order to activate its profile.
name String The name of the OS to be used to activate a profile.
family String The general family of the OS to be used to activate a profile (e.g. 'windows')
arch String The architecture of the OS to be used to activate a profile.
version String The version of the OS to be used to activate a profile.
property This is the property specification used to activate a profile. If the value field is empty, then the existence of the named property will activate the profile, otherwise it does a case-sensitive match against the property value as well.

name String The name of the property to be used to activate a profile.
value String The value of the property to be used to activate a profile.
file This is the file specification used to activate a profile.
The missing value will be the location of a file that needs to exist, and if it doesn't the profile must run. On the other hand, exists will test for the existence of the file, and if it is there will run the profile.

missing String The name of the file that should be missing to activate a profile. exists String The name of the file that should exist to activate a profile.
repository The repository contains the information needed for establishing connections with the remote repository

releases RepositoryPolicy
How to handle downloading of releases from this repository
snapshots RepositoryPolicy

 How to handle downloading of snapshots from this repository
id String A unique identifier for a repository.
name String Human readable name of the repository.
url String The URL of the repository.
layout String The type of layout this repository uses for locating and storing artifacts - can be "legacy" or "default". The default value is default.

releases

Download policy

enabled boolean Whether to use this repository for downloading this type of artifact. The default value is: true.

updatePolicy String The frequency for downloading updates - can be "always", "daily" (default), "interval:XXX" (in minutes) or "never" (only if it doesn't exist locally).

checksumPolicy String What to do when verification of an artifact checksum fails - warn, fail, etc. Valid values are "fail" or "warn".

pluginRepository

Repository contains the information needed for establishing connections with remote repository

releases RepositoryPolicy How to handle downloading of releases from this repository

snapshots RepositoryPolicy How to handle downloading of snapshots from this repository

id String A unique identifier for a repository.

name String Human-readable name of the repository.

url String

The URL of the repository.

layout String The type of layout this repository uses for locating and storing artifacts - can be "legacy" or "default". The default value is default.

In this article, we have seen Maven settings.xml File with example and descriptions..