> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-cli/administration/advanced-network-configuration.md).

# Advanced network configuration

The SonarQube CLI communicates with your SonarQube server and downloads auxiliary components over HTTPS. In enterprise environments that route traffic through a proxy, use a custom certificate authority (CA), or require mutual TLS (mTLS), you configure the CLI's network behavior using environment variables.

The same settings apply when the CLI launches the [SonarQube MCP server](https://github.com/SonarSource/sonarqube-mcp-server) for agent integrations or `sonar run mcp`.

> **Note:** Proxy and certificate configuration is not fully supported by secrets detection, Software Composition Analysis, and [Sonar Vortex context augmentation](/agent-centric-development-cycle/guide/sonar-vortex-context-augmentation.md) features inside the CLI.

## Proxy configuration

Set `SONAR_HTTPS_PROXY_URL`, `SONAR_HTTP_PROXY_URL`, and `SONAR_NO_PROXY` as described in [Environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md#network-connectivity).

### Proxy URL format

```
http://proxy.corp.com:3128
```

For proxies that require basic authentication, include credentials in the URL:

```
http://username:password@proxy.corp.com:3128
```

> **Warning:** Don't set credentials inline in terminal commands; they'll be saved to shell history. Instead, add them to your shell profile (for example, `~/.bashrc` or `~/.zshrc`), or use your CI/CD platform's secrets management.

### Bypassing the proxy for specific hosts

Set `SONAR_NO_PROXY` to a comma-separated list of hosts that the CLI should reach directly, without going through the proxy:

```bash
export SONAR_NO_PROXY="sonar.internal.corp.com,localhost,127.0.0.1"
```

Supported entry formats:

| Format                    | Matches                                                    |
| ------------------------- | ---------------------------------------------------------- |
| `sonar.internal.corp.com` | Exact hostname only                                        |
| `corp.com`                | The domain itself and all its subdomains                   |
| `*.corp.com`              | Subdomains only; does not match the root domain `corp.com` |
| `sonar.corp.com:9000`     | That hostname, but only when connecting on port 9000       |
| `*`                       | All hosts; bypasses the proxy entirely                     |

## Workarounds for unsupported proxy types

The CLI supports only basic-authentication proxies configured via environment variables. If your environment uses a more complex proxy protocol, use a local proxy adapter to bridge the gap.

### NTLM and Kerberos proxies

Corporate proxies that require Windows-domain authentication (NTLM or Kerberos) can't be configured directly. Tools like [Cntlm](http://cntlm.sourceforge.net/) and [Px Proxy](https://github.com/genotrance/px) authenticate with the corporate proxy using your domain credentials and expose a simple unauthenticated endpoint on localhost that the CLI can use.

1. Install and configure Cntlm or Px Proxy with your domain credentials.
2. Start the local proxy. By default it listens on `http://localhost:3128`.
3. Point the CLI to the local proxy:

```bash
export SONAR_HTTPS_PROXY_URL="http://localhost:3128"
```

Your domain credentials stay in the local proxy's configuration file and are never passed to the CLI.

### PAC file environments

The CLI doesn't read PAC (Proxy Auto-Config) files. If your organization distributes proxy settings via a PAC file, find the proxy URL that applies to your SonarQube server hostname (or ask your network team) and set it manually:

```bash
export SONAR_HTTPS_PROXY_URL="http://proxy.corp.com:3128"
```

In many environments a PAC file evaluates to a single proxy for most corporate traffic, so this reduces to one URL to copy.

## Custom CA certificates

Use this when your SonarQube server's certificate is signed by an internal CA, or when an SSL-inspecting proxy (such as Zscaler, Bluecoat, or Netskope) re-encrypts HTTPS traffic with a corporate certificate.

Set `SONAR_CA_CERT` as described in [Environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md#network-connectivity).

> **Warning:** Don't set `NODE_TLS_REJECT_UNAUTHORIZED=0` as a workaround for certificate errors. It bypasses `NODE_EXTRA_CA_CERTS` but not `SONAR_CA_CERT`, so it won't resolve issues with this CLI and disables certificate validation entirely. Use `SONAR_CA_CERT` to trust a specific CA instead.

### Certificate format

The certificate must be in PEM format: a Base64-encoded text file that begins with `-----BEGIN CERTIFICATE-----`. If your certificate is in a different format, convert it using `openssl` before setting the environment variable.

#### DER (.der, .crt)

```bash
openssl x509 -inform DER -in corp-ca.der -out corp-ca.pem
```

#### PKCS#12 / PFX

```bash
openssl pkcs12 -in bundle.pfx -nokeys -cacerts -out corp-ca.pem
```

#### P7B / PKCS#7

```bash
openssl pkcs7 -print_certs -in corp-ca.p7b -out corp-ca.pem
```

### Export from the system certificate store

#### macOS

1. Open **Keychain Access** and find the CA certificate.
2. Right-click the certificate and select **Export**.
3. Choose **Privacy Enhanced Mail (.pem)** as the format and save the file.

#### Windows

1. Open **certmgr.msc**.
2. Expand **Trusted Root Certification Authorities > Certificates**.
3. Right-click the CA certificate and select **All Tasks > Export**.
4. On the **Export File Format** page, choose **Base-64 encoded X.509 (.CER)**.
5. Complete the wizard and choose a file name when prompted.

The exported file is in PEM format and can be used directly with `SONAR_CA_CERT`.

## TLS client certificates

Use this when your SonarQube server requires a client certificate for HTTPS connections (mutual TLS).

Set `SONAR_TLS_CLIENT_CERT`, and when needed `SONAR_TLS_CLIENT_KEY_FILE` and `SONAR_TLS_CLIENT_PASSPHRASE`, as described in [Environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md#network-connectivity).

### Required variables

| Variable                      | Description                                                                                                                                          |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SONAR_TLS_CLIENT_CERT`       | Path to your client certificate PEM file, or a PKCS#12 bundle (`.p12` or `.pfx`)                                                                     |
| `SONAR_TLS_CLIENT_KEY_FILE`   | Path to the private key PEM file that matches the certificate. Required when `SONAR_TLS_CLIENT_CERT` is a PEM file, not when it is a PKCS#12 bundle. |
| `SONAR_TLS_CLIENT_PASSPHRASE` | Optional passphrase when the private key or PKCS#12 bundle is encrypted                                                                              |

When `SONAR_TLS_CLIENT_CERT` points to a PEM file, `SONAR_TLS_CLIENT_KEY_FILE` is required. If a required file is missing or cannot be read, the CLI records a configuration error and reports it in `sonar system status`.

### Certificate and key format

You can configure a client certificate in either of these ways:

**PEM files (separate certificate and key)**

Both files must be in PEM format. The certificate file begins with `-----BEGIN CERTIFICATE-----`. The key file begins with `-----BEGIN PRIVATE KEY-----` or `-----BEGIN RSA PRIVATE KEY-----`.

**PKCS#12 bundle (`.p12` or `.pfx`)**

Set `SONAR_TLS_CLIENT_CERT` to the bundle path. The CLI extracts the certificate and private key from the file, so you don't set `SONAR_TLS_CLIENT_KEY_FILE`. Set `SONAR_TLS_CLIENT_PASSPHRASE` when the bundle is password-protected.

You can combine a client certificate with a custom CA certificate (`SONAR_CA_CERT`) when your server uses an internal CA and also requires a client certificate.

### Examples

PEM certificate and key:

```bash
export SONAR_TLS_CLIENT_CERT=/etc/ssl/client-cert.pem
export SONAR_TLS_CLIENT_KEY_FILE=/etc/ssl/client-key.pem
export SONAR_TLS_CLIENT_PASSPHRASE=my-secret   # only when the key is encrypted
sonar list issues -p <YourProjectKey>
```

PKCS#12 bundle:

```bash
export SONAR_TLS_CLIENT_CERT=/etc/ssl/client-cert.p12
export SONAR_TLS_CLIENT_PASSPHRASE=my-secret   # only when the bundle is encrypted
sonar list issues -p <YourProjectKey>
```

> **Warning:** Don't set `SONAR_TLS_CLIENT_PASSPHRASE` to its value directly in the terminal; it'll be saved to shell history. Instead, add it to your shell profile (for example, `~/.bashrc` or `~/.zshrc`), or use your CI/CD platform's secrets management.

Run `sonar system status` to verify the CLI resolved your certificate path (and key path for PEM files). When configuration is invalid, the **Network** section shows the error and **Recommendations** suggests how to fix it.

## SonarQube MCP server

When the CLI starts the SonarQube MCP server (`sonar run mcp` or through `sonar integrate` for supported agents), it passes your resolved network configuration into the MCP container:

| Setting                                                                   | How the CLI applies it                                                                                        |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Proxy (`SONAR_HTTPS_PROXY_URL`, `SONAR_HTTP_PROXY_URL`, `SONAR_NO_PROXY`) | Translated to Java proxy system properties in `JAVA_OPTS`.                                                    |
| Custom CA (`SONAR_CA_CERT`)                                               | Certificate file mounted read-only into the container; the MCP image updates the system CA bundle at startup. |
| Client certificate (`SONAR_TLS_CLIENT_*`)                                 | PKCS#12 keystore mounted for mutual TLS.                                                                      |

When `SONAR_TLS_CLIENT_CERT` points to PEM files, the CLI converts them to a temporary PKCS#12 file under `~/.sonar/sonarqube-cli/cli-tmp/` and removes it when the MCP server process exits. PKCS#12 bundles (`.p12` or `.pfx`) are mounted directly.

Set the `SONAR_*` network variables in the environment of your AI agent or terminal session before the MCP server starts. On Windows with WSL, the CLI translates certificate paths so Docker can mount them correctly.

## Related pages

* [Check system status](/sonarqube-cli/administration/system-status.md)
* [Environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sonarsource.com/sonarqube-cli/administration/advanced-network-configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.