LP#1436047: Allow disabling of "bang commands" in srfsh
[OpenSRF.git] / README
diff --git a/README b/README
index 668060d..a5895c0 100644 (file)
--- a/README
+++ b/README
@@ -28,20 +28,23 @@ before you can successfully configure, compile, and install OpenSRF.
 On Debian and Ubuntu, the easiest way to install these prerequisites
 is to use the Makefile.install prerequisite installer.
 
-Issue the following commands as the root user to install prerequisites
-using the Makefile.install prerequisite installer, substituting your
-operating system identifier for <osname> below:
+Issue the following commands as the *root* Linux account to install 
+prerequisites using the Makefile.install prerequisite installer, substituting 
+your operating system identifier for <osname> below:
 
+[source, bash]
 ---------------------------------------------------------------------------
-aptitude install make
+apt-get install make
 make -f src/extras/Makefile.install <osname>
 ---------------------------------------------------------------------------
 
 Well-tested values for <osname> include:
 
+  * `debian-jessie` for Debian 8.0
+  * `debian-wheezy` for Debian 7.0
   * `debian-squeeze` for Debian 6.0
-  * `ubuntu-lucid` for Ubuntu 10.04
   * `ubuntu-precise` for Ubuntu 12.04
+  * `ubuntu-trusty` for Ubuntu 14.04
   * `fedora` for Fedora 17 and later
 
 Patches and suggestions for improvement from users of these distributions,
@@ -87,6 +90,7 @@ build OpenSRF. The default installation prefix (PREFIX) for OpenSRF is
 If you are building OpenSRF for Evergreen, issue the following commands as
 the *user* Linux account to configure and build OpenSRF:
 
+[source, bash]
 ---------------------------------------------------------------------------
 ./configure --prefix=/openils --sysconfdir=/openils/conf
 make
@@ -138,6 +142,7 @@ file. Here are entries that you could add to a stock `/etc/hosts` file for our
 example domains:
 
 .Example added entries for `/etc/hosts`
+[source, bash]
 ---------------------------------------------------------------------------
 127.0.1.2      public.localhost        public
 127.0.1.3      private.localhost       private
@@ -168,7 +173,7 @@ 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
+have to make a few changes to the default configuration file to make ejabberd
 work for OpenSRF. 
 
 1. Stop ejabberd before making any changes to its configuration by issuing the
@@ -186,19 +191,47 @@ work for OpenSRF.
 systemctl stop ejabberd.service
 ---------------------------------------------------------------------------
 +
-2. Open `/etc/ejabberd/ejabberd.cfg` and make the following
+2. Edit the ejabberd config file.
++
+(Debian Wheezy / Ubuntu) Ejabberd 2.x.x::
+Open `/etc/ejabberd/ejabberd.cfg` and make the following
 changes:
   a. Define your public and private domains in the `hosts` directive. For
    example:
 +
+[source, bash]
 ---------------------------------------------------------------------------
 {hosts, ["localhost", "private.localhost", "public.localhost"]}.
 ---------------------------------------------------------------------------
 +
-  b. Comment out the `mod_offline` directive
-  c. Increase the `max_user_sessions` value to 10000
-  d. Change all `max_stanza_size` values to 2000000
-  e. Change all `maxrate` values to 500000 
+  b. Change all `max_stanza_size` values to 2000000
+  c. Change all `maxrate` values to 500000
+  d. Increase the `max_user_sessions` value to 10000
+  e. Comment out the `mod_offline` directive
++
+(Debian Jessie) Ejabberd 13.x and 14.x::
+Open `/etc/ejabberd/ejabberd.yml` and make the following
+changes:
+  a. Define your public and private domains in the `hosts` directive. For
+   example:
++
+[source, bash]
+---------------------------------------------------------------------------
+hosts:
+  - "localhost"
+  - "private.localhost"
+  - "public.localhost"
+---------------------------------------------------------------------------
++
+  b. Change all `max_stanza_size` values to 2000000
+  c. Change `shaper:` `normal` and `fast` values to 500000
+  d. Increase the `max_user_sessions:` `all:` value to 10000
+  e. Comment out the `mod_offline` directive
++
+-----------------------
+##mod_offline:
+    ##access_max_user_messages: max_user_offline_messages
+-----------------------
 +
 3. Restart the ejabberd server to make the changes take effect:
 +
@@ -268,7 +301,7 @@ Updating the OpenSRF configuration files
      to create your locally customizable OpenSRF configuration files:
 +
 .Copying the example OpenSRF configuration files
-[source,bash]
+[source, bash]
 ---------------------------------------------------------------------------
 cd SYSCONFDIR
 cp opensrf_core.xml.example opensrf_core.xml
@@ -298,15 +331,15 @@ following command as the *opensrf* Linux account:
 
 [source, bash]
 ---------------------------------------------------------------------------
-osrf_ctl.sh -l -a start_all
+osrf_control --localhost --start-all
 ---------------------------------------------------------------------------
 
 To stop all OpenSRF services with a hostname of `localhost`, issue the
 following command as the *opensrf* Linux account:
 
-[source,bash]
+[source, bash]
 ---------------------------------------------------------------------------
-osrf_ctl.sh -l -a stop_all
+osrf_control --localhost --stop-all
 ---------------------------------------------------------------------------
 
 Testing the default OpenSRF services
@@ -320,19 +353,120 @@ services, test the services as follows:
    command as the *opensrf* Linux account:
 +
 .Starting the `srfsh` interactive OpenSRF shell
-[source,bash]
+[source, bash]
 ---------------------------------------------------------------------------
 srfsh
 ---------------------------------------------------------------------------
 +
 2. Issue the following request to test the `opensrf.math` service:
 +
+[source, bash]
 ---------------------------------------------------------------------------
 srfsh# request opensrf.math add 2,2
 ---------------------------------------------------------------------------
 +
 You should receive the value `4`.
 
+Optional: Websockets installation instructions
+----------------------------------------------
+Websockets are new to OpenSRF 2.4+ and are required for operating the new web-based
+staff client for Evergreen.  Complete the following steps as the *root* Linux 
+account:
+
+1. Install git if not already present:
++
+[source, bash]
+---------------------------------------------------------------------------
+apt-get install git-core
+---------------------------------------------------------------------------
++
+2. Install the apache-websocket module:
++
+[source, bash]
+---------------------------------------------------------------------------
+# Use a temporary directory
+cd /tmp
+git clone https://github.com/disconnect/apache-websocket
+cd apache-websocket
+apxs2 -i -a -c mod_websocket.c
+---------------------------------------------------------------------------
++
+3. Create the websocket Apache instance (more information about this in 
+   `/usr/share/doc/apache2/README.multiple-instances`)
++
+.(Debian / Ubuntu Precise)
+[source, bash]
+---------------------------------------------------------------------------
+sh /usr/share/doc/apache2.2-common/examples/setup-instance websockets
+---------------------------------------------------------------------------
++
+.(Ubuntu Trusty)
+[source, bash]
+---------------------------------------------------------------------------
+sh /usr/share/doc/apache2/examples/setup-instance websockets
+---------------------------------------------------------------------------
++
+4. Remove from the main apache instance
++
+[source, bash]
+---------------------------------------------------------------------------
+a2dismod websocket
+---------------------------------------------------------------------------
++
+5. Copy into place the config files
++
+.(Debian / Ubuntu Precise)
+[source, bash]
+---------------------------------------------------------------------------
+cp examples/apache2/websockets/apache2.conf /etc/apache2-websockets/
+---------------------------------------------------------------------------
++
+.(Ubuntu Trusty)
+[source, bash]
+---------------------------------------------------------------------------
+cp examples/apache_24/websockets/apache2.conf /etc/apache2-websockets/
+---------------------------------------------------------------------------
++
+6. OPTIONAL: add these configuration variables to `/etc/apache2-websockets/envvars`
+   and adjust as needed.
++
+[source, bash]
+---------------------------------------------------------------------------
+export OSRF_WEBSOCKET_IDLE_TIMEOUT=120
+export OSRF_WEBSOCKET_IDLE_CHECK_INTERVAL=5
+export OSRF_WEBSOCKET_CONFIG_FILE=/openils/conf/opensrf_core.xml
+export OSRF_WEBSOCKET_CONFIG_CTXT=gateway
+export OSRF_WEBSOCKET_MAX_REQUEST_WAIT_TIME=600
+---------------------------------------------------------------------------
++
+  * `IDLE_TIMEOUT` specifies how long we will allow a client to stay connected
+    while idle.  A longer timeout means less network traffic (from fewer
+    websocket CONNECT calls), but it also means more Apache processes are
+    tied up doing nothing.
+  * `IDLE_CHECK_INTERVAL` specifies how often we wake to check the idle status
+    of the connected client.
+  * `MAX_REQUEST_WAIT_TIME` is the maximum amount of time the gateway will
+    wait before declaring a client as idle when there is a long-running
+    outstanding request, yet no other activity is occurring.  This is
+    primarily a fail-safe to allow idle timeouts when one or more requests
+    died on the server, and thus no response was ever delivered to the gateway.
+  * `CONFIG_FILE / CTXT` are the standard opensrf core config options.
+
+7. Before you can start websockets, you must install a valid SSL certificate 
+   in `/etc/apache2/ssl/`.  It is possible, but not recommended, to generate a 
+   self-signed SSL certificate.  For example, if you need to test with a self-signed 
+   certicate on Chrome or Chromimum browsers, one workaround is to start the browser 
+   with `--ignore-certificate-errors`.
+
+8. After OpenSRF is up and running (or after any re-install),
+   fire up the secondary Apache instance. Errors will appear in
+   `/var/log/apache2-websockets/error.log`. Start apache2-websockets with:
++
+[source, bash]
+---------------------------------------------------------------------------
+/etc/init.d/apache2-websockets start
+---------------------------------------------------------------------------
+
 Troubleshooting note for Python users
 -------------------------------------
 
@@ -357,5 +491,5 @@ Getting help
 ------------
 
 Need help installing or using OpenSRF? Join the mailing lists at
-http://evergreen-ils.org/listserv.php or contact us on the Freenode
-IRC network on the #evergreen channel.
+http://evergreen-ils.org/communicate/mailing-lists/ or contact us 
+on the Freenode IRC network on the #evergreen channel.