How to remote debug Datafari

Valid from Datafari X.X

The way you will debug Datafari depends on the component you want to debug ! According to the module you want to debug, you will need to open a debug port on the right component JVM.

For any webapp related class or jsp file, the tomcat JVM is concerned;
For any Manifoldcf connector, the Manfifoldcf agent and tomcat MCF JVM are concerned;
For any lib or class used by Solr (eg update processor, plugin), the Solr JVM is concerned.

To enable remote debug on a JVM, you must set the following java option in the start script of the JVM:

-agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=n

This will allow IDEs (Integrated Development Environment) to connect to the port specified by the address parameter to debug the JVM. The suspend parameter can be set to 'y' to tell the JVM to only start once an IDE is connected, this can be useful when you want to debug something that happens at the very beginning of the JVM start and cannot be triggered on purpose for instance.

Be careful with the address, in case you are debuging several components, be sure to have a different address for each component and be also sure that the specified address is not already used by another process on the machine !

Here is the location of the file to modify in order to add the remote debug java option for each component of Datafari:

Component	Location of the file to modify	Where to set the java option

Component	Location of the file to modify	Where to set the java option
Tomcat (Datafari main webapp)	[DATAFARI_HOME]/tomcat/bin/setenv.sh	The file already contains a commented line that you just need to uncomment (and adjust the `address` parameter if needed) to enable the remote debug: `#CATALINA_OPTS="$CATALINA_OPTS -agentlib:jdwp=transport=dt_socket,server=y,address=8696,suspend=n"`
Tomcat MCF	[DATAFARI_HOME]/tomcat-mcf/bin/setenv.sh	The file already contains a commented line that you just need to uncomment (and adjust the `address` parameter if needed) to enable the remote debug: `#CATALINA_OPTS="$CATALINA_OPTS -agentlib:jdwp=transport=dt_socket,server=y,address=8697,suspend=n"`
ManifoldCF agent	[DATAFARI_HOME]/mcf/mcf_home/options.env.unix	As we cannot add comments to this file, unlike the other components, there is no prepared line. You will need to add the following line (and adjust the `address` parameter if needed) to any place in the file:
Solr	[DATAFARI_HOME]/solr/bin/solr.in.sh	The file already contains a commented line that you just need to uncomment (and adjust the `address` parameter if needed) to enable the remote debug:

Once the java option correctly set, you will need to restart the concerned component: https://datafari.atlassian.net/wiki/spaces/DATAFARI/pages/2852716547

After that you will be able to perform remote debugging with your favorite IDE. For instance, using Eclipse as an IDE, if we want to debug a servlet in the Datafari webapp, after having modified the setenv.sh file to enable remote debug on port 8696, we simply need to configure a debug configuration on the datafari-webapp module as follow:

Eclipse example

IntelliJ example

Then in the Debug configuration window, we need to double click on the “Remote Java Application” option to create a new remote debug conf of a JVM associated to the selected module:

In the right panel we can set several options, like the name of the debug configuration, but also the host and port of the JVM we want to connect to:

The host depends on the location of the JVM you want to debug. If it is on the same machine where you are running your IDE then it is ‘localhost', otherwise it is the hostname of the machine holding the JVM you want to debug (in that case you will need to be sure that a connection on the specified port is allowed between the machine running the IDE and the machine running the JVM to debug).

Connection Type selected on Socket Attach is suitable for most cases when you want to debug a VM and attach your source code to it. Connection Type selected on Socket Listen is suitable for listening incoming connections.

Once everything is correctly configured you can click on the “Apply” button, then on the “Debug” button. The IDE will connect to the JVM and you will be able to set breakpoints in the code as if you were debugging a local application.

Debugging on a remote Datafari Server

Depending on your environment when working on the customer's Datafari, there are several ways to remote debug you can try:

You must be connected to the customer’s VPN network.

If you can’t launch debugging, check the connection to the server port: nc -zvw3 datafari_server_IP port, for example nc -zvw3 10.42.9.7 8696. If the connection fails, ask for the port to be opened for external use.

First method

Considering the method explained above for local debug, there are 2 parameters to modify:

in the java option of the JVM, add “*:" to the addres parameter: address=*:8696
in your IDE, specify the IP address where the component affected is located for the Host parameter of the Remote Debug script.

For example, if we consider debugging the datafari-webapp module of a Datafari installed on a server whose IP address is 10.42.9.7 on a VPN network:

The command line for the “[DATAFARI_HOME]/tomcat/bin/setenv.sh" file:

Second method

If the first method does not work, you must redirect the port of the Datafari component you wish to debug.

For example, on a client server, all the elements described above remain valid, except for this difference: it is necessary to redirect the server desired port to the localhost:desired_port, for example to debug the webapp (Tomcat on port 8696 as described above):

Then, your IDE configuration is the same as above.