Installing OpenSRF 2.0

In the following instructions, you are asked to perform certain steps as either the root user or the opensrf user.

• Debian To become the root user, issue the su - command and enter the password of the root user.
• Ubuntu To become the root user, issue the sudo su - command and enter the password of your current 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.

Also, in the following instructions, /path/to/OpenSRF/ represents the path to the OpenSRF source directory.

1. As the root user, add the opensrf user. We set the default shell for the new user to /bin/bash to inherit a reasonable environment:

   useradd -m -s /bin/bash opensrf
   passwd opensrf

2. As the opensrf user, download and extract the source files for OpenSRF 2.0.1:

   wget http://evergreen-ils.org/downloads/opensrf-2.0.1.tar.gz
   tar xzf opensrf-2.0.1.tar.gz

   A new directory opensrf-2.0.1 is created.

3. As the root user, install the software prerequisites using the automatic prerequisite installer. Replace <distribution> below with the following value for your distribution:
   • debian-lenny for Debian Lenny (5.0)
   • debian-squeeze for Debian Squeeze (6.0)
   • fedora13 for Fedora 13
   • ubuntu-hardy for Ubuntu Hardy Heron (8.04)
   • ubuntu-lucid for Ubuntu Lucid Lynx (10.04)
   • centos for CentOS 5
   • rhel for Red Hat Enterprise Linux 5

     aptitude install make
     cd /path/to/OpenSRF
     make -f src/extras/Makefile.install <distribution>

     This will install a number of packages required by OpenSRF on your system, including some Perl modules from CPAN. The first time you run CPAN, it will ask you whether you want it to automatically configure itself to download and install Perl modules from CPAN; in general, we suggest that you let CPAN auto-configure itself. Also, always allow the CPAN installer to install prerequisite modules when it asks.

4. Build OpenSRF:
   1. As the opensrf user, configure and compile OpenSRF. You can include the –enable-python configure options if you want to include support for Python:

      cd /path/to/OpenSRF
      ./configure --prefix=/openils --sysconfdir=/openils/conf
      make

   2. As the root user, return to your OpenSRF build directory and install OpenSRF:

      cd /path/to/OpenSRF
      make install

   3. As the root user, add /openils/lib to the system dynamic library path and make your system recognize the newly installed libraries. For example, on Ubuntu or Debian you would perform the following steps:
      1. Create a file named /etc/ld.so.conf.d/osrf.conf containing the following line:

         /openils/lib
         /usr/local/lib

      2. Run the following command:

         ldconfig

   4. 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 and private.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

   5. As the root user, change the ownership of the installed files to the opensrf user:

      chown -R opensrf:opensrf /openils

5. As the root user, stop the ejabberd service:

   /etc/init.d/ejabberd stop

   • If ejabberd reports that it is already stopped, it may have run into a problem starting back at the installation stage. (NOTE: Frequently, although stopping ejabberd as shown above does not show an error, it also does not stop properly, so you may wish to at least ensure that it is stopped as shown below by killing the processes.) One possible fix is to kill any remaining beam and epmd processes, then edit /etc/default/ejabberd to hardcode a domain:

     epmd -kill
     killall beam; killall beam.smp
     rm /var/lib/ejabberd/*
     echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd

6. As the root user, edit /etc/ejabberd/ejabberd.cfg to increase the default limits (meant for a small instant messaging server) to something reasonable for our use of XMPP as a message bus:
   • Change

     {hosts, ["localhost"]}.

     to

     {hosts, ["localhost", "private.localhost", "public.localhost"]}.

   • Increase the maximum number of times a user can log in concurrently:
     • Newer versions of ejabberd: {access, max_user_sessions, [{10, all}]}., then change it to {access, max_user_sessions, [{10000, all}]}.
     • Older versions of ejabberd: change {max_user_sessions, 10}. to {max_user_sessions, 10000}.
   • Change all three occurrences of max_stanza_size to 2000000.
   • Change both occurrences of maxrate to 500000.
   • Comment out the {mod_offline line by placing two % signs in front.
7. As the root user, restart the ejabberd service to test the configuration changes and to register your users:

   /etc/init.d/ejabberd start

8. 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
   1. Therefore, 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>
      ejabberdctl register router private.localhost <password>
      ejabberdctl register opensrf private.localhost <password>
      ejabberdctl register router public.localhost <password>
      ejabberdctl register opensrf public.localhost <password>

      Note: There appears to be a problem with ejabberdctl in that it does not escape input correctly, so a password like '0P3N$SRF' will be created as '0P3N'. A bug against ejabberd has been filed. To register a password using ejabberdctl with special shell characters until such time as that bug is resolved, the workaround is to specify a double-escaped character at the command line, for example, '0P3N\\\\$RF'

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

   1. 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 (line 38*)
      • /config/gateway/username = opensrf
      • /config/gateway/passwd = password for public.localhost opensrf user (line 97*)
      • /config/routers/router/transport - first entry, where transport/server == public.localhost :
        • username = router
        • password = password for public.localhost router user (line 121*)
      • /config/routers/router/transport - second entry, where transport/server == private.localhost :
        • username = router
        • password = password for private.localhost router user (line 143*)
        • * if there are future changes to the opensrf_core.xml file, these line numbers may be off
   2. 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.
10. 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, while public.localhost will only give you access to those OpenSRF services that are publicly exposed)
    • username and password must match your opensrf ejabber user for the chosen domain
    • logfile 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>

11. As the opensrf user, set the path of the opensrf user's .bashrc file:

    echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc

As the root user, before starting OpenSRF, ensure that your Jabber and memcached daemons are running.

/etc/init.d/ejabberd restart
/etc/init.d/memcached restart
# restarts are less disruptive to the system than 'start' when you are unsure of the service's current state

As the opensrf user, start OpenSRF. Starting OpenSRF with the start_all option starts the OpenSRF router, Perl services, and C services. (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 the opensrf user, but you can manually set it using the following command:

  export PATH=$PATH:/openils/bin

Once you have installed and started OpenSRF, test your connection to OpenSRF via srfsh:

1. Start srfsh and try calling the add 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.

1. As the opensrf user, stop OpenSRF:

   osrf_ctl.sh -l -a stop_all