ePages Installation Guide for Linux 6.15.4
Created: 6.12.2; Updated: 6.15.3

Table of Contents

1 ePages Installation Basics

1.1 Components of an ePages Installation

An ePages 6 system consists of 5 main components:

All RPM packages require epages-requires*.rpm, epages-common*.rpm, epages-patch*.rpm, epages-perl*.rpm. Packages epages-appsrv'' and epages-mysqld additionally require epages-mysql*.rpm.

The RPM 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

For distributed installations all involved machines must have the same system time. 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).

1.3 ePages YUM Repositories

ePages RPM packages (see above) are provided by different ePages YUM repositories, depending on:

ePages YUM repository configuration files can be found in /etc/yum.repos.d/epages-*.repo.

ePages YUM repositories are mirrored and can be found in:

YUM chooses the repository with the fastest access.

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

Before starting the ePages installation, the ePages YUM repository configuration files must be added to /etc/yum.repos.d/ by executing rpmify-epages.sh:

  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh

rpmify-epages.sh executes:

Installing epages-release.noarch.rpm adds following files to the system:

/etc/yum.repos.d/*epages*
repository configuration files
/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 (added to the system by 'rpm --import ...')

1.3.1 Using a Local Repository

If (parts of) your ePages installation has no (due to firewall) or slow internet connection, you may want to mirror the ePages repositories to a local machine and install ePages from the local repository. The following 3 steps show you how.

1. Create a copy of the epages repository on your local machine. Choose your preferred mirroring/synchronization tool. The following example uses lftp to synchonize ftp://epages-software.de/pub/products/RPMS with the local directory /opt/epages-repository (directory may vary):

  cd /opt
  lftp -u ftp,ftp -e "mirror --delete --only-newer --verbose pub/products/RPMS epages-repository; quit" epages-software.de

2. Use the local repository for installing ePages:

  /opt/epages-repository/rpmify/rpmify-epages.sh -repo /opt/epages-repository

3. Now you can do everything with yum as described in the document, e.g. install ePages from the local repository:

  yum groupinstall epages

The only difference to the official ePages repository is that the local repository isn't updated automatically. If you want to have your local repository up-to-date, run lftp (or your preferred mirror tool) once a month or so.

The -repo argument of rpmify-epages.sh also allows any other http or ftp URL. For example, you may store the ePages repository on your local http server.

1.4 Verify RPM Packages

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 by rpmify-epages.sh, get from the web site http://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 already installed by rpmify-epages.sh):

  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://epages.com/RPMS/epages-release.noarch.rpm
  http://epages.com/RPMS/epages-release.noarch.rpm: (sha1) dsa sha1 md5 gpg OK

1.5 Customizable Installation Parameters

Executing rpmify-epages.sh installs the installation configuration file /etc/sysconfig/epages6.

After executing rpmify-epages.sh and before installing ePages you may change /etc/sysconfig/epages6 to customize your ePages installation:

  vi /etc/sysconfig/epages6
  . /etc/sysconfig/epages6

For single server installations, normally you won't change /etc/sysconfig/epages6. Even in distributed installations it is not necessary to change /etc/sysconfig/epages6. Following sections describe the most important customizable parameters; every single parameter is described in /etc/sysconfig/epages6 itself.

For distributed installations, all involved servers must use the same configuration file /etc/sysconfig/epages6.

To achive this, following steps must be executed (see sections Custom Installation on Two Machines or Custom Installation on Three Machines below):

  1. Run rpmify-epages.sh on the file server.
  2. Customize /etc/sysconfig/epages6 as described in the following sections.
  3. Share the installed file system on the file server (and mount it on the other servers later).

1.5.1 Users and Groups

A distributed ePages 6 installation requires user and group definitions with the same user and group IDs on all machines.

parameter defines default
EPAGES_INSTALL_WS_GROUP web server group name ep_web
EPAGES_INSTALL_WS_RUNUSER user who runs the web server eprunweb
EPAGES_INSTALL_AS_RUNUSER user who runs the application server eprunapp
EPAGES_INSTALL_EPAGESJ_USER user who runs the java server epagesj
EPAGES_INSTALL_WS_RUNUID ID of $EPAGES_INSTALL_WS_RUNUSER
EPAGES_INSTALL_WS_UID ID of the web server file owner
EPAGES_INSTALL_WS_GID ID of the web server group
EPAGES_INSTALL_EP_GID ID of the group epages
EPAGES_INSTALL_AS_RUNUID ID of $EPAGES_INSTALL_AS_RUNUSER
EPAGES_INSTALL_AS_UID ID of the application server file owner ep_appl
EPAGES_INSTALL_DB_UID ID of the database server user ep_db
EPAGES_INSTALL_EPAGESJ_UID ID of $EPAGES_INSTALL_EPAGESJ_USER

1.5.2 Server Names, IPs, Ports

A distributed ePages 6 installation needs to know what hosts shall run what services. Furthermore you may choose what IPs and ports to use (especially if you have more than 1 network card).

Set those parameters in /etc/sysconfig/epages6.

Define server names/IPs and ports in /etc/sysconfig/epages6. All variables ending in _HOST must contain either a host name (long as host1.example.com or short as host1) or an IP address:

parameter defines
EPAGES_INSTALL_AS_HOST application server host
EPAGES_INSTALL_RR_HOST request router host (typically same as web server)
EPAGES_INSTALL_WS_HOST web server host
EPAGES_INSTALL_EPAGESJ_HOST java server host
EPAGES_INSTALL_SOLR_HOST solr server host
EPAGES_INSTALL_SOLRSLAVE_HOST solr slave host
EPAGES_INSTALL_MONGO_HOST mongodb server host
EPAGES_INSTALL_MYSQL_CONNECTION MySQL server connection string

For each variable ending in _HOST there is a variable ending in _HOSTIP that defines the IP of the host. Set both variables if hostname and IP are not DNS resolvable or if there is more than 1 network card.

For each variable ending in _HOST there is a variable ending in _PORT defining the server port. These variables are optional and have sensible defaults. Do not change this variables unless you really need to.

1.5.3 MySQL Parameters

If the password of the MySQL user root has changed (i.e. is neither empty nor epages), change EPAGES_INSTALL_MYSQL_PASS in /etc/sysconfig/epages6 accordingly, e.g.:

  export EPAGES_INSTALL_MYSQL_PASS="secret_password"

2 Installing ePages

2.1 Basic ePages Installation

If you set the environment variable VERBOSE=1 then you get a verbose yum installation.

1. Add ePages to your YUM repository:

  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh

If some RPM packages are missing that are required for the ePages installation, a message is shown how to install those packages first. Then re-run the command above.

2. File /etc/sysconfig/epages6 contains variable settings.

All variables are optional and have sensible defaults. Read the variable descriptions in /etc/sysconfig/epages6.

If you want to customize variables, edit /etc/sysconfig/epages6.

If the password of the MySQL user root has changed (i.e. it is neither empty nor epages), change EPAGES_INSTALL_MYSQL_PASS in /etc/sysconfig/epages6 accordingly, e.g.:

  export EPAGES_INSTALL_MYSQL_PASS="secret_password"

3. Install and start ePages:

  yum groupinstall epages

2.2 Install a Specific ePages Release

Beside the latest release, the ePages repository also provides any other releases starting from version 6.10.0. Installing old releases is similar to installing the latest release:

  1. Install the ePages repositories into /etc/yum.repos.d/ with rpmify-epages.sh.
  2. Install ePages with yum from the repository of the desired version.
Run (VERSION=6.12.0 may differ):

  VERSION=6.12.0
  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh
  yum -y groupinstall epages --enablerepo epages-$VERSION --disablerepo epages-setup

2.3 Installing ePages With Language Packs

You may install ePages with language packs automatically starting from version 6.13.1.

For versions 6.13.x and 6.14.0 run following command to install all languages:

  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh
  EPAGES_LANGUAGES=any EPAGES_LANG_KEY='k4_h1Hx+RH' yum groupinstall epages

If you want to install specific languages, use the 2-character language codes, e.g. for Spanish and Italian:

  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh
  EPAGES_LANGUAGES='es it' EPAGES_LANG_KEY='k4_h1Hx+RH' yum groupinstall epages

Starting from 6.14.1 EPAGES_LANG_KEY is not necessary anymore.

2.4 Installing ePages Without Starting the Database Installation

To avoid starting the database installation after the file installation: instead of installing the complete @epages group, just install its parts:

  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh
  yum groupinstall epages-appsrv epages-reqsrv epages-mysqld epages-webconf epages-j

epages-j was introduced with 6.14.0, omit this if you want to install an older version.

3 Distributed Installation

Distributed installation allows you to install certain components of ePages (as described in Components of an ePages Installation) on specific machines:

If you want to install ePages distributed in a different way, use the following framework:

1. Choose one server as file server and run on it:

  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh
  /var/tmp/epages-fs.sh -share

2. On all other servers run (where FILESERVER is the name of the file server):

  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh
  /var/tmp/epages-fs.sh -mount FILESERVER

3. (Optionally) Edit and start /etc/sysconfig/epages6:

  vi /etc/sysconfig/epages6
  . /etc/sysconfig/epages6

4. Install on each servers its components. Choose one/more of following command:

  yum groupinstall epages-appsrv
  yum groupinstall epages-reqsrv
  yum groupinstall epages-mysqld
  yum groupinstall epages-webconf
  yum groupinstall epages-j

epages-j is only introduces with 6.14.0, don't use it if you want to install an older version.

5. Start ePages on each server (order: first on java server, then on web server/request router, then on database server, last on application server):

  yum install epages-setup

3.1 Custom Installation on Two Machines

3.1.1 Machine 1: Database Server and File System

1. Run rpmify-epages.sh:

  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh

2. Edit /etc/sysconfig/epages6 as described in Customizable Installation Parameters (if necessary).

3. Share the file system:

  /var/epages/epages-fs.sh -share

4. Install the database server:

  yum groupinstall epages-mysqld

5. Ignore ePages schedulers on the database server (or change $EPAGES_CONFIG/Scheduler.conf manually):

  /var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGES_IGNORE_CRON -v 1 -i

6. If SELinux is enabled, set the SELinux context for ePages:

  /srv/epages/eproot/bin/se-file-context.sh --set --perl-cgi

3.1.2 Machine 2: Application Server, Java Server and Web Server

1. Run rpmify-epages.sh:

  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh

2. Mount the previously shared file system (replace HOSTNAME by the hostname of machine 1):

  /var/epages/epages-fs.sh -mount HOSTNAME

3. Install the application server, java server, web server and request router:

  yum groupinstall epages-appsrv epages-j epages-reqsrv epages-webconf

4. If SELinux is enabled, set the SELinux context for ePages:

  /srv/epages/eproot/bin/se-file-context.sh --set --perl-cgi
  /srv/epages/eproot/bin/se-webnfs-context.sh --set --no-start
  /etc/init.d/epages6 start_java

3.1.3 Start ePages 6 Services

After successful installation first (order is important!) start ePages 6 first on the database server, then on the application/web server:

  yum install epages-setup

3.2 Custom Installation on Three Machines

3.2.1 Machine 1: Application Server and Java Server

1. Run rpmify-epages.sh:

  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh

2. Edit /etc/sysconfig/epages6 as described in Customizable Installation Parameters (if necessary).

3. Share the installed system:

  /var/epages/epages-fs.sh -share

4. Install the application server:

  yum groupinstall epages-appsrv epages-j

5. If SELinux is enabled, set the SELinux context for ePages:

  /srv/epages/eproot/bin/se-file-context.sh --set --perl-cgi

3.2.2 Machine 2: Database Server

1. Run rpmify-epages.sh:

  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh

2. Mount the previously shared file system (replace HOSTNAME by the hostname of machine 1):

  /var/epages/epages-fs.sh -mount HOSTNAME

3. Install the database server:

  yum groupinstall epages-mysqld

4. Ignore ePages schedulers on database server (or change $EPAGES_CONFIG/Scheduler.conf manually):

  /var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGES_IGNORE_CRON -v 1 -i

5. If SELinux is enabled, set the SELinux context for ePages:

  /srv/epages/eproot/bin/se-file-context.sh --set --perl-cgi

3.2.3 Machine 3: Web Server and Request Router

1. Run rpmify-epages.sh:

  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh

2. Mount the previously shared file system (replace HOSTNAME by the hostname of machine 1):

  /var/epages/epages-fs.sh -mount HOSTNAME

3. Install web server and request router:

  yum groupinstall epages-webconf epages-reqsrv

4. Ignore ePages schedulers on web server (or change $EPAGES_CONFIG/Scheduler.conf manually):

  /var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGES_IGNORE_CRON -v 1 -i

5. If SELinux is enabled, set the SELinux context for ePages:

  /srv/epages/eproot/bin/se-file-context.sh --set --perl-cgi
  /srv/epages/eproot/bin/se-webnfs-context.sh --set --no-start

3.2.4 Start ePages 6 Services

After successful installation first (order is important!) start ePages 6 first on the web server, second on the database server, third on the application server:

  yum install epages-setup

3.3 Custom Installation with Load Balancing

If ePages is installed on 2 machines as described in Custom Installation on Two Machines, you may simply add a further application server to achive load balancing and scalability.

This sections describes how to add a further application server to your system.

The ePages installation will still work if one of the application servers is down. If the database server is down, ePages won't work anymore. To achive this you must replicate database server, file server and load balancer by your own.

Following description works only for ePages installations with initial version 6.15.1 or higher. If you want to use load balancing as described here on older installations:

1. update ePages to (at least) 6.15.1, 2. backup the original Apache configuration in /etc/httpd (resp. /etc/apache2), 3. execute on any host with epages web server:

  /srv/epages/eproot/bin/use-local-httpd.sh -r

3.3.1 Install ePages

First install ePages on 2 machines as described in Custom Installation on Two Machines.

Configure the application server (replace _IP_ by the IP of machine 1):

  /var/epages/ini-config.sh -f /etc/default/epages6 -k HTTPD_OPTS -v '"-DSSL -DRPAF"' -i
  /var/epages/ini-config.sh -f /etc/default/epages6 -k LOAD_BALANCER_IP -v _IP_ -i

3.3.2 Install Additional Application Server

Install ePages on a additional machine in the same way as described in Machine 2: Application Server, Java Server and Web Server.

On the additional application server, configure epages (replace _IP_ by the IP of machine 1):

  /var/epages/ini-config.sh -f /srv/epages/eproot/j/conf/epagesj.conf -k host -v $(hostname --fqdn) -i
  /var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGESJ_HOST -v $(hostname --fqdn) -i
  /var/epages/ini-config.sh -f /etc/default/epages6 -k HTTPD_OPTS -v '"-DSSL -DRPAF"' -i
  /var/epages/ini-config.sh -f /etc/default/epages6 -k LOAD_BALANCER_IP -v _IP_ -i
  /var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGES_IGNORE_CRON -v 1 -i
  rm -f /srv/epages/eproot/Shared/Config/appsrv.ini

If SELinux is enabled, set the SELinux context for ePages:

  /srv/epages/eproot/bin/se-file-context.sh --set --perl-cgi
  /srv/epages/eproot/bin/se-webnfs-context.sh --set --no-start
  /etc/init.d/epages6 start_java

Go on with installing/configuring the load balancer.

3.3.3 Install Load Balancer

Install (unless already done) the load balancer on the database server (machine 1):

  yum groupinstall epages-webconf

This installs Apache, you may install any load balancer. In the following we assume that Apache is used as load balancer.

3.3.4 Configure Load Balancer

On the load balancer, configure the Apache web server (replace "machine2.example.com machine3.example.com" by your application server list):

  /var/epages/ini-config.sh -f /etc/default/epages6 -k HTTPD_OPTS -v '"-DSSL -DLB"' -i
  /var/epages/ini-config.sh -f /etc/default/epages6 -k BALANCER_MEMBERS -v "(machine2.example.com machine3.example.com)" -i

and (unless already done) change the domain name in the databases:

  . /etc/default/epages6
  $PERL $EPAGES_CARTRIDGES/DE_EPAGES/ShopConfiguration/Scripts/ChangeDomainName.pl -address $(hostname --fqdn)

After that change, new ePages URLs are http://machine1.example.com/... resp. https://machine1.example.com/... (replace machine1.example.com by the domain name of your load balancer).

3.3.5 Start ePages 6 Services

After successful installation first restart ePages on the load balancer (machine 1):

  /etc/init.d/epages6 start

Then on the application server(s) already existing before enhacement:

  /etc/init.d/epages6 start

Then on the new application server:

  yum install epages-setup

3.3.6 Load Balancer Monitor

Check if the load balancer works by accessing the web page http://machine1.example.com/balancer-manager (replace machine1.example.com by the name of the load balancer).

Because the page is 'Allow from' restricted, the IP of your desktop (where you run the web browser) must be mentioned in the environment variable EPAGES_ALLOW_FROM= in /etc/default/epages6.

Allow access for your desktop (e.g. 1.2.3.4) to the restricted page by executing following commands on the load balancer as well on all balancer members:

  /var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGES_ALLOW_FROM -v '"1.2.3.4"' -i
  /etc/init.d/epages6 start_httpd

Another restricted page shows you request statistics handled by the request routers: http://machine1.example.com/Monitor/spy.pl

The number of request routers shown there should be equal to the number of epages hosts (if you installed ePages as described before).

3.3.7 Failover

If at least one of the application servers is still running, ePages will stay working.

If the primary applications server goes down, one other server must overtake the scheduler jobs, run on this server:

  /var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGES_IGNORE_CRON -v "" -i
  /etc/init.d/epages6 start_cron

3.3.8 Failback

If a application server goes live again, restart the load balancer:

  /etc/init.d/epages6 start_httpd

If the primary application server goes live again:

1. shut down the scheduler jobs on the failover server:

  /etc/init.d/epages6 stop_cron
  /var/epages/ini-config.sh -f /etc/default/epages6 -k EPAGES_IGNORE_CRON -v 1 -i

2. restart the request router on any application server:

  /etc/init.d/epages6 start_rr

3.4 Load Balancing for Experts

It is also possible to install load balancer and balancer member on the same machine. This might be not very useful in a productive environment, but you can test load balancing on a single server. This section shows how to use load balancing on a single server installation, afterwards extended by a further balancer member on a different host.

3.4.1 Environment Variables for Load Balancing

If the load balancer runs on one host, and the balancer members run on other hosts (each on a different, say machine2 and machine3), then following environment variables must be set on the load balancer:

  /var/epages/ini-config.sh -f /etc/default/epages6 -k HTTPD_OPTS -v '"-DSSL -DLB"' -i
  /var/epages/ini-config.sh -f /etc/default/epages6 -k BALANCER_MEMBERS -v "(machine2 machine3)" -i

and following environment variables must be set on each balancer member (_IP_ is IP of load balancer):

  /var/epages/ini-config.sh -f /etc/default/epages6 -k HTTPD_OPTS -v '"-DSSL -DRPAF"' -i
  /var/epages/ini-config.sh -f /etc/default/epages6 -k LOAD_BALANCER_IP -v _IP_ -i

This we did in section Custom Installation with Load Balancing.

If ePages was installed as Basic ePages Installation, add load balancing by setting environment variables as follows (assuming `hostname` is resolvable by dig):

  /var/epages/ini-config.sh -f /etc/default/epages6 -k HTTPD_OPTS -v '"-DSSL -DLB"' -i
  /var/epages/ini-config.sh -f /etc/default/epages6 -k LOAD_BALANCER_IP \
  -v $(dig +short $(hostname) +search +noall +answer | head -1) -i
  /var/epages/ini-config.sh -f /etc/default/epages6 -k BALANCER_MEMBERS -v "(8008)" -i

This is rather proxying than load balancing because (until now) we only have one balancer member: the web server on port 8008 (port may vary).

The SSL port of the balancer member defaults to 8443, you may change this (to e.g. 8444) by executing:

  /var/epages/ini-config.sh -f /etc/default/epages6 -k BALANCER_MEMBERS_SSL -v "(8444)" -i

Start the load balancer and the balancer member:

  /etc/init.d/epages6 start_httpd

Check if everything works fine, see section Load Balancer Monitor.

3.4.2 Add a Further Balancer Member

On the load balancer, share the file system:

  /var/epages/epages-fs.sh -share

Add a further balancer member as described in Install Additional Application Server.

On the new balancer member, start ePages:

  /etc/init.d/epages6 start

On the load balancer, add a new balancer member (replace machine2.example.com by the name of the new host):

  x=$(/var/epages/ini-config.sh -f /etc/default/epages6 -k BALANCER_MEMBERS -g)
  x="${x%)*} machine2.example.com)"
  /var/epages/ini-config.sh -f /etc/default/epages6 -k BALANCER_MEMBERS -v "$x" -i

If you changed BALANCER_MEMBERS_SSL before, run same commands with BALANCER_MEMBERS_SSL.

On the load balancer, start epages:

  /etc/init.d/epages6 start_httpd

Check if everything works fine, see section Load Balancer Monitor.

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 (as described below) or on command line. For detailed instructions and information on patching ePages 6, see ePages Patch Installation.

5.1 Patch ePages to the Latest Version

YUM can be used for patching only if the installed ePages has at least version 6.10.0.

Patching ePages consists of three steps:

  1. Update the ePages repositories with rpmify-epages.sh.
  2. Check for new RPM versions.
  3. Update new RPMs with yum.
  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh
  yum check-update 'epages-*' --disablerepo epages-setup --enablerepo epages-update
  yum update 'epages-j' --disablerepo epages-setup --enablerepo epages-update
  yum update 'epages-*' --disablerepo epages-setup --enablerepo epages-update

Depending on the source version, it is possible that the target version can't be reached directly. Then, run the commands above again until the desired target version is reached.

5.2 Patch ePages to a Specific Version

ePages also can be patched to any desired version (starting from the installed version, at least 6.10.0). Patching to old versions is similar to patching to the latest version:

  1. Update the ePages repositories with rpmify-epages.sh.
  2. Enable the update repository for the desired version(and disable the update repository for the latest version).
  3. Update new RPMs with yum.
Run (VERSION=6.12.0 may differ):

  VERSION=6.12.0
  curl http://www.epages.com/RPMS/rpmify/rpmify-epages.sh | sh
  yum update 'epages-j' --disablerepo epages-setup --enablerepo epages-update-$VERSION
  yum update 'epages-*' --disablerepo epages-setup --enablerepo epages-update-$VERSION

Depending on the source version, it is possible that the target version can't be reached directly. Then, run the commands above again until the desired target version is reached.

5.3 Log Files for Patches

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

/tmp/epages-6.12.0.new-versions
contains versions of all installed ePages patches
/tmp/epages-6.12.0.install-patch
contains the executed commands of the patch installation
~/epages-6.12.0-install.log
contains the output of the executed commands

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 update 'epages-j' --disablerepo epages-setup --enablerepo epages-update
  EPAGES_DO_PATCH=0 yum update 'epages-*' --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_BACKUP_DIR= EPAGES_BACKUP_DB= yum update 'epages-*' --disablerepo epages-setup --enablerepo epages-update

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

  EPAGES_PATCH_CONF=/path/to/Conf yum update 'epages-*' --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

You can patch distributed installation with yum only under very special circumstances, normally distributed installations are patched manually with the patch.tar.gz file, see ePages Patch Installation.

You may patch a distributed installation with yum if the installation consists of only 2 servers: a) the database server and b) the host with all other services. Then, first run on the database server:

  yum -y update 'epages-*' --disablerepo epages-setup --enablerepo epages-empty

Then run on the other server:

  yum -y update 'epages-j' --disablerepo epages-setup --enablerepo epages-update
  yum -y update 'epages-*' --disablerepo epages-setup --enablerepo epages-update

6 Removing ePages

You may remove a single server ePages installation by executing:

  yum remove @epages

This does 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, files, users, and databases.

6.1 Removing Distributed Installations

1. Run on each server but the file server:

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

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

2. Run on the file server:

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

... means all packages you installed with yum groupinstall ... 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 oon the file server):

  /var/epages/delete-epages.sh

7 YUM Troubleshooting

7.1 Metadata File Does Not Match Checksum

Problem:

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

Solution:

  yum clean all

7.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.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.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 2013