perfino configuration options that cannot be changed in the perfino UI are contained in the text file perfino.properties in the perfino installation directory. You can either edit that text file in a text editor or use the configure executable in the perfino installation directory. The latter presents an organized view of all properties, saves the file even if elevated privileges are required and can restart the perfino server to apply your changes.

The properties themselves are documented with comments in perfino.properties. Here, a couple of scenarios are discussed where it is necessary to adjust the default parameters.

Data directory

The dataDirectory property points to the directory where all variable data is located. The following subdirectories are created by perfino:

• db

  Contains the embedded H2 database.

• log

  Contains all log files. By default, log files are rotated. The rotation settings can be changed in the log4j.properties file in the perfino installation directory. Different settings can be applied to the three different log files, "server", "connection" and "event". All log files can be viewed in the perfino UI.

• snapshots

  Memory snapshots and profiling snapshots are saved in this directory. These snapshots can be downloaded or deleted in the "Snapshots" view in perfino.

• ssl

  This directory contains the file pair agent.ks / server.ks for authentication and encryption as well as the SSL certificate for the web server.

If you run two perfino servers on the same machine, they have to have different data directories. By default, the installer always suggests the same location for the data directory, so in the case of multiple installations you have to adjust it in the installer or after the installation in the perfino.properties file.

Web server

perfino comes with a built-in web server that listens on port 8020 by default. You can adjust that port with the httpPort property and switch to HTTPS by setting useHttps to true.

When you use HTTPS, perfino will generate a self-signed certificate ssl/self_signed.ks in the perfino data directory. Browsers will display warning messages with this certificate. If you have a certificate signed by a recognized certificate authority, you can copy it in PKCS12 format to ssl/web.pkcs12. If the certificate file has a different name, you can specify the keystoreName property.

If the certificate is protected with a password, you can specify it in the keystorePassword property. While the password cannot be encrypted, it can at least be obfuscated with the command line tool perfino_obfuscate:

perfino_obfuscate [password]

If you put perfino behind a reverse proxy, you have to set the reverseProxy property to true. The web server will then analyze the proxy headers to create correct URLs. If this should not work due to a problem with the reverse proxy, set the reverseProxyHost to the host name of the proxy.

If you have infrastructure that can check the health of a web server by making an HTTP GET request, you can set the healthCheckPort to a non-zero value to create such an HTTP port in perfino. Any HTTP request to that port will return a document with HTML mime type and the text "Alive". For example, Amazon Web Services provides a health check service that is used by Route 53 to determine if an IP address can be routed to or not.

The REST API service is enabled by setting the apiPort property to a non-zero value. You cannot set it to the same port as the web server. The REST API port uses the same protocol (HTTP/HTTPS) as configured for the web server.

Communication with monitored VMs

Monitored VMs create a TCP connection on the port that is configured with the vmPort property.

By default, the communication between monitored VMs and the perfino collector is unencrypted and unauthenticated. This means that every VM can connect to the perfino server and the perfino agent has no way of knowing if the perfino server on the other side can be trusted. This can be acceptable in certain local area networks, but it is not suitable for connecting over WANs or even over the internet.

To enable authentication and encryption set the property vmUseSsl to true. In that case, the file pair ssl/agent.ks and ssl/server.ks will be created. Now, the server will only allow connections from agents who possess the agent.ks file and agents will only connect to servers who have the server.ks file. In addition, the communication protocol will be encrypted.

For more information on this topic, see the chapter on monitoring JVMs.

Remote perfino UI

Running the perfino UI on a different server than the collector can have two purposes. First, it allows you to split the server load of the UI and the collector to separate machines, which is a good idea if you have many users. Second, some network topologies require that the collector runs in one and the perfino UI in another network. For example, if the collector runs in an internal network that is protected by a dual firewall, and the perfino UI should be available to the outside, the perfino UI has to run on a machine in the DMZ.

The first change you have to make is to set the startRemoteServer property to true. Then, the perfino server will listen for remote perfino UIs on the port configured with the remoteServerPort property.

The perfino UI can be deployed as a WAR file to a servlet container like Tomcat or Jetty. The WAR file has to be generated with the deploy tool in the deploy directory of your perfino installation. It will create the file perfino-standalone.war in the same directory.

In the application server, define the JNDI property perfino/server with a value of "server name"[:port] where "server name" is the name or IP address of the server where the perfino collector server is running. The port is optional and defaults to 1099 unless you have configured the remoteServerPort property differently. Then, deploy the generated WAR file into your application server. The perfino web application will make an RMI connection to the configured data collection server automatically.