Using the IAF

The IAF runtime

Once installed, running the IAF is straightforward. As already stated, the IAF is not a development library but a generic adapter framework whose functionality can be tailored according to a user’s requirements through loading of the appropriate plug-ins.

In order to create an adapter with the IAF, one must supply a configuration file. This file – described in The IAF configuration file – specifies which plug-ins to load and what parameters to configure them with, defines the translation and transformation rules of the Semantic Mapper, and configures communication with Apama.

The adapter can then be started as follows:

iaf *configuration.xml*

IAF library paths

In order for the IAF to successfully locate and load C/C++ transport layer and codec plug-ins, the location(s) of these must be added to the environment variable LD_LIBRARY_PATH on UNIX, or PATH on Windows.

A transport or codec plug-in library may depend on other dynamic libraries, whose locations should also be added to the LD_LIBRARY_PATH or PATH environment variable as appropriate for the platform. The documentation for a packaged adapter will state which paths should be used for the adapter’s plug-ins. Note that on the Windows platform, the IAF may generate an error message indicating that it was unable to load a transport or codec plug-in library, when in fact it was a dependent library of the plug-in that failed to load. On UNIX platforms the IAF will correctly report exactly which library could not be loaded.

When using the IAF with a Java adapter the location of the Java Virtual Machine (JVM) library is determined in the same way. On UNIX systems the LD_LIBRARY_PATH environment variable will be searched for a library called libjvm.so, and on Windows the IAF will search for jvm.dll, in directories on JAVA_HOME environment variable, then in any other directories on the PATH environment variable. Using a JVM other than the one shipped with Apama is not supported and Technical Support will generally request that any Java-related problems with the IAF are reproduced with the supported JVM.

See Java configuration (optional) for information about how the location of Java plug-in classes are determined.

IAF command-line options

The iaf executable starts the IAF. This is located in the bin directory of the Apama installation.

Synopsis

To start the adapter, run the following command:

iaf [ *options* ] [ *config.xml* ]

where *config.xml* is the name of a configuration file using the format described in The IAF configuration file. A configuration file must be provided unless the -h or -V options are used.

When you run this command with the –h option, the usage message for this command is shown.

Description

Unless the –e or --events options are used, the above will generate and start a custom adapter, load and initialize the plug-ins defined in the configuration file, connect to Apama, and start processing incoming messages.

When the –e or --events options are used, the iaf executable generates event definitions that can be saved to a file and injected during your application’s startup sequences as specified by Apama Plugin for Eclipse or Apama command-line tools. If either of these options is used, the IAF will load the IAF configuration file, process it, generate the event definitions and print them out onto stdout (standard output) and promptly exit. A valid configuration file must be supplied with either of these options. The output definitions are grouped by package, with interleaved comments between each set. If all the event types in the configuration are in the same package, the output will be valid EPL code that can be injected directly into the correlator. Otherwise, it will have to be split into separate files for each package. The IAF can be configured to automatically inject event definitions into a connected correlator, but this is not the default behavior. The event definitions generated by the -e or --events options are exactly what the IAF would inject into the correlator, if configured to do so.

For more information about the service configuration file, see Using the Apama component extended configuration file.

If the --logfile and --loglevel options are provided, any logging settings set in the IAF configuration file (<logging> and <plugin-logging>) will be ignored.

If the IAF cannot write to the log file specified either with the --logfile option or in the adapter’s configuration file, the IAF will fail to start.

Options

The iaf executable takes the following options:

IAF log file status messages

The IAF sends status information to its log file every 5 seconds (the default behavior) or at time intervals you specify with the --logQueueSizePeriod option when you start the IAF. For example:

Status: ApEvRx=589 ApEvTx=2056000 TrEvRx=2056008 TrEvTx=587 vm=407200 pm=956240 si=0.0 so=0.0 oq=10

Where the fields have the following meanings:

IAF log file rotation

Rotating the IAF log file refers to closing the IAF log file while the IAF is running and opening a new log file. This lets you archive log files and avoid log files that are too large to easily view.

Each site should decide on and implement its own IAF log rotation policy. You should consider the following:

• How often to rotate log files.
• How large an IAF log file can be.
• What IAF log file naming conventions to use to organize log files.

There is a lot of useful header information in the log file being used when the IAF starts. If you need to provide log files to Apama technical support, you should be able to provide the log file that was in use when the IAF started, as well as any other log files that were in use before and when a problem occurred.

Note:

Regularly rotating log files and storing the old ones in a secure location may be important as part of your personal data protection policy. For more information, see Protecting and erasing data from Apama log files.

On Windows, to automate log file rotation, you can set up scheduled tasks that run the following tools:

• The following command instructs the IAF to close the log file it is using and start using a log file that has the name you specify. When you run this request to rotate the log file the IAF log file has a new name each time you rotate it. This is because Windows does not let you change the name of a file that is being used. If the name of the file contains blanks, be sure enclose it in quotation marks.

  iaf_management --setLogFile *new-log-filename*
  

• You can configure the IAF to log to two separate files. Each command instructs the IAF to start using the specified log file for either the IAF core processes (generic IAF information such as status messages) or the IAF plug-in processes (transports and codecs being used). If the name of a file contains blanks, be sure enclose it in quotation marks.

  iaf_management -r setCoreLogFile *new-log-filename*
  iaf_management -r setPluginLogFile *new-log-filename*
  

  Consider using two IAF log files when you need to focus on diagnosing something specific to your application, for example, you need to easily spot authentication messages. If you do use separate log files you might want to rotate them at the same time so that they stay in sync with each other.

On UNIX, to automate log file rotation, you can write a cron job that periodically does any of the following:

• Set log file name:

  iaf_management --setLogFile *new-log-filename*
  

• Set core log file and plug-in log file:

  iaf_management -r setCoreLogFile *new-log-filename*
  iaf_management -r setPluginLogFile *new-log-filename*
  

• Reopen the log:

  iaf_management --reopenLog
  

  Move the IAF log file before you execute the --reopenLog option. Since UNIX allows you to rename a file that is in use, the IAF processes will log to the renamed log file. When you then request the IAF to reopen its log file, the IAF creates a new log file with the same name. For example, suppose you move iaf_current.log to iaf_archive_2014_01_31.log and then send a reopenLog request. The IAF creates iaf_current.log, opens it, and begins sending any log messages to it. Be sure to enclose the argument after -r in quotation marks.

  If you are using two IAF log files, the --reopenLog option applies to both of them. Consequently, you want to move both log files before you issue the --reopenLog option.

• Send a SIGHUP signal:

  You can write a cron job that sends a SIGHUP signal to IAF processes. The standard UNIX SIGHUP mechanism causes IAF processes to re-open their log files.

  The cron job should first rename log files. Since UNIX allows you to rename a file that is in use, the IAF processes will log to the renamed log files until the cron job sends a SIGHUP to IAF processes. The SIGHUP signal makes the processes re-open their log files and so they open files that have the old names and begin using them. Of course, these files are initially empty because the IAF must re-create them.

  Sending a SIGHUP signal does the same thing as the reopenLog request. Also, a SIGHUP signal forces the IAF configuration file to be reloaded and this reload stops and starts the transports and codecs.

If you instruct the IAF to open a named log file and the IAF cannot open that log file or cannot write to that log file, the IAF sends log messages to stderr but does not generate an error.

Apama does not support automatic log file rotation based on time of day or log file size.

Note:

Some people use the term “log rolling” instead of “log rotation”.

Using the Apama component extended configuration file

The Apama component extended configuration file is an optional file that can be used by the IAF. You can use it to do the following:

• Bind Apama server components to a particular set of addresses.
• Specify that Apama client connections must be from a particular IP address or range of IP addresses.
• Set environment variables for Apama components.

In an extended configuration file, if a line includes a special character that you want to be treated as a literal, you must escape it by inserting a backslash just before it. A character that follows two consecutive backslashes (\\) is treated as a literal. Single quotes inside double quotes are treated as a literal. Double quotes inside single quotes are treated as a literal.

Note:

To configure the correlator, see Configuring the correlator.

Binding server components to particular addresses

To bind Apama server components to a particular address or set of addresses, specify a BindAddress line for each address. Specify this in the [Server] section of the extended configuration file. For example:

[Server]
BindAddress=127.0.0.1:15903
BindAddress=10.0.0.1

You can specify as many BindAddress lines as you want. Clients can connect to any of the listed addresses.

An IP address is required. If you do not specify a port, the Apama server components use the port that is specified when the correlator is started. This makes it possible to share extended configuration files if you want to restrict connections according to only addresses.

If you do not specify an extended configuration file when you start the correlator, or there are no BindAddress entries in the extended configuration file, the Apama components bind to the wildcard address (0.0.0.0).

Ensuring that client connections are from particular addresses

To ensure that client connections are from particular addresses, add one or more AllowClient entries to the extended configuration file in the [Server] section. For example:

[Server]
AllowClient=127.0.0.1
AllowClient=192.168.128.0/17

An AllowClient entry takes an IP address, as in the first example above, or a CIDR (Classless Inter-Domain Routing) address range, as in the second example above. With these example entries in the extended configuration file, the Apama components allow connections from either the localhost (127.0.0.1) or IP addresses where the first 17 bits match the first 17 bits of 192.168.128.0. The Apama components do not accept connections from any other IP addresses.

If you specify an extended configuration file when you start the correlator, and if there are any AllowClient entries in the extended configuration file, then the Apama components do not allow connections from any IP address that does not fall within one of the AllowClient ranges specified. If you do not specify an extended configuration file when you start the correlator, or there are no AllowClient entries in an extended configuration file that you do specify, the Apama components accept connections from any client.

Important: This feature is intended to prevent mistakenly connecting to the wrong server. It is not intended to prevent malicious intruders since it provides no protection against address spoofing.

Setting environment variables for Apama components

You can use the extended configuration file to set environment variables. Put environment variable declarations in the [Environment] section. For example:

[Environment]
MY_ENV_VAR=myvalue

If you specify an extended configuration file when you start the correlator, and if there are any environment variable entries in the extended configuration file, then the Apama components use those environment variable settings. If you do not specify an extended configuration file when you start the correlator, or there are no environment variable entries in an extended configuration file that you do specify, the Apama components use the environment variable settings specified elsewhere.

Note:

You cannot use this feature to set variables such as LD_PRELOAD and LD_LIBRARY_PATH because UNIX dictates that they are set before the affected process starts execution. These environment variables should therefore be considered read-only.

Sample extended configuration file

Save the extended configuration file as a text file. Blank lines are ignored. For example, the contents of ApamaExtendedConfig.txt might be as follows:

[Server]
BindAddress=127.0.0.1:15903
BindAddress=10.0.0.1
AllowClient=127.0.0.1
AllowClient=10.0.0.0/24
[Environment]
LD_LIBRARY_PATH=/usr/local/mydir

IAF Management – Managing a running adapter I

The iaf_management tool is provided for performing generic component management operations on a running adapter. It can be used to shut down a running adapter, request the process ID of a running adapter, or check that an adapter process is running and acknowledging communications. The executable for this tool is located in the bin directory of the Apama installation. Any output information is displayed on stdout.

See also IAF Client – Managing a running adapter II for IAF-specific management information, as opposed to this generic component management tool.

Synopsis

To manage a running adapter, run the following command:

iaf_management [ *options* ]

When you run this command with the –h option, the usage message for this command is shown.

Description

For historical reasons, iaf_management does the same as engine_management. The only difference in behavior is that iaf_management defaults to the default IAF port (16903).

For detailed descriptions of all options and exit values, see Shutting down and managing components.

IAF Client – Managing a running adapter II

The iaf_client tool is provided for performing IAF-specific management operations on a running adapter. It can be used to stop a running adapter, to temporarily pause sending of events from an adapter into the correlator, and to request an adapter to dynamically reload its configuration. The executable for this tool is located in the bin directory of the Apama installation.

Synopsis

To manage a running adapter, run the following command:

iaf_client [ *options* ]

When you run this command with the –h option, the usage message for this command is shown.

Description

If the adapter is listening for control connections on a non-standard port (specified with the -–port option to the iaf executable), you must pass the same port number to the iaf_client tool.

When the IAF is started, it loads all the transport and codec plug-ins defined in its configuration file, and initializes them with any plug-in-specific properties provided.

You can use the --reload option to dynamically reconfigure a running adapter from a changed configuration file without restarting the IAF. When this option is used, the IAF will:

• Pass the current set of <property> names and values in the configuration file to each loaded transport and codec layer plug-in.

  Note: Although plug-in authors will support dynamic reconfiguration of properties wherever possible, it is important to be aware that there may be some properties that by the nature cannot be changed while the adapter is still running. These should be detailed in the documentation for the transport or codec plug-in. Some transport and codec plug-ins may not support configuration file reloading at all. This should be documented by the specific plug-ins.

• Load and initialize any new transport and codec layer plug-ins that have been listed in the <transports> and <codecs> sections of the configuration file.

• Unload any transport and codec layer plug-ins that are no longer listed in the <transports> and <codecs> sections of the configuration file.

Changing the name of a running plug-in and performing a reload is equivalent to unloading the plug-in and then loading it again. It is important to realize that this will result in any runtime state stored in memory by the plug-in being lost.

Note:

It is not possible to dynamically change a loaded plug-in’s C/C++ library filename or Java className, nor to change a C/C++ plug-in into a Java one (or vice-

versa).

If an adapter is reconfigured to use a different log file and the IAF cannot write to the new log file when reloaded, the IAF uses the log file the adapter was using before reconfiguring. If the IAF cannot use the original log file, it writes to stderr.

Options

The iaf_client tool takes the following options:

IAF Watch – Monitoring running adapter status

The iaf_watch tool allows you to monitor the live status of a running adapter. The executable for this tool is located in the bin directory of the Apama installation.

Synopsis

To monitor the status of a running adapter, run the following command:

iaf_watch [ *options* ]

When you run this command with the –h option, the usage message for this command is shown.

Description

If the adapter is listening for control connections on a non-standard port (specified with the -–port option to the iaf executable), you must pass the same port number to the iaf_watch tool.

By default, the tool collects status information from the adapter once per second and displays this in a human-readable form.

Options

The iaf_watch tool takes the following options: