Wowza media server software can be managed and monitored through a Java Management Extensions (JMX) interface. JMX is a standards-based technology for exposing Java application components through a unified object interface. This interface can then be consumed by open source and commercial monitoring tools such as HP OpenView, OpenNMS, JConsole, and VisualVM. This article describes how to enable the JMX interface for Wowza media server software and manage it using JConsole.
Local Management Using JConsole
Remote JMX Interface Configuration
Authenticate, PasswordFile, AccessFile
JConsole is a general-purpose tool for managing a Java-based server. JConsole communicates with Java servers using the Java Management Extensions (JMX) protocol. The Wowza media server exposes a rich set of objects for monitoring the server. The Java virtual machine also exposes a set of JMX objects that can be used to monitor the virtual machine.
The easiest way to view these objects is to use the JConsole applet that ships with the Java Development Kit (JDK) of most popular VMs. This tool is usually located in the [java-install-dir]/bin folder that's created by the JDK installation. This location differs based on platform:
- JDK version 6 (or later) is required to work with Wowza media server software. We recommend installing the most recent version of the Java JDK for your platform.
- Most Java Runtime Environment (JRE or JVM) vendors require that you install the full JDK to get the JConsole management and monitoring application. See your vendor's documentation for more information.
The Attributes panel has attributes that are attached to this object. Some values are read-only and others are read-write. If you double-click on a read-write value, you can change its value in a live running server. Read-only integer values can be graphed by double-clicking on them.
The Operations panel has methods that are attached to this object that use normal parameters (String, int, long). You can execute methods by entering values for the parameters and clicking that operations button.
Local Management Using JConsole
By default, the Wowza media server files [install-dir]/bin/startup.bat and [install-dir]/bin/startup.sh are configured to expose the JMX object interface to a locally running copy of JConsole. To view the JMX interface, start the Wowza media server, and then run JConsole. In JConsole, you should see a list of the running Java virtual machines that expose a JMX interface. The Wowza media server is listed as com.wowza.wms.bootstrap.Bootstrap start. Select this item, and then click Connect.
You can then explore the different tab panels that are included in JConsole. The Wowza media server management objects are located under the MBeans tab in the WowzaMediaServerPro group.
Remote JMX Interface Configuration
By default, the startup and service scripts are configured to only expose the JMX interface to a locally running monitoring application. You can also configure a remote JMX interface for monitoring the Wowza media server from a remote computer. Both the JVM and Wowza media server include remote JMX interfaces. It's only necessary to configure one of these remote interfaces to enable remote monitoring. We recommend that you use the Wowza media server remote interface because it's easier to configure and can be properly exposed through hardware-based and software-based firewalls.
The remote JMX interface that's built-in with the Wowza media server can be configured through the JMXRemoteConfiguration and AdminInterface containers in the [install-dir]/conf/Server.xml file. This section describes the configuration settings.
JMXRemoteConfiguration - Enable, IpAddress, RMIServerHostName, RMIConnectionPort, RMIRegistryPort
The Enable setting is a Boolean value that can be either true or false. It's the "switch" to enable and disable the remote JMX interface. The default value is false. Setting this value to true (with no further modifications to the other settings) enables the remote JMX interface with authentication. The default user name/password is admin/admin. The URL for invocation in JConsole is:
The IpAddress and RMIServerHostName settings work together to expose the JMX interface to the network. In general, set the IpAddress value to the internal IP address of the Wowza media server and the RMIServerHostName value to the external IP address or domain name of the computer. For example, if the Wowza media server is behind a network-translated IP address (NAT), such that the internal IP address of the server is 192.168.1.7 and the external IP address is 188.8.131.52, the two settings should be:
With this configuration, you would use the following URL to connect to the JMX interface:
The RMIConnectionPort and RMIRegistryPort settings control the TCP ports that are used to expose the RMI connection and RMI registry interfaces. You should only change these values if the Wowza media server reports port conflicts during startup. The default values for these settings are 8084 and 8085 respectively. The RMIConnectionPort corresponds to the first port number in the connection URL and the RMIRegistryPort to the second.
The IpAddress, RMIConnectionPort, and RMIRegistryPort settings affect the connection URL in the following way:
If the remote JMX interface is enabled, the Wowza media server will log the URL of the currently configured JMX interface when it starts. This is probably the most reliable way to determine the JMX URL to use to connect to the server.
To enable remote JMX monitoring through software-based and hardware-based firewalls, open TCP communication for the two ports defined by the RMIConnectionPort and RMIRegistryPort settings.
JMXRemoteConfiguration - Authenticate, PasswordFile, AccessFile
The Authenticate setting is a Boolean value that can be either true or false. It's the "switch" to enable and disable remote JMX interface authentication. The PasswordFile and AccessFile settings are the full path to the JMX password and access files respectively. These files define three named users:
admin monitorRole controlRole
To be functional, a user must have an entry in both the password and the access files.
The password file is a text file with one line per user. Each line contains a username followed by a space and the password for that username (the default password is admin). For an example, see the [install-dir]/conf/jmxremote.password file.
The access file is a text file with one line per user. Each line contains a username followed by a space and a value that defines the permitted access for that username (the default value is readonly). For an example, see the [install-dir]/conf/jmxremote.access file. In the jmxremote.access file, acceptable values to define permitted access for a user are readonly and readwrite. To change the access permissions for any named user, open the jmxremote.access file in a text editor, change the value for the user, and then restart the media server software to apply the changes.
- Some Java Runtime Environments (JREs) require that both the password and access files have read-only privileges. On Linux operating systems, this can be achieved by setting the permissions on both files to 600:chmod 600 conf/jmxremote.access chmod 600 conf/jmxremote.password
- For more information about restricting permissions, see Password files and Access files.
JMXRemoteConfiguration - SSLSecure
The SSLSecure setting is a Boolean value that can be either true or false. It's the "switch" to enable and disable the remote JMX interface over Secure Sockets Layer (SSL). Do the following to configure SSLSecure.
- Open your [install-dir]/conf/Tune.xml file in a text editor and add the following VMOption:
<VMOption>-Dcom.sun.management.jmxremote.port=[port] -Djavax.net.ssl.keyStore=[yourKeyStore] -Djavax.net.ssl.keyStorePassword=[yourPassword] -Dcom.sun.management.jmxremote.password.file="[jmxremote.password]" -Dcom.sun.management.jmxremote.ssl.need.client.auth=true</VMOption>Where:
- [port] is replaced with 9999 or another available port.
- [yourKeyStore] is replaced with the full path and name of your keystore file.
- [yourPassword] is replaced with the password for your keystore.
- [jmxremote.password] is replaced with the full path and name of your jmxremote.password file.
- Restrict permissions for JMX user roles as well as for the operating system. To restrict JMX user permissions, update the jmxremote.password file as described in JMXRemoteConfiguration - Authenticate, PasswordFile, AccessFile, above. To restrict operating system permissions, set the owner's operating system permissions to readonly and remove all other permissions.
- Launch the JConsole client with the following options:
jconsole -J-Djavax.net.ssl.trustStore=[yourTrustStore] -J-Djavax.net.ssl.trustStorePassword=[yourPassword]Where:
- [yourTrustStore] is replaced with the full path and name of your truststore file.
- [yourPassword] is replaced with the password for your truststore.
Note: SSL configuration can be quite involved and additional configuration may be required. For more information about how to enable SSL with JMX, see Using SSL.
AdminInterface/ObjectListThe AdminInterface/ObjectList setting is a comma-separated list of object types that you can expose through the JMX interface. This list can contain any number of the following items:
Server - Server-level connection and performance info and notifications VHost - Information about currently running virtual hosts VHostItem - Details of currently configured virtual hosts Application - Application-level connection and performance info ApplicationInstance - Application Instance-level connection and performance info Module - Details of currently loaded modules MediaCaster - Details of media caster object (live stream repeater) Client - Details of each connected Flash session MediaStream - Details of each individual server-side NetStream object SharedObject - Details of currently loaded shared objects Acceptor - Details of currently running host ports or TCP ports IdleWorker - Details of currently running idle workers
- Open the Services console (Start > Control Panel > Administrative Tools > Services).
- Right-click the Wowza media server service, and then select Properties.
- On the Log On tab, change the Log on as option to This account, and then enter a user name and password for a local user.
Remote Management Using JConsole
JConsole can be used to monitor a remote Wowza media server. After you configure the remote JMX interface (see Remote JMX Interface Configuration), run JConsole and then enter the remote JMX interface URL in the Remote Process field. The default remote JMX interface URL for the JMX interface that's built-in with the Wowza media server is:
This section describes the more important top-level objects that can be used to monitor Wowza media server performance and uptime. This section doesn't cover every object that's exposed by the server. These objects are available under the WowzaMediaServer object in the MBeans section of JConsole.
Server: The server object contains information about when the server was started and how long it has been running.
VHosts: The VHosts collection includes information about each of the running virtual hosts. From here, you get access to each of the running applications and applications instances. At each level of the hierarchy (Server, VHost, Application, ApplicationInstance), you can get detailed information about the number of connections (Connections object) and the input/output performance (IOPerformance object).
IOPerformance: The Server exposes IOPerformance objects at many different levels of the object hierarchy. These objects can be used to monitor server performance and throughput at that section of the server. For example, the IOPerformance object under a particular VHost displays the throughput of that particular virtual host.
Connections: The Server exposes Connections objects at many different levels of the object hierarchy. These objects can be used to monitor client connections at that section of the server. For example, the Connections object under a particular Application object displays the current number of clients that are connected to that particular application.
VHost/[vHostName] - HandlerThreadPool, TransportThreadPool: The HandlerThreadPool and TransportThreadPool objects expose information about each of the worker thread pools that are owned by each of the virtual hosts. You can use this object to monitor thread usage and load.
ServerNotifications: The ServerNotifications object publishes notification events related to the connection limits and connection bursting capabilities of the Wowza media server. The Wowza media server can generate the following notification events:
com.wowza.wms.connect.WarningServerLicenseLimit - connection accepted in bursting zone (warning) com.wowza.wms.connect.ErrorServerLicenseLimit - connection refused due to license limit com.wowza.wms.connect.WarningVHostLimit - connection refused due to virtual host limit
Monitoring and Management Using JMX Technology
If you're having problems or want to discuss this article, post in our forum.