Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

file 395 lines (318 sloc) 14.469 kb

Managing Maven Settings

Introduction

When you move an organization to a repository manager such as Nexus, one of the constant challenges is keeping everyone’s Maven Settings synchronized to ensure the Nexus server is used and any further configuration in the settings file is consistent. In additions different users or use cases require different settings files. You can find out more about the Maven settings file in [config]. Nexus Professional allows you to define templates for Maven Settings stored on the server and provide them to users via the user interface or automated download.

If a Nexus administrator makes a change which requires every developer to modify his or her ~/.m2/settings.xml file, this feature can be used to manage the distribution of Maven Settings changes to the entire organization. Once you have defined a Maven Settings template in Nexus Professional, developers can then use the Nexus M2Settings Maven Plugin to retrieve the new Maven settings file directly from Nexus Professional.

Manage Maven Settings Templates

To manage Maven Settings templates, click on Maven Settings in the Enterprise section of the Nexus menu on the left side of the Nexus UI. This will load the panel shown in The Maven Settings Panel.

maven settings template
Figure 1. The Maven Settings Panel

The Maven Settings panel allows you to add, delete, and edit Maven Settings templates. The default template has an id of "default" and can not be changed. It contains the recommended settings for a standard Nexus installation. To create a new Maven Settings template, click on the Add… button and select Settings Template. Once the new template is created, assign a name to the template in the Template ID text input and click the Save button.

To edit a template, click on a template that has a User Managed value of true in the list and edit the template in the tab below the list. Once you are finished editing the template, click Save to save the template. When editing the template you can insert some property references that will be replaced on the server with their values at request time:

baseurl

the base URL of the Nexus installation

userId

the user id of the user that is generating a Maven Settings file from this template

Server side interpolation takes effect even when the download of the settings template is done with tools like curl. These properties can be referenced in the settings file using the the syntax ${property}:

<settings>
  <mirrors>
    <mirror>
      <id>nexus</id>
      <mirrorOf>*</mirrorOf>
      <url>${baseurl}/content/groups/public</url>
    </mirror>
...

To preview a Maven Settings template, click on the Template URL in the list. Clicking on this URL loads a dialog window which contains the Maven Settings file generated from this template. This rendered view of the Maven Settings template has all variable references replaced using the current context of the user. This is the result of running the property replacement on the Nexus server.

The Nexus M2Settings Maven Plugin supports the more powerful and feature rich, client side replacement of properties using a $[property] syntax.

Client side properties supported by the Nexus M2Settings Maven Plugin are

baseurl

the base URL of the Nexus installation.

userId or username

the username of the user that is requesting a Maven Settings file from this template.

password

the password of the user

userToken

the formatted user token composed of name code, : and pass code.

userToken.nameCode

the name code part of the user token

userToken.passCode

the pass code part of the user token

userToken.encrypted

the encrypted, formatted user token

userToken.nameCode.encrypted

the encrypted name code part of the user token

userToken.passCode.encrypted

the encrypted pass code part of the user token

Client side interpolation allows you to fully populate a <server> section with the required properties either with the plain text username and password,

<server>
  <id>nexus</id>
  <username>$[username]</username>
  <password>$[password]</password>
</server>

the usertoken equivalent

<server>
  <id>nexus</id>
  <!-- User-token: $[userToken] -->
  <username>$[userToken.nameCode]</username>
  <password>$[userToken.passCode]</password>
</server>

or with Maven master-password encryption with the master keyword in settings-security.xml:

<server>
  <id>nexus-client-side-interp-encrypted</id>
  <!-- User-token: $[userToken.encrypted] -->
  <username>$[userToken.nameCode.encrypted]</username>
  <password>$[userToken.passCode.encrypted]</password>
</server>

The usage of the .encrypted keys results in values using the encrypted value syntax based on the master keyword similar to

<server>
  <id>nexus-client-side-interp-encrypted</id>
  <!-- User-token: {2Sn+...} -->
  <username>{3HQg...}</username>
  <password>{fsx2f...}</password>
</server>
Warning
userToken.* properties are only expanded to values if the User Token feature as documented in [config-sect-usertoken] is enabled and configured.

Nexus M2Settings Maven Plugin

Once you have defined a set of Maven templates, you can use the Nexus M2Settings Maven Plugin to distribute changes to the settings file to the entire organization.

Running the Nexus M2Settings Maven Plugin

To invoke a goal of the Nexus M2Settings Maven Plugin, you will initially have to use a fully qualified groupId and artifactId in addition to the goal. An example invocation of the download goal is:

mvn org.sonatype.plugins:nexus-m2settings-maven-plugin:download

In order to be able to use an invocation with the simple plugin prefix like this

mvn nexus-m2settings:download

you have to have the appropriate plugin group org.sonatype.plugins configured in your Maven Settings file:

<settings>
  ...
  <pluginGroups>
    <pluginGroup>org.sonatype.plugins</pluginGroup>
  </pluginGroups>
  ...

An initial invocation of the download goal will update your settings file, with a template from Nexus Professional. The default template in Nexus Professional adds the org.sonatype.plugins group to the pluginGroups, so you will not have to do this manually. It is essential that you make sure that any new, custom templates also includes this plugin group definition. Otherwise, there is a chance that a developer could update his or her Maven Settings and lose the ability to use the Nexus Maven plugin with the short identifier.

Tip
This practice of adding pluginGroups to the settings file is useful for your own Maven plugins or other plugins that do not use the default values of org.apache.maven.plugins or org.codehaus.mojo as well, since it allows the short prefix of a plugin to be used for an invocation outside a Maven project using the plugin.

The download goal of the Nexus M2Settings Maven Plugin downloads a Maven Settings file from Nexus Professional and stores it locally. The default file name for the settings file is the Maven default for the current user of ~/.m2/settings.xml file. If you are replacing a Maven Settings file, this goal can be configured to make a backup of an existing Maven Settings file.

Note
The download with the Nexus Maven Plugin is deprecated and has been replaced with the Nexus M2Settings Maven Plugin.

Configuring Nexus M2Settings Maven Plugin

The download goal of the Nexus M2Settings Maven plugin prompts the user for all required parameters, which include the Nexus server URL, the username and password and the template identifier.

Note
For security reason the settings download requires a HTTPS connection to your Nexus instance. If you are running Nexus via plain HTTP you will have to set the secure parameter to false.

The required configuration parameters can either be supplied as invocation parameters or when prompted by the plugin and are:

nexusUrl

points to the Nexus server installation’s base URL. If you have installed Nexus on your local machine, this would be http://localhost:8081/nexus/. Access via http only works with the secure configuration parameter set to false.

username

the username to use for authenticating to Nexus. Default value is the the Java System property user.name

password

password to use for authenticating to Nexus

templateId

the Template ID for the settings template as defined in the Nexus user interface

Additional general configuration parameters are related to the security of the transfer and the output file:

secure

by default set to true, this parameter forces a Nexus URL access with HTTPS. Overriding this parameter and setting it to false allows you to download a settings file via HTTP. When using this override it is important to keep in mind that the username and password transfered via HTTP can be intercepted.

outputFile

defines the filename and location of the downloaded file and defaults to the standard ~/.m2/settings.xml

backup

If true and there is a pre-existing settings.xml file in the way of this download, backup the file to a date-stamped filename, where the specific format of the date-stamp is given by the backupTimestampFormat parameter. Default value is true.

backup.timestampFormat

When backing up an existing settings.xml file, use this date format in conjunction with SimpleDateFormat to construct a new filename of the form: settings.xml-$(format). Date stamps are used for backup copies of the settings.xml to avoid overwriting previously backed up settings files. This protects against the case where the download goal is used multiple times with incorrect settings, where using a single static backup-file name would destroy the original, pre-existing settings. Default value is: yyyyMMddHHmmss.

encoding

Use this optional parameter to define a non-default encoding for the settings file.

As a Maven plugin the Nexus M2Settings Maven Plugin relies on Apache Maven execution and therefore on the fact that the Central Repository can be contacted for downloading the required plugins and dependencies. If this access is only available via a proxy server you can configure the proxy related parameters proxy, proxy.protocol, proxy.host, proxy.port, proxy.username and proxy.password.

Downloading Maven Settings

You can download the Maven Settings from Nexus Professional with a simple invocation, and rely on the plugin to prompt you for the required parameters:

$ mvn org.sonatype.plugins:nexus-m2settings-maven-plugin:download
[INFO] Scanning for projects...
[INFO]
[INFO] -----------------------------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] -----------------------------------------
[INFO]
[INFO] --- nexus-m2settings-maven-plugin:1.6.2:download (default-cli) @ standalone-pom ---
Nexus URL: https://localhost:8081/nexus
Username [manfred]: admin
Password: ********
[INFO] Connecting to: https://localhost:8081/nexus (as admin)
[WARNING] Insecure protocol: https://localhost:8081/nexus/
[INFO] Connected: Sonatype Nexus Professional 2.4.0-07
Available Templates:
   0) default
   1) example
Select Template: 0
[INFO] Fetching content for templateId: default
[INFO] Backing up: /Users/manfred/.m2/settings.xml to: /Users/manfred/.m2/settings.xml-20130404120146
[INFO] Saving content to: /Users/manfred/.m2/settings.xml
[INFO] -----------------------------------------
[INFO] BUILD SUCCESS
[INFO] -----------------------------------------
[INFO] Total time: 29.169s
[INFO] Finished at: Thu Apr 04 12:01:46 PDT 2013
[INFO] Final Memory: 12M/153M
[INFO] -----------------------------------------

If your Nexus server is hosted internally and does not use https you can download a settings file with

$ mvn org.sonatype.plugins:nexus-m2settings-maven-plugin:download -Dsecure=false

As displayed the plugin will query for all parameters and display a list of the available templates. Alternatively, you can specify the username, password, Nexus URL and template identifier on the command line.

$ mvn org.sonatype.plugins:nexus-m2settings-maven-plugin:download \
-DnexusUrl=https://localhost:8443/nexus \
-Dusername=admin \
-Dpassword=admin123 \
-DtemplateId=default

Enabling proxy access with -Dproxy=true will trigger the plugin to query the necessary configuration:

[INFO] Connecting to: https://localhost:8443/nexus (as admin)
Proxy Protocol:
   0) http
   1) https
Choose: 1
Proxy Host: myproxy.example.com
Proxy Port: 9000
Proxy Authentication:
   0) yes
   1) no
Choose: 0
Proxy Username [manfred]: proxy
Proxy Password: ******
[INFO] Proxy enabled: proxy@https:myproxy.example.com:9000

In some scenarios you have to get an initial settings file installed on a computer that does not have internet access and can therefore not use the Maven plugin. For this first initial configuration, that connects the computer to Nexus for following Maven invocations, a simple HTTP GET command to retrieve an unmodified settings file can be used:

curl -u admin:admin123 -X GET "http://localhost:8081/nexus/service/local/templates/settings/default/content" > ~/.m2/settings.xml

Modify the commandline above by changing the username:password supplied after -u and adapting the url to Template URL visible in the Nexus user interface. This invocation will however not do the client side replacement of parameters, so you will have to manually change any username or password configuration, if applicable.

Summary

Overall the Maven Settings integration in Nexus allows you to maintain multiple settings template files on the central Nexus server. You can configure settings files for different use cases like referencing a repository group containing only approved components in the mirror section for your release or QA builds, while at the same time providing an open public group mirror reference to all your developers for experimentation with other components.

By using the Nexus M2Settings Maven Plugin you can completely automate initial provisioning and updates of these settings files to your users.

Something went wrong with that request. Please try again.