engine_connect can take connection information from a file for connecting and disconnecting event correlators. A sample of such a configuration file is shown below, which defines the topology shown in Example of a pipelined engine topology.

Each entry in the configuration file specifies connection information for a single correlator in the deployment. Entries can be specified in any order. The general format of an entry is:

where <connection> is defined as:

<correlator_name> is a symbolic identifier for a correlator, used to identify source correlators in target correlator connection information. It can consist of any combination of characters other than whitespace, colon, comma or open/close brace characters, which are reserved as separators. <host> and <port> identify the specific correlator this entry applies to. They can be omitted, in which case the defaults of localhost and 15903 are used respectively.

Following this information are details of all connections to source correlators for the current (target) entry. This information is omitted if no correlators sit ‘upstream’ of the current entry (as with the correlator router, above). If there are multiple upstream source correlators, each name should be separated by a comma (as with tallier, above, which takes events from worker3 and worker4).

For each connection it is possible to specify the channel(s) on which the target correlator will listen. If no channels are specified the target correlator will register to receive all events emitted by the source correlator regardless of channel (as with correlators worker3 and worker4 which register for all events from worker1 and worker2 respectively). One can specify specific channel names by enclosing them in braces and separating multiple channels by commas (as with watcher which registers with router for all events on channels chan1 and chan2).

In effect, the configuration file is a convenient way of grouping several calls to engine_connect. For example to set up the connections for the correlator tallier would require two commands using engine_connect:

The configuration file can be used to both establish and remove connections in a multi-correlator engine topology. For example, assuming the above file is saved as topology.dat, the following commands will first set up then tear down all the connections specified therein:

In each of these cases, engine_connect will exit with non-zero exit status on the first error it detects in the configuration file. An error message will be printed to standard error (stderr).

The behavior of engine_connect without the -x option is additive. This means that successive calls to engine_connect will attempt to add the channels specified to any existing connection between the source and target correlator(s). For example, with reference to the configuration file above, these commands:

will first add a connection from correlator router to worker1 on channel foo, then (from the configuration file) extend that connection so that worker1 also receives all events from router emitted on channel chan1.

Once a connection is set up between two correlators on a channel, any further attempt to set up that connection on the same channel will have no effect. It is therefore possible to re-play the configuration file by invoking engine_connect without creating duplicate connections. This can be useful if there is an error in the configuration file signaled when engine_connect is called, as the error can be fixed and engine_connect re-run without requiring removal of connections that were successfully set up by the first call to engine_connect.