Hermes Daemon

The daemon is a background process that performs functions defined on a schedule or based on certain system events.

imperia's daemon is represented by the scripts /site/bin/site_hermes_unix.pl or /site/bin/site_hermes_win.pl and /site/bin/site_hermes.pl and is characterized by a modular structure. All functions are outsourced to external plug-ins. This provides maximum flexibility and scalability.

It is responsible for all automatic functions on both imperia's develop and target systems. These include monitoring directories, execution of system services and SiteActives.

If necessary the Hermes can be started for testing purposes. It also offers a debug mode for troubleshooting that could be activated by a corresponding command line option.

The design characteristics of individual functions of the plug-ins are stored in a table that provides information on when and under what conditions a plug-in should run.

Starting the Background Daemon Hermes#

It is recommended to run the daemon in the background. On Windows^® operating systems, the additional registration of the daemon as a system service is recommended. The Hermes must be running on the develop and target systems.

Starting the Daemon under UNIX^®#

On UNIX^®, the Hermes should be run in the background when the system starts. To manually start the background daemon, proceed as follows:

Open a console and change to the site/bin directory of your imperia installation (development or target system).
There, type the following command:
```
nohup ./site_hermes_unix.pl &
```

Starting the Daemon under Windows^®#

To manually start the background daemon on Windows^®, proceed as follows:

Open a DOSBox and change to the site/bin directory of your imperia installation (development or target system). Enter the following command:
```
perl site_hermes_win.pl
```
Leave the DOSBox open.

The Daemon as a System Service under Windows^®#

Important

All necessary files can be found in the site/util/XYNTService directory of imperia's installation.

Installation#

“XYNTService” offers the opportunity to start the Hermes as a system service in the background on Windows^®. The XYNTService.ini file, which must be in the directory of the program, has to be adjusted.

Example configuration of XYNTService.ini

Adapt the entries “Command Line” and “WorkingDir” to the environment in this file.
It is also possible to change the entry “PauseEnd”. “PauseEnd” defines a shutdown delay in milliseconds until the process is properly completed.
- In the example, 600000 milliseconds are chosen, which corresponds to 10 minutes. However, this value may not be sufficient, if the Hermes script is busy too.
- After the time passes, the Hermes script exits “XYNTService.exe” immediately.
To install the system service, open a DOSBox, change to the directory where “XYNTService.exe” is located and enter the following command:

XYNTService.exe -i
If the service has been successfully installed, you see a service “Hermes” available in the list of services in Windows Service Manager (the name is defined by the entry “Service Name” in XYNTService.ini).
The service is started when Windows^® starts. It can also be started manually in Windows Service Manager or with the following command from a DOSBox:

net start Hermes

Uninstall#

If the system service has to be removed, open a DOSBox, change to the directory where “XYNTService.exe” is located and enter the following command:

XYNTService.exe -u

If the service was successfully uninstalled, the entry “Hermes” (defined by the entry “Service Name” in XYNTService.ini) in the list of system services in Windows Service Manager disappears.

Command Line Options#

The operation of the daemon can be affect through system-specific command line options.

Usage#

site_hermes_unix.pl [OPTIONS] | site_hermes_win.pl [OPTIONS]

Use the following line to see the help of the script, where you can see all the available options:

site_hermes_unix.pl -h, --help | site_hermes_win.pl -h, --help

Log File#

All activities of the daemon are stored in the site/logs/hermes.log file. Depending on the selected debug mode, the amount and type of information logged can vary greatly. Here's a typical excerpt from a log file:

[Wed Jun 10 16:07:17 2011] HERMES IS RUNNING ...
[Wed Jun 10 16:07:18 2011] Hermes running with pid 3516
[Wed Jun 10 16:07:18 2011] FOUND 8 PLUGINS (SiteActive, ArchiveMinimizer,
     Import, ExpiryDate, CleanUp, MessageCheck, LogRotate, AutoPublish)
[Wed Jun 10 16:07:18 2011] SCHEDULING PLUGINS
[Wed Jun 10 16:07:18 2011] SUCCESSFULLY LOADED PLUGIN SiteActive
[Wed Jun 10 16:07:18 2011] SUCCESSFULLY LOADED PLUGIN ArchiveMinimizer
[Wed Jun 10 16:07:18 2011] SUCCESSFULLY LOADED PLUGIN Import
[Wed Jun 10 16:07:18 2011] SUCCESSFULLY LOADED PLUGIN ExpiryDate
[Wed Jun 10 16:07:18 2011] SUCCESSFULLY LOADED PLUGIN CleanUp
[Wed Jun 10 16:07:18 2011] SUCCESSFULLY LOADED PLUGIN MessageCheck
[Wed Jun 10 16:07:19 2011] SUCCESSFULLY LOADED PLUGIN LogRotate
[Wed Jun 10 16:07:19 2011] SUCCESSFULLY LOADED PLUGIN AutoPublish
[Wed Jun 10 16:07:19 2011] STARTUP DONE

HERMES IS RUNNING ...
[Wed Jun 10 16:07:19 2011] [MessageCheck] Processing notification
                           '469df2e40360bf2.free'
[Wed Jun 10 16:07:19 2011] [MessageCheck] Processing notification
                           '469df2e403606e0.free'
[Wed Jun 10 16:07:19 2011] [MessageCheck] Processing notification
                           '469df2e40360f41.free'
[Wed Jun 10 16:07:19 2011] [Import] looking for configuration file
                           C:/imperia/dev/sanne/site/config/import.conf
[Wed Jun 10 16:07:19 2011] [Import] not found, falling back to hardcoded
                           defaults
[Wed Jun 10 16:07:19 2011] [Import] successfully (re)initialized plugin
                           Ascii
[Wed Jun 10 16:07:19 2011] [Import] successfully (re)initialized plugin
                           ImperiaXML
[Wed Jun 10 16:07:19 2011] [Import] successfully (re)initialized plugin
                           Meta
[Wed Jun 10 16:07:49 2011] SCHEDULING HERMES FOR QUIT ...
[Wed Jun 10 16:07:50 2011] EXIT SIGNAL RECEIVED.
[Wed Jun 10 16:07:50 2011] HERMES IS GOING AWAY...
[Wed Jun 10 16:07:50 2011] TERMINATING PID: 2912

Note

The file excerpt above is wrapped for display reasons.

In addition the process ID of the daemon is saved in the hermes.pid file in the site/logs directory. In general, this file exists only if the daemon is running. It will be deleted when the daemon is terminated normally.

Plug-in Table#

When the daemon starts for the first time, all found plug-ins will be included in the version table. Each featured plug-in receives an ID used to identify it.

The table contains the name (NAME), function (FUNCTION), ID (ID) and all other properties of a plug-in. These include: execution time (EXEC_TIME), maximum runtime (MAX_RUNTIME), priority (PRIORITY), date of last execution (LAST_RUN).

The entries in the plug-in table are listed by order of precedence. The execution time (EXEC_TIME) column allows for multiple entry formats: Time interval in seconds (e.g. 300 => 5 minutes, 0 => always), fixed time in hh:mm[:ss] ( e.g. '0:00' => midnight), number of execution based on an identification no.

The table remains valid even after the daemon is stopped.

Plug-ins are only loaded when the background daemon starts. To remove a plug-in, the background daemon must be stopped. Then, remove the relevant plug-in from the site/modules/core/Dynamic/Hermes directory and restart the daemon.

Hermes Import#

Several plug-ins for different formats are included in imperia, if you want to import data using the background daemon. Hermes contains a hard-coded default import configuration, where the settings for these standard formats are defined.
The following formats can be imported:

ASCII files with the extension .simple,
XML files, named according to the ﾬred*.xml scheme,
imperia meta files with the extension .meta.

To import other formats, a corresponding import plug-in must be programmed and the default import configuration - extended. The modified configuration must be saved in /site/config/import.conf.

Please note

This file does not exist after installation, but must be created because the default import configuration is an integral part of the /site/modules/core/Dynamic/Hermes/Import.pm module.
The configuration set in the import.conf overrides the default import configuration.
If, in addition to the new configuration, the standard import configuration has to be used, it must be copied from the module into import.conf.

All imported documents contain an additional meta variable __imperia_imported after import. This variable contains a timestamp with the number of seconds since a certain time (epoch). On most systems, this is 1st of January 1970, 00:00 GMT.

Hermes's Default Import Configuration#

The standard import configuration contains sections for all included in imperia's shipment import plug-ins. Each format is defined in a filetype tag. This tag must contain the following tags:

A mask tag that contains a regular expression that is compared to the names of files to be imported.
A plugin tag, containing the names of the plug-ins to be used.
An optional data tag can be transferred with other data of a plug-in.

Important

Only one data tag per filetype tag is allowed. Further data tags are ignored.

The standard import configuration is as follows:

<?xml version="1.0" encoding="us-ascii"?>
<import_config>

  <filetype>
    <mask>^.*\.simple$</mask>
    <plugin>Ascii </plugin>
    <data>additional data for the ASCII plug-in</data>
  </filetype>

  <filetype>
    <mask>.*/red[^/]*\.xml$</mask>
    <plugin>ImperiaXML </plugin>
    <data>additional data for *imperia* XML plug-in</data>
  </filetype>

  <filetype>
    <mask>^.*\.meta$</mask>
    <plugin>Meta</plugin>
    <data>additional data for the meta plug-in</data>
  </filetype>
</import_config>

With this import configuration the following formats can be imported:

ASCII files that have the extension .simple, processed by the ASCII plug-in.
XML files that match the regular expression .*/red[^/]*\.xml$, processed by imperia's XML plug-in.
imperia meta files with the extension .meta, processed by the meta plug-in.

The configuration must be adjusted for other formats to be imported. A corresponding plug-in must be present for each additional format.

For programming your own plug-ins use /site/modules/core/Dynamic/Import/Ascii.pm as reference.

Defining Target Category#

A common reason for import failure is the lack of import category information. In this case, imperia cannot decide in which category to import a document.

Plug-ins decide this based on the contents of the data tags in the configuration file. First, the meta variable __imperia_category (name of category) is tried and if it fails, the system allocates to the meta variable __imperia_node_id (digits).

If the configuration file does not have information on the category to be used, imperia checks whether the files to be imported into one category are specified. If this is not the case, the import fails and Hermes throws an error message.

If several categories with the same name exist in the category tree, Hermes uses the first matching category. To use a particular category, it must be clearly identified by its NodeID.

A NodeID consists of two parts:

the category ID, e.g. /12/24/35/
the document ID, e.g. 130336.

The full NodeID from these two parts is : /12/24/35/130336. Both the document ID and each individual part of the category ID are guaranteed to be unique, because imperia generates them using an auto-incrementing counter.

If the meta variable __imperia_node_id contains a valid NodeID, a category is generated from this information; the document ID will be ignored. The files are then imported into the found category.

Replacing Existing Documents#

Besides the possibility to import documents based on their NodeID in a given category, there are two meta variables, that allow to “merge” already existing and imported documents:

__imperia_clobber_by_name = 1 | 0
__imperia_clobber_by_id = nodeID, e.g. /1/2/3

If the meta variable __imperia_clobber_by_name is enabled (1), the system seaches the document tree for a document that has the same URL as the document to be imported. If such documents are found, the two are merged, i.e. any additional information from the XML file is written as Meta fields in Meta::Info of the already existing in the Archive document.

The meta variable __imperia_clobber_by_id has the same function, but it looks for NodeIDs. This alternative is faster than the URL search.

In both cases, only the selected category will be searched (see Defining Target Category).

Import File Structure#

This section describes the file formats which can be imported with the default import plug-ins.

ASCII Import#

A file that has to be imported by the ASCII plug-in must consist of key-value pairs, where key and value are separated by equal signs. Example:

filename = index.html
directory = /import/ascii
title = Import-Test
metapage = movies
author = superuser
docid = 131875
__imperia_node_id = /4/10
expiry_date = 2012-03-11 10:06

XML Import#

A file that should be imported using imperia's XML plug-in must include a corresponding tag for each meta field, that in turn must contain the value of the meta field.

Example:

<?xml version="1.0" encoding="ASCII" standalone="yes"?>
<IMPERIA_CONTENT>
  <filename>index.html</filename>
  <directory>/import/xml</directory>
  <title>Import-Test</title>
  <metapage>movies</metapage>
  <author>superuser</author>
  <docid>131876</docid>
  <__imperia_node_id>/4/11</__imperia_node_id>
  <expiry_date>2012-03-11 10:06</expiry_date>
</IMPERIA_CONTENT>

Meta Import#

imperia meta files handle binary files that cannot be produced easily by hand. This import is used to transfer existing imperia documents from one imperia installation to another (based on the same software version).