RenderX

Chapter 4 of the IREn InGrid User Guide

Running IREn InGrid Access Point and Engines

To run IREn InGrid, launch the access point on one of the servers and several IREn engines, usually on separate computers. ${instDir}/ingrid is a shell script that launches the access point; it issues the following command:

 java -cp ${instDir}/lib/ingrid.jar com.renderx.ingrid.XepMultiplexer etc/ingrid.conf

where ingrid.conf is the configuration file; The configuration syntax is explained in Section 4.1. On a platform which supports Bourne shell scripts, use the convenience features the script provides (execute bin/ingrid -help for usage instructions), otherwise just run the command above.

${instDir}/bin/engine launches an IREn engine; it is a call (to a Java program):

 java com.renderx.xepx.cliser.Engine -DCONFIG=/path/to/xep.xml

(replace the path to xep.xml with the actual location of IREn configuration).

The CLASSPATH system variable should include paths to:

  • ingrid.jar, the main executable;

  • All necessary libraries of IREn engine, which IREn InGrid uses for actual formatting;

Additional command-line switches are:

  • -port n TCP port for data communications (6570 by default), several engines may be run in separate Java Virtual Machines on the same computer if they use different ports, or change the default port value if you have a reason to do so;

  • -hcport n HTTP port. The engine has a built-in Web server, the server displays the current status of the engine, as well as allowing it to switch the engine off or suspend it. The HTTP server may be disabled by specifying hcport=-1.

  • -label name The engine's name is displayed on the monitor's web page; it is convenient to assign a unique name to each of the engines so that you can easily see which one you've connected to.

Both the access point and the engines run embedded HTTP servers; the servers display the current state, to monitor activity and help performance tuning. By default, the HTTP ports are 6570 for Actinia, 6575 for Toaster, 6577 for Fairy, and 6580 for IREn.

4.1. Writing Configuration Files

To run IREn InGrid, you must configure it. A configuration file determines both how IREn InGrid interacts with the outside world and how it manages IREn engines and distributes the load. While for many parameters the default values are satisfactory, some values are required to be set explicitly to describe your local environment (the network and the computer).

IREn InGrid is packaged with a set of initial configuration files called actinia.conf.example, toaster.conf.example, fairy.conf.example, and fork.conf.example. Copying and editing example configs from ${instDir}/etc/ is the fastest and the easiest way to start.

The configuration file is in the following XML format (in Relax NG). The complete specification of IREn InGrid configuration file follows:

config = actinia | toaster | fairy | fork
actinia = element actinia {
    actinia-folders & settings
}

toaster = element toaster {
    toaster-folders  & settings
}

fairy = element fairy {
    fairy-folders & settings
}

fork = element fork {
    fork-tines & element option {
        attribute name {"http-port"},
        attribute value {string}
    }?
}

fork-tines = element tine {
        attribute conf {string}
    }+

settings = options & servers & cliser

actinia-folders = element folders {
    attribute input {string},
    attribute output {string},
    attribute quarantine {string},
    attribute temporary {string}
}

toaster-folders = element folders {
    attribute temporary {string}
}

fairy-folders = element folders {
    attribute temporary {string}
}

options = element option {
    attribute name {token},
    attribute value {string}
}*

servers = servers {
    element server {
        attribute host {token}?,
        attribute port {token}?
    }+
}

cliser = element cliser {
    attribute format {token}?,
    options
}

The IREn InGrid mode is set by the top-level element; it is either toaster (network server), actinia (active folder), fairy (SOAP server) or fork(proxying mode). All modes except fork require folders and servers elements.

Attributes of folders are temporary, input, output, and quarantine which specify paths to the temporary folder (IREn InGrid kernel needs it), and, only for Actinia, to the input, output and quarantine folders. Actinia looks for XSL-FO sources in the inputfolder and writes formatted results to output folder. It keeps a copy of each XSL-FO source in the quarantine folder until the processing has finished. This allows the user to re-submit documents after a malfunction (for example, due to a power failure or a hardware problem). Both input and output attribute values can point to the same location: Actinia picks files ending with '.fo' extension by default. You can set a different input filter. See the list of options below.

Here's a sample folders section:

<folders
    temporary="'C:/InGrid/tmp'"/>

servers defines servers available to the access point. For each server, host is the server's host name or IP address ('localhost' by default), and port is the IREn engine's port (the default value is 6570). You can list the same server multiple times if you want it to load it more heavily. IREn engines are multi-threaded and handle concurrent sessions efficiently.

Here's a sample servers section:

<servers>
    <server host="'localhost'" port="6570"/>
</servers>

CLISER, RenderX IREn Client-Server protocol, is the underlying protocol layer; element cliser sets the required document format (pdf is the default value, ps (for PostScript), or xep may be used), and can contain CLISER options (see the documentation on IREn for the list of option names). Use the same names as are available for IREn and prepend core options with 'FRM:' and generator options with 'GEN:' (optionally followed by the format's name and a colon). For example, the following fragment:

<cliser format="pdf">
  <option name="FRM:VALIDATE" value="'true'"/>
  <option name="GEN:pdf:COMPRESS" value="'false'"/>
</cliser>

sets output format to PDF, enables validation and turns off compression.

4.2. Configuration Options and Tuning Performance

IREn InGrid allows tuning its performance through a number of options. The default configuration values are fine for most applications. By changing them you can build the exact configuration you want and fine-tune the load on the grid, the throughput, and the response time. Here is the list of all available options, with their data types and default values in parentheses:

4.2.1. Actinia Options

  • pickup-interval (seconds:1) interval to check for new source documents;

  • pickup-delay (seconds:2) delay after the last modification of a source document, Actinia needs it to avoid picking up documents while they are being written;

  • end-of-input (string:'stop') when Actinia finds a file with this name in the input folder, it shuts down;

  • input-filter (regular expression: (\.fo|\.xml|\.xep)$) regular expression for file names treated as source documents in the input directory;

4.2.2. Toaster Options

  • data-port (int:6575) TCP port which Toaster accepts data and return results on;

  • data-backlog (int:0) backlog for data connections, default is no backlog.

4.2.3. Fairy Options

  • soap-port (int:6577) TCP port which Fairy SOAP server accepts requests and return results on.

  • data-backlog (int:0) backlog for data connections, default is no backlog.

  • format-method (string:'format') Remote method name called to submit a formatting request.

  • stop-method (string:'stop') Remote method name called to stop Service.

  • accept-path (string:'/fairy') Service alias, used in HTTP requests.

  • Access-Control-Allow-Origin (string) required for sending formatting requests to Fairy from a Web site via the Web Browser. This option specifies the value of Access-Control-Allow-Origin parameter in HTTP header returned by SOAP server (Fairy). A more detailed information is available at W3C Recommendation on Cross-Origin Resource Sharing.

  • use-https (boolean:False) Enables HTTPS. If enabled, formatting requests over plain HTTP will be rejected. Requires specifying server-ssl-certfile and server-ssl-keyfile.

  • TLS-version (string:'TLSv1_2') Deprecated. Specifies TLS version. Default version is TLSv1.2. Can be used to downgrade TLS version to TLSv1 or TLSv1_1, which is strongly discouraged for security considerations.

  • server-ssl-certfile (string) Path to the file with server's certificate file in PEM format.

  • server-ssl-keyfile (string) Path to the file with server's private key in PEM format.

  • mutual-authentication (boolean:False) Enables mutual authentication (two-way TLS). All clients submitting requests must provide a valid certificate. Fairy server verifies those against the CA certificate (or certificate chain) specified in ca-certs-file file. Requests that failed to provide with one will be rejected.

  • ca-certs-file (string) Path to a file with CA certificate (or certificate chain) in PEM format.

  • max-request-queue-size (integer:0) Controls how load balancing work. This option specifies maximum size of this queue. A non-zero value makes IREn InGrid reject the request until the working queue frees an allocation slot. See Section 7.5 for details. Default value is 0, which means that the queue is unlimited.

  • service-temporarily-unavailable-page (string) Specifies a path to a file containing a custom Error 503 page. This can be any document in plain text or HTML.

  • use-disk-cache (boolean:False) Enables disk caching for XSL-FO files. This option should be only enabled for processing very large documents (larger than the available memory), otherwise negative impact on performance may occur.

4.2.4. Fork Options

Fork accepts one or more tine elements (one per IREn InGrid instance to run) and an optional option element with http-port attribute specifying port number for Fork Web interface to reside at. Each tine element should have a conf attribute which string value should contain a pathname to a valid IREn InGrid config.

  • http-port (integer:6600) HTTP port for connecting to the Web interface.

4.2.5. Common Options

  • agents-count (integer: number of servers) number of agents to launch, default is equal to the number of servers;

  • putback-interval (seconds: 1) dead servers are brought back periodically; a separate thread tries to re-connect to them, and if it succeeds, IREn InGrid starts sending documents to them again;

  • socket-timeout (seconds: indefinite) connections to servers would time out after this interval, thus even if a server went down without properly closing its socket, IREn InGrid will notice its outage and temporarily unregister it;

  • log-path (string: None) path to the log file; if omitted, IREn InGrid prints to the standard error stream (stderr) by default

  • log-level (string:'errors') logging level, one of none, errors, all;

    Note: Remember that specifying log-level option to all negatively affects on performance. It is recommended to use log-level option set to errors, unless for troubleshooting purposes.

  • report-label (string:'IREn InGrid:Actinia' or 'IREn InGrid:Toaster') default heading for HTTP report (change it for each IREn InGrid instance if you have several ones)

  • http-port (integer:6590 for Actinia, 6595 for Toaster, and 6597 for Fairy) HTTP port the logger listens on.

    Note: When running multiple instances of IREn InGrid on the same machine, different ports need to be used for both data and HTTP.