Wednesday, May 2, 2018

How to Connect to Alfresco with JConsole for JMX Access

The most straight-forward and basic way to make configuration changes in Alfresco is to stop Alfresco. Open alfresco-global.properties file (in tomcat/shared/classes sub-directory), make settings changes, save them and then start Alfresco. If you are making long-term changes to a production environment, this is the best way to go about doing that. However, before you can make these well-thought-out changes to production, it is a good idea to test them first in a test, staging or QA environment. But making changes to the configuration in global properties can be a bit time consuming. Were you aware that you can make most changes to Alfresco using JMX without a restart? Most Java applications do allow for this if they have enabled the JMX protocol.

The Java Management Extension (JMX) interface allows you to make changes to Alfresco Content Services through a JMX client that supports JMX Remoting (JSR-160). This client called JConsole allows you to:

  • Manage subsystems (includes many configuration setting changes)
  • Change log levels
  • Enable or disable file servers (FTP/CIFS)
  • Set the server to read-only mode
  • Set the server to single-user mode
  • Set server maximum user limit, including ability to prevent further logins
  • Count user sessions/tickets
  • User session/ticket invalidation

Setting up Alfresco for JMX connections

In order to allow for Alfresco to make use of JMX, we'll need to add a few settings to a Alfresco.

In alfresco-global.properties we add:

alfresco.jmx.connector.enabled=true
alfresco.rmi.services.port=50500
alfresco.rmi.services.host=<hostname>

For alfresco.rmi.services.host, make sure you are setting a hostname that is externally and internally resolvable. When you start Alfresco, you can make sure that JMX is enabled by running in Linux:

# sudo lsof -i :50500
COMMAND   PID USER   FD   TYPE   DEVICE SIZE/OFF NODE NAME
java    13248 root  552u  IPv6 13356213      0t0  TCP *:50500 (LISTEN)

You should of course, see a running process listening on 50500.

Running JConsole

If you happen to have GUI access on the server you are running Alfresco, you can run the following to start jconsole:

If you have a full JDK installed, you can typically run:

# jconsole

or

# java/bin/jconsole

If using Alfresco's JRE:

# java/bin/java -jar java/lib/jconsole.jar

If you can pull up jconsole, you can typically connect to Alfresco using the Local Process option. This won't require a long and complex URL or username/password. If you use the jconsole executable, you choose Local Process (make sure you select the running Tomcat process)



Next, you'll see a pop-up box showing insecure connection. Go ahead and click on the Insecure connection button.


Once it starts up, you'll see the start up window.



Click on the MBeans tab at the top and you should then see the Alfresco drop-down line.



If you have to use the Alfresco JRE, you will first need to add the JMX url and a username/password combo to get in.



You will need to add the following:


  • URL: service:jmx:rmi:///jndi/rmi://localhost:50500/alfresco/jmxrmi
  • Username: controlRole
  • Password: change_asap


Keep in mind that these are the default properties. It is possible that maybe an admin may have changed the username and passwords. In that case, you'll need to have a look through these files to get that information:


  • alfresco-jmxrmi.password
  • alfresco-jmxrmi.access


Keep in mind that this process will also allow you to connect to a remote Alfresco server provided you are on the same network.

Now, if your Alfresco install is in an AWS environment, you will need to follow a little bit of a different process. For reasons I don't fully understand, jconsole seems to have a difficult time making a direct connection to Alfresco running in AWS. What I've found that works is using an ssh tunnel to get to it.

To get this to work, you can run ssh client using a console on your workstation:

# ssh -D 1234 username@hostname

Next, you can run jconsole using a socket proxy:

# jconsole -J-DsocksProxyHost=localhost -J-DsocksProxyPort=1234

Note that this also works with jvisualvm:

# jvisualvm -J-DsocksProxyHost=localhost -J-DsocksProxyPort=1234

For jconsole, you then would fill in the rest of the URL, username and password in the dialog box and you should be able to get in.

service:jmx:rmi:///jndi/rmi://<hostname>:50500/alfresco/jmxrmi