<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="services.jmx.config" xml:lang="en"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:mml="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>jmx service configuration</title>
  </info>

  <para>The <emphasis role="bold">jmx</emphasis> service is a mandatory
  service, so its automatically started in order to administrate or instrument
  the <xi:include href="../../variables.xml" xpointer="appserver" /> server.
  It uses the JMX extensions provided by the current Java EE platform.</para>

  <para>The <emphasis role="bold">jmx</emphasis> service creates at stratup,
  one or more JMX Remote connectors (one for each protocol configured in
  CAROL, see<xref linkend="config.protocol" />). This allows remote management
  for JMX-based administration applications. A connector's address is based on
  the corresponding protocol's URL, the protocol name and the server
  name.</para>

  <para>Let's consider the default CAROL configuration, where the RMI/JRMP
  protocol is used with the following URL:</para>

  <para><screen>carol.protocols=jrmp
carol.jrmp.url=rmi://localhost:1099</screen>The address of the JMX Remote
  connector for a server named <emphasis>myJonas</emphasis> is:<screen>service:jmx:rmi:///jndi/rmi://localhost:1099/jrmpconnector_myJonas</screen></para>

  <para>The <emphasis role="bold">jmx</emphasis> service can be started in
  <emphasis role="bold">secured</emphasis> or <emphasis
  role="bold">non-secured</emphasis> mode:</para>

  <itemizedlist>
    <listitem>
      <para>In non-secured mode, the JOnAS server accepts JMX connections
      directly, without requiring the client to provide any credentials (no
      user names or passwords). This implies that any person that has access
      to the JOnAS server's JMX port (by default, its RMI/JRMP port) can also
      take any action on the server (including remote code execution).</para>
    </listitem>

    <listitem>
      <para>In secured mode, any client that connects to the JOnAS server via
      JMX must provide a valid user name and password.</para>

      <itemizedlist>
        <listitem>
          <para>When connecting, the client provides a user name and password
          by setting the <emphasis
          role="bold">JMXConnector.CREDENTIALS</emphasis> key of the
          properties passed to the connection (<emphasis
          role="bold">env</emphasis> variable of the <emphasis
          role="bold">JMXConnector.connect</emphasis> method).</para>

          <para>This user name and password is always directly transmitted to
          the JOnAS server the client is connecting to, and it's that server's
          decision whether:</para>

          <itemizedlist>
            <listitem>
              <para>The user name and password is considered as being valid,
              therefore the connection will be accepted. This phase is called
              <emphasis role="bold">Authentication </emphasis>.</para>
            </listitem>

            <listitem>
              <para>That user has the right of accessing a certain method of a
              certain instance. This phase is called <emphasis
              role="bold">Authorization</emphasis>.</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>For authentication, you can use any JAAS LoginModule of the
          JMX extensions provided by your platform.</para>

          <para>For authorization, you can use any Security Manager provided
          by your platform.</para>
        </listitem>
      </itemizedlist>
    </listitem>
  </itemizedlist>

  <para>Here is the part of <filename>jonas.properties</filename> concerning
  the <emphasis role="bold">jmx</emphasis> service:</para>

  <screen>
###################### JOnAS JMX service configuration
#
#  Set the name of the implementation class of the JMX service
jonas.service.jmx.class                         org.ow2.jonas.jmx.internal.JOnASJMXService

#  Set to true if the JMXRemote interface should require the client to provide
#  authentication information. That information is provided when establishing
#  the JMX connection, using the JMXConnector.CREDENTIALS key.
#
#  Note that if you enable JMX security for a server, all clients (including
#  any administration tool such as the domain master) connecting to this
#  instance via JMX must provide a valid user name and password.
jonas.service.jmx.secured                       false

#  If jonas.service.jmx.secured is set to true, defines the authentication
#  method and the method's parameter. For example, to use file-based
#  authentication using the conf/jmx.passwords file, define:
#      jonas.service.jmx.authentication.method    jmx.remote.x.password.file
#      jonas.service.jmx.authentication.parameter conf/jmx.passwords
#  You are free to use the authentication provider you wish.
jonas.service.jmx.authentication.method         jmx.remote.x.password.file
jonas.service.jmx.authentication.parameter      conf/jmx.passwords
#  You may for example choose to use JAAS LoginModule for authentication.
#  In this case define the used configuration in the JAAS configuration file
#  using the jonas.service.jmx.authentication.parameter:
#      jonas.service.jmx.authentication.method      jmx.remote.x.login.config
#      jonas.service.jmx.authentication.parameter   jaas-jmx

#  If jonas.service.jmx.secured is set to true, defines the authorization
#  method and the method's parameter. For example, to use file-based
#  authorization using the conf/jmx.access file, define:
#      jonas.service.jmx.authorization.method    jmx.remote.x.access.file
#      jonas.service.jmx.authorization.parameter conf/jmx.access
#  You are free to use the authorization provider you wish.
jonas.service.jmx.authorization.method          jmx.remote.x.access.file
jonas.service.jmx.authorization.parameter       conf/jmx.access
#  You may for example choose to use role-based authorization manager
#  configured using conf/jmx.rolebased.access file. In this case, define:
#      jonas.service.jmx.authorization.method          jmx.remote.x.access.rolebased.file
#      jonas.service.jmx.authorization.parameter       conf/jmx.rolebased.access

</screen>
</section>