Jolokia on Roland Huß

Why Jolokia is not RESTful

Thu, 03 Nov 2016 00:00:00 +0000

From time to time people come to me and say: “I really would love Jolokia if only it would be RESTful”. This post tells you why.

I really like REST, yes I do. If I would crete a new application on a green field, its remote access API would very likely obey the REST paradigm.¹

However, Jolokia is a different beast. It is a bridge to the world of JMX, providing an open minded alternative to the rusty and Java specific JSR-160 standard. Its protocol is based on JSON over HTTP, so in principle it could be REST. But it is not, mainly for the following two reasons:

JMX resource naming is a mess
#

Jolokia doesn’t not have any influence on the naming of the resources it accesses. These resources are JMX MBeans and their identifiers are ObjectNames. ObjectNames have a certain structure but beside this they can be named arbitrarily. So if you want to provide an HTTP API for accessing these repositories, this free form addressing poses some challenges, especially for read operations with GET. For example it is impossible to transmit a slash (/) or backslash (\\) as part of an URL’s path info. The reason is security related, and each application server handles this differently: Tomcat for example completely rejects such requests whereas Wildfly / Undertow refuses to URL decode %2F (for /) and %5C for \\. Jetty doesn’t care much. So in order to address a JMX MBean which contains these characters as part of their names, the typical encoding as part of an URL path doesn’t work. One could use query parameters for this kind of addressing and in fact, Jolokia supports this, too. But it’s still ugly. Also, implementers of MBeans tend to put semantic information into the MBean name like the port of a connector or the name of a database scheme. It can’t excluded that the MBean name alone can carry sensitive information. However GET urls are not secured via the transport protocol and tend to end up in log files. So, its much safer to send these requests via POST, even when only performing read operations on JMX attributes.

Bulk requests
#

A special feature of Jolokia are Bulk Requests. This allows a very efficient monitoring of multiple values with a single HTTP request. It works by sending a list of individual, JSON encoded Jolokia requests with a single HTTP POST request. That list can contain any valid Jolokia operation: Reading and writing attributes, executing some operations, searching for or listing of MBeans. The heterogenous nature of this kind of requests makes it hard to map them to one single HTTP verb as REST suggests. Also, the sheer length of the request parameter forbids to send a bulk request via GET as Servlet container or other application servers impose certain restrictions on the length of an URL, which vary however from server to server.

Jolokia implements both
#

For every Jolokia operation, we play both: GET and POST ². As an integration tool, which helps to bridge different worlds without really having control over these worlds, the focus is on maximal flexibility so that it can adapt to any environment where it is used. REST is only of second importance here, but if you think the issues described above can be solved in a more RESTful way, I’m more than open.

I’ve to confess that I’m really not a REST expert, so if you don’t agree with my arguments, I’d kindly ask you to leave a comment or tweet me for corrections. ↩︎
or: “Country and Western” ↩︎

Java EE Management is dead

Mon, 10 Oct 2016 00:00:00 +0000

Now that some weeks has been passed we all had time to absorb the revised Java EE 8 proposal presented at Java One. As you know, some JSRs remained, some things were added and some stuff was dropped. Java EE Management API 2.0, supposed to be a modern successor of JSR 77, is one of the three JSRs to be dropped.

What does this mean for the future of Java EE management and monitoring ?

First of all it’s fair to state that JSR 373 never really took off. Since February 2015 there were not more than 86 mails on the expert group mailing list, half of them written in March 2015 during incubation. At the latest of January 2016 it was clear that JSR-373 is not on Oracle’s focus anymore. To be honest, even we members of the expert group, we were not able to push this JSR further.

How did it come that far ? Let’s have a look back into history.

All starts with JSR 3 back in 1999. This first JMX specification is the foundation of all Java resources management. As it can been seen by its age, Java folks took care about Management and Monitoring from the very beginning on. And even better, since JS2E 5 JMX is integral part of Java SE so its available on every JVM out there.

Over the years, additional JSRs were added on top of this base:

JSR 160 defines a remote protocol for JMX,, which is based on RMI. This might have been a good decision in 2003, but turned out to be awful to use especially for non-Java based monitoring systems.
JSR 262 was started to overcome this by defined a “WebServices Connector for Java Management Extensions Agents” which was mostly around SOAP services. However although even an initial implementation existed, it was withdrawn before the final release. It’s not completely clear why it was stopped in 2008 and later withdrawn, as the public review ballot has been approved, although it was a tight result. The biggest objections were on dependencies on “proprietary” WS-* specifications.
“J2EE Management” JSR 77 was finished in 2002 and defines a hierarchy how Management and Monitoring resources exposed by a Java EE server is structured. It allows a uniform interface for how to access the various Java EE resources, like web applications or connector pools. Beside this it also defines how statistics are exposed by defining various metrics formats. However, implementing the StatisticsProvider model is not mandatory and from my personal experience it was implemented only rarely by some vendors and if so, not for every resource.
JSR 88 complements JSR 77 and defines a common format for deploying Java EE artefacts.
JSR 255 was started to be the next version of JMX and supposed to be included in Java 7. Although it was already nearly finished and integrated, it didn’t make it into Java 7 (nor Java 8). The spec was then dormant until it was finally withdrawn in 2016.

With the dead of JMX 2.0 in 2009 the evolution of JMX as a standard for Java SE has stalled. But what’s about Java EE Management ? At least JSR 77 is still part of Java EE 7 and for Java EE 8 the successor was supposed to be JSR 373. JSR 373 tackles the problem of remote access, whereas JSR 77 still relies on RMI as a standard implementation protocol as defined in JSR 160.

The two major goals of JSR 373 were:

Provide an update of the hierarchal resource and statistics structure as defined by JSR 77
Provide a REST access to these resources independent of JMX

In the often cited Java EE 8 Community Survey more than 60% were in favour of defining a new API for managing application, which should be based on REST (83% pro-votes). This finally lead to JSR 373. However, as it seems in retrospective, a deep interest in this topic was not really given and probably lead to this final decision to drop JSR 373 from Java EE 8.

So, what is the state of Monitoring and Management of Java and in particular Java EE applications nowadays and what can be expected in the future ? Let’s have a look into the crystal ball.

JMX is here to stay. It is part of Java SE and I don’t know of any plans for removing it from future Java editions. Ok, it feels a bit rusty but it is still rock solid and gives you deep insight in the state of your JVM. With tools like Jolokia you can overcome most of the restrictions JSR 160 imposes. (Disclaimer: since I’m the author of Jolokia all my personal opinions given here should be evaluated in this light :)
It is not clear how the Management API of Java EE 8 and beyond looks like. It does not look like that JSR 77 will survive. Will there be a standard for Java EE management at all ? Probably not, and so there is the danger that vendors will push their proprietary management APIs, which already happens to some extent. Luckily, most of these proprietary APIs are also mirrored in JMX these days.
On the other hand, it could be also a good thing that there is no other Management API which is not based on JMX. That’s because you will always need JMX to monitor the basic aspects like Heap Memory usage or Thread count, which are covered by Java SE. Adding a different, REST like protocol for Java EE monitoring requires operators to access a Java EE server with two different protocols (JMX and Rest), duplicating configuration efforts on the monitoring side. This can only be avoided if the Java EE resources are mirrored in JMX, too.

To sum it up, I think its a shame that Management and Monitoring, which played a prominent role over the whole evolution of Java EE, will probably be dropped completely in Java EE 8. As a replacement the new Health Check API has been announced, but to be honest, that can’t be a full replacement for classical management and monitoring where the evaluation of a system’s health is done on a dedicated monitoring platform (e.g. like Nagios or Prometheus). These platforms take the plain metrics data exposed by the application and does the data evaluation on their own.

The good thing is still that you have JMX to the rescue and I’m pretty sure that this technology will survive also this storm. Especially if vendors are willing to support it for their application server metrics, too.

Even without a Java EE standard.

Jolokia 2.0 - JMX Notifications

Wed, 13 Jan 2016 00:00:00 +0000

This screencast gives a live demo of the forthcoming JMX notification support in Jolokia 2.0.

Jolokia supports currently two notification modes. In all modes, the Jolokia agent itself subscribe to a JMX notification locally and then dispatches the notifications to its clients.

Pull Mode : Here, the agent keeps the notification received for a client in memory and sends it back on an JMX request to a Jolokia specific MBean. A client typically queries this notification MBean periodically.
SSE Mode : Server Sent Events are a W3C standard for pushing events from an HTTP server to a client. With this mode the Jolokia agents directly pushes any notification it receives to the client. The advantage is of course a much lower latency compared to the pull mode, but SSE is not available for Internet Explorer, including 11. What a pity.

The Jolokia protocol has been extended with the top level action notification and subcommands.

register / unregister : Register / unregister a notification client
add / remove : Add / remove a listener subscription
list : list all subscriptions for a client
ping : Keep subscription alive
open : Use for creating a back channel. E.g. the SSE mode keeps this GET request for pushing back an event stream.

Currently only the new Jolokia JavaScript client supports JMX notification. If you are interested in having it in other clients (e.g. Java), too, please let me know. I would be more than happy for coders jumping on the Jolokia bandwagon since there is still quite some stuff to do for 2.0.

The source code to this demo and the new Jolokia JavaScript client is on GitHub: https://github.com/jolokia-org/jolokia-client-javascript.

Welcome to 2016 - the year Jolokia 2.0 will see the light of day

Wed, 06 Jan 2016 00:00:00 +0000

I hope you all had a good start into 2016 and have charged all your batteries during the time of stillness.

Jolokia had a good start, too. During the holiday season I took the opportunity to continue to work on version 2.0 which now takes on form. If you have followed the history of Jolokia you know that work on 2.0 started early 2013 but advanced quite slowly for multiple reasons.

Now its time to go out on a limb with announcing Jolokia 2.0 for 2016. A bit of pressure sometimes really helps ;-)

Here’s are the major themes for Jolokia 2.0:

Jolokia 2.0 will be backwards compatible on the protocol level. This is a design goal. There might be some changes in default values, however this should be easy to fix. Any such change will be announced prominently (like artefact renaming). So, all your clients will be usable with 2.0 with minor changes.
JMX Notification support is here. Yeah, this was quite some work. The extensions to the Jolokia 2.0 protocol are able to push notifications in various ways. Currently the agents supports two modes:
- Pull mode will collect JMX notification on the server (agent) side and can be fetched by a client with an HTTP request, which typically happens periodically. This introduces some latencies but is the most robust way to transmit notifications to a client.
- SSE mode uses Server Sent Events for pushing JMX notifications immediately with very low latency. This is the preferred mode if a client supports this (Internet Explorer does not).
The notification support is nearly complete on the agent side, and the Jolokia JavaScript client already supports both modes. In the future more mode like WebSockets or Web-Hooks should be easy to add. The next post will give a demo about the notification support.
Namespaces extend Jolokia beyond JMX which means you can access other entities than JMX MBeans with the very same protocol. This feature is still in the conceptual state but one can easily imagine to access
- Spring Beans
- CDI Objects
- JNDI Directories
- Zookeeper Directories
- ….
the same was as JMX. The namespace is selected as part of the (MBean) name. More on this in this design document. Since this feature would extend the usage pattern of Jolokia quite a bit, I’m not 100% sure whether to include it into 2.0 since it feels a bit against my Unix based education (“do one thing and do it well”).
With the addition of even more features, modularization becomes even more important. Jolokia was and is always picky about its footprint, which is currently 430k for the WAR agent with all features included. Jolokia 2.0 introduces various internal services which can be picked and chosen by repackaging the agent. Or the agent can be extended with own functionality, too. A way for easily packaging and creating agents will be provided either by a Web-UI or by a CLI tool (or both).

In addition there are also some non-functional changes to polish Jolokia a bit:

Non-agent based addition like client libraries, integration tests, JBoss Forge support are extracted into extra GitHub repositories. All this will happen within the GitHub organization jolokia-org. The first project here is the JavaScript client which already moved to a dedicated jolokia-client-javascript repository.
The website will get a face-lift.
Documentation will switch from Docbook to a Markdown or AsciiDoc based format.

Finally some stuff will get dropped. This happens because of limited resources (Jolokia, to be frankly, still doesn’t have a big community, so that most of the work is done by a single person. ‘would like to change that, though) and because I think these feature never took off:

Mule agent. I never got much feedback from the Mule community so I’m really not sure whether this agent is really used or needed. Jolokia 1.x will continue to support the Mule agent, however there will be no stock Jolokia 2.0 Mule agent. Said that, you are always free to adopt Jolokia 2.0 to the Mule management platform. Considering the extra code needed included in Jolokia 1.3 for Mule support this should be fairly trivial. I’m happy to support anyone doing the port. Also, there is always the alternative to use the JVM agent for attaching Jolokia to Mule, which is the preferred way for 2.0 to monitor Mule with Jolokia.
Spring Roo Support will be dropped for much the same reasons. I never received an issue on the Jolokia Spring Roo support, which is a clear sign that nobody is using it. It might popup as an extra project.

So, what’s the roadmap ? Here’s the plan:

Milestone 2.0.0-M1 is here. You find the JVM and WAR agents in Maven central.
Every month, a new milestone will be released.
Final release is aligned to Red Hat Summit / DevNation. July 1st.

Isn’t this a nice new year’s resolution ? ;-)

In the next post I will demo JMX notifications and how you can use them in your JavaScript projects.

Jmx4Perl for everyone

Tue, 28 Jul 2015 00:00:00 +0000

As you might know, Jmx4Perl is the mother of Jolokia. But what might be not so known is, that Jmx4Perl provides a set of nice CLI tools for accessing Jolokia agents. However, installing Jmx4Perl manually is cumbersome because of its many Perl and also native dependencies.

However, if you are a Docker user there is now a super easy way to benefit from this gems.

Even if Perl is not your cup of tea, you might like the following tool (for which of course no Perl knowledge is required at all):

jmx4perl is a command line tool for one-shot querying Jolokia agents. It is perfectly suited for shell scripts.
j4psh is a readline based, JMX shell with coloring and command line completion. You can navigate the JMX namespace like directories with cd and ls, read JMX attributes with cat and execute operations with exec.
jolokia is an agent management tool which helps you in downloading Jolokia agents of various types (war, jvm, osgi, mule) and versions. It also knows how to repackage agents e.g. for enabling security for the war agent by in-place modification of the web.xml descriptor.
check_jmx4perl is a full featured Nagios plugin.

How can you now use these tools ? All you need is a running Docker installation. The tools mentioned above are all included within the Docker image jolokia/jmx4perl which is available from Docker Hub.

Some examples:

# Get some basic information of the server
docker run --rm -it jolokia/jmx4perl \
 jmx4perl http://localhost:8080/jolokia

# Download the current jolokia.war agent
docker run --rm -it -v `pwd`:/jolokia jolokia/jmx4perl \
 jolokia

# Start an interactive JMX shell
# server "tomcat" is defined in ~/.j4p/jmx4perl.config
docker run --rm -it -v ~/.j4p:/root/.j4p jolokia/jmx4perl \
 j4psh tomcat

In these examples we mounted some volumes:

If you put your server definitions into ~/.j4p/jmx4perl.config you can use them by mounting this directory as volume with -v ~/.j4p:/root/.j4p.
For the management tool jolokia it is recommended to mount the local directory with -v $(pwd):/jolokia so that downloaded artefacts are stored in the current host directory. (Note for boot2docker users: This works only when you are in a directory below you home directory)

It is recommended to use aliases as abbreviations:

alias jmx4perl="docker run --rm -it -v ~/.j4p:/root/.j4p jolokia/jmx4perl jmx4perl"
alias jolokia="docker run --rm -it -v `pwd`:/jolokia jolokia/jmx4perl jolokia"
alias j4psh="docker run --rm -it -v ~/.j4p:/root/.j4p jolokia/jmx4perl j4psh"

As an additional benefit of using Jmx4Perl that way, you can access servers which are not directly reachable by you. The Jolokia agent must be reachable by the Docker daemon only. For example, you can communicate with a SSL secured Docker daemon running in a DMZ only. From there you can easily reach any other server with a Jolokia agent installed, so there is no need to open access to all servers from your local host directly.

Finally, here’s a short appetiser with an (older) demo showing j4psh in action.

Jmx4Perl on OS X

Mon, 23 Mar 2015 00:00:00 +0000

The HTTP-JMX Bridge Jolokia allows easy access to JMX. It exposes all JMX information and operations via an REST-like interface and has tons of nifty features. Jmx4Perl on the other side is a client for Jolokia, which beside Perl access modules also provides quite some nice CLI tools for accessing and installing Jolokia. This post explains how install these tools on OS X.

Jmx4Perl provides some nice CLI commands:

jmx4perl is a simple access tool which is useful for quick queries and ideal for inclusion in shell scripts.
j4psh is a powerful interactive, readline based JMX shell with tab completion and syntax highlighting.
jolokia is a tool for managing Jolokia agents (downloading, changing init properties etc.)

All this tools are very helpful in order to explore the JMX namespace and installing the agent. They all are fairly good documented and each of them probably deserves an own blog post.

However, the installation or Perl modules and programs is a bit tedious. Although cpan helps here and also resolves transitive dependencies it’s still a lengthy process, which fails from time to time. Native Linux packages are planned, but don’t hold your breath ;-).

For OS X users with Homebrew can install Jmx4Perl quite easily, though:

$ brew install cpanm
$ cpanm --sudo install JMX::Jmx4Perl

This will do all the heavy lifting for you and at the end all the fine Jmx4Perl tools are installed and available under /usr/local/bin.

j4psh uses libreadline for the input handling. For the best user experience GNU ReadLine is recommended. Unfortunately, OS X doesn’t ship with a true libreadline but with libedit which is a stripped down version of libreadline. In order to use GNU readline, some tricks are needed which are described in this recipe. For me, the following steps worked (but are probably a bit “dirty”):

$ brew install readline
$ brew link --force readline
$ sudo mv /usr/lib/libreadline.dylib /tmp/libreadline.dylib 
$ cpanm --sudo Term::ReadLine::Gnu
$ sudo mv /tmp/libreadline.dylib /usr/lib/libreadline.dylib
$ brew unlink readline

These steps are really only necessary if you need advanced readline functionality (or a coloured prompt in j4psh ;-).

Health Checks with Jolokia

Sat, 17 Jan 2015 00:00:00 +0000

A health check is a useful technique for determining the overall operational state of a system in a consolidated form. It provides some kind of internal monitoring which collects metrics, evaluates them against some thresholds and provides a unified result. Health checks are now coming to Jolokia. This post explains the strategy to include health checks into Jolokia without blowing up the agents to much.

Health checks are different to classical monitoring solutions like Nagios, where external systems collect metrics and evaluate them against some threshold on their own. While monitoring with Nagios was and is always possible with Jolokia (and in fact was the original motivation for creating it), intrinsic health checks were avoided for the vanilla agent up to now because of the extra complexity they introduce into the agent. One of the major design goals of Jolokia is to keep it small and focussed.

The upcoming release 1.3.0 (scheduled for the end of this month) will introduce a simple plugin architecture into Jolokia which allows to hook into the agent’s lifecycle. A so called MBeanPlugin in Jolokia also allows access to the agent configuration and to the JMX system. Currently it is supported for the WAR and JVM agent, where plugins are created via a simple class path lookup. For the OSGi agent it is planned that it will pick up plugins as OSGi services.

Having this new infrastructure in place, extra functionality like health checks can be added easily. The GitHub repository jolokia-extra was created to host various extensions to the Jolokia agent, also to keep the original agent as lean as possible. Beside the new health checks there is already an extension jsr77 for simplifying the access to JSR-77 compliant JEE Servers like WebSphere.

The new health addon in jolokia-extra has just been started. Currently it contains not much more as proof-of-concept with some hardcoded health checks, but it already illustrate the concept: A MBeanPlugin registers a certain SampleHealthCheckMBean during startup which exposes the health checks as JMX operations (and which can be executed as usual with Jolokia). These operations have access to JMX via the MBeanPluginContext and can query any MBean in the system.

But that is only the beginning. There are still a lot of design decisions to take:

How should health check specification look like ? Should it be done via JSON or should a more expressive DSL based e.g. on Groovy should be used ?
How are the health check store on the agent side ?
- Looking them up in the filesystem (from a configurable path with a sane default like ~/.jolokia_healthchecks)
- Baking it into the agent jar
- Uploading it via an MBean operation (and then storing them in the filesystem as well)
What kind of meta data should be provided so that consoles like hawt.io can dynamically create their health check views ?
How should the parameter and return value for the health checks look like ?

If you would like to participate, the discussion about the implementation details will take place in issue #1 and the current working state is summarized in this wiki page.

Spicy Docker Java Images with Jolokia

Thu, 09 Oct 2014 00:00:00 +0000

While on the way of transforming the Jolokia integration test suite from a tedious, manual, half-a-day procedure to a full automated process I ran into and felt in love with Docker. As a byproduct a java-jolokia docker repository emerged, which can be easily used as a Java base image for enabling a Jolokia JVM agent during startup for any Java application.

These images are variants of the official java Java docker image. In order to use the Jolokia agent, a child image should call the script jolokia_opts (which is in the path). This will echo all relevant startup options that should be included as argument to the Java startup command.

Here is a simple example for creating a Tomcat 7 images which starts Jolokia along with Tomcat:

FROM jolokia/java-jolokia:7
ENV TOMCAT_VERSION 7.0.55
ENV TC apache-tomcat-${TOMCAT_VERSION}

EXPOSE 8080 8778
RUN wget http://archive.apache.org/dist/tomcat/tomcat-7/v${TOMCAT_VERSION}/bin/${TC}.tar.gz
RUN tar xzf ${TC}.tar.gz -C /opt

CMD env CATALINA_OPTS=$(jolokia_opts) /opt/${TC}/bin/catalina.sh run

(Don’t forget to use $(jolokia_opts) or with backticks, but not ${jolokia_opts})

The configuration of the Jolokia agent can be influenced with various environments variables which can be given when starting the container:

JOLOKIA_OFF : If set disables activation of Jolokia. By default, Jolokia is enabled.
JOLOKIA_CONFIG : If set uses this file (including path) as Jolokia JVM agent properties (as described in Jolokia’s reference manual. By default this is /opt/jolokia/jolokia.properties. If this file exists, it will automatically be taken as configuration
JOLOKIA_HOST : Host address to bind to (Default: 0.0.0.0)
JOLOKIA_PORT : Port to use (Default: 8778)
JOLOKIA_USER : User for authentication. By default authentication is switched off.
JOLOKIA_PASSWORD : Password for authentication. By default authentication is switched off.

So, if you start your tomcat with docker run -e JOLOKIA_OFF no agent will be started.

Currently this image is available from Docker Hub for the latest versions of Java 6,7 and 8, respectively, as they are provided by the official Docker java image.

Other base images can be easily added by using the configuration and templates from a super simple node based build system.

All appserver images from ConSol/docker-appserver (Docker Hub) are based now on this image, so Jolokia will always be by your side ;-)

Jolokia and CORS

Mon, 18 Aug 2014 00:00:00 +0000

Jolokia has configurable CORS support so that it plays nicely together with the Browser world when it comes to cross origin requests. However, Jolokia’s CORS support is not without gotchas. This post explains how Jolokias CORS supports works, what are the issues and how I plan to solve them.

tldr; Jolokia CORS support is configured via jolokia-access.xml but has issues with authenticated requests which are tackled for the next release 1.3.0

CORS Primer
#

CORS (Cross Origin Resource Sharing) is a specification for browsers to allow controlled access for JavaScript code to locations which are different than the origin of the JavaScript code itself.

In simple cases, it works more or less like this:

A JavaScript code (coming from the original location http://a.com) requests HTTP access via XMLHttpRequest to http://b.com
Since the the origin of the script and target URL of the request differs, the browser adds some extract checking on the response of this request.
The request to b.com contains a header Origin: http://a.com.
The server at b.com answering the request has to decided upon this header whether it wants allow this request. The server decision is contained in the response header Access-Control-Allow-Origin
The value of this header can be either a literal URL (e.g. http://a.com) or a wildcard like in Access-Control-Allow-Origin: * which allows access from any original location.
The browser finally decides whether it returns the response to the JavaScript based on the returned access control header. If not, is throws an exception before handing out the response data.

This is it for simple requests. A simple request has the following characteristics:

HTTP method is either GET,HEAD or POST
The request contains only the following headers
- Accept
- Accept-Language or Content-Language
- Content-Type with the value application/x-www-form-urlencoded, multipart/form-data or text/plain

If this criteria are not match for a request (e.g. because it uses a different method or additional headers), a so called preflight request is sent to the server before the actual request is performed. The preflight is an HTTP request with method OPTIONS and contains the headers Origin (http://a.com in our case), Access-Control-Request-Method for the HTTP method requested and Access-Control-Request-Headers with a comma separated list of additional header names. The server in turn answers with the allowed request methods and headers, whether an authenticated request is allowed and how long the client might cache this answer. An important point is, that a preflight request must not be authenticated.

And in fact, browsers never sent an authentication header with the preflight request even when already authenticated against the target server. More on this later.

Jolokia CORS Support
#

By default, Jolokia allows any CORS request. For the preflight the agent answers with

Access-Control-Allow-Origin: http://a.com
Access-Control-Allow-Headers: accept, authorization, content-type

The allowed headers returned are exactly the same headers as requested. For the real request with an origin header Origin: http://a.com the answer is

Access-Control-Allow-Origin: http://a.com
Access-Control-Allow-Credentials: true

For best computability Jolokia always answers with the provided Origin: which is extracted from the request (except when the origin is null in which case the wildcard * is returned.

This behavior can be tuned by adapting the jolokia-access.xml policy as described in the reference manual :

<cors>
 <allow-origin>http://www.jolokia.org</allow-origin>
 <allow-origin>*://*.jmx4perl.org</allow-origin>

 <strict-checking/>
</cors>

If a <cors> section is present in jolokia-access.xml then only those hosts declared in this sections are allowed. The Origin URLs to match against can be specified either literally or as pattern containing the wildcard *. The optional declaration <strict-checking/> is not really connected to CORS but helps in defending against Cross-Site-Request-Forgery (CSRF). If this option is given, then the given patterns are used for every request to compare it against the Origin: or Referer: header (not only for CORS requests).

CORS and Authentication
#

Since Authorization: is for CORS not a simple header, when authentication is used, preflight checking is always applied. However, there is often a catch 22:

The preflight check using the OPTIONS HTTP Method must not be authenticated as explained above, so browser doesn’t send the appropriate authentication headers when doing the preflight.
The Jolokia agent is typically secured completely no matter which HTTP method is used.
The preflight check fails, the request fails.

The only clean solution is to setup Jolokia Authentication that way that OPTIONS request are not secured.

Let’s have a look at the individual Agents:

JVM Agent
#

Since the JVM agent does all the security stuff on its own, it is not a big deal to introduce this specific behavior. Next one.

WAR Agent
#

The WAR agent use authentication and authorization as defined in the Servlet Specification, i.e. the appropriate <security-constraint> must be added manually to the web.xml (jolokia is a CLI tool which helps in this repackaging). Unfortunately there is no way to secure the same <url-pattern> differently for different HTTP Methods (i.e. secured with an <auth-constraint> for GET and POST, but accessible for everybody for OPTIONS). I tried hard by providing multiple <security-constraint> but failed miserably (if you know how to this, please let me know).

The only solution is to switch over to checking a given role on our own without relying on the declarative JEE security mechanism. Since we can check the role programmatically (HttpServletRequest.isUserInRole()) this should not be that big deal. But it’s still some work ….

OSGi Agent
#

When using an OSGI HttpService adding this behavior should not be difficult since security is handled programmatically here as well (HttpContext.handleSecurity())

Other Agent variants
#

This is the dark matter, because I don’t know where and how Jolokia is integrated directly into a bigger context. I know that ActiveMQ, Karaf and Spring Boot uses Jolokia internally. In order to support authenticated CORS access they probably needs to be changed to allow unauthorized OPTIONS access for everybody. Since this is not under my control I have no idea when and even whether it ever will happen. Generic purpose console like hawt.io rely in some setups on CORS access so it would be real cool if we can get it out there. Help with this is highly appreciated ;-)

Roadmap
#

Since 1.2.2 is already finished and about to be published today, the stuff I can do as described above will go into a 1.3.0. Looking back at my release history this will probably be ready approx. end of august.

Jolokia on Roland Huß

Why Jolokia is not RESTful

JMX resource naming is a mess #

Bulk requests #

Jolokia implements both #