# Appendix: Settings Details

## 15.1. Quick Overview

The settings element in the _settings.xml_ file contains elements used to define values which configure Maven execution. Settings in this file are settings which apply to many projects and which should not be bundled to any specific project, or distributed to an audience. These include values such as the local repository location, alternate remote repository servers, and authentication information. There are two locations where a _settings.xml_ file may live:

- Maven Installation Directory: _$M2_HOME/conf/settings.xml_
- User-specific Settings File: _~/.m2/settings.xml_

Here is an overview of the top elements under settings:

**Overview of top-level elements in settings.xml.**

```
<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>
```

## 15.2. Settings Details

#### 15.2.1. Simple Values

Half of the top-level settings elements are simple values, representing a range of values which configure the core behavior of Maven:

**Simple top-level elements in settings.xml.**

```
<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>${user.dir}/.m2/repository</localRepository>
    <interactiveMode>true</interactiveMode>
    <usePluginRegistry>false</usePluginRegistry>
    <offline>false</offline>
    <pluginGroups>
        <pluginGroup>org.codehaus.mojo</pluginGroup>
    </pluginGroups>
    ...
</settings>
```

The simple top-level elements are:

**localRepository**  
This value is the path of this build system’s local repository. The default value is _${user.dir}/.m2/repository_.

**interactiveMode**  
`true` if Maven should attempt to interact with the user for input, `false` if not. Defaults to `true`.

**usePluginRegistry**  
`true` if Maven should use the _${user.dir}/.m2/plugin-registry.xml_ file to manage plugin versions, defaults to `false`.

**offline**  
`true` if this build system should operate in offline mode, defaults to `false`. This element is useful for build servers which cannot connect to a remote repository, either because of network setup or security reasons.

**pluginGroups**  
This element contains a list of `pluginGroup` elements, each contains a `groupId`. The list is searched when a plugin is used and the `groupId` is not provided in the command line. This list contains `org.apache.maven.plugins` by default.

#### 15.2.2. Servers

The `distributionManagement` element of the POM defines the repositories for deployment. However, certain settings such as security credentials should not be distributed along with the _pom.xml_. This type of information should exist on the build server in the _settings.xml_.

**Server configuration in settings.xml.**

```
<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">
    ...
    <servers>
        <server>
            <id>server001</id>
            <username>my_login</username>
            <password>my_password</password>
            <privateKey>${user.home}/.ssh/id_dsa</privateKey>
            <passphrase>some_passphrase</passphrase>
            <filePermissions>664</filePermissions>
            <directoryPermissions>775</directoryPermissions>
            <configuration></configuration>
        </server>
    </servers>
    ...
</settings>
```

The elements under server are:

**id**  
This is the `id` of the server (not of the user to login as) that matches the `distributionManagement` repository element’s `id`.

**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 a passphrase, if required. The passphrase and password elements may be externalized in the future, but for now they must be set plain-text in the _settings.xml_ file.

**filePermissions, directoryPermissions**  
When a repository file or directory is created on deployment, these are the permissions to use. The legal values of each is a three digit number corresponding to *nix file permissions, i.e. 664, or 775.

#### 15.2.3. Mirrors

**Mirror configuration in settings.xml.**

```
<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">
    ...
    <mirrors>
        <mirror>
            <id>planetmirror.com</id>
            <name>PlanetMirror Australia</name>
            <url>http://downloads.planetmirror.com/pub/maven2</url>
            <mirrorOf>central</mirrorOf>
        </mirror>
    </mirrors>
    ...
</settings>
```

**id, name**  
The unique identifier of this mirror. The id is used to differentiate between mirror elements.

**url**  
The base URL of this mirror. The build system will use prepend this URL to connect to a repository rather than the default server URL.

**mirrorOf**  
The id of the server that this is a mirror of. For example, to point to a mirror of the Maven central server ( [https://repo1.maven.org/maven2](https://repo1.maven.org/maven2)), set this element to central. This must not match the mirror id.

#### 15.2.4. Proxies

**Proxy configuration in settings.xml.**

```
<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">
    ...
    <proxies>
        <proxy>
            <id>myproxy</id>
            <active>true</active>
            <protocol>http</protocol>
            <host>proxy.somewhere.com</host>
            <port>8080</port>
            <username>proxyuser</username>
            <password>somepassword</password>
            <nonProxyHosts>*.google.com|ibiblio.org</nonProxyHosts>
        </proxy>
    </proxies>
    ...
</settings>
```

**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.

#### 15.2.5. Profiles

The `profile` element in the _settings.xml_ is a truncated version of the _pom.xml_ profile element. It consists of the `activation`, `repositories`, `pluginRepositories` and `properties` elements. The profile elements only include these four elements because they concern themselves with the build system as a whole (which is the role of the _settings.xml_ file), not about individual project object model settings.

If a profile is active from settings, its values will override any equivalent profiles which matching identifiers in a POM or _profiles.xml_ file.

#### 15.2.6. Activation

Activations are the key of a profile. Like the POM’s profiles, the power of a profile comes from its ability to modify some values only under certain circumstances; those circumstances are specified via an activation element.

**Defining Activation Parameters in settings.xml.**

```
<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">
    ...
    <profiles>
        <profile>
            <id>test</id>
            <activation>
                <activeByDefault>false</activeByDefault>
                <jdk>1.5</jdk>
                <os>
                    <name>Windows XP</name>
                    <family>Windows</family>
                    <arch>x86</arch>
                    <version>5.1.2600</version>
                </os>
                <property>
                    <name>mavenVersion</name>
                    <value>2.0.3</value>
                </property>
                <file>
                    <exists>${basedir}/file2.properties</exists>
                    <missing>${basedir}/file1.properties</missing>
                </file>
            </activation>
            ...
        </profile>
    </profiles>
    ...
</settings>
```

Activation occurs when all specified criteria have been met, though not all are required at once.

**jdk**  
activation has a built in, Java-centric check in the jdk element. This will activate if the test is run under a jdk version number that matches the prefix given. In the above example, 1.5.0_06 will match.

**os**  
The `os` element can define some operating system specific properties shown above.

**property**  
The profile will activate if Maven detects a property (a value which can be dereferenced within the POM by _content_area-module-3_) of the corresponding name=value pair.

**file**  
Finally, a given filename may activate the profile by the existence of a file, or if it is missing.

The `activation` element is not the only way that a profile may be activated. The _settings.xml_ file’s `activeProfile` element may contain the profile’s id. They may also be activated explicitly through the command line via a comma separated list after the P flag (e.g. `-P` test).

To see which profile will activate in a certain build, use the maven-help-plugin.

```
mvn help:active-profiles
```

#### 15.2.7. Properties

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 elements value.

**+settings.+x**  
A dot-notated (.) path in the _settings.xml_ will contain the corresponding elements value.

**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 file, the value may be used as _${someVar}_.

**Setting the _${user.install}_ property in settings.xml.**

```
<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">
    ...
    <profiles>
        <profile>
            ...
            <properties>
                <user.install>${user.dir}/our-project</user.install>
            </properties>
            ...
        </profile>
    </profiles>
    ...
</settings>
```

The property _${user.install}_ is accessible from a POM if this profile is active.

#### 15.2.8. 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.

**Repository Configuration in settings.xml.**

```
<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">
    ...
    <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>
```

**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` or `false` for whether this repository is enabled for the respective type (releases or snapshots).

**updatePolicy**  
This element specifies how often updates should attempt to occur. Maven will compare the local POMs timestamp to the remote. The choices are: `always`, `daily` (default), `interval:X` (where X is an integer in minutes) or `never`.

**checksumPolicy**  
When Maven deploys files to the repository, it also deploys corresponding checksum files. Your options are to `ignore`, `fail`, or `warn` 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 or legacy. If you are upgrading from Maven 1 to Maven 2, and you want to use the same repository which was used in your Maven 1 build, list the layout as `legacy`.

#### 15.2.9. Plugin Repositories

The structure of the `pluginRepositories` element block is similar to the `repositories` element. The `pluginRepository` elements each specify a remote location of where Maven can find plugins artifacts.

**Plugin Repositories in settings.xml.**

```
<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">
    ...
    <profiles>
        <profile>
            ...
            <repositories>
                ...
            </repositories>
            <pluginRepositories>
                <pluginRepository>
                    <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>
                </pluginRepository>
            </pluginRepositories>
            ...
        </profile>
    </profiles>
    ...
</settings>
```

#### 15.2.10. Active Profiles

**Setting active profiles in settings.xml.**

```
<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">
    ...
    <activeProfiles>
        <activeProfile>env-test</activeProfile>
    </activeProfiles>
</settings>
```

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 it will be active. If no such profile is found then execution will continue as normal.

#### 15.2.11. Encrypting Passwords in Maven Settings

Once you start to use Maven to deploy software to remote repositories and to interact with source control systems directly, you will start to collect a number of passwords in your Maven Settings and without a mechanism for encrypting these passwords, a developer’s _~/.m2/settings.xml_ will quickly become a security risk as it will contain plain-text passwords to source control and repository managers. Maven 2.1 introduced a facility to encrypt passwords in a user’s Maven Settings (_~/.m2/settings.xml_). To do this, you must first create a master password and store this master password in a _security-settings.xml_ file in _~/.m2/settings-security.xml_. You can then use this master password to encrypt passwords stored in Maven Settings (_~/.m2/settings.xml_).

To illustrate this feature, consider the process Maven uses to retrieve an unencrypted server password for a user’s Maven Settings. A user will reference a named server using an identifier in a project’s POM, Maven looks for a matching server in Maven Settings. When it finds a matching server element in Maven Settings, Maven will then use the password associated with that server element and send this password along to the server. The password is stored as plain-text in _~/.m2/settings.xml_ and it is readily available to anyone who has read access to this file.

_Figure 15.1. Storing Unencrypted Passwords in Maven Settings_

Next, consider the process Maven uses to support encrypted passwords.

To configure encrypted passwords, create a master password by running `mvn -emp` or `mvn --encrypt-master-password` followed by your master password.

```
$ mvn -emp mypassword
{rsB56BJcqoEHZqEZ0R1VR4TIspmODx1Ln8/PVvsgaGw=}
```

Maven prints out an encrypted copy of the password to standard out. Copy this encrypted password and paste it into a _~/.m2/settings-security.xml_ file.

**settings-security.xml with Master Password.**

```
<settingsSecurity>
    <master>{rsB56BJcqoEHZqEZ0R1VR4TIspmODx1Ln8/PVvsgaGw=}</master>
</settingsSecurity>
```

After you have created a master password, you can then encrypt passwords for use in your Maven Settings. To encrypt a password with the master password, run `mvn -ep` or `mvn --encrypt-password`. Assume that you have a repository manager and you need to send a username of "deployment" and a password of "qualityFIRST". To encrypt this particular password, you would run the following command:

```
$ mvn -ep qualityFIRST
{uMrbEOEf/VQHnc0W2X49Qab75j9LSTwiM3mg2LCrOzI=}
```

At this point, copy the encrypted password printed from the output of `mvn -ep` and paste it into your Maven Settings.

**Storing an Encrypted Password in Maven Settings (~/.m2/settings.xml).**

```
<settings>
    <servers>
        <server>
            <id>nexus</id>
            <username>deployment</username>
            <password>{uMrbEOEf/VQHnc0W2X49Qab75j9LSTwiM3mg2LCrOzI=}</password>
        </server>
    </servers>
    ...
</settings>
```

When you run a Maven build that needs to interact with the repository manager, Maven will retrieve the Master password from the _~/.m2/settings-security.xml_ file and use this master password to decrypt the password stored in your _~/.m2/settings.xml_ file. Maven will then send the decrypted password to the server.

What does this buy you? It allows you to avoid storing your passwords in _~/.m2/settings.xml_ as plain-text passwords providing you with the peace of mind that your critical passwords are not being stored, unprotected in a Maven Settings file. Note that this feature does not provide for encryption of the password while it is being sent to the remote server. An enterprising attacker could still capture the password using a network analysis tool.

For an extra level of security, you can encourage your developers to store the encrypted master password on a removable storage device like a USB hard drive. Using this method, a developer would plug a removable drive into a workstation when she wanted to perform a deployment or interact with a remote server. To support this, your _~/.m2/settings-security.xml_ file would contain a reference to the location of the _settings-security.xml_ file using the relocation element.

**Configuring Relocation of the Master Password.**

```
<settingsSecurity>
    <relocation>/Volumes/usb-key/settings-security.xml</relocation>
</settingsSecurity>
```

The developer would then store the _settings-security.xml_ file at _/Volumes/usb-key/settings-security.xml_ which would only be available if the developer were sitting at the workstation.