AHMED ZBYR

AHMED ZBYR

Biker, EV Enthusiast

Zabbix 2.0 introduced native support for monitoring JMX applications through the Zabbix Java gateway. This Java-based daemon acts as an intermediary, allowing the Zabbix server to retrieve JMX counter values from remote applications. The beauty of this approach is that the target application only needs to be started with the -Dcom.sun.management.jmxremote option; no additional software installation is required on the monitored host. This guide provides a detailed walkthrough of installing and configuring the Zabbix Java gateway on CentOS 6.5.

Understanding zabbix-java-gateway Architecture

The zabbix-java-gateway facilitates communication between the Zabbix server and JMX-enabled applications, effectively translating Zabbix requests into JMX queries. Here’s a breakdown of the process:

  1. JMX Configuration: You configure the Java application (e.g., Tomcat, JBoss) to expose JMX metrics by setting specific JAVA_OPTS.
  2. Zabbix Host Configuration: In the Zabbix server UI, you add a host and configure a JMX Interface, specifying the IP address and port where the Java application exposes its JMX data.
  3. Communication Flow: The zabbix-server communicates with the zabbix-java-gateway on port 10053 (by default). The gateway then communicates with the JMX-enabled application (e.g., Tomcat) on the port defined in the JAVA_OPTS (e.g., 12345).
  4. Data Retrieval: The zabbix-java-gateway retrieves JMX data from the application based on requests from the Zabbix server and sends the data back to the server.
	[Zabbix-Server] 
                |
                +--(port:10053)--> 
                               [zabbix-java-gateway] 
                                          |
                                          +--(port:12345)--> 
                                                    [JMX enabled server, Example:Tomcat/WebServer]

Step 1: Installing zabbix-java-gateway on the Zabbix Server

This step assumes you have a Zabbix server already installed and configured. If not, refer to the official Zabbix documentation for server installation instructions. The zabbix-java-gateway should ideally be installed on the same server as the Zabbix server, although it can be installed on a separate machine.

Open a terminal on your Zabbix server and execute the following command:

[ahmed@ahmed-server ~]$ sudo yum install zabbix-java-gateway

This command utilizes yum, the package manager for CentOS, to download and install the zabbix-java-gateway package along with its dependencies.

Step 2: Configuring the Host with JMX (Example: Tomcat)

This step focuses on configuring the Java application you want to monitor using JMX. We’ll use Tomcat as an example, but the principles apply to other JMX-enabled applications.

  1. Locate setenv.sh: Navigate to the bin directory within your Tomcat installation (e.g., apache-tomcat-7/bin/). If the setenv.sh file doesn’t exist, create it. This script allows you to set environment variables specifically for Tomcat.

  2. Add JMX Options: Open setenv.sh in a text editor and add the following lines:

export JAVA_OPTS="$JAVA_OPTS\
 -server\
 -Xms1024m\
 -Xmx2048m\
 -XX:MaxPermSize=256m\
 -XX:MaxNewSize=256m\
 -XX:NewSize=256m\
 -XX:SurvivorRatio=12\
 -Dcom.sun.management.jmxremote\
 -Dcom.sun.management.jmxremote.port=12345\
 -Dcom.sun.management.jmxremote.authenticate=false\
 -Dcom.sun.management.jmxremote.ssl=false"

Explanation of Options:

  • -Dcom.sun.management.jmxremote: Enables JMX remote monitoring.
  • -Dcom.sun.management.jmxremote.port=12345: Specifies the port on which the JMX agent will listen for connections. Important: Choose a port that is not already in use and ensure it’s open in your firewall.
  • -Dcom.sun.management.jmxremote.authenticate=false: Disables authentication for JMX connections. Warning: For production environments, never disable authentication. See the security notes below.
  • -Dcom.sun.management.jmxremote.ssl=false: Disables SSL encryption for JMX connections. Warning: For production environments, always enable SSL. See the security notes below.
  • -Xms1024m -Xmx2048m: Sets the initial and maximum heap size for the JVM. Adjust these values based on your application’s memory requirements.
  • -XX:MaxPermSize=256m: Sets the maximum size of the permanent generation (PermGen) memory space. (Relevant for older JVMs, less so for Java 8 and later).
  • -XX:MaxNewSize=256m -XX:NewSize=256m: Configures the young generation size for garbage collection.

  1. Restart Tomcat: After saving the setenv.sh file, restart your Tomcat server for the changes to take effect.

    apache-tomcat-7/bin/shutdown.sh
apache-tomcat-7/bin/startup.sh

Security Considerations:

Disabling authentication and SSL is highly discouraged in production environments. To secure your JMX connection, you should:

  • Enable Authentication: Set com.sun.management.jmxremote.authenticate=true. You will then need to configure a password file for JMX authentication. Refer to the Java documentation for details on configuring JMX authentication.
  • Enable SSL: Set com.sun.management.jmxremote.ssl=true. You will need to generate and configure certificates for secure JMX communication. Refer to the Java documentation for details on configuring JMX with SSL.

Step 3: Configuring zabbix-server.conf

This step involves configuring the Zabbix server to connect to the zabbix-java-gateway.

  1. Locate zabbix_server.conf: The configuration file is typically located in /etc/zabbix/zabbix_server.conf.

  2. Edit zabbix_server.conf: Open the file in a text editor and locate the following lines (they might be commented out):

### Option: JavaGateway
#        IP address (or hostname) of Zabbix Java gateway.
#        Only required if Java pollers are started.
#
#  Mandatory: no
#  Default:
#JavaGateway=

### Option: JavaGatewayPort
#        Port that Zabbix Java gateway listens on.
#
#  Mandatory: no
#  Range: 1024-32767
#  Default:
#JavaGatewayPort=

### Option: StartJavaPollers
#        Number of pre-forked instances of Java pollers.
#
#  Mandatory: no
#  Range: 0-1000
#  Default:
#StartJavaPollers=
  1. Uncomment and Configure: Uncomment the lines and configure them as follows:
### Option: JavaGateway
#        IP address (or hostname) of Zabbix Java gateway.
#        Only required if Java pollers are started.
#
#  Mandatory: no
#  Default:
JavaGateway=10.10.18.27  # Replace with the actual IP address of your Zabbix Java gateway

### Option: JavaGatewayPort
#        Port that Zabbix Java gateway listens on.
#
#  Mandatory: no
#  Range: 1024-32767
#  Default:
JavaGatewayPort=10053  # Default port for Zabbix Java gateway

### Option: StartJavaPollers
#        Number of pre-forked instances of Java pollers.
#
#  Mandatory: no
#  Range: 0-1000
#  Default:
StartJavaPollers=5  # Adjust the number of Java pollers based on your monitoring needs

Explanation:

  • JavaGateway: Specifies the IP address or hostname of the server where the zabbix-java-gateway is running. If the gateway is on the same server as the Zabbix server, use its IP address (e.g., 127.0.0.1 or the server’s actual IP).
  • JavaGatewayPort: Specifies the port on which the zabbix-java-gateway is listening (default is 10053).
  • StartJavaPollers: Determines the number of pre-forked instances of Java pollers. Adjust this value based on the number of JMX metrics you plan to monitor. A value of 5 is a good starting point.

  1. Restart Zabbix Server: After making these changes, restart the Zabbix server for the configuration to take effect.

    sudo service zabbix-server restart

Step 4: Configuring zabbix-java-gateway

This step configures the zabbix-java-gateway itself.

  1. Locate zabbix_java_gateway.conf: The configuration file is typically located in /etc/zabbix/zabbix_java_gateway.conf.

  2. Edit zabbix_java_gateway.conf: Open the file in a text editor and locate the following lines:

### Option: zabbix.listenIP
#        IP address to listen on.
#
#  Mandatory: no
#  Default:
#LISTEN_IP="0.0.0.0"

### Option: zabbix.listenPort
#        Port to listen on.
#
#  Mandatory: no
#  Range: 1024-32767
#  Default:
#LISTEN_PORT=10053

### Option: zabbix.pidFile
#        Name of PID file.
#        If omitted, Zabbix Java Gateway is started as a console application.
#
#  Mandatory: no
#  Default:
#PID_FILE=

#PID_FILE="/var/run/zabbix/zabbix_java.pid"

### Option: zabbix.startPollers
#        Number of worker threads to start.
#
#  Mandatory: no
#  Range: 1-1000
#  Default:
#START_POLLERS=5
  1. Uncomment and Configure: Uncomment the lines and configure them as follows:
### Option: zabbix.listenIP
#        IP address to listen on.
#
#  Mandatory: no
#  Default:
LISTEN_IP="10.10.18.27"  # Replace with the IP address of the Zabbix Java gateway

### Option: zabbix.listenPort
#        Port to listen on.
#
#  Mandatory: no
#  Range: 1024-32767
#  Default:
LISTEN_PORT=10053

### Option: zabbix.pidFile
#        Name of PID file.
#        If omitted, Zabbix Java Gateway is started as a console application.
#
#  Mandatory: no
#  Default:
#PID_FILE=

PID_FILE="/var/run/zabbix/zabbix_java.pid"

### Option: zabbix.startPollers
#        Number of worker threads to start.
#
#  Mandatory: no
#  Range: 1-1000
#  Default:
START_POLLERS=5

Explanation:

  • LISTEN_IP: Specifies the IP address on which the zabbix-java-gateway will listen for connections. If you’re running the gateway on the same server as the Zabbix server, you can use the server’s IP address or 127.0.0.1.
  • LISTEN_PORT: Specifies the port on which the zabbix-java-gateway will listen (default is 10053). This must match the JavaGatewayPort setting in zabbix_server.conf.
  • PID_FILE: Specifies the path to the process ID (PID) file. Uncomment this line to enable the creation of a PID file.
  • START_POLLERS: Determines the number of worker threads to start. Adjust based on your monitoring load; 5 is a good starting point.
  1. Start the zabbix-java-gateway:
sudo service zabbix-java-gateway start
  1. Verify the Gateway is Running:
sudo service zabbix-java-gateway status

This command should indicate that the zabbix-java-gateway is running. You can also check the logs for any errors. The log file is typically located at /var/log/zabbix/zabbix_java_gateway.log.

Step 5: Configuring the Host in Zabbix UI

Now, you need to configure the host in the Zabbix web interface to use the JMX interface.

  1. Login to the Zabbix Web Interface: Access your Zabbix web interface using your browser.

  2. Navigate to Configuration -> Hosts: Go to the “Configuration” section and then select “Hosts.”

  3. Create or Edit a Host: Create a new host or edit an existing one that corresponds to the Java application you configured in Step 2.

  4. Add JMX Interface: In the host configuration, go to the “Interfaces” tab and click “Add.” Select “JMX” as the interface type.

  5. Enter JMX Details:
    • IP address: Enter the IP address of the server where the Java application is running.
    • Port: Enter the JMX port you configured in the setenv.sh file (e.g., 12345).
  6. Add JMX Items: Create JMX items to monitor specific JMX metrics. You’ll need to know the object name and attribute name for the JMX metrics you want to monitor. You can use tools like JConsole or VisualVM to browse the JMX metrics exposed by your Java application.

Troubleshooting

  • Gateway Not Running: Check the zabbix-java-gateway logs (/var/log/zabbix/zabbix_java_gateway.log) for errors. Ensure the service is started.
  • Connection Refused: Verify that the firewall on both the Zabbix server and the server running the Java application allows communication on ports 10053 (for the gateway) and the JMX port (e.g., 12345).
  • No Data Received: Double-check the JMX configuration in setenv.sh, the zabbix_server.conf, and the zabbix_java_gateway.conf files. Ensure the correct IP addresses and ports are configured. Verify that the JMX items in Zabbix are configured correctly with the correct object names and attribute names.
  • Java Pollers Not Starting: Ensure that StartJavaPollers is set to a value greater than 0 in zabbix_server.conf and that the Zabbix server has been restarted.

Conclusion

By following these steps, you should have successfully installed and configured the Zabbix Java gateway and be able to monitor JMX applications using Zabbix. Remember to prioritize security in production environments by enabling JMX authentication and SSL. This comprehensive guide provides a solid foundation for monitoring your Java applications with Zabbix.

You May Also Enjoy