== Disclaimer

JMX poses several security concerns and had been leveraged to conduct arbitrary code execution.
This threat is mitigated by not allowing remote connections to JMX, setting up authentication and pre-authentication filters.
However, we recommend to either run James in isolation (docker / own virtual machine) or disable JMX altogether.<br/>

James JMX endpoint provides command line utilities and exposes a few metrics, also available on the metric endpoint.</p>

== Configuration

This is used to configure the JMX MBean server via which all management is achieved.

Consult this link:{sample-configuration-prefix-url}/jmx.properties[example]
in GIT to get some examples and hints.

.jmx.properties content
|===
| Property name | explanation

| jmx.enabled
| Boolean. Should the JMX server be enabled? Defaults to `true`.

| jmx.address
|The IP address (host name) the MBean Server will bind/listen to.

| jmx.port
| The port number the MBean Server will bind/listen to.
|===

To access from a remote location, it has been reported that `-Dcom.sun.management.jmxremote.ssl=false` is needed as
a JVM argument.

== JMX Security

In order to set up JMX authentication, we need to put `jmxremote.password` and `jmxremote.access` file
to `/conf` directory.

- `jmxremote.password`: define the username and password, that will be used by the client (here is james-cli)

File's content example:
```
james-admin pass1
```

- `jmxremote.access`: define the pair of username and access permission

File's content example:
```
james-admin readwrite
```

When James runs with option `-Djames.jmx.credential.generation=true`, James will automatically generate `jmxremote.password` if the file does not exist.
Then the default username is `james-admin` and a random password. This option defaults to true.

=== James-cli

When the JMX server starts with authentication configuration, it will require the client need provide username/password for bypass.
To do that, we need set arguments `-username` and `-password` for the command request.

Command example:
```
james-cli -h 127.0.0.1 -p 9999 -username james-admin -password pass1 listdomains
```

