Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 41 ยท Repositories

settings.xml, Mirrors and Credentials

Configure Maven per machine with settings.xml: user and global files, mirrors, proxies, server credentials, password encryption and a Nexus or Artifactory proxy.

The POM describes a project, and it travels with the code. But some facts do not belong in the project: your corporate proxy, your username for the company repository, the folder where you keep the local cache. Those facts belong to a machine or a person, not to the code. Maven keeps them in a separate file called settings.xml.

This lesson shows where Maven looks for that file, what you can put in it, and how mirrors and credentials work together when your company runs a repository manager such as Nexus or Artifactory. It builds on Repositories and the Local Cache. The real settings.xml and the real mvn commands cannot run on this site, so the XML below is read-only. The runnable part is a stand-in written in Java: a small model of how Maven picks a mirror and looks up credentials. It follows the same rules, but it is not Maven's code.

Two files, one merged view

Maven reads up to two settings files and merges them. The user file wins when both set the same thing.

Level Typical location Meant for
Global <maven-home>/conf/settings.xml Defaults for everyone who uses this Maven installation
User ~/.m2/settings.xml (on Windows C:\Users\you\.m2\settings.xml) Your own mirrors, credentials and preferences

Most developers only ever edit the user file, because the global file lives inside the Maven installation and is replaced on upgrade. You can also point to a different file for one build with -s path/to/settings.xml (user) or -gs path/to/settings.xml (global). CI servers often do exactly this, so that secrets come from the CI system and not from a file in the project.

Never put settings.xml with real passwords inside your project repository. The POM is shared; settings are personal. That separation is the whole point of the file.

What lives in settings.xml

Mirrors Redirect repository requests to another URL.
Servers Usernames and passwords by repository id.
Proxies How to reach the internet from your network.
Local repository Where the cache folder lives.
1 / 2

The skeleton

A settings file has a root element and a handful of optional sections. This is an almost empty but valid file:

XML
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0
                              https://maven.apache.org/xsd/settings-1.2.0.xsd">

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

  <servers>   <!-- credentials -->   </servers>
  <mirrors>   <!-- redirects -->     </mirrors>
  <proxies>   <!-- network proxies --></proxies>
  <profiles>  <!-- settings-level profiles --></profiles>
  <activeProfiles>  </activeProfiles>
</settings>

localRepository moves the cache. You rarely need it, but on a build machine with a small system disk it can point to a bigger drive. offline set to true has the same effect as always passing -o. For one build, -Dmaven.repo.local=/some/path overrides the cache folder without editing any file.

Mirrors

A mirror tells Maven: "when a build asks for repository X, use this URL instead." The most common reason is a repository manager inside your company. Instead of every laptop and CI agent downloading from Maven Central directly, they all talk to one internal server that caches what it has already fetched. Builds get faster, the company controls what can enter, and builds keep working when the internet is slow.

XML
<mirrors>
  <mirror>
    <id>company-nexus</id>
    <name>Company repository manager</name>
    <url>https://nexus.example.com/repository/maven-public/</url>
    <mirrorOf>*</mirrorOf>
  </mirror>
</mirrors>

The important element is mirrorOf. It decides which repositories the mirror replaces, by their id:

mirrorOf value Meaning
central Only the repository whose id is central
* Every repository
external:* Every repository that is not on localhost or a file: URL
central,jcenter A comma-separated list of ids
*,!my-snapshots Everything except the repository with that id

If more than one mirror matches a repository, Maven uses the first matching mirror in the file. Maven does not try the next one when the first server is down. That is a feature of repository managers, which can hide several upstream sources behind one URL, and it is why a single * mirror is the usual setup.

Since Maven 3.8.1, plain http:// repositories are blocked by a built-in mirror, because downloads over HTTP can be tampered with. If you see a message about a blocked mirror, the fix is to use an https:// URL, not to disable the blocker.

flowchart LR
  B["Build asks for<br/>repository 'central'"] --> M{"Mirror matches<br/>'central'?"}
  M -- "yes" --> N["company-nexus<br/>(your internal URL)"]
  M -- "no" --> C["Original URL<br/>(Maven Central)"]
  N --> U["Nexus fetches from<br/>Central once, then caches"]

A mirror swaps the URL before the request leaves your machine.

Servers and credentials

A repository that needs a login is described in two places that are tied together by one string, the id. The URL lives in the POM or in the mirror. The username and password live in settings, in a server with the same id.

XML
<servers>
  <server>
    <id>company-nexus</id>
    <username>${env.NEXUS_USER}</username>
    <password>${env.NEXUS_TOKEN}</password>
  </server>
</servers>

The id must match the mirror id or the repository id exactly, including capitalization. A mismatch is the number one cause of "401 Unauthorized" errors that "work in the browser". The ${env.NAME} form reads an environment variable, which is how CI systems inject secrets without ever writing them to disk. Servers are also used when you publish artifacts, where the id matches the distributionManagement entry; see the publishing lesson later in this track.

Hiding passwords: what encryption really does

Maven can encrypt passwords in settings.xml. You first create a master password, then encrypt the real one with it:

Terminal
mvn --encrypt-master-password
mvn --encrypt-password

The first command prints a value for a file called ~/.m2/settings-security.xml. The second prints a value in curly braces that you paste into <password>:

XML
<password>{COQLCE6DU6GtcS5P=}</password>

This keeps a password from being read at a glance or pasted into a chat by accident. It is not strong protection: anyone who can read both files on your machine can decrypt the password, because Maven must be able to do so itself. Treat it as obfuscation. For real secrets, prefer an environment variable or a token from your CI system, and prefer short-lived tokens over personal passwords.

Proxies

If your network reaches the internet through an HTTP proxy, tell Maven in a proxy element:

XML
<proxies>
  <proxy>
    <id>office</id>
    <active>true</active>
    <protocol>http</protocol>
    <host>proxy.example.com</host>
    <port>3128</port>
    <nonProxyHosts>localhost|127.0.0.1|*.example.com</nonProxyHosts>
  </proxy>
</proxies>

nonProxyHosts lists hosts that must be reached directly, separated by |. If your internal repository manager lives inside the network, add it there, otherwise Maven will try to send internal traffic through the proxy. When a build works at home and fails at the office with certificate or connection errors, a missing proxy block is the first thing to check.

A typical company setup

Put the pieces together and a developer's whole file is often just a mirror and a server:

  1. The company runs Nexus or Artifactory with a "group" repository that combines Maven Central and the internal artifacts.
  2. settings.xml has one mirror with mirrorOf set to * pointing at that group URL.
  3. One server with the same id carries the credentials, read from environment variables.
  4. Projects need no special configuration at all, because every request is redirected before it leaves the machine.

You can see what Maven decided with mvn help:effective-settings, which prints the merged result, and mvn -X which logs which repository URL each download used.

Stand-in: how Maven picks a mirror

The program below models the decision Maven makes for each repository. It implements the mirrorOf rules from the table above: *, external:*, lists and ! exclusions. Then it applies the first-match rule and looks up credentials by id. Passwords are masked in the output, as you should do in any log.

Java Mirror selection and credential lookup

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

central goes to the company mirror, because * matches it. my-snapshots goes to the snapshots mirror, because that mirror is listed first and its mirrorOf names it exactly. local-dev is excluded by !local-dev, so it is reached directly. Real Maven also checks whether a mirror's layout matches and merges several details, but the first-match rule and the mirrorOf grammar are the same.

Stand-in: user settings override global settings

The second program models the merge. A value from the user file replaces the same value from the global file, and servers are combined by id.

Java Merging global and user settings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

You can print the real merged result any time with mvn help:effective-settings. When a setting is not behaving, this is the quickest way to see whether the user file, the global file or a -s option is responsible.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where should your personal repository password go?

    Credentials are personal and must not be committed. A server entry in settings.xml is matched to a repository or mirror by its id.
  2. 2. What does <mirrorOf>*</mirrorOf> mean?

    The star matches every repository id. Use !id to exclude a repository from it, or external:* to skip localhost and file URLs.
  3. 3. Two mirrors match the same repository. Which one does Maven use?

    The first match wins. Maven does not fall back to the second mirror if the first server is unreachable.
  4. 4. How strong is the protection of an encrypted password in settings.xml?

    Maven must be able to decrypt it by itself, so the master password sits in settings-security.xml on the same machine. Prefer environment variables or short-lived tokens for CI.
  5. 5. A build gets 401 Unauthorized from your repository manager although you wrote the credentials. What do you check first?

    The id is the only link between a repository URL and its credentials. A typo or different capitalization means Maven sends no login.

Summary

  • settings.xml holds personal and machine-specific configuration; the POM holds shared project configuration.
  • The global file lives in the Maven installation, the user file in ~/.m2; the user file wins. -s and -gs choose other files.
  • A mirror redirects repository requests; mirrorOf selects repositories with *, external:*, lists and ! exclusions, and the first matching mirror is used.
  • Credentials sit in a server whose id must equal the repository or mirror id; use ${env.NAME} to keep secrets out of files.
  • Password encryption is obfuscation, not strong security, and proxies need nonProxyHosts for internal servers.
  • mvn help:effective-settings shows what Maven actually sees.

Next: Running Tests with Surefire