# curl https://devtools.krishanchawla.com/raw/maven-proxy-configuration.txt

MAVEN PROXY CONFIGURATION
Configure Maven Proxy to download maven dependencies behind organization's proxy.

Category: Maven · Type: snippet
Official docs: https://maven.apache.org/

────────────────────────────────────────────────────────────

## What is Maven?

**Maven** is a powerful build automation and project management tool primarily used for Java projects. This guide focuses on configuring Maven to work behind corporate proxy servers for dependency downloads.

**⚡ Key Features**
- Proxy authentication support
- HTTP and HTTPS proxy settings
- Non-proxy host exclusions
- Encrypted password storage
- Environment variable integration

**🎯 Use Cases**
- Corporate network setup
- Enterprise environments
- Firewall configurations
- Private repository access
- Secure credential storage

---

## 🛠️ Interactive Settings Builder

Fill in your proxy details and copy a ready-to-paste `<proxy>` block for `~/.m2/settings.xml`.

## 🌐 Proxy - Basic Configuration

Add proxy configuration to `~/.m2/settings.xml`.

```xml
<settings>
  <proxies>
    <proxy>
      <id>company-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.company.com</host>
      <port>8080</port>
    </proxy>
  </proxies>
</settings>
```

## 🔐 Proxy - With Authentication

Configure proxy with username and password.

```xml
<proxy>
  <id>company-proxy-auth</id>
  <active>true</active>
  <protocol>http</protocol>
  <host>proxy.company.com</host>
  <port>8080</port>
  <username>your-username</username>
  <password>your-password</password>
</proxy>
```

## 🔒 Security - Encrypted Password

Store passwords securely using Maven's encryption.

### Create Master Password

```bash
mvn --encrypt-master-password
```

Save output to `~/.m2/settings-security.xml`:

```xml
<settingsSecurity>
  <master>{ENCRYPTED_MASTER_PASSWORD}</master>
</settingsSecurity>
```

### Encrypt Proxy Password

```bash
mvn --encrypt-password
```

Use encrypted password in `settings.xml`:

```xml
<password>{ENCRYPTED_PASSWORD}</password>
```

## ⛔ Proxy - Exclude Hosts

Bypass proxy for specific hosts (nonProxyHosts).

```xml
<proxy>
  <id>company-proxy</id>
  <active>true</active>
  <protocol>http</protocol>
  <host>proxy.company.com</host>
  <port>8080</port>
  <nonProxyHosts>localhost|127.0.0.1|*.internal.com|nexus.company.com</nonProxyHosts>
</proxy>
```

### Common Patterns

| Pattern | Matches |
|---------|---------|
| `localhost` | localhost only |
| `127.0.0.1` | Loopback IP |
| `*.internal.com` | All internal.com subdomains |
| `10.*` | All 10.x.x.x addresses |
| `host1\|host2` | Multiple hosts (pipe separator) |

## 🔄 Proxy - Multiple Protocols

Configure different proxies for HTTP and HTTPS.

```xml
<proxies>
  <!-- HTTP Proxy -->
  <proxy>
    <id>http-proxy</id>
    <active>true</active>
    <protocol>http</protocol>
    <host>http-proxy.company.com</host>
    <port>8080</port>
  </proxy>

  <!-- HTTPS Proxy -->
  <proxy>
    <id>https-proxy</id>
    <active>true</active>
    <protocol>https</protocol>
    <host>https-proxy.company.com</host>
    <port>8443</port>
  </proxy>
</proxies>
```

## 🏢 Corporate - Complete Setup

Common configuration for enterprise environments.

```xml
<proxies>
  <proxy>
    <id>corporate-proxy</id>
    <active>true</active>
    <protocol>http</protocol>
    <host>proxy.corp.company.com</host>
    <port>8080</port>
    <username>${env.PROXY_USER}</username>
    <password>${env.PROXY_PASS}</password>
    <nonProxyHosts>
      localhost|127.0.0.1|
      *.company.com|
      nexus.company.com|
      artifactory.company.com|
      10.*|172.16.*|192.168.*
    </nonProxyHosts>
  </proxy>
</proxies>
```

### Environment Variables

Set in shell profile:

```bash
export PROXY_USER="your-username"
export PROXY_PASS="your-password"
```

## ☕ JVM - Proxy Arguments

Pass proxy settings directly to Maven via JVM arguments.

```bash
mvn clean install \
  -Dhttp.proxyHost=proxy.company.com \
  -Dhttp.proxyPort=8080 \
  -Dhttp.proxyUser=username \
  -Dhttp.proxyPassword=password \
  -Dhttps.proxyHost=proxy.company.com \
  -Dhttps.proxyPort=8080
```

## ⚙️ JVM - MAVEN_OPTS

Set persistent proxy options via MAVEN_OPTS.

Add to `~/.bashrc` or `~/.zshrc`:

```bash
export MAVEN_OPTS="-Dhttp.proxyHost=proxy.company.com -Dhttp.proxyPort=8080"
```

## ✅ Verify - Test Connection

Test proxy setup by downloading a dependency.

```bash
mvn dependency:get \
  -Dartifact=org.apache.commons:commons-lang3:3.12.0 \
  -X
```

## 📄 Verify - Effective Settings

View final resolved settings including proxy.

```bash
mvn help:effective-settings
```

## 🐛 Verify - Debug Mode

Check if proxy is being used in debug mode.

```bash
mvn clean install -X 2>&1 | grep -i proxy
```

## 🚫 Troubleshoot - Cannot Access Repository

Fix "Unable to access repository" error.

### Checklist

- [ ] Verify proxy host and port
- [ ] Check if authentication is required
- [ ] Ensure `<active>true</active>` is set
- [ ] Verify `nonProxyHosts` doesn't block Maven Central
- [ ] Check firewall/network access

### Test Proxy Manually

```bash
curl -x http://proxy.company.com:8080 https://repo.maven.apache.org/maven2/
```

## ❌ Troubleshoot - 407 Authentication Required

Fix "407 Proxy Authentication Required" error.

### Solution

Add credentials to proxy configuration:

```xml
<proxy>
  <username>your-username</username>
  <password>your-password</password>
</proxy>
```

### NTLM Authentication

For Windows domains:

```xml
<proxy>
  <username>DOMAIN\username</username>
  <password>password</password>
</proxy>
```

## 🔓 Troubleshoot - SSL Certificate Error

Fix "PKIX path building failed" SSL certificate error.

### Temporary Fix (Development Only)

```bash
mvn clean install -Dmaven.wagon.http.ssl.insecure=true \
  -Dmaven.wagon.http.ssl.allowall=true
```

### Proper Fix - Import Certificate

```bash
keytool -import \
  -alias company-proxy \
  -file proxy-cert.crt \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit
```

## 🐳 Docker - Proxy Configuration

Pass proxy settings to Maven in Docker container.

### Dockerfile

```dockerfile
FROM maven:3.9-openjdk-17

# Set proxy environment variables
ENV HTTP_PROXY=http://proxy.company.com:8080
ENV HTTPS_PROXY=http://proxy.company.com:8080
ENV NO_PROXY=localhost,127.0.0.1

# Or configure in settings.xml
COPY settings.xml /root/.m2/settings.xml
```

### Build Args

```bash
docker build \
  --build-arg HTTP_PROXY=http://proxy.company.com:8080 \
  --build-arg HTTPS_PROXY=http://proxy.company.com:8080 \
  -t my-maven-app .
```

## 💡 IDE - IntelliJ IDEA

Configure proxy in IntelliJ IDEA.

1. **File → Settings → Build → Build Tools → Maven**
2. Set **User settings file** to your `settings.xml`
3. **Verify** proxy settings are loaded

## 🌙 IDE - Eclipse

Configure proxy in Eclipse.

1. **Window → Preferences → Maven → User Settings**
2. Point to your `settings.xml` file
3. Click **Update Settings**

## 📝 IDE - VS Code

Configure Maven settings in VS Code.

Add to `.vscode/settings.json`:

```json
{
  "maven.executable.path": "/usr/local/bin/mvn",
  "maven.settingsFile": "/Users/username/.m2/settings.xml"
}
```

## 📂 Settings - File Locations

Maven settings file locations by OS.

| OS | Path |
|----|------|
| Linux/Mac | `~/.m2/settings.xml` |
| Windows | `C:\Users\YourName\.m2\settings.xml` |
| Global | `${maven.home}/conf/settings.xml` |

### Create Directory

```bash
mkdir -p ~/.m2
touch ~/.m2/settings.xml
```

## 🧪 Testing - Proxy Test Script

Test script to verify proxy configuration.

Save as `test-maven-proxy.sh`:

```bash
#!/bin/bash

echo "Testing Maven proxy configuration..."

# Test proxy connectivity
echo -n "1. Testing proxy connection: "
nc -zv proxy.company.com 8080 2>&1 | grep succeeded && echo "✓" || echo "✗"

# Test Maven Central via proxy
echo -n "2. Testing Maven Central via proxy: "
curl -s -x http://proxy.company.com:8080 https://repo.maven.apache.org/maven2/ > /dev/null && echo "✓" || echo "✗"

# Check settings.xml
echo -n "3. Checking settings.xml: "
[ -f ~/.m2/settings.xml ] && echo "✓" || echo "✗ (not found)"

# Test dependency download
echo "4. Testing dependency download:"
mvn dependency:get -Dartifact=org.apache.commons:commons-lang3:3.12.0 -q && echo "✓" || echo "✗"
```

## 📦 Complete Example

Full `settings.xml` with proxy, mirrors, and repositories.

```xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">

  <!-- Proxy Configuration -->
  <proxies>
    <proxy>
      <id>corporate-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.company.com</host>
      <port>8080</port>
      <username>${env.PROXY_USER}</username>
      <password>${env.PROXY_PASS}</password>
      <nonProxyHosts>localhost|127.0.0.1|*.company.com</nonProxyHosts>
    </proxy>
  </proxies>

  <!-- Mirror to internal Nexus -->
  <mirrors>
    <mirror>
      <id>nexus</id>
      <mirrorOf>*</mirrorOf>
      <url>http://nexus.company.com/repository/maven-public/</url>
    </mirror>
  </mirrors>

  <!-- Server Authentication -->
  <servers>
    <server>
      <id>nexus</id>
      <username>${env.NEXUS_USER}</username>
      <password>${env.NEXUS_PASS}</password>
    </server>
  </servers>

</settings>
```

## 📊 Debug - Enable Logging

Enable debug logging for troubleshooting.

```bash
mvn clean install -X > maven-debug.log 2>&1
```

## 🔌 Debug - Test Connection

Test HTTP and HTTPS connections through proxy.

```bash
# Test HTTP
curl -v -x http://proxy.company.com:8080 http://repo.maven.apache.org/maven2/

# Test HTTPS
curl -v -x http://proxy.company.com:8080 https://repo.maven.apache.org/maven2/
```

## 🔍 Debug - Verify Active Settings

Check if proxy settings are active.

```bash
mvn help:effective-settings | grep -A 10 "<proxy>"
```

## 🚨 Common Issues

Frequent proxy configuration problems.

- Proxy host/port incorrect
- Missing authentication credentials
- Certificate trust issues
- Blocked by firewall
- Wrong protocol (http vs https)
- nonProxyHosts blocking required hosts

────────────────────────────────────────────────────────────

Full page: https://devtools.krishanchawla.com/devtools/maven-proxy-configuration
More tools: https://devtools.krishanchawla.com