war.xml

<?xml version="1.0" encoding="utf-8"?>
<!--
  ~ Copyright 2009-2013 Roland Huss
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~       http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->

<section id="agents-war">
  <title>JEE Agent (WAR)</title>
  
  <section id="war-agent-installation">
    <title>Installation and Configuration</title>
    <para>
      The WAR agent is the most popular variant, and can be deployed
      in a servlet container just like any other JEE web application.<sidebar>
      <title>Tomcat example</title>
      A simple example for deploying the agent on Tomcat can be found
      in the Jolokia <ulink
      url="http://www.jolokia.org/tutorial.html">quickstart</ulink>.
    </sidebar>    
    Often, installation is simply a matter of copying the agent WAR to
    a deployment directory. On other platforms an administrative Web
    GUI or a command line tool need to be used for
    deployment. Providing detailed installation instructions for every servlet
    container is out of scope for this document.
    </para>
    <para>
      The servlet itself can be configured in two ways:
    </para>
  <variablelist>
    <varlistentry>
      <term><emphasis role="bold">Servlet Init Parameters</emphasis></term>
      <listitem>
        Jolokia can be configured with <literal>init-param</literal>
        declarations within the servlet definition in
        <filename>WEB-INF/web.xml</filename>. The known parameters are
        described in <xref linkend="agent-war-init-params"/>. The
        stock agent needs to be repackaged, though, in order to modify
        the internal <filename>web.xml</filename>.
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><emphasis role="bold">Servlet Context Parameters</emphasis></term>
      <listitem>
        A more convenient possibility might be to use servlet context
        parameters, which can be configured outside the WAR
        archive. This is done differently for each servlet container
        but involves typically the editing of a configuration
        file. E.g. for <ulink
        url="http://tomcat.apache.org/tomcat-7.0-doc/config/context.html">Tomcat</ulink>,
        the context for 
        the Jolokia agent can be adapted by putting a file
        <filename>jolokia.xml</filename> below
        <filename>$TC/conf/Catalina/localhost/</filename> with a
        content like: <programlisting><![CDATA[<Context> 
   <Parameter name="maxDepth" value="1"/> 
</Context>]]></programlisting>
      </listitem>
    </varlistentry>
  </variablelist>
  <para>
    The configuration options <literal>discoveryEnabled</literal> and
    <literal>discoveryAgentUrl</literal> can be provied via environent
    variables or system properties, too. See the below for details. 
  </para>
  <table id="agent-war-init-params">
    <title>Servlet init parameters</title>
    <thead>
        <tr>
          <td>Parameter</td>
          <td>Description</td>
          <td>Example</td>
        </tr>        
      </thead>
      <tr>
        <td><constant>dispatcherClasses</constant></td>
        <td>
          Classnames (comma separated) of <constant>RequestDispatcher</constant> used in addition
          to the
          <constant>LocalRequestDispatcher</constant>. Dispatchers are
          a technique used by the JSR-160 proxy to dispatch (or
          'route') a request to a different destination.
        </td>
        <td>
          <literal>org.jolokia.jsr160.Jsr160RequestDispatcher</literal>
          (this is the dispatcher for the JSR-160 proxy)
        </td>
      </tr>
      <tr>
        <td><constant>policyLocation</constant></td>
        <td>
          Location of the policy file to use. This is either a URL
          which can read from (like a <literal>file:</literal> or
          <literal>http:</literal> URL) or with the special protocol
          <literal>classpath:</literal> which is used for looking up
          the policy file in the web application's classpath. See
          <xref linkend="security-policy-location"/> for details about this
          parameter.
        </td>
        <td>
          <filename>file:///home/jolokia/jolokia-access.xml</filename>
          for a file based access to the policy file. Default is
          <filename>classpath:/jolokia-access.xml</filename>
        </td>
      </tr>
      <tr>
        <td><constant>restrictorClass</constant></td>
        <td>
          Full classname of an implementation of <literal>org.jolokia.restrictor.Restrictor</literal>
          which is used as a custom restrictor for securing access via Jolokia.
        </td>
        <td>
          <literal>com.mycompany.jolokia.CustomRestrictor</literal> (which must be included in the
          war file and must implement <literal>org.jolokia.restrictor.Restrictor</literal>)
        </td>
      </tr>
      <tr>
        <td><constant>debug</constant></td>
        <td>
          Debugging state after startup. Can be changed via
          the config MBean during runtime.
        </td>
        <td>
          Default: <constant>false</constant>
        </td>
      </tr>
      <tr>
        <td><constant>historyMaxEntries</constant></td>
        <td>
          Entries to keep in the history. Can be changed at
          runtime via the config MBean.
        </td>
        <td>
          Default: <constant>10</constant>
        </td>
      </tr>
      <tr>
        <td><constant>debugMaxEntries</constant></td>
        <td>
          Maximum number of entries to keep in the local
          debug history (if enabled). Can be changed via
          the config MBean at runtime.
        </td>
        <td>
          Default: <constant>100</constant>
        </td>
      </tr>
      <tr>
        <td><constant>maxDepth</constant></td>
        <td>
          Maximum depth when traversing bean properties.
          If set to 0, depth checking is disabled
        </td>
        <td>
          Default: <constant>15</constant>
        </td>
      </tr>
      <tr>
        <td><constant>maxCollectionSize</constant></td>
        <td>
          Maximum size of collections returned when
          serializing to JSON. When set to 0,
          collections are never truncated.
        </td>
        <td>
          Default: <constant>1000</constant>
        </td>
      </tr>
      <tr>
        <td><constant>maxObjects</constant></td>
        <td>
          Maximum number of objects which are traversed
          when serializing a single response. Use this
          as an airbag to avoid boosting your memory and
          network traffic. Nevertheless, when set to 0
          no limit is imposed.
        </td>
        <td>
          Default: <constant>0</constant>
        </td>
      </tr>
      <tr>
        <td><constant>mbeanQualifier</constant></td>
        <td>
          Qualifier to add to the ObjectName of Jolokia's own
          MBeans. This can become necessary if more than one agent is
          active within a servlet container. This qualifier is added
          to the <constant>ObjectName</constant> of this agent with a
          comma. For example a <constant>mbeanQualifier</constant>
          with the value <constant>qualifier=own</constant> will
          result in Jolokia server handler MBean with the name
          <constant>jolokia:type=ServerHandler,qualifier=own</constant>
        </td>
        <td></td>
      </tr>
      <tr>
        <td><constant>mimeType</constant></td>
        <td>
          MIME to use for the JSON responses
        </td>
        <td>
          Default: <constant>text/plain</constant>
        </td>
      </tr>
      <tr>
        <td><constant>canonicalNaming</constant></td>
        <td>
          This option specifies in which order the key-value
          properties within ObjectNames as returned by
          <constant>list</constant> or <constant>search</constant> are
          returned. By default this is the so called 'canonical order'
          in which the keys are sorted alphabetically. If this option
          is set to <constant>false</constant>, then the natural order
          is used, i.e. the object name as it was registered. This
          option can be overridden with a query parameter of the same
          name.
        </td>
        <td>
          Default: <constant>true</constant>
        </td>
      </tr>
      <tr>
        <td><constant>includeStackTrace</constant></td>
        <td>
          Whether to include a stacktrace of an exception in case of
          an error. By default it it set to <constant>true</constant>
          in which case the stacktrace is always included. If set to
          <constant>false</constant>, no stacktrace is included. If
          the value is <constant>runtime</constant> a stacktrace is
          only included for RuntimeExceptions. This global option can
          be overridden with a query parameter.
        </td>
        <td>
          Default: <constant>true</constant>
        </td>
      </tr>
      <tr>
        <td><constant>serializeException</constant></td>
        <td>
          When this parameter is set to <constant>true</constant>,
          then an exception thrown will be serialized as JSON and
          included in the response under the key
          <constant>error_value</constant>. No stacktrace information
          will be included, though. This global option can be
          overridden by a query parameter of the same name.
        </td>
        <td>
          Default: <constant>false</constant>
        </td>
      </tr>
      <tr>
        <td><constant>detectorOptions</constant></td>
        <td>
          Extra options passed to an detector after successful
          detection of an application server. See below for an
          explanation. 
        </td>
        <td>          
        </td>
      </tr>
      <tr>
        <td><constant>discoveryEnabled</constant></td>
        <td>
          Is set to <literal>true</literal> then this servlet will
          listen for multicast request (multicastgroup 239.192.48.84,
          port 24884). By default this option is disabled in order to
          avoid conflicts with an JEE standards (though this should't
          harm anyways). This option can also be switched on with an 
          environment variable
          <literal>JOLOKIA_DISCOVERY</literal> or the system
          property <literal>jolokia.discoveryEnabled</literal> set to
          <literal>true</literal>.
        </td>
        <td>
          Default: <constant>false</constant>
        </td>
      </tr>
      <tr>
        <td><constant>discoveryAgentUrl</constant></td>
        <td>
          Sets the URL to respond for multicast discovery requests. If
          given, <constant>discoveryEnabled</constant> is set
          implicetly to true. This URL can also be provied by an
          environment variable
          <literal>JOLOKIA_DISCOVERY_URL</literal> or the system
          property <literal>jolokia.discoveryUrl</literal>. Within the value you can use the
          placeholders <literal>${host}</literal> and <literal>${ip}</literal> which gets replaced
          by the autodetected local host name/address. Also with <literal>${env:ENV_VAR}</literal> and
          <literal>${sys:property}</literal> environment and system properties can be referenced, respectively.
        </td>
        <td>          
          <constant>http://10.9.11.87:8080/jolokia</constant>
        </td>
      </tr>
      <tr>
        <td><constant>agentId</constant></td>
        <td>
          A unique ID for this agent. By default a unique id is
          calculated. If provided it should be ensured that this id is
          unique among all agent reachable via multicast requests used
          by the discovery mechanism. It is recommended not to set
          this value. Within the <literal>agentId</literal> specification you
          can use the same placeholders as in <literal>discoveryAgentUrl</literal>.
        </td>
        <td>          
          <constant>my-unique-agent-id</constant>
        </td>
      </tr>
      <tr>
        <td><constant>agentDescription</constant></td>
        <td>
          An optional description which can be used for clients to
          present a human readable label for this agent.
        </td>
        <td>          
          <constant>Intranet Timebooking Server</constant>
        </td>
      </tr>
    </table>
    <para>
      Jolokia has various detectors which can detect the brand and
      version of an application server it is running in. This version
      is revealed with the <constant>version</constant> command. With
      the configuration parameter <constant>detectorOptions</constant>
      extra options can be passed to the detectors. These options take
      the form of a JSON object, where the keys are productnames and
      the values other JSON objects containing the specific
      configuration. This configuration is feed to a successful
      detector which can do some extra initialization on agent
      startup. Currently the following extra options are supported:
    </para>
   <table id="agent-war-detector-options">
      <title>Servlet init parameters</title>
      <thead>
        <tr>
          <td>Product</td>
          <td>Option</td>
          <td>Description</td>
        </tr>        
      </thead>
      <tr>
        <td>glassfish</td>
        <td>bootAmx</td>
        <td>If <constant>false</constant> and the agent is running on
        Glassfish, this will cause the AMX subsystem not to be booted
        during startup. By default, AMX which contains all relevant
        MBeans for monitoring Glassfish is booted.
        </td>
      </tr>
   </table>
  </section>
  <section id="agent-war-security">
    <title>Security Setup</title>
    <para>
      In order use JEE security within the war, some extrat
      configuration steps are required within
      <filename>web.xml</filename>.<sidebar>
      <title>Using jmx4perl's <literal>jolokia</literal> tool</title>
      <ulink url="http://www.jmx4perl.org">jmx4perl</ulink> comes
      with a nice command line utility called <ulink
      url="http://search.cpan.org/~roland/jmx4perl/scripts/jolokia">jolokia</ulink>
      which allows for an easy setup of security within a given
      <filename>jolokia.war</filename>. See <xref linkend="tools-jmx4perl"/> for
      more details.
    </sidebar>
    There is a commented section which can serve as an example. All
    current client libraries are able to use BASIC HTTP authentication
    with user and password. The
    <literal>&lt;login-config&gt;</literal> should be set
    accordingly. The <literal>&lt;security-constraint&gt;</literal>
    specifies the URL pattern (which is in the default setup specify
    all resources provided by the Jolokia servlet) and a role name
    which is used to find the proper authentication credentials.  This
    role must be referenced outside the agent WAR within the servlet
    container, e.g. for Tomcat the role definition can be found in
    <filename>$TOMCAT/config/tomcat-users.xml</filename>.
    </para>
  </section>
  
  <section id="agent-war-programmatic">
    <title>Programmatic usage of the Jolokia agent servlet</title>
    <para>
      The Jolokia agent servlet can be integrated into one's own
      web-applications as well. Simply add a servlet with
      the servlet class
      <classname>org.jolokia.http.AgentServlet</classname> to your
      own <filename>web.xml</filename>. The following example maps
      the agent to the context <literal>/jolokia</literal>:
    </para>
    <programlisting language="xml"><![CDATA[
    <servlet>
      <servlet-name>jolokia-agent</servlet-name>
      <servlet-class>org.jolokia.http.AgentServlet</servlet-class>
      <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
      <servlet-name>jolokia-agent</servlet-name>
      <url-pattern>/jolokia/*</url-pattern>
    </servlet-mapping>
    ]]></programlisting>
    <para>
      Of course, any init parameter as described in <xref
      linkend="agent-war-init-params"/> can be used here as well. 
    </para>
    <para>
      In order for this servlet definition to find the referenced
      Java class, the JAR <filename>jolokia-core.jar</filename> must
      be included. This jar can be found in <ulink
      url="http://repo1.maven.org/maven2/org/jolokia/jolokia-core">Maven central
      </ulink>. Maven users will can declare a
      dependency on this jar artifact:
    </para>
    <programlisting language="xml"><![CDATA[
    <project>
      <!-- ....  --> 
      <dependencies>
        <dependency>
          <groupId>org.jolokia</groupId>
          <artifactId>jolokia-core</artifactId>
          <version>${jolokia.version}</version>
        </dependency>
      </dependencies>
      <!-- .... -->
    </project>]]></programlisting>
    <para>
      The <classname>org.jolokia.http.Agent</classname> can be
      subclassed, too in order to provide a custom restrictor or a
      custom log handler. See <xref linkend="security-restrictor"/>
      for details.<footnote>
      <para>
        Replace
        <classname>org.jolokia.osgi.http.AgentServlet</classname> with
        <classname>org.jolokia.http.AgentServlet</classname> to use
        the servlet in a non-OSGi environment.
      </para>
    </footnote>
    </para>
    <para>
      Also, multiple Jolokia agents can be deployed in the same JVM
      without problem. However, since the agent deploys some
      Jolokia-specific MBeans on the single
      <literal>PlatformMBeansServer</literal>, for multi-agent
      deployments it is important to use the
      <constant>mbeanQualifier</constant> init parameter to
      distinguish multiple Jolokia MBeans by adding an extra
      propery to those MBeans' names. This also needs to be done if
      multiple webapps containing Jolokia agents are deployed on
      the same JEE server. 
    </para>
  </section>
</section>