[Opensrf-commits] r1565 - trunk
svn at svn.open-ils.org
svn at svn.open-ils.org
Mon Dec 22 15:44:00 EST 2008
Author: dbs
Date: 2008-12-22 15:43:56 -0500 (Mon, 22 Dec 2008)
New Revision: 1565
Modified:
trunk/README
Log:
Sync up README with rel_1_0 - cover multidomain configuration
Modified: trunk/README
===================================================================
--- trunk/README 2008-12-22 20:43:15 UTC (rev 1564)
+++ trunk/README 2008-12-22 20:43:56 UTC (rev 1565)
@@ -1,4 +1,4 @@
-README for OpenSRF 1.0 RC
+README for OpenSRF
Installing prerequisites:
========================
@@ -43,11 +43,13 @@
Configuration and compilation instructions:
==========================================
-For the time being, we are still installing everything in the /openils/
-directory (with the exception of the Perl modules, which are installed
-into system directories). Issue the following commands to configure and
-build OpenSRF:
+Use the "configure" command to configure OpenSRF, and the "make" command to
+build OpenSRF. The default installation prefix (PREFIX) for OpenSRF is
+"/opensrf/".
+If you are building OpenSRF for Evergreen, pass the --prefix and --sysconfdir
+options as follows:
+
./configure --prefix=/openils --sysconfdir=/openils/conf
make
@@ -63,8 +65,9 @@
make install
-This will install OpenSRF, including example configuration files in
-/openils/conf/ that you can use as templates for your own configuration files.
+This will install OpenSRF in the prefix directory that you specified in the
+configuration step. This will also install example configuration files that
+you can use as templates for your own configuration files.
Create and set up the opensrf Unix user environment:
===================================================
@@ -75,21 +78,35 @@
substituting <PREFIX> with the value you passed to --prefix in your
configure command:
-$ useradd -m -s /bin/bash opensrf
-$ echo "export PERL5LIB=\$PERL5LIB:/<PREFIX>/lib" > /home/opensrf/.bashrc
-$ echo "export PATH=\$PATH:/<PREFIX>/bin" > /home/opensrf/.bashrc
-$ passwd opensrf
+# useradd -m -s /bin/bash opensrf
+# echo "export PATH=\$PATH:/<PREFIX>/bin" >> /home/opensrf/.bashrc
+# passwd opensrf
+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" and "private.localhost".
+
+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 entries that you could make to a stock /etc/hosts
+file for our example domains:
+
+127.0.1.2 public.localhost public
+127.0.1.3 private.localhost private
+
Adjust the system dynamic library path:
======================================
-Add /openils/lib/ to the system's dynamic library path, and then run "ldconfig"
+Add <PREFIX>/lib/ to the system's dynamic library path, and then run "ldconfig"
as root.
On Debian and Ubuntu systems, run the following commands as root:
-$ echo /openils/lib > /etc/ld.so.conf.d/opensrf.conf
-$ ldconfig
+# echo <PREFIX>/lib > /etc/ld.so.conf.d/opensrf.conf
+# ldconfig
On most other systems, you can add these entries to a /etc/ld.so.conf, or create
a file within the /etc/ld.so.conf.d/ directory, and then run "ldconfig" as root.
@@ -100,20 +117,34 @@
OpenSRF requires an XMPP (Jabber) server. For performance reasons, ejabberd is
the Jabber server of choice for the OpenSRF project. In most cases, you only
have to make a few changes to the default ejabberd.cfg file to make ejabberd
-work for OpenSRF. Open /etc/ejabberd/ejabberd.cfg and make the following
+work for OpenSRF.
+
+1. Stop ejabberd before making any changes to its configuration by issuing the
+following command as root:
+
+# /etc/init.d/ejabberd stop
+
+2. Open /etc/ejabberd/ejabberd.cfg and make the following
changes:
-1. Comment out the "mod_offline" directive
-2. Increase the "max_user_sessions" value to 1000
-3. Change all "max_stanza_size" values to 200000
-4. Change all "maxrate values" to 500000
+a. Define your public and private domains in the "hosts" directive. For
+ example:
-Restart the ejabberd server to make the changes take effect.
+{hosts, ["private.localhost", "public.localhost"]}
+b. Comment out the "mod_offline" directive
+c. Increase the "max_user_sessions" value to 1000
+d. Change all "max_stanza_size" values to 200000
+e. Change all "maxrate values" to 500000
+
+3. Restart the ejabberd server to make the changes take effect:
+
+# /etc/init.d/ejabberd start
+
Create the OpenSRF Jabber users:
===============================
-You need two Jabber users to manage the OpenSRF communications:
+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"
@@ -123,15 +154,17 @@
Create the Jabber users by issuing the following commands as root. Substitute
<password> for your chosen passwords for each user respectively:
-$ ejabberdctl register router localhost <password>
-$ ejabberdctl register opensrf localhost <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>
Update the OpenSRF configuration files:
======================================
There are two critical files that you must update to make OpenSRF work.
-"SYSCONFDIR" will be /openils/conf/ if you followed the configuration
-suggestion above:
+"SYSCONFDIR" is "/opensrf/etc" by default, or the value that you passed to
+--sysconfdir during the configuration phase:
* SYSCONFDIR/opensrf.xml - this file lists the services that this
OpenSRF installation supports; if you create a new OpenSRF service,
@@ -148,16 +181,17 @@
* SYSCONFDIR/opensrf_core.xml - this file lists the Jabber connection
information that will be used for the system, as well as determining
logging verbosity and defining which services will be exposed on the
- HTTP gateway. There are three username/password pairs to update in this
+ HTTP gateway. There are four username/password pairs to update in this
file:
- 1. <config><opensrf> = use the Jabber "opensrf" user
- 2. <config><gateway> = use the Jabber "opensrf" user
- 3. <config><routers><router> = use the Jabber "router" user
+ 1. <config><opensrf> = use the private Jabber "opensrf" user
+ 2. <config><gateway> = use the public Jabber "opensrf" user
+ 3. <config><routers><router> = use the public Jabber "router" user
+ 4. <config><routers><router> = use the private Jabber "router" user
You should also create a .srfsh.xml file in the home directory of each user
that you want to enable to use the srfsh to communicate with OpenSRF services.
-Copy /openils/conf/srfsh.xml to ~/.srfsh.xml and update the username and
+Copy <SYSCONFDIR>/srfsh.xml to ~/.srfsh.xml and update the username and
password values with the Jabber "opensrf" user credentials.
Starting and stopping OpenSRF services:
@@ -194,9 +228,9 @@
entry for localhost, and point your local DNS resolver to dnsmasq. For example,
on Ubuntu you can issue the following commands as root:
-$ aptitude install dnsmasq
-$ echo "webserver=/localhost/127.0.0.1/" >> /etc/dnsmasq.conf
-$ /etc/init.d/dnsmasq restart
+# aptitude install dnsmasq
+# echo "webserver=/localhost/127.0.0.1/" >> /etc/dnsmasq.conf
+# /etc/init.d/dnsmasq restart
Then edit /etc/resolv.conf and ensure that "nameserver 127.0.0.1" is the first
entry in the file.
More information about the opensrf-commits
mailing list