Integrity Checks in the ePages System 6.17.41
Created: 6.0.8; Updated: 6.17.5

In order to further increase security of the ePages System, its integrity can be regularly checked.

The following procedure is used:

  1. The relevant files are signed, and comparison-lists with file characteristics are created (target lists).
  2. The signatures and comparison parameters are automatically checked via the Scheduler (target value comparison).
  3. If differences are found, a warning will be sent by E-Mail.
For this reason, beginning with ePages 6.0.7 (Patch or complete version) the "CheckIntegrity.PL" script will be installed, along with its configuration-file, "CheckIntegrity.conf".

Read section Installation and Execution to find out how integrity checks are normally set up and used.

Read section Analysis and Errors to find out which results are produced and how you will be notified of errors.

Read section Configuration to find out how you can customize the integrity check to your needs.

Read section Setting Up the Scheduler to find out how the Scheduler can be set up and started.

Read section Signing External Cartridges to find out how you can set up the integrity check for your self-developed cartridges.

Table of Contents

1 Installation and Execution

The integrity check functionality will be installed during either the full installation or a patch as of ePages version 6.0.7. It will be configured with standard parameter values that fit most situations.

The integrity check must be started manually. Proceed as follows:

1.1 Patch Installation

Execute following command inside the patch directory:

  ./patch.sh start_sic

1.2 Full Installation

Execute following commands:

  . /etc/default/epages6
  $PERL $EPAGES/bin/CheckIntegrity.PL -add scheduler
  /etc/init.d/epages6 start_cron

1.3 Analysis and Errors

The target value comparison is set by default to be carried out once every minute. The signatures are checked every hour. If a difference is found, the differing files are saved into a .tar.gz package and an error message is sent by E-Mail. This E-Mail is sent by default to the address entered into the TBO as recipient for error messages.

If the same discrepancy is registered during the next integrity check (the same files demonstrate the same violations of the rules), there will be no reaction.

All files that are produced by CheckIntegrity.PL are located in:

.epages/CheckIntegrity/ contains the following files:

  *.NOMINAL : desired state
  *.ACTUAL  : actual state
  *.ERROR   : file-system inconsistencies
  *.tar.gz  : package with files that differ from the norm

2 Configuration

Integrity checking is installed and started with default values that should fit most installations.

When necessary, you can customize the integrity check. The configuration is defined in the following file:

  $EPAGES_CONFIG/CheckIntegrity.conf

The most important parameters are those that determine which files in what directories should be tested, and how that should happen:

Check=
This parameter defines what should be tested. In addition to the signature, all file-characteristics can be tested which are returned by 'perl -e "stat(FILE)"'. 'owner' includes both 'uid' (User) and 'gid' (Group).
Example: Check=signature,size,mode,owner,inode,ctime,mtime
CheckFiles=
Only the status of those files will be tested whose suffix is included in the list (as long as Check= contains something other than the signature).
Example: CheckFiles= .pl|.pm
CheckPath=
Only those files found in the entered paths will be tested. If SignaturePath= is set, only a directory may be entered here.
Example: CheckPath=$ENV{EPAGES_PERL}/bin
In the following description, the individual sections of the standard configuration file are explained. The numbers at the beginning of the lines are not found in the configuration file itself; they are only used to refer to the actual line numbers in the file.

2.1 :Default:

   1  [:Default:]
   2  # Each parameter in this section can also be written as
        parameter:HOSTNAME.
   3  # If parameter:HOSTNAME exists, then host HOSTNAME uses
        parameter:HOSTNAME,
   4  # otherwise it uses parameter (HOSTNAME is the short name without
        dots).
   5
   6  # Path to CheckIntegrity.PL (parameter must be set)
   7  Command=$ENV{EPAGES}/bin/CheckIntegrity.PL
   8  # VarDir contains variable data files (default: ~/.epages)
   9  VarDir=
  10  ### For GPG:
  11  # Path to the gpg program (if not in PATH)
  12  GpgPath=
  13  # list of public keys (files,dirs,URLs) to import separated by ','
  14  PublicKeys=$ENV{EPAGES_CONFIG}/pubring.txt
  15  #PublicKeys=http://epages.com/security/b1d28320.txt
  16  ### For mail:
  17  # e-mail address of sender (default: as defined in MailConnection
        resp. MailStore)
  18  MailSender=
  19  # list of recipients separated by [;,] (default: MailSender)
  20  MailRecipient=
  21  # EITHER use the e-mail connection as defined in store (only with
        ePages perl; default: Site):
  22  MailStore=
  23  # OR define the e-mail connection explicitly (default: localhost):
  24  # Format: passwd:user@server or user@server or server
  25  MailConnection=
  26  ### For UNIX:
  27  # Path to wrapScheduler.sh script
       (default: $ENV{EPAGES}/bin/wrapScheduler.sh)
  28  WrapSchedulerSh=
  29  # Path to wrapScheduler.PL script
       (default: $ENV{EPAGES}/bin/wrapScheduler.PL)
  30  WrapSchedulerPl=
  31  # Use '/bin/env perl' or ePages perl? (default: ePages perl)
  32  UseBinEnvPerl=

The :Default:-section contains parameter values that are used whenever parameters are missing in the actual sections.

Command=
Path to CheckIntegrity.PL, must be set for scheduler.
VarDir=
Contains variable ePages-files, comparable to the UNIX-/var-directory.
GpgPath=
Path to GPG-Exe (Version 1.x oder 2.x), as long as the GPG-Exe is not already included in the Path, or GPG is installed in an unusual place. The gpg-exe tests the signature of ePages files. Without a pre-installed GPG, no ePages patches or complete versions can be installed.
PublicKeys
A comma-separated list of GPG public-keys that are to be used in the signature test. The public-keys can be saved in files, directories or URLs.
MailSender=, MailRecipient=, MailStore=, MailConnection=
See section SendProgramOutput.
WrapSchedulerSh=, WrapSchedulerPl=
The paths to the scripts are variable so that CheckIntegrity.PL can also be run outside the ePages system.
UseBinEnvPerl=
If this variable has a positive value, the Perl distribution included in the operating system will be used instead of the ePages Perl distribution. This allows CheckIntegrity.PL to be run outside the ePages system.

2.2 :Example:

Each section that begins and ends with a ":" are ignored (except for :Default:). The :Example: section demonstrates all the settings that can be configured for CheckIntegrity.PL.

Warning!: No section name that needs to be used may contain a colon, except for :Default:.

  34  [:Example:]
  35  # check what:
  36  Check=signature,size,mode,owner,inode,ctime,mtime
  37  # check internal signature of files ending in: (separated by |)
  38  InternalSignatures=.conf|.PL|.pl|.pm|.t|.sh
  39  # check external signature of files ending in: (separated by |)
  40  ExternalSignatures=.so|.exe|.dll
  41  # check status of files ending in: (separated by |)
  42  CheckFiles=.so|.exe
  43  # check where (if SignaturePath isn't defined: path list separated
        by ',')
  44  CheckPath=$ENV{EPAGES_PERL}/bin
  45  # check against (if detached signatures):
  46  SignaturePath=$ENV{EPAGES_PERL}/.gpg/bin
  47  # run? (1 - yes, else - no)
  48  IsActive=1
  49  # what? (section names separated by ',')
  50  SubTasks=DE_EPAGES_Size,Perl_Size,Perl_Signature,Config,Core
  51  # where? (separated by ','; unset -> any)
  52  Machine=
  53  # when? (job won't run if Cron= (UNIX) or Schtasks= and At= (Win)
        is/are unset)
  54  # when? (Unix: minute/hour/day of month/month/day of week)
        [see 'man crontab']
  55  Cron=* * * * *
  56  # when? (Windows: schtasks arguments) [see online help of
        schtasks]
  57  Schtasks=/st 00:00 /sc MINUTE /mo 1
  58  # when? (Windows: at args) [if schtasks runs, ignore at; see
        online help of at]
  59  At=00:00 /every:5,10,15,20,25,30,35,40,45,50,55
  60  # how long the cronjob may take without a subsequent instance
        reports
  61  # an error? (default: until the next instance occurs)
  62  # MaxDuration has one of the formats:
  63  # <DAYS>-<HOURS>:<MINUTES> (e.g.: MaxDuration=3-12:00)
  64  # <HOURS>:<MINUTES>        (e.g.: MaxDuration=2:16)
  65  # <MINUTES>                (e.g.: MaxDuration=18)
  66  MaxDuration=4
  67  # what command options? (-section SECTION must be set)
  68  Options=-section :Example:

InternalSignatures=
Only those files whose suffix is included in the list will undergoa signature test (if Check= contains a signature). The signature is found at the beginning of each file to be tested. Internal signatures can only be used for files that recognize a "#" as a comment-begin character.
ExternalSignatures=
The signature will only be tested for files whose suffix is contained in the list (and as long as Check= a signature). The signature is kept in an extra (detached) signature file.
SignaturePath=
Contains the signature files for external signatures.
SubTasks=
Contains section names which have been combined to a higher-level task. If CheckIntegrity.PL is run with '-section ...', only the entered section (including sub-tasks, if available) will be executed. Without the '-section ...' parameter, all sub-tasks belonging to all sections with sub-tasks will be executed.
IsActive=, Machine=, Cron=, Schtasks=, At=, MaxDuration=, Options=
Will be sent to the scheduler. Options= must contain '-section OWNER_NAME'.

2.3 Real World Sections

In the next section, several sections of the standard configuration file are explained.

DE_EPAGES_Signature
Checks the internal signature of all files in $ENV{EPAGES_CARTRIDGES}/DE_EPAGES, that end with either .pl or .pm:
  70  [DE_EPAGES_Signature]
  71  Check=signature
  72  InternalSignatures=.pl|.pm
  73  CheckPath=$ENV{EPAGES_CARTRIDGES}/DE_EPAGES

DE_EPAGES_Stat
Checks size, owner, access rights and time of the last changes in all files found in $ENV{EPAGES_CARTRIDGES}/DE_EPAGES:
  75  [DE_EPAGES_Stat]
  76  Check=size,owner,mode,mtime
  77  CheckPath=$ENV{EPAGES_CARTRIDGES}/DE_EPAGES

Perl_Signature
Checks the external signature of all files found in $ENV{EPAGES_PERL}/bin. The external signatures are located in $ENV{EPAGES_PERL}/.gpg/bin. This section, by default, will not be executed, because $ENV{EPAGES_PERL}/bin can change:
  79  [Perl_Signature]
  80  IsActive=0
  81  Check=signature
  82  ExternalSignatures=
  83  CheckPath=$ENV{EPAGES_PERL}/bin
  84  SignaturePath=$ENV{EPAGES_PERL}/.gpg/bin

bin_Signature
Checks the internal signature of all files found in $ENV{EPAGES}/bin that end in .PL, .pl or .sh. Internal signatures are only possible for files that support "#" as a comment-begin character; this is not possible for .cmd files.
  90  [bin_Signature]
  91  Check=signature
  92  InternalSignatures=.PL|.pl|.sh
  93  CheckPath=$ENV{EPAGES}/bin

Core_Signature
Checks the internal signature of all files in Core or WebInterface that end in .pl or .pm.
  99  [Core_Signature]
 100  Check=signature
 101  InternalSignatures=.pl|.pm
 102  CheckPath=$ENV{EPAGES_CARTRIDGES}
 /DE_EPAGES/Core,$ENV{EPAGES_CARTRIDGES}/DE_EPAGES/WebInterface

Config_Stat
Checks size, owner, access rights and time of the last changes of the files Servlet.conf and log4perl.conf in $ENV{EPAGES_CONFIG}:
 104  [Config_Stat]
 105  Check=size,owner,mode,mtime
 106  CheckFiles=Servlet.conf|log4perl.conf
 107  CheckPath=$ENV{EPAGES_CONFIG}

Task_Cartridges_Hourly
Executes CheckIntegrity.PL hourly from DE_EPAGES_Signature on UNIX-servers (because no At or Schtasks can be defined). Using the "-again" option, you can cause system inconsistencies to alwaysgenerate E-Mails, and not to be ignored by further executions:
 109  [Task_Cartridges_Hourly]
 110  IsActive=1
 111  SubTasks=DE_EPAGES_Signature
 112  Machine=
 113  Cron=55 * * * *
 114  MaxDuration=
 115  Options=-section Task_Cartridges_Hourly -again

Task_Cartridges_UNIX
Executes CheckIntegrity.PL every minute from DE_EPAGES_Stat and Core_Signature on UNIX-servers:
 117  [Task_Cartridges_UNIX]
 118  IsActive=1
 119  SubTasks=DE_EPAGES_Stat,Core_Signature
 120  Machine=
 121  Cron=* * * * *
 122  MaxDuration=4
 123  Options=-section Task_Cartridges_UNIX

3 Setting Up the Scheduler

Prerequisite: Knowledge of the ePages-Scheduler concept

Until now, the only way to run jobs was via the ePages Scheduler. Now, UNIX cron jobs can be administered directly. That has the advantage that the integrity tests can run outside the ePages environment.

If the -add option for the parameter scheduler=epages is entered, the ePages scheduler will be used. The parameter can also be set to scheduler=cron. Then a standard UNIX cron job will be used (default setting).

This extended scheduler concept lets you define scheduler tasks via $HOME/.epages/cron.d/* in addition to the standard $EPAGES_CONFIG/Scheduler.conf and $EPAGES_CONFIG/Scheduler.d/*.env. $HOME is the Homedir of user 'root', '$AMUSER', 'ep_appl', 'ep_db' or 'ep_web'.

The files found in $HOME/.epages/cron.d/* are copied by /etc/init.d/epages6 start_cron (and also /epages6 start) to /etc/cron.d. They are removed from that folder by /epages6 stop. Files found in /etc/cron.d will be run as cron jobs.

In UNIX, the following commands create the same results:

  perl $EPAGES/bin/CheckIntegrity.PL -add scheduler=cron
  perl $EPAGES/bin/CheckIntegrity.PL -add scheduler

These commands create cron-job files in $HOME/.epages/cron.d/. /etc/init.d/epages6 start is used to start the cron jobs.

3.1 SendProgramOutput

The output of each cron job is sent by wrapscheduler.PL via SendProgramOutput.pl (for ePages-Perl) or SMTPSendProgramOutput.PL (for any other Perl).

The connection to the mail server can be defined via the following parameters in the scheduler configuration file, such as Scheduler.conf:

MailStore=
(only possible with ePages Perl) use the e-mail connection as defined in store (default: Site)
MailConnection=
Format: passwd:user@server or user@server or server
Mail sender and recipient can also be defined in the configuration file:

MailSender=
e-mail address of sender (default: as defined in MailConnection resp. MailStore)
MailRecipient=
list of recipients separated by [;,] (default: MailSender)

3.2 UNIX Users in Scheduler.conf

Until now, all jobs defined in Scheduler.conf were run by UNIX-user "ep_appl". Now, other users can be defined via the parameter "User=".

  [ClearTrash]
    # run? (1 - yes, else - no)
    IsActive=1
    # who? (UNIX user)
    User=$ENV{EPAGES_APPUSER}
  ...

If no user is entered, "ep_appl" will be chosen. Allowed users are:

Only "root" or the crontab owner can change the user.

The following code is found in /etc/init.d/epages6:

  [ -z "$EPAGES_IGNORE_CRON" ] && $SU_EXE ep_web -c ". \"$EP_DEFAULT\" ;
  LOGNAME=ep_web \"$EPAGES\"/bin/epagesScheduler.sh start" 2>/dev/null
  [ -z "$EPAGES_IGNORE_CRON" ] && $SU_EXE ep_db -c ". \"$EP_DEFAULT\" ;
  LOGNAME=ep_db \"$EPAGES\"/bin/epagesScheduler.sh start" 2>/dev/null
    $SU_EXE ep_appl -c ". \"$EP_DEFAULT\" ; LOGNAME=ep_appl
    \"$EPAGES\"/bin/epagesScheduler.sh start" 2>/dev/null
    $SU_EXE $EPAGES_APPUSER -c ". \"$EP_DEFAULT\" ; LOGNAME=
    $EPAGES_APPUSER \"$EPAGES\"/bin/epagesScheduler.sh start" 2>
    /dev/null

The patch sets all scheduler jobs (except those that begin with "Sybase") to 'User=$ENV{EPAGES_APPUSER}'. This applies only to jobs from Database/Data/Scheduler/Scheduler.conf.

This doesn't apply for cron jobs that don't come from ePages. If a cron job doesn't run, then use 'User=ep_appl' instead of 'User=$ENV{EPAGES_APPUSER}' (or the other way around).

4 Signing External Cartridges

The script "SignFiles.PL" is used by ePages to sign files with the ePages key. It can also be used by third-parties to sign their self- developed cartridges with their own keys.

In order to do this, you must obtain a private-/public-key-pair. The private key is used to sign the files. The public key is given to the code owner. The user must add the path to the public key as the value for PublicKeys= in CheckIntegrity.conf.

The signatures are created with the following script:

  $EPAGES/bin/SignFiles.PL

The script is mainly meant to create GPG signatures. It can also, however, check or remove GPG signatures, similar to CheckIntegrity.PL. Contrary to CheckIntegrity.PL, SignFiles.PL does not use a configuration file. Each parameter must be entered in a command window. The following command illustrates the possible parameters and their use:

  perl SignFiles.PL -help

SignFiles.PL understands the following modes:

  -verify :     verifies files
  -unsign :     removes the signature
  -resign :     removes the signature and writes them again
   (otherwise): signs files

The remaining options correspond to parameters in CheckIntegrity.conf:

  -files "LIST" : see InternalSignatures= or ExternalSignatures=
  -dir DIR      : see CheckPath=
  -detach DIR   : see SignaturePath=


Copyright ePages GmbH 2016