From 4ca07b37bad3ef0a705bda1dd3298c706f599125 Mon Sep 17 00:00:00 2001 From: dbs Date: Mon, 22 Dec 2008 20:43:56 +0000 Subject: [PATCH] Sync up README with rel_1_0 - cover multidomain configuration git-svn-id: svn://svn.open-ils.org/OpenSRF/trunk@1565 9efc2488-bf62-4759-914b-345cdb29e865 --- README | 100 ++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 67 insertions(+), 33 deletions(-) diff --git a/README b/README index a118ebc..fe3cebe 100644 --- a/README +++ b/README @@ -1,4 +1,4 @@ -README for OpenSRF 1.0 RC +README for OpenSRF Installing prerequisites: ======================== @@ -43,10 +43,12 @@ See "Developer instructions" at the bottom of the file. 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 @@ command as the root user to install OpenSRF: 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 @@ 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: ====================================== -Add /openils/lib/ to the system's dynamic library path, and then run "ldconfig" +Add /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 /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 @@ 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,15 +154,17 @@ 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: ====================================== 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 @@ 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. -Copy /openils/conf/srfsh.xml to ~/.srfsh.xml and update the username and +Copy /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 @@ 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.43.2