|
5 | 5 | xmlns:xlink="http://www.w3.org/1999/xlink"> |
6 | 6 | <info> |
7 | 7 | <title>Java Management Extensions (JMX)</title> |
8 | | - <date>2Q19</date> |
| 8 | + <date>1Q23</date> |
9 | 9 | <keywordset> |
10 | 10 | <keyword>java-development</keyword> |
11 | 11 | <keyword>operations</keyword> |
|
14 | 14 |
|
15 | 15 | <!-- ================================================================== --> |
16 | 16 |
|
17 | | - <para>eXist-db provides access to various management interfaces via Java Management Extensions |
18 | | - (JMX). An agent in the Java virtual machine exposes agent services as so-called MBeans that |
19 | | - belong to different components running within the virtual machine. A JMX-compliant |
20 | | - management application can then connect to the agent through the MBeans and access the |
21 | | - available services in a standardized way. </para> |
22 | | - <para>The standard Java installation includes a simple client, JConsole, which will also display |
23 | | - the eXist-specific services. eXist also provides a command-line client for quick access to |
24 | | - server statistics and other information.</para> |
25 | | - <para>Right now, eXist only exposes a limited set of read-only services. Most of them are useful |
26 | | - for debugging purposes only.</para> |
| 17 | + <para>eXist-db provides access to various management interfaces via Java Management Extensions (JMX). An agent in the Java Virtual Machine exposes agent services as <emphasis>MBeans</emphasis> that belong to different components running within the Virtual Machine. A JMX-compliant management application can then connect to the agent through the MBeans and access the available services in a standardized way. </para> |
| 18 | + <para>The standard Java installation includes a simple client, JConsole, which will display the eXist-specific services. eXist also provides a command-line client for quick access to server statistics and other information.</para> |
| 19 | + <para>eXist only exposes a limited set of read-only services. Most of them are useful for debugging purposes only.</para> |
27 | 20 |
|
28 | 21 | <!-- ================================================================== --> |
29 | 22 |
|
30 | 23 | <sect1 xml:id="enable"> |
31 | 24 | <title>Enabling the JMX agent</title> |
32 | | - |
33 | | - <para>To enable the platform server within the host virtual machine, pass the following Java |
34 | | - system properties:</para> |
| 25 | + <para>The JMX agent is enabled by default for connections to local processes only: it is not exposed over TCP by default.</para> |
| 26 | + <para>To enable the platform server on the host virtual machine over TCP, pass the following Java system properties (e.g. as part of the <code>JAVA_OPTS</code> environment variable):</para> |
35 | 27 | <programlisting xlink:href="listings/listing-1.txt"/> |
36 | 28 | <warning> |
37 | | - <para>These options makes the server publicly accessible. Please check the Oracle <link |
38 | | - xlink:href="https://docs.oracle.com/javase/1.5.0/docs/guide/management/agent.html"> |
39 | | - JMX documentation</link> for details.</para> |
| 29 | + <para>These options make the server publicly accessible. Please check the Oracle <link xlink:href="https://docs.oracle.com/javase/1.5.0/docs/guide/management/agent.html"> JMX documentation</link> for details.</para> |
40 | 30 | </warning> |
41 | | - <para>The extension can now be activated by passing a <code>-j</code> or <code>-jmx</code> |
42 | | - command-line parameter to the eXist start scripts (<literal>client.sh</literal>, |
43 | | - <literal>startup.sh</literal> etc.). This parameter must be followed by the port number |
44 | | - through which the JMX/RMI connections are enabled. For instance:</para> |
45 | | - <programlisting xlink:href="listings/listing-2.txt"/> |
46 | 31 | </sect1> |
47 | 32 |
|
48 | 33 | <!-- ================================================================== --> |
49 | 34 |
|
50 | 35 | <sect1 xml:id="monitoring"> |
51 | 36 | <title>Monitoring and Management</title> |
52 | | - <para>This sections explains how to monitor an exist instant using common java tools.</para> |
| 37 | + <para>This section explains how to monitor an eXist instance using common Java tools.</para> |
53 | 38 |
|
54 | 39 |
|
55 | 40 |
|
|
58 | 43 | <sect2 xml:id="jconsole"> |
59 | 44 | <title>Use JConsole</title> |
60 | 45 |
|
61 | | - <para>Use a JMX-compliant management console to access the management interfaces. For |
62 | | - example, call JConsole, which is included with the JDK:</para> |
63 | | - <programlisting>jconsole localhost:1099</programlisting> |
| 46 | + <para>Use a JMX compliant management console to access the management interfaces. For example, call JConsole, which is included with the JDK:</para> |
| 47 | + <programlisting>jconsole</programlisting> |
| 48 | + <para>When connecting locally, select the entry starting <code>org.codehaus.mojo.appessembler.booter.Appass...</code> under "Local Proccess"</para> |
| 49 | + <para>When connecting remotely over TCP, provide the hostname and port under "Remote Process", or provide them directly from the command line:</para> |
| 50 | + <programlisting>jconsole hostname:port</programlisting> |
| 51 | + <para>You may be presented with a dialogue box stating that a secure connection could not be established: it should be possible to continue with an insecure connection.</para> |
64 | 52 | <para>Clicking on the <guimenuitem>MBeans</guimenuitem> tab should show some |
65 | 53 | eXist-specific MBeans below the standard Java MBeans (in the tree component to the |
66 | 54 | left).</para> |
|
167 | 155 | <para>For example, to get a report on current memory usage and running instances, use |
168 | 156 | the following URL:</para> |
169 | 157 | <programlisting>http://localhost:8080/exist/status?c=memory&c=instances</programlisting> |
| 158 | + <note> |
| 159 | + <para>The JMX information is only accessible via the HTTP interface when either:</para> |
| 160 | + <itemizedlist> |
| 161 | + <listitem> |
| 162 | + <para>the client accesses the API on localhost</para> |
| 163 | + </listitem> |
| 164 | + <listitem> |
| 165 | + <para>a valid token is provided when accessing the API from a remote IP address. A file containing this token and an example of its use can be found in the eXist data directory at <code>$EXIST_HOME/data/jmxservlet.token</code>.</para> |
| 166 | + </listitem> |
| 167 | + </itemizedlist> |
| 168 | + </note> |
| 169 | + <note> |
| 170 | + <para>Consider using <link xlink:href="production_web_proxying">a web proxy</link> if you wish to provide this service separately from other eXist applications.</para> |
| 171 | + </note> |
170 | 172 | <para>This returns something like:</para> |
171 | 173 | <programlisting language="xml" xlink:href="listings/listing-8.xml"/> |
172 | | - <para>The different JMX objects in eXist are organized into categories. One or more |
173 | | - categories can be passed to the servlet in parameter <literal>c</literal>. The |
174 | | - following categories are recognized:</para> |
| 174 | + <para>The different JMX objects in eXist are organized into categories. One or more categories can be passed to the servlet in the URL parameter <literal>c</literal>. The following categories are recognized:</para> |
175 | 175 | <variablelist> |
176 | 176 | <varlistentry> |
177 | 177 | <term><code>memory</code></term> |
|
195 | 195 | <varlistentry> |
196 | 196 | <term><code>system</code></term> |
197 | 197 | <listitem> |
198 | | - <para>Contains system information: eXist version ...</para> |
| 198 | + <para>Contains system information, such as the running eXist version.</para> |
199 | 199 | </listitem> |
200 | 200 | </varlistentry> |
201 | 201 | <varlistentry> |
|
0 commit comments