ePages Installation Guide for Linux 6.17.48
Created: 6.12.2; Updated: 6.17.46

Table of Contents

1 ePages Installation Preliminaries

If you just want to install ePages on a dedicated host then continue with section Basic ePages Installation.

1.1 Components of an ePages Installation

ePages can be installed either on Red Hat/CentOS (with RPM packages) or Debian (with DEB packages).

An ePages 6 system consists of 5 main components:

The packages can be installed on one machine (single server installation), or distributed over various machines (distributed installation). The installation instructions below describe both scenarios.

1.2 System Requirements

1.2.1 Time Server

System time on all involved hosts must be the same and correct. If a network time protocol daemon (as ntpd) is used, all machines must use the same configuration file (as ntp.conf). For more information about the network time protocol daemon, see the manual pages (as man ntpd).

2 Basic ePages Installation

2.1 Single Server Standard Installation

Install the latest version of ePages on a single host by executing:

  curl http://www.epages.com/repo/epages/install-epages.sh | bash

2.2 Single Server Installation Using a Specific Repository

If you want to use other repository than http://www.epages.com/repo/epages define EPAGES_REPOURL:

  export EPAGES_REPOURL=ftp://epages-software.de/repo/epages
  curl http://www.epages.com/repo/epages/install-epages.sh | bash

2.3 Installing ePages Packages Without Starting ePages

install-epages.sh installs the ePages packages in the following way:

  1. Create configuration files in /srv/epages/eproot/Shared/Config
  2. Install ePages packages (.rpm or .deb)
  3. If a package has a postinstall script, run it (e.g. for epages-mysqld create the ePages databases)
If you want to execute just step 2 then run:

  export EPAGES_REPOURL=http://www.epages.com/repo/epages
  export EPAGES_INSTALLATION='unpack'
  curl http://www.epages.com/repo/epages/install-epages.sh | bash

If you want to execute just steps 1 and 2 then run:

  export EPAGES_REPOURL=http://www.epages.com/repo/epages
  export EPAGES_INSTALLATION='nostart'
  curl http://www.epages.com/repo/epages/install-epages.sh | bash

2.4 Basic Options for Repository, Version and Package Handling

If you want more customization run /var/epages/install-epages.sh with options on the command line. This also has the advantage that installation log files are created in /tmp/epages.

For that you must first install the package epages-release which provides /var/epages/install-epages.sh:

  export EPAGES_REPOURL=http://www.epages.com/repo/epages
  export EPAGES_INSTALLATION='-epages'
  curl http://www.epages.com/repo/epages/install-epages.sh | bash

Then you may run /var/epages/install-epages.sh with the options described below.

2.4.1 Set Repository

Environment variables EPAGES_REPOURL and EPAGES_INSTALLATION are only recognized if install-epages.sh is piped into the bash. You can't use EPAGES_REPOURL with /var/epages/install-epages.sh. Instead, if you want to use a different repository, run:

  REPOURL=ftp://epages-software.de/repo/epages
  /var/epages/install-epages.sh --singlehost --repo $REPOURL

2.4.2 Set Version

If you want to install a different ePages version run (replace 6.17.34 with your version):

  VERSION=6.17.34
  REPOURL=ftp://epages-software.de/repo/epages
  /var/epages/install-epages.sh --singlehost --repo $REPOURL --version $VERSION

2.4.3 Just Unpack Packages

Use options --unpack or --nostart in a similiar way as described above:

  REPOURL=ftp://epages-software.de/repo/epages
  /var/epages/install-epages.sh --singlehost --unpack --repo $REPOURL

2.5 Single Server Installation with Configuration Files

With command line arguments you only can customize ePages version and repository. Any other customization must be done via configuration files, for example:

Sample configuration files can be found in /srv/epages/etc/sysconfig from package epages-release. Running install-epages.sh with configuration files shall be done in three steps:

  1. install epages-release which provides /srv/epages/etc/sysconfig and /var/epages/install-epages.sh
  2. Use files in /srv/epages/etc/sysconfig as a sample for your configuration files
  3. Run /var/epages/install-epages.sh --configfile install-epages.conf

2.5.1 Install Package epages-release

First install epages-release:

  export EPAGES_REPOURL=http://www.epages.com/repo/epages
  export EPAGES_INSTALLATION='-epages'
  curl http://www.epages.com/repo/epages/install-epages.sh | bash

2.5.2 Customize Configuration Files

Use install-epages.conf.sample as a sample for your configuration file:

  cd /srv/epages/etc/sysconfig
  /bin/cp -p install-epages.conf.sample install-epages.conf

Add user information for already existing ePages users (created in previous step above):

  cd /srv/epages/etc/sysconfig
  id=($(awk -F: '/^ep_appl:/{print $3 " " $4}' /etc/passwd))
  /var/epages/ini-config.sh -f install-epages.conf -k ep_appl -v "${id[0]}" -i
  /var/epages/ini-config.sh -f install-epages.conf -k epages -v "${id[1]}" -i

Configuration files in /srv/epages/etc/sysconfig already have reasonable values. However, you may edit those configuration files.

2.5.3 Configuration Files Contents

Option --configfile of /var/epages/install-epages.sh defines the base configurations file. Some keys in the base configurations file may point to other configuration files for specific ePages services.

The base configuration file has following sections:

general information
common settings for all servers
unix groups
group name - group ID mapping for ePages groups
unix users
user name - user ID mapping for ePages users
All other sections are (fully qualified or short) hostnames. If a host runs /var/epages/install-epages.sh then it notes only its own section. If no own section found but section localhost exists then it uses this localhost section.

Each hostname sections defines (beside some general settings) what ePages services shall be run and what special configuration files they use.

If a ePages services key is missing, empty or set to 0 then then this service is not used. Otherwise it is. Then, the value of the service key may be a service configuration file path relative to the base configuration file.

For example, if /srv/epages/etc/sysconfig/install-epages.conf contains patchhost=patchhost.conf then patchhost.conf is stored in /srv/epages/etc/sysconfig/patchhost.conf.

Following service keys can be used (see /srv/epages/etc/sysconfig/install-epages.conf.sample):

patchhost=patchhost.conf
host runs the ePages initial installation and patches
patchhost.conf contains environment variables for installation and patch
appsrv=appsrv/localhost.conf
host runs an ePages application server
appsrv/localhost.conf contains settings for WebInterface.conf and ServerConfig.xml. Here you can change the number of the application servers (by extending the ports= range) or the maxmemory= (in MB) each appserver can consume.
ascsrv=ascsrv/localhost.conf
host runs an ePages ASPoolDB cache server
ascsrv/localhost.conf contains settings for ServerConfig.xml. You should not change this for single server installations.
reqsrv=reqsrv/localhost.conf
host runs an ePages request router
reqsrv/localhost.conf contains settings for ServerConfig.xml. You should not change this for single server installations.
mysqld=mysqld/simple.conf
host runs a MySQL server
mysqld/simple.conf defines what business units the server shall provide and some configuration for the business units. See as well mysqld/complex.conf for how to add (cartridges/languages to) business units.
webconf=1
host runs a web server (Apache)
j=j/localhost.conf
host runs a ePages Java server
j/localhost.conf may contain the secret.key for epagesj

2.5.4 Install ePages with Configuration Files

After customizing the configuration start install-epages.sh:

  export REPOURL=http://www.epages.com/repo/epages
  /var/epages/install-epages.sh --repo $REPOURL --configfile install-epages.conf

2.6 Log Files for ePages Installation

Find log files of the ePages installation in:

3 Distributed Installation with Configuration Files

ePages services can be distributed over different hosts. The same service (as e.g. the application server) may reside on various hosts. Business units may be distributed over various hosts.

The base configuration file install-epages.conf defines hostname sections. Each section contains as keys the services which shall be run on that host.

Following service keys can be selected:

fileserver
stores the Shared/ file system (define exactly 1 host as file server)
appsrv
ePages application server
patchhost
application server that runs the ePages initial installation and patches (define exactly 1 host as patch host)
ascsrv
ePages ASPoolDB cache server
reqsrv
ePages request router
mysqld
MySQL server
webconf
Apache web server
j
ePages Java server
ePages must be installed on the distributed hosts in a specific order:

  1. First run install-epages.sh on the file server.
  2. Run install-epages.sh on ePages Java server only after creating epagesj database (executed by install-epages.sh on right MySQL server).
  3. Run install-epages.sh on ePages ASPoolDB cache server / Request Router only after creating ASPoolDB database (executed by install-epages.sh on right MySQL server).
  4. Finally run install-epages.sh on the patch host.
If these dependencies are conflicting then single services may be installed by using option --distributed. For example, if the base configuration file defines the services mysqld, ascsrv and reqsrv to be installed on one host then you may install first the database:

  /var/epages/install-epages.sh --distributed mysqld --configfile install-epages.conf

and later the ASPoolDB cache server and Request Router:

  /var/epages/install-epages.sh --distributed 'ascsrv reqsrv' --configfile install-epages.conf

3.1 Example Part 1: Customize Configuration Files on File Server

In following example we assume ePages distributed over three hosts:

First install package epages-release on file server:

  export EPAGES_REPOURL=http://www.epages.com/repo/epages
  export EPAGES_INSTALLATION='-epages'
  curl http://www.epages.com/repo/epages/install-epages.sh | bash

Then create install-epages.conf as required before:

  cd /srv/epages/etc/sysconfig
  cat >>install-epages.conf <<HERE
  [asjs.example.com]
  fileserver=server
  patchhost=1
  appsrv=1
  j=1
  [wsrr.example.com]
  fileserver=client
  ascsrv=1
  reqsrv=1
  webconf=1
  [db.example.com]
  fileserver=client
  mysqld=1
  HERE

3.2 Example Part 2: Install ePages on distributed servers

After starting the file server and configuring the installation, run install-epages.sh on the MySQL server (note that you must define the used file server in EPAGES_INSTALLATION):

  export EPAGES_REPOURL=http://www.epages.com/repo/epages
  export EPAGES_INSTALLATION='fileserver=asjs.example.com'
  curl http://www.epages.com/repo/epages/install-epages.sh | bash
  CFG=/srv/epages/etc/sysconfig/install-epages.conf
  /var/epages/install-epages.sh --version $VERSION --repo $EPAGES_REPOURL --configfile $CFG

Then run install-epages.sh on wsrr.example.com (note that you must define the used file server in EPAGES_INSTALLATION):

  export EPAGES_REPOURL=http://www.epages.com/repo/epages
  export EPAGES_INSTALLATION='fileserver=asjs.example.com'
  curl http://www.epages.com/repo/epages/install-epages.sh | bash
  CFG=/srv/epages/etc/sysconfig/install-epages.conf
  /var/epages/install-epages.sh --version $VERSION --repo $EPAGES_REPOURL --configfile $CFG

Finally go back to the file server (which is also patch host) and run:

  export EPAGES_REPOURL=http://www.epages.com/repo/epages
  CFG=/srv/epages/etc/sysconfig/install-epages.conf
  /var/epages/install-epages.sh --version $VERSION --repo $EPAGES_REPOURL --configfile $CFG

4 Starting and Stopping Services

Services may be started automatically (initlevel or rc scripts) or manually by the UNIX command:

  /etc/init.d/epages6 <start parameter>

Services may be stopped automatically (initlevel or rc scripts) or manually by the UNIX command:

  /etc/init.d/epages6 <stop parameter>

<parameter> defines the components of the application involved:

start parameter stop parameter controls
start_httpd stop_httpd web server (only if installed and configured with epages)
start_service stop_service application server
start_rr stop_rr request router
start_db stop_db database server
start_java stop_java includes mongod, epagesj, epages-solr, epages-solr-slave
start stop includes web, database, java and application server
show   show all running ePages processes

A manual start of an active service causes that service to stop and restart.

Starting the SSL web server works only if:

  1. The SSL certificate file for the web server is stored in $HTTPD_ROOT/conf/ssl.crt/server.crt (where $HTTPD_ROOT is for example /etc/httpd).
  2. The SSL certificate key file for the web server is stored in $HTTPD_ROOT/conf/ssl.key/server.key (where $HTTPD_ROOT is for example /etc/httpd).
The epagesj server is started as follows:

/etc/init.d/epagesj start

The solr server is started as follows:

/etc/init.d/epages-solr start

The solr slave server is started as follows:

/etc/init.d/epages-solr-slave start

Stop all servers with 'stop', show status of those servers with 'status'.

5 Patching ePages

ePages may be patched by yum/apt-get (as described below) or on command line. For detailed instructions and information on patching ePages 6, see ePages Patch Installation.

5.1 Red Hat: Patch ePages to the Latest Version

Patching ePages consists of three steps:

  1. Update epages-release.
  2. Update new RPMs with yum (epages-patch as last package!).
  rpm -hUv http://www.epages.com/repo/epages/yum/epages-release.noarch.rpm
  yum -y update 'epages-[a-oq-z]*' --disablerepo epages-setup --enablerepo epages-update
  yum -y update epages-patch --disablerepo epages-setup --enablerepo epages-update

5.2 Debian: Patch ePages to the Latest Version

Patching ePages consists of three steps:

  1. Update epages-release.
  2. Update new DEBs with apt-get (epages-patch as last package!).
  curl -O http://www.epages.com/repo/epages/apt/epages-release_all.deb
  dpkg -i epages-release_all.deb
  apt-get -y update
  apt-get -y --only-upgrade install 'epages-[^pt]'
  apt-get -y install epages-patch

5.3 Log Files for Patches

If a patch is installed with YUM following log files are written (version 6_17_6 may vary):

/tmp/epages-patch_6_17_6-prerequisites.log
contains the output of the patch pre-installation commands
/tmp/epages-patch_6_17_6-install.log
contains the output of the patch installation commands
/srv/epages/eproot/Shared/Patches/var_patch_VERSION/
contains the output of the patch API

5.4 Installing ePages Patch Files Without Starting the Patch

If you want to install the patch files into $EPAGES_SHARED/Patches/patch_X_Y_Z/ but don't want to start the patch executing './patch.sh install', run:

  yum -y update 'epages-[a-oq-z]*' --disablerepo epages-setup --enablerepo epages-update
  EPAGES_DO_PATCH=0 yum -y update epages-patch --disablerepo epages-setup --enablerepo epages-update

Then after installing the patch files, run following commands to install the patch itself:

  cd $EPAGES_SHARED/Patches/patch_*
  ./patch.sh install

5.5 Customizing the ePages Patch Installation

  EPAGES_PREREQ_INI=/tmp/prerequisits.ini yum update epages-patch --disablerepo epages-setup --enablerepo epages-update

  EPAGES_PATCH_CONF=/path/to/Conf yum update epages-patch --disablerepo epages-setup --enablerepo epages-update

Read the prerequisits.ini file resp. the Conf/ directory provided by the patch to find customizable parameters.

5.6 Patching Distributed Installations

Section 'Patch a Distributed ePages Installation' in document ePages Patch Installation explains how to patch a distributed installation.

6 Removing ePages

You may remove a single server ePages installation by executing:

on Red Hat:

  yum remove @epages

on Debian:

  apt-get remove epages

Both commands do not remove ePages completely, changed files remain on the server. To remove ePages on a single server completely, run:

  /var/epages/delete-epages.sh

This removes all ePages RPMs/DEBs, files, users, and databases.

6.1 Removing Distributed Installations on Red Hat

1. Run on each server but the file server:

  /var/tmp/epages-fs.sh -unmount
  yum remove ...

... means all packages you installed with yum install ... before.

2. Run on the file server:

  /var/tmp/epages-fs.sh -unshare
  yum remove ...

... means all packages you installed with yum install ... before.

This does not remove ePages completely, changed files remain on the server. To remove ePages completely, run (first on each server but the file server, then on the file server):

  /var/epages/delete-epages.sh

7 ePages Repositories and Packages

ePages RPM packages (see above) are provided by different ePages YUM repositories.

ePages DEB packages (see above) are provided by different ePages APT repositories.

ePages YUM repository configuration files are stored in /etc/yum.repos.d/epages-*.repo.

ePages APT repository configuration file is stored in /etc/apt/sources.list.d/epages.list.

ePages repositories are mirrored and can be found in:

YUM chooses the repository with the fastest access.

You may browse through ftp://epages-software.de/repo/epages/ to see what RPM packages ePages provides.

Installing the package epages-release adds following files to the system:

/var/epages/
directory with shell scripts required for installing ePages
/etc/sysconfig/epages6
see Customizable Installation Parameters
/etc/pki/rpm-gpg/RPM-GPG-KEY-epages
public key for signatures of ePages RPM files
/etc/debsig/policies/9798CC69B1D28320/epages.pol
public key for signatures of ePages DEB files
/etc/yum.repos.d/*epages*
RPM repository configuration files
/etc/apt/sources.list.d/epages.list
DEB repository configuration file

7.1 Verify RPM Packages on Red Hat

All ePages RPM packages are signed by a GNU Privacy Guard (GPG) key. If you want to verify that a RPM package was really made by ePages, you need the public key. Unless already installed as part of epages-release, get it from the web site http://www.epages.com/security/b1d28320.txt .

To show which key was used to sign an ePages RPM package, run the command:

  rpm --checksig -v <filename>.rpm

To verify the signature of an ePages RPM package, first import the public key (unless installed already package epages-release):

  rpm --import b1d28320.txt

Then execute:

  rpm -K <filename>.rpm

The command should return:

  <filename>.rpm: (sha1) dsa sha1 md5 gpg OK

Example:

  # rpm -K http://www.epages.com/repo/epages/yum/epages-release.noarch.rpm
  http://www.epages.com/repo/epages/yum/epages-release.noarch.rpm: (sha1) dsa sha1 md5 gpg OK

7.2 YUM Troubleshooting

7.2.1 Metadata File Does Not Match Checksum

Problem:

  http://www.epages.com/repo/epages/6.16.3/i386/repodata/filelists.xml.gz: [Errno -1] Metadata file does not match checksum

Solution:

  yum clean all

7.2.2 Protected Multilib Versions

Problem:

  yum install krb5-libs.i686 openssl.i686 openssl098e.i686
  ...
  Error: Protected multilib versions: openssl-1.0.0-20.el6.i686 != openssl-1.0.0-10.el6_1.4.x86_64
  Error: Protected multilib versions: krb5-libs-1.9-22.el6_2.1.i686 != krb5-libs-1.9-9.el6_1.1.x86_64
   You could try using --skip-broken to work around the problem
   You could try running: rpm -Va --nofiles --nodigest

Solution:

  yum install --setopt=protected_multilib=false krb5-libs.i686 openssl.i686 openssl098e.i686

7.2.3 File Conflicts

Problem:

  yum install openssl.i686
  ...
  Transaction Check Error:
    file /usr/share/doc/openssl-1.0.0/README.FIPS from install of openssl-1.0.0-20.el6.i686 conflicts with file from package openssl-1.0.0-10.el6_1.4.x86_64
    file /usr/share/man/man1/ca.1ssl.gz from install of openssl-1.0.0-20.el6.i686 conflicts with file from package openssl-1.0.0-10.el6_1.4.x86_64
    file /usr/share/man/man1/openssl.1ssl.gz from install of openssl-1.0.0-20.el6.i686 conflicts with file from package openssl-1.0.0-10.el6_1.4.x86_64
    file /usr/share/man/man1/req.1ssl.gz from install of openssl-1.0.0-20.el6.i686 conflicts with file from package openssl-1.0.0-10.el6_1.4.x86_64
    file /usr/share/man/man1/x509.1ssl.gz from install of openssl-1.0.0-20.el6.i686 conflicts with file from package openssl-1.0.0-10.el6_1.4.x86_64

Solution 1 (preferred):

  yum -y install yum-utils
  mkdir -p download && cd download
  yumdownloader --resolve openssl.i686
  mv openssl-*.i686.rpm ..
  rpm -hUv *.rpm
  cd ..
  rpm -hiv --nodocs openssl-*.i686.rpm

Solution 2:

  rpm -qa --qf '%{name}-%{version}-%{release}.%{arch}\n' 2>&1 | grep openssl
  # openssl-1.0.0-10.el6_1.4.x86_64
  rpm -e --justdb --nodeps openssl-1.0.0-10.el6_1.4.x86_64
  yum install krb5-libs.i686 openssl.i686 openssl098e.i686

7.2.4 TypeError: Unsupported Operand Type

Problem:

  yum groupinstall epages
  ...
  Total download size: 220 M
  Is this ok [y/N]: y
  Downloading Packages:
  Traceback (most recent call last):
  File "/usr/bin/yum", line 29, in ?
  yummain.user_main(sys.argv[1:], exit_code=True)
  File "/usr/share/yum-cli/yummain.py", line 229, in user_main
  errcode = main(args)
  File "/usr/share/yum-cli/yummain.py", line 181, in main
  return_code = base.doTransaction()
  File "/usr/share/yum-cli/cli.py", line 386, in doTransaction
    problems = self.downloadPkgs(downloadpkgs, callback_total=self.download_callback_total_cb)
  File "/usr/lib/python2.4/site-packages/yum/__init__.py", line 1108, in downloadPkgs
  remote_size += po.size
  TypeError: unsupported operand type(s) for +=: 'int' and 'str'

Solution:

  yum -y install yum-utils
  mkdir -p download && cd download
  yumdownloader --resolve yum-metadata-parser
  rpm -hiv --force yum-metadata-parser-*.el5.i386


Copyright ePages GmbH 2016