From a69e6ff022066ac92278c8207b1088ee6fdfdfcf Mon Sep 17 00:00:00 2001 From: dbs Date: Sat, 20 Dec 2008 02:56:26 +0000 Subject: [PATCH] Update README to try to cover the brave new world of multidomain configuration. git-svn-id: svn://svn.open-ils.org/OpenSRF/branches/rel_1_0@1555 9efc2488-bf62-4759-914b-345cdb29e865 --- README | 75 ++++++++++++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 53 insertions(+), 22 deletions(-) diff --git a/README b/README index c947b26..b6227f0 100644 --- a/README +++ b/README @@ -75,10 +75,24 @@ commands as root to create the "opensrf" user and set up its environment, substituting with the value you passed to --prefix in your configure command: -$ useradd -m -s /bin/bash opensrf -$ echo "export PERL5LIB=\$PERL5LIB://lib" > /home/opensrf/.bashrc -$ echo "export PATH=\$PATH://bin" > /home/opensrf/.bashrc -$ passwd opensrf +# useradd -m -s /bin/bash opensrf +# echo "export PATH=\$PATH://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 @@ 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 /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 @@ Configure the ejabberd server: 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: + +{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: -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 @@ You need two Jabber users to manage the OpenSRF communications: Create the Jabber users by issuing the following commands as root. Substitute for your chosen passwords for each user respectively: -$ ejabberdctl register router localhost -$ ejabberdctl register opensrf localhost +# ejabberdctl register router private.localhost +# ejabberdctl register opensrf private.localhost +# ejabberdctl register router public.localhost +# ejabberdctl register opensrf public.localhost Update the OpenSRF configuration files: ====================================== @@ -148,11 +178,12 @@ suggestion above: * 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. = use the Jabber "opensrf" user - 2. = use the Jabber "opensrf" user - 3. = use the Jabber "router" user + 1. = use the private Jabber "opensrf" user + 2. = use the public Jabber "opensrf" user + 3. = use the public Jabber "router" user + 4. = 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 @@ you need to install the dnsmasq package, configure it to serve up a DNS 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. -- 2.11.0