This is an old revision of the document!
Table of Contents
Installing OpenSRF Trunk on Redhat
The following steps have been tested on Redhat x86 (32-bit) and x86-64 (64-bit) platforms.
In the following instructions, you are asked to perform certain steps as either the root user or the opensrf user.
- To become the root user, issue the
su -
command and enter the password of the root user.
To switch from the root user to a different user, issue the su - <username>
command; for example, su - opensrf
. Once you have become a non-root user, to become the root user again simply issue the exit
command.
- As the root user, register with the redhat network(if you haven't already), disable selinux, and reboot:
rhnreg_ks --username=<user> --password=<pass> --profilename=<name> vi /etc/sysconfig/selinux # change from enforcing to disabled reboot
- As firewall rules are beyond the scope of this document, I recommend that while testing you disable your firewall with the following commands as root:
/etc/init.d/iptables stop chkconfig --del iptables
- As the root user, install subversion and then add the opensrf user. We set the default shell for the new user to
/bin/bash
to inherit a reasonable environment:yum install -y subversion useradd -m -s /bin/bash opensrf passwd opensrf # only necessary if you want to log in to this user directly
- As the root user, add libevent-1.4 to the exclude section of yum.conf:
echo exclude=libevent-1.4* >> /etc/yum.conf
- As the opensrf user, download and patch the source files for OpenSRF trunk:
cd && svn checkout svn://svn.open-ils.org/OpenSRF/trunk OpenSRF-trunk wget http://esilibrary.com/~ldickens/rhel-evg/opensrf-rhel.diff cd /home/opensrf/OpenSRF-trunk patch -p0 < ../opensrf-rhel.diff
- As the root user, install the prerequisites:
make -f src/extras/Makefile.install rhel
This will install a number of packages required by OpenSRF on your system, including some Perl modules from CPAN. You can say “no” to the initial CPAN configuration prompt to allow it to automatically configure itself to download and install Perl modules from CPAN. The CPAN installer will ask you a number of times whether it should install prerequisite modules - say “yes”.
- Build OpenSRF:
- As the opensrf user, configure and compile OpenSRF. You can include the
–enable-python
and–enable-java
configure options if you want to include support for Python and Java, respectively:cd /home/opensrf/OpenSRF-trunk cat /usr/share/aclocal/libtool.m4 >> aclocal.m4 mkdir m4 && ./autogen.sh export memcached_LIBS=/usr/local/lib/libmemcached export memcached_CFLAGS=-lmemcached ./configure --prefix=/openils --sysconfdir=/openils/conf --with-apxs=/usr/sbin/apxs make
- As the root user, return to your OpenSRF build directory and install OpenSRF:
cd /home/opensrf/OpenSRF-trunk make install
- As the root user, add
/openils/lib
to the system dynamic library path and make your system recognize the newly installed libraries.- Create a file named
/etc/ld.so.conf.d/osrf.conf
containing the following line:/openils/lib
- Run the following command:
ldconfig
- Define your public and private OpenSRF domains. For security purposes, OpenSRF uses Jabber domains to separate services into public and private realms. Throughout these instructions, we will use the example domains
public.localhost
for the public domain andprivate.localhost
for the private domain. On a single-server system, the easiest way to define public and private domains is to define separate hostnames by adding entries to the/etc/hosts
file. Here are the entries to add as root to a stock/etc/hosts
file for our example domains:127.0.1.2 public.localhost public 127.0.1.3 private.localhost private
- As the root user, change the ownership of the installed files to the opensrf user:
chown -R opensrf:opensrf /openils
- As the root user, stop the ejabberd service:
/opt/ejabberd/bin/ejabberdctl stop
- If ejabberd reports that it is already stopped, it may have run into a problem starting back at the installation stage. One possible fix is to kill any remaining
beam
andepmd
processes:/opt/ejabberd/bin/epmd -kill
- As the root user, edit
/opt/ejabberd/conf/ejabberd.cfg
:- Change
{hosts, ["localhost"]}.
to
{hosts, ["localhost", "private.localhost", "public.localhost"]}.
- Change
{max_user_sessions, 10}.
to{max_user_sessions, 10000}.
- Change all three occurrences of
max_stanza_size
to2000000
. - Change both occurrences of
maxrate
to500000
. - Comment out the
{mod_offline
line by placing two%
signs in front.
- As the root user, restart the ejabberd service to test the configuration changes and to register your users:
/opt/ejabberd/bin/ejabberdctl start
- On each domain, you need two Jabber users to manage the OpenSRF communications:
- a "router" user, to whom all requests to connect to an OpenSRF service will be routed; this Jabber user must be named "router"
- an "opensrf" user, which clients use to connect to OpenSRF services; this user can be named anything you like, but we will use "opensrf" in our examples
- As the root user, register your "router" and "opensrf" ejabber users for the OpenSRF router service on each domain. The users should have different passwords on each domain. These users will correspond to your configuration in
opensrf_core.xml
:# Syntax for registering a user with ejabberdctl # ejabberdctl register <user> <domain> <password> /opt/ejabberd/bin/ejabberdctl register router private.localhost <password> /opt/ejabberd/bin/ejabberdctl register opensrf private.localhost <password> /opt/ejabberd/bin/ejabberdctl register router public.localhost <password> /opt/ejabberd/bin/ejabberdctl register opensrf public.localhost <password>
- As the opensrf user, create the
/openils/conf/opensrf_core.xml
and/openils/conf/opensrf.xml
configuration files from the example templates:cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
- Edit
/openils/conf/opensrf_core.xml
to change the Jabber usernames and passwords as follows. I'm using XPath syntax on the left-hand side to indicate the position in the XML file:/config/opensrf/username
= opensrf/config/opensrf/passwd
= password for private.localhost opensrf user/config/gateway/username
= opensrf/config/gateway/passwd
= password for public.localhost opensrf user/config/routers/router/transport
- first entry, wheretransport/server
== public.localhost :username
= routerpassword
= password for public.localhost router user
/config/routers/router/transport
- second entry, wheretransport/server
== private.localhost :username
= routerpassword
= password for private.localhost router user
- We also need to specify the domains from which we'll accept and to which we'll make connections. If you are installing OpenSRF on a single server and using the "private.localhost" / "public.localhost" domains, these will already be set to the correct values. Otherwise, search and replace to match your values.
- Copy
/openils/conf/srfsh.xml.example
to.srfsh.xml
in the home directory of each user you want to use to run the srfsh command line client for testing OpenSRF, and edit.srfsh.xml
as follows:domain
is the router hostname (following our domain examples,private.localhost
will give your srfsh access to all OpenSRF services, whilepublic.localhost
will only give you access to those OpenSRF services that are publicly exposed)username
andpassword
must match youropensrf
ejabber user for the chosen domainlogfile
is the full path for a log file to which that user has write access<?xml version="1.0"?> <!-- This file follows the standard bootstrap config file layout found in opensrf_core.xml --> <srfsh> <router_name>router</router_name> <domain>private.localhost</domain> <username>opensrf</username> <passwd>privsrf</passwd> <port>5222</port> <logfile>/tmp/srfsh.log</logfile> <loglevel>3</loglevel> </srfsh>
- As the opensrf user, set the path of the opensrf user's
.bashrc
file:echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc exit
Starting OpenSRF
Before starting OpenSRF, ensure that your Jabber and memcached daemons are running. As the root user:
/opt/ejabberd/bin/ejabberdctl start /etc/init.d/memcached start
You might want to add these to start when the machine boots:
useradd -m -s /bin/bash ejabberd chown ejabberd:ejabberd -R /opt/ejabberd cp /opt/ejabberd/bin/ejabberd.init /etc/init.d/ejabberd vi /etc/init.d/ejabberd
Now add these lines to the top of /etc/init.d/ejabberd immediately below the #!/bin/sh:
# chkconfig: 2345 95 20 # description: ejabberd start/stop init script # Script to start and stop ejabberd # processname: ejabberd
Now Finnish adding these programs to autostart:
chkconfig --level 2345 ejabberd on chkconfig --level 2345 memcached on
Starting OpenSRF with the start_all
option starts the OpenSRF router, Perl services, and C services. As the opensrf user, start OpenSRF (NOTE: use the -l
flag only if you wish to force the hostname for the <hosts>
section in opensrf.xml
to be localhost
):
osrf_ctl.sh -l -a start_all
- If you receive the error message bash: osrf_ctl.sh: command not found, then your environment variable PATH does not include the
/openils/bin
directory; this should have been set by.bashrc
when you logged in as theopensrf
user, but you can manually set it using the following command:export PATH=$PATH:/openils/bin
Testing connections to OpenSRF
Once you have installed and started OpenSRF, test your connection to OpenSRF via srfsh
:
- Start
srfsh
and try calling theadd
method on the OpenSRF math service:/openils/bin/srfsh srfsh# request opensrf.math add 2 2
You should see a result like:
Received Data: 4 ------------------------------------ Request Completed Successfully Request Time in seconds: 0.007519 ------------------------------------ srfsh#
If this does not work, it's time to do some troubleshooting. Please do not make any significant changes to your configuration. If you have followed the entire set of installation steps listed here closely, you are probably extremely close to a working system. Gather your configuration files and log files in
/openils/var/log
and contact the Evergreen development mailing list for assistance before making any drastic changes to your system configuration.
Stopping OpenSRF
- As the opensrf user, stop OpenSRF:
osrf_ctl.sh -l -a stop_all