> ## Documentation Index
> Fetch the complete documentation index at: https://docs.germainux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Engine Proxy Configuration

> Configure proxy access when the GermainUX Engine Manager or its Engines cannot connect directly to Germain Enterprise or another required HTTP/HTTPS endpoint.

Components
[`Engine`](/main/germain-ux-engine)

Availability
2022.1 or later

> **[Configure the Engine Manager](#configure-the-engine-manager)**
>
> Startup and service settings

> **[Configure an individual Engine](#configure-an-individual-engine)**
>
> Per-Engine proxy properties

> **[Relay the Engine Manager proxy settings](#relay-the-engine-manager-proxy-settings)**
>
> Apply manager proxy everywhere

> **[Troubleshooting](#troubleshooting)**
>
> Fix proxy connection issues

**Engine Proxy Configuration**

Configure proxy access when the GermainUX Engine Manager or its Engines cannot connect directly to Germain Enterprise or another required HTTP/HTTPS endpoint.

The Engine Manager and individual Engines run in separate JVMs. Their proxy settings must therefore be configured independently unless **Relay Proxy Settings** is enabled.

## Before you begin

Obtain the following information from your network team:

| | Item |
| - | - |
| 1 | Proxy hostname |
| 2 | Proxy port |
| 3 | Required protocol HTTP, HTTPS, or both |
| 4 | Authentication requirements |
| 5 | Hosts that must bypass the proxy |
| 6 | TLS certificate or truststore requirements |

Also confirm whether the proxy permits the HTTP methods, request sizes, connection duration, and destinations required by GermainUX.

## Java proxy properties

Use the following JVM system properties.

### HTTP proxy

```text theme={null}
-Dhttp.proxyHost=<proxy-host>
-Dhttp.proxyPort=<proxy-port>
```

Example:

```text theme={null}
-Dhttp.proxyHost=proxy.example.com
-Dhttp.proxyPort=8080
```

### HTTPS proxy

```text theme={null}
-Dhttps.proxyHost=<proxy-host>
-Dhttps.proxyPort=<proxy-port>
```

Example:

```text theme={null}
-Dhttps.proxyHost=proxy.example.com
-Dhttps.proxyPort=8800
```

Configure both sets when the Engine must access HTTP and HTTPS destinations through different proxy listeners.

## Configure the Engine Manager

The Engine Manager uses its local startup or service configuration.

### Windows

Open:

```text theme={null}
ENGINE_HOME\bin\startEngineManager.bat
```

Add the required properties to `VMARGS`.

Example:

```text theme={null}
SET VMARGS=-Dgermain.jvm=%JAVA% ^
 -Xms256m ^
 -Xmx512m ^
 -XX:+CrashOnOutOfMemoryError ^
 -Dhttps.proxyHost=proxy.example.com ^
 -Dhttps.proxyPort=8800
```

Keep `VMARGS` on one line if the script does not support Windows continuation characters.

If the Engine Manager runs as a Windows service, update the JVM arguments in the service definition used by that service. Editing `startEngineManager.bat` will not affect a service that starts from a different XML or wrapper configuration.

### Linux

Open:

```text theme={null}
ENGINE_HOME/bin/startEngineManager.sh
```

Add the required proxy properties to the Engine Manager’s JVM arguments.

Example:

```text theme={null}
VMARGS="$VMARGS \
-Dhttps.proxyHost=proxy.example.com \
-Dhttps.proxyPort=8800"
```

If the Engine Manager runs through `systemd`, confirm whether the service invokes this script or defines its own Java command. Update the configuration actually used by the service.

### Restart the Engine Manager

Restart the Engine Manager after changing its proxy configuration.

Windows:

```text theme={null}
Restart the Engine Manager from services.msc
```

Linux with `systemd`:

```text theme={null}
sudo systemctl restart <engine-manager-service>
```

Review:

```text theme={null}
ENGINE_HOME/logs/EngineManager.log
```

Confirm that it connects to Germain Enterprise successfully.

## Configure an individual Engine

Configure Engine-specific JVM proxy properties centrally through the Workspace.

1. Sign in to the GermainUX Workspace.
2. Open GermainUX Workspace -> Left Menu → Settings → **Germain -> State → Engine**.
3. Select the Engines view.
4. Find and select the required node and Engine.
5. Select **Show Advanced**.
6. Add the required proxy properties to the Engine’s JVM options.

   ![JVM Options for GermainUX Engine](https://mintcdn.com/germain-ux/8KX3c-GSSWR99tdN/images/main/engine-proxy-configuration/image-20260826-220925.png?fit=max\&auto=format\&n=8KX3c-GSSWR99tdN\&q=85\&s=e573112d57b3ca4e331cadf4aa2b91b3)

   JVM Options for GermainUX Engine
7. Save the configuration.
8. Restart the Engine.

Older GermainUX versions may display this page under:

```text theme={null}
APM > APM State
```

### HTTP example

Add each option as a separate JVM property:

```text theme={null}
-Dhttp.proxyHost=proxy.example.com
-Dhttp.proxyPort=8080
```

### HTTPS example

```text theme={null}
-Dhttps.proxyHost=proxy.example.com
-Dhttps.proxyPort=8800
```

The Engine must restart before the settings take effect.

## Relay the Engine Manager proxy settings

To apply the Engine Manager’s proxy configuration automatically to its Engines:

1. Open the node configuration in the GermainUX Workspace.
2. Enable **Relay Proxy Settings**(Germain -> State → Engine).

   ![Engine Proxy Configuration: Relay the Engine Manager proxy settings](https://mintcdn.com/germain-ux/8KX3c-GSSWR99tdN/images/main/engine-proxy-configuration/image-20260826-221108.png?fit=max\&auto=format\&n=8KX3c-GSSWR99tdN\&q=85\&s=8fd4e4e409d1c1092522917398937e43)
3. Save the node configuration.
4. Restart the affected Engines.
5. Verify their effective process command lines and connectivity.

Use this option when the Engine Manager and all Engines on the node require the same proxy.

Configure Engines individually when:

* Different Engines require different proxies.
* Only selected Engines require proxy access.
* The Engine Manager connects directly but an Engine does not.
* Different monitored destinations have different network requirements.

## Configure proxy bypass

Some destinations—such as local services, internal databases, or private application endpoints—may need to bypass the proxy.

Standard Java properties include:

```text theme={null}
-Dhttp.nonProxyHosts=<hosts>
-Dhttps.nonProxyHosts=<hosts>
```

Example:

```text theme={null}
-Dhttp.nonProxyHosts="localhost|127.*|*.example.internal"
-Dhttps.nonProxyHosts="localhost|127.*|*.example.internal"
```

Confirm the required syntax and support for the Java version used by the Engine. In Windows batch files, special characters such as `|` may require quoting or escaping.

## Proxy authentication

Do not place proxy passwords directly in scripts, JVM command lines, screenshots, or documentation. JVM arguments may be visible to users who can inspect running processes.

If the proxy requires authentication:

* Use the authentication mechanism supported by the Engine distribution.
* Store credentials through your organization’s approved secret-management process.
* Restrict access to service and configuration files.
* Confirm whether the proxy supports the authentication method used by Java.
* Contact GermainUX Support if the supplied Engine package requires additional authentication configuration.

## TLS inspection

If the proxy intercepts HTTPS traffic, the Engine JVM must trust the certificate authority used to issue the proxy’s certificates.

When you see certificate errors such as:

```text theme={null}
PKIX path building failed
unable to find valid certification path
```

verify:

* The proxy certificate chain
* The Java truststore used by the Engine Manager
* The truststore used by individual Engines
* Certificate validity dates
* Hostname matching

Do not disable TLS certificate validation to work around trust errors.

## Validate the configuration

After restarting the affected processes, confirm that:

* The Engine Manager connects to Germain Enterprise.
* The node heartbeat appears in **Germain > State**.
* Individual Engines start successfully.
* Monitoring components can reach their target endpoints.
* Direct internal connections bypass the proxy when configured.
* No proxy authentication or TLS errors appear in the logs.
* The effective Java command line contains the expected proxy properties.
* No duplicate or conflicting proxy settings exist.

## Troubleshooting

### Engine Manager connects, but an Engine does not

The Manager and Engine use separate JVMs. Configure the Engine’s JVM options or enable **Relay Proxy Settings**.

### Engine connects directly instead of using the proxy

Check:

* JVM property spelling and capitalization
* Whether the correct process was restarted
* Proxy-bypass patterns
* Whether a service definition overrides the startup script
* Whether the destination uses HTTP or HTTPS

### Internal endpoints fail after enabling the proxy

Add the internal hosts to the proxy-bypass configuration and restart the affected process.

### Proxy returns `407 Proxy Authentication Required`

The proxy requires authentication that is missing, invalid, or unsupported. Confirm the authentication requirements with the network team and use the credential mechanism supported by the Engine distribution.

### Configuration changes are not applied

Verify that:

* You changed the correct Engine or Engine Manager.
* The service uses the edited startup file.
* The configuration was saved.
* The affected process restarted.
* The effective JVM command line contains the new properties.

## Get Help

> **[Contact GermainUX Support](/main/support.md)**
>
> The Germain Team can help you set this up.

> **Can't find what you need?**
>
> Search all GermainUX docs with **Ctrl + K**, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.