Maven settings.xml: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
No edit summary
 
(38 intermediate revisions by the same user not shown)
Line 9: Line 9:
=Overview=
=Overview=


<tt>settings.xml</tt> is the place to store configuration that should not be bundled with a specific project. This includes various "personal" configuration values, the location of the local repository, alternate remote [[Maven Repositories|repository servers]] and authentication information. Usually, this information is bundled in specific [[Maven_Profile#In_Settings|profiles]].
<tt>settings.xml</tt> is the place to store configuration that should not be bundled with a specific project, but it concerns the build system as a whole. This includes various "personal" configuration values, the location of the local repository, alternate remote [[Maven Repositories|repository servers]] and authentication information. Usually, this information is bundled in specific [[Maven_Profile#In_Settings|profiles]].


There are two types of settings.xml files:
There are two types of settings.xml files:


* ''global'', placed in ${MAVEN_HOME}/conf/settings.xml.
* ''global'', placed in ${MAVEN_HOME}/conf/settings.xml.
* ''user settings'', placed in ${HOME}/.m2/settings.xml.
* ''user settings'', placed in ${HOME}/.m2/settings.xml. An alternate user settings file location can be specified with [[Maven_Command_Line_Options#-s.2C_--settings|-s|--settings]].


If both exist, the contents are merged and the user-specific values take precedence.
If both exist, the contents are merged and the user-specific values take precedence.
[[Maven Standard System Properties#Overview|System properties]] and [[Maven and Environment Variables#Overview|environment variables]] can be both used in settings.xml.
Note that properties defined in profiles within settings.xml cannot be dereferenced.
<syntaxhighlight lang='xml'>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.1.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0
  http://maven.apache.org/xsd/settings-1.1.0.xsd">
    <servers>
        <server>
            <id>...</id>
            ...
        </server>
        ...
    </servers>
    <profiles>
        <profile>
            <id>Blue Profile</id>
            ...
        </profile>
        ...
    </profiles>
    <activeProfiles>
        <activeProfile>Blue Profile</activeProfile>
    </activeProfiles>
</settings>
</syntaxhighlight>
=Elements=
==<localRepository>==
The location of the [[Maven Repositories#local_repository|local repository]].
<pre>
<localRepository>${user.home}/.m2/repository</localRepository>
</pre>
==<interactiveMode>==
<pre>
<interactiveMode>true</interactiveMode>
</pre>
See [[Maven_Concepts#Interactive_Mode|Maven interactive mode]].
==<offline>==
<pre>
<offline>false</offline>
</pre>
==<servers>==
{{External|https://maven.apache.org/settings.html#Servers}}
Declares a [[Maven_Concepts#Servers|server]].
<pre>
<servers>
    <server>
        <id>server001</id>
        <username>my_login</username>
        <password>my_password|{encrypted_password=}</password>
        <privateKey>${user.home}/.ssh/id_dsa</privateKey>
        <passphrase>some_passphrase</passphrase>
        <filePermissions>664</filePermissions>
        <directoryPermissions>775</directoryPermissions>
        <configuration>
          ...
        </configuration>
    </server>
</servers>
</pre>
===Advanced Configuration===
====Authenticating by Writing Headers====
Attempts to authenticate against a HTTPS repository by specifying <username>/<password> in the <server> configuration did fail in Maven 3.5.2 because even if the configuration seemed correct, it did not result in Maven sending the corresponding "Authorization: " header on the wire, for causes yet unknown.
The workaround was to specify the "Authorization: " header explicitly, as follows:
  <servers>
    <server>
      <id>a-https-repository</id>
        <configuration>
          '''<httpHeaders>'''
            <property>
              <name>'''Authorization'''</name>
                <!-- Base64-encoded "username:password" -->
                <value>Basic b3ZpZGl1Om42XzRHUnk3NENT</value>
              </property>
            </httpHeaders>
        </configuration>
    </server>
  </servers>
The content of  the "Authorization: " header can be obtained by executing:
curl -v -u <''username''>:<''password''> https://....
Also see: {{Internal|Maven_Repositories#Password-Protected_Repositories|Password-Protected Repositories}}
==<profiles>==
See:
{{Internal|Maven Profile|Maven Profile}}
==<activeProfiles>==
See:
{{Internal|Maven_Profile#In_Settings|Maven Profile}}
==<usePluginRegistry>==
See [[Maven_Concepts#Plugin_Registry|plugin registry]].
==<pluginGroups>==
==<mirrors>==
Configures [[Maven_Concepts#Mirror|Maven repository mirrors]].
Setting a mirror is useful when an [[OpenShift Nexus]] instance is available and it can be used to speed up the build. See:{{Internal|OpenShift_Nexus#Configure_Maven_from_Maven_Build_Pods_to_Use_Nexus_as_Mirror|Configure Maven to Use Nexus as Mirror}}
==<proxies>==
See [[Maven_Concepts#Proxy|proxy]].

Latest revision as of 01:12, 22 January 2018

External

Internal

Overview

settings.xml is the place to store configuration that should not be bundled with a specific project, but it concerns the build system as a whole. This includes various "personal" configuration values, the location of the local repository, alternate remote repository servers and authentication information. Usually, this information is bundled in specific profiles.

There are two types of settings.xml files:

  • global, placed in ${MAVEN_HOME}/conf/settings.xml.
  • user settings, placed in ${HOME}/.m2/settings.xml. An alternate user settings file location can be specified with -s|--settings.

If both exist, the contents are merged and the user-specific values take precedence.

System properties and environment variables can be both used in settings.xml.

Note that properties defined in profiles within settings.xml cannot be dereferenced.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.1.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0
		  http://maven.apache.org/xsd/settings-1.1.0.xsd">

    <servers>
        <server>
            <id>...</id>
            ...
        </server>
        ...
    </servers>

    <profiles>
        <profile>
            <id>Blue Profile</id>
            ...
        </profile>
        ...
    </profiles>

    <activeProfiles>
        <activeProfile>Blue Profile</activeProfile>
    </activeProfiles>

</settings>

Elements

<localRepository>

The location of the local repository.

<localRepository>${user.home}/.m2/repository</localRepository>

<interactiveMode>

<interactiveMode>true</interactiveMode>

See Maven interactive mode.

<offline>

<offline>false</offline>

<servers>

https://maven.apache.org/settings.html#Servers

Declares a server.

<servers>
    <server>
        <id>server001</id>
        <username>my_login</username>
        <password>my_password|{encrypted_password=}</password>
        <privateKey>${user.home}/.ssh/id_dsa</privateKey> 
        <passphrase>some_passphrase</passphrase>
        <filePermissions>664</filePermissions>
        <directoryPermissions>775</directoryPermissions>
        <configuration>
           ...
        </configuration>
    </server>
</servers>

Advanced Configuration

Authenticating by Writing Headers

Attempts to authenticate against a HTTPS repository by specifying <username>/<password> in the <server> configuration did fail in Maven 3.5.2 because even if the configuration seemed correct, it did not result in Maven sending the corresponding "Authorization: " header on the wire, for causes yet unknown.

The workaround was to specify the "Authorization: " header explicitly, as follows:

 <servers>
   <server>
     <id>a-https-repository</id>
       <configuration>
         <httpHeaders>
           <property>
             <name>Authorization</name>
               <value>Basic b3ZpZGl1Om42XzRHUnk3NENT</value>
             </property>
           </httpHeaders>
        </configuration>
    </server>
 </servers>

The content of the "Authorization: " header can be obtained by executing:

curl -v -u <username>:<password> https://....

Also see:

Password-Protected Repositories

<profiles>

See:

Maven Profile

<activeProfiles>

See:

Maven Profile

<usePluginRegistry>

See plugin registry.

<pluginGroups>

<mirrors>

Configures Maven repository mirrors.

Setting a mirror is useful when an OpenShift Nexus instance is available and it can be used to speed up the build. See:

Configure Maven to Use Nexus as Mirror

<proxies>

See proxy.