Maven: The Complete Reference - 15.2. Settings Details |
|
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:
The 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:
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>
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>
The If a profile is active from settings, its values will override any equivalent profiles which matching identifiers in a POM or profiles.xml file. 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.
The To see which profile will activate in a certain build, use the maven-help-plugin. mvn help:active-profiles 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:
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. 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>
The structure of the 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>
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 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 as shown in Figure 15.1, “Storing Unencrypted Passwords in 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. Next, consider the process Maven uses to support encrypted passwords as shown in Figure 15.2, “Storing Encrypted Passwords in Maven Settings”. To configure encrypted passwords, create a master password by running
$ 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 as shown in 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 qualityFIRST {uMrbEOEf/VQHnc0W2X49Qab75j9LSTwiM3mg2LCrOzI=} At this point, copy the encrypted password printed from the output of
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. |