[Opensrf-commits] r1555 - branches/rel_1_0

[svn at svn.open-ils.org]

Author: dbs
Date: 2008-12-19 21:56:26 -0500 (Fri, 19 Dec 2008)
New Revision: 1555

Modified:
   branches/rel_1_0/README
Log:
Update README to try to cover the brave new world of multidomain configuration.


Modified: branches/rel_1_0/README
===================================================================
--- branches/rel_1_0/README	2008-12-20 02:55:54 UTC (rev 1554)
+++ branches/rel_1_0/README	2008-12-20 02:56:26 UTC (rev 1555)
@@ -75,11 +75,25 @@
 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:
 ======================================
 
@@ -88,8 +102,8 @@
 
 On Debian and Ubuntu systems, run the following commands as root:
 
-$ echo /openils/lib > /etc/ld.so.conf.d/opensrf.conf
-$ ldconfig
+# echo /openils/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 +114,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,8 +151,10 @@
 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:
 ======================================
@@ -148,11 +178,12 @@
   * 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.
@@ -194,9 +225,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.