[frs-252] Manual Instance installation in FR 4


This procedure applies to FusionReactor 4.x and above.

Introduction

The normal method for installing FusionReactor into a J2EE container is to use the FusionReactor Administration Manager's Instance Manager. This page, located in Instances -> Instance Manager, allows you to easily administer all instances present on a single machine.

If FusionReactor doesn't detect your instance, you may have to install it manually. There are some caveats to this process:

  • The instance will not be displayed within the Instance Manager.
    • You won't be able to use the IM to administer it. Internal webserver port, IP address and the "Bind to all interfaces" flag will only be changed by editing the fram.conf file (more on that later).
  • The instance will be unable to use the FusionReactor Administration Manager to offload the zipping of logfiles, or the shipping of logfiles to FusionAnalytics.

Procedure

This procedure has been developed for Unix-type operating systems, including Linux. FusionReactor may be installed manually on windows, by changing the corresponding paths. A Windows-specific template configuration is available, and this is noted later in this procedure.

Prerequisites

The following list outlines the prerequisites which must be fulfilled prior to beginning this procedure.

  • The target J2EE container must be installed and running.
  • If you have previously installed FusionReactor 3.x manually, this must be uninstalled.
    • The FusionReactor filter definition, which is inserted usually in a web.xml (or default-web.xml) must be removed.
    • The FusionReactor installation folder (Unix: /opt/fusionreactor, Windows: C:FusionReactor) must be removed.
  • You should know in which file your J2EE server defines its servlets and filters. You'll need to know this in order to add the FusionReactor filter later.

This will give a clean environment in which FR4 can be installed.

Installing FusionReactor Administration Manager

The FusionReactor Administration Manager, or FRAM, is a cut-down version of FusionReactor which runs inside its own server, and provides administrative and monitoring functionality for other FusionReactor instances.

Although, as a manual install, you won't be able to take advantage of these functions, FRAM does contain an instance template which you can use to create a manually-installed instance.

  • Unix users who do not have X-Windows or another GUI available to them can run the FusionReactor 4 installer in command-line mode. Simply start it with ./FusionReactor_linux_4_0_0.sh -c
  • Unix users with a GUI available, and Windows users, can proceed through the graphical install wizard.

After the wizard completes, and assuming default answers, the FusionReactor Administration Manager will be installed into /opt/fusionreactor (c:FusionReactor on Windows).

It is not strictly necessary to start FRAM, but if you wish to do so, it can be started using the shell script (/opt/fusionreactor/tomcat/bin/framd start), or by starting the FusionReactor AM service on Windows. If you picked the default port, the service will be available in your browser at http://localhost:8087/.

Installing a Manual Instance

FusionReactor Administration Manager includes a template instance which you can customize. The four main steps are:

  • Creating a new instance folder and customizing the configuration.
  • Inserting the filter definition (a small snippet of XML) into your J2EE container's web.xml (or default-web.xml) file.
  • Copying the fusionreactor.jar file to a location accessible by your J2EE container instance.
  • Arranging for the FusionReactor native library to be loaded.

Creating a New Instance Folder.

For the purposes of illustration, we will be installing a manual instance into Adobe's ColdFusion server, located in /opt/coldfusion9.

  • Locate the supplied instance template folder. This will be in /opt/fusionreactor/etc and is called instance-template.
  • Copy this template to /opt/fusionreactor/instance, and rename it to a unique name. This is the the instance name.
    • In our case, we're going to rename it to cf9.

Customizing the Instance

Within the /opt/fusionreactor/instance/cf9/conf folder, you will see two subfolders, unix and windows.

  • Copy either the contents of the unix or the contents of the windows folder to cf9/conf.

You should now have a reactor.conf and a filter-def.xml file in the conf folder.

  • Open the reactor.conf file with an editor.
  • Search for all occurences of the string __INSTANCENAME__ and replace them with the name you chose above.
    • In our case, this is cf9.
  • If you have installed FusionReactor in a location other than the standard /opt/fusionreactor (C:FusionReactor):
    • Search for all occurences of the installation folder (/opt/fusionreactor) and change them to your install location.

The internal web server is configured in the file fram.conf.

  • Open the fram.conf file with an editor.
  • The internal webserver, allowing access to FusionReactor over a port independent of your main webserver, is controlled using the webserver.* keys.
Key Meaning
webserver.active Whether the internal webserver is made available. If not, FusionReactor will be available over your main webserver under http://localhost/fusionreactor.
webserver.address The IP address to which the internal webserver should bind.
webserver.all Whether the webserver should bind to all addresses.
webserver.port The port on which the webserver listens.

Perhaps most important is the last key: webserver.port. You must ensure you use a port here which is not in use by any other application.

Adding the Filter Definition

The file filter-def.xml contains an XML snippet which must be added to your J2EE container's web.xml file. You should ascertain the location of this file by referring to the container's documentation.

  • Open the filter-def.xml file.
  • Copy the whole content of this file (a filter block and a filter-mapping block) into the clipboard.
  • Open the filter/servlet definition file.
    • In ColdFusion's case, this is /opt/coldfusion9/runtime/servers/coldfusion/SERVER-INF/default-web.xml.
  • Below the web-app start tag, just before the first filter definition (if one is present, if not, just before the first servlet definition), paste the complete content of the clipboard.
  • Customize the __INSTANCENAME__ placeholder to point to your newly-created instance folder.

You should now have inserted the FusionReactor filter and filter-mapping block just prior to the first filter (or servlet) definition.

Copying the fusionreactor.jar file

Within the folder /opt/fusionreactor/etc/lib, you'll find a copy of the fusionreactor.jar file. This must be copied to somewhere visible to your J2EE server's webapp instance.

  • In our case, we copy the file to /opt/coldfusion9/runtime/servers/coldfusion/SERVER-INF/lib/.

Making the Native Library Available

Some functions of FusionReactor, in particular the CPU usage monitor, reside with a custom native library, also located with the /opt/fusionreactor/etc/lib folder.

  • Locate the correct native library for your platform, taking care to match the CPU word-size (32- or 64-bit).
  • Copy the native library to somewhere accessible to your Java binary.

There are several options to achieve the last point:

  • Add /opt/fusionreactor/etc/lib to your LD_LIBRARY_PATH variable (in which case no copy is required).
  • Copy /opt/fusionreactor/etc/lib/libFusionReactor.so to a directory that is already known to contain native libraries (e.g. /opt/coldfusion9/lib)

For ColdFusion:

  • Modify /opt/coldfusion9/runtime/bin/jvm.config and add the path /opt/fusionreactor/etc/lib to the java.library.path property.

Finally, start your J2EE container, and watch its standard-out and standard-error logs. If anything is misconfigured, you should be able to start debugging the problem from the output presented there.

Issue Details

Type: Technote
Issue Number: FRS-252
Components: Installer
Environment:
Resolution: Fixed
Last Updated: 09/Aug/11 10:06 AM
Affects Version: 4.0.0
Fixed Version: 4.0.0
Server:
Platform:
Related Issues: