LP#1436047: Allow disabling of "bang commands" in srfsh
[OpenSRF.git] / README
diff --git a/README b/README
index 8631eb0..a5895c0 100644 (file)
--- a/README
+++ b/README
@@ -32,6 +32,7 @@ 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]
 ---------------------------------------------------------------------------
 apt-get install make
 make -f src/extras/Makefile.install <osname>
@@ -89,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
@@ -140,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
@@ -170,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
@@ -188,11 +191,15 @@ 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"]}.
 ---------------------------------------------------------------------------
@@ -202,6 +209,30 @@ changes:
   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:
 +
 .(Debian / Ubuntu) Starting ejabberd
@@ -270,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
@@ -306,7 +337,7 @@ 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_control --localhost --stop-all
 ---------------------------------------------------------------------------
@@ -322,13 +353,14 @@ 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
 ---------------------------------------------------------------------------
@@ -343,14 +375,14 @@ account:
 
 1. Install git if not already present:
 +
-[source,bash]
+[source, bash]
 ---------------------------------------------------------------------------
 apt-get install git-core
 ---------------------------------------------------------------------------
 +
 2. Install the apache-websocket module:
 +
-[source,bash]
+[source, bash]
 ---------------------------------------------------------------------------
 # Use a temporary directory
 cd /tmp
@@ -360,23 +392,23 @@ 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)
+   `/usr/share/doc/apache2/README.multiple-instances`)
 +
 .(Debian / Ubuntu Precise)
-[source,bash]
+[source, bash]
 ---------------------------------------------------------------------------
 sh /usr/share/doc/apache2.2-common/examples/setup-instance websockets
 ---------------------------------------------------------------------------
 +
 .(Ubuntu Trusty)
-[source,bash]
+[source, bash]
 ---------------------------------------------------------------------------
 sh /usr/share/doc/apache2/examples/setup-instance websockets
 ---------------------------------------------------------------------------
 +
 4. Remove from the main apache instance
 +
-[source,bash]
+[source, bash]
 ---------------------------------------------------------------------------
 a2dismod websocket
 ---------------------------------------------------------------------------
@@ -384,20 +416,21 @@ a2dismod websocket
 5. Copy into place the config files
 +
 .(Debian / Ubuntu Precise)
-[source,bash]
+[source, bash]
 ---------------------------------------------------------------------------
-cp /home/opensrf/OpenSRF/examples/apache2/websockets/apache2.conf /etc/apache2-websockets/
+cp examples/apache2/websockets/apache2.conf /etc/apache2-websockets/
 ---------------------------------------------------------------------------
 +
 .(Ubuntu Trusty)
-[source,bash]
+[source, bash]
 ---------------------------------------------------------------------------
-cp /home/opensrf/OpenSRF/examples/apache_24/websockets/apache2.conf /etc/apache2-websockets/
+cp examples/apache_24/websockets/apache2.conf /etc/apache2-websockets/
 ---------------------------------------------------------------------------
 +
-6. OPTIONAL: add these configuration variables to /etc/apache2-websockets/envvars
+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
@@ -406,18 +439,18 @@ 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
+  * `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
+  * `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
+  * `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.
+  * `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 
@@ -429,7 +462,7 @@ export OSRF_WEBSOCKET_MAX_REQUEST_WAIT_TIME=600
    fire up the secondary Apache instance. Errors will appear in
    `/var/log/apache2-websockets/error.log`. Start apache2-websockets with:
 +
-[source,bash]
+[source, bash]
 ---------------------------------------------------------------------------
 /etc/init.d/apache2-websockets start
 ---------------------------------------------------------------------------
@@ -458,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.