** The *user* Linux account is the account that you use to log onto the
Linux system as a regular user.
** The *root* Linux account is an account that has system administrator
- privileges. On Debian and Fedora you can switch to this account from
+ privileges. On Debian you can switch to this account from
your *user* account by issuing the `su -` command and entering the
password for the *root* account when prompted. On Ubuntu you can switch
to this account from your *user* account using the `sudo su -` command
Well-tested values for <osname> include:
- * `debian-jessie` for Debian 8.0
- * `debian-wheezy` for Debian 7.0
- * `ubuntu-trusty` for Ubuntu 14.04
+ * `debian-buster` for Debian 10
+ * `debian-stretch` for Debian 9
+ * `debian-jessie` for Debian 8
* `ubuntu-xenial` for Ubuntu 16.04
- * `fedora` for Fedora 17 and later
+ * `ubuntu-bionic` for Ubuntu 18.04
Patches and suggestions for improvement from users of these distributions,
or others, are welcome!
Add `<PREFIX>/lib/` to the system's dynamic library path, and then run
`ldconfig` as the *root* Linux account.
-On Debian, Ubuntu, and Fedora systems, run the following commands as the *root*
+On Debian and Ubuntu systems, run the following commands as the *root*
Linux account:
.Adjusting the system dynamic library path
1. Stop ejabberd before making any changes to its configuration by issuing the
following command as the *root* Linux account:
+
-.(Debian / Ubuntu Trusty) Stopping ejabberd
-[source, bash]
----------------------------------------------------------------------------
-/etc/init.d/ejabberd stop
----------------------------------------------------------------------------
-+
-.(Fedora / Ubuntu Xenial) Stopping ejabberd
+.(Debian / Ubuntu Xenial / Ubuntu Bionic) Stopping ejabberd
[source, bash]
---------------------------------------------------------------------------
systemctl stop ejabberd.service
+
2. Edit the ejabberd config file.
+
-(Debian Wheezy / Ubuntu Trusty) 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. Change all `maxrate` values to 500000
- c. Increase the `max_user_sessions` value to 10000
- d. Comment out the `mod_offline` directive
-+
(Debian Jessie) Ejabberd 13.x and 14.x::
Open `/etc/ejabberd/ejabberd.yml` and make the following
changes:
##access_max_user_messages: max_user_offline_messages
-----------------------
+
-(Ubuntu Xenial) Ejabberd 16.x::
+(Debian Stretch / Ubuntu Xenial) Ejabberd 16.x::
Open `/etc/ejabberd/ejabberd.yml` and make the following
changes:
a. Define your public and private domains in the `hosts` directive. For
##access_max_user_messages: max_user_offline_messages
-----------------------
+
-3. Restart the ejabberd server to make the changes take effect:
+(Debian Buster / Ubuntu Bionic) Ejabberd 18.x::
+Open `/etc/ejabberd/ejabberd.yml` and make the following
+changes:
+ a. Define your public and private domains in the `hosts` directive. For
+ example:
+
-.(Debian / Ubuntu Trusty) Starting ejabberd
[source, bash]
---------------------------------------------------------------------------
-/etc/init.d/ejabberd start
+hosts:
+ - "localhost"
+ - "private.localhost"
+ - "public.localhost"
---------------------------------------------------------------------------
+
-.(Fedora / Ubuntu Xenial) Starting ejabberd
+ b. Change `starttls_required` to false
+ c. Change `auth_password_format` to plain
+ d. Change `shaper:` `normal` and `fast` values to 500000
+ e. Increase the `max_user_sessions:` `all:` value to 10000
+ f. Comment out the `mod_offline` directive
++
+-----------------------
+##mod_offline:
+ ##access_max_user_messages: max_user_offline_messages
+-----------------------
++
+ g. Uncomment or add the `mod_legacy_auth` directive under the `modules:` section
++
+-----------------------
+mod_legacy_auth: {}
+-----------------------
++
+3. Restart the ejabberd server to make the changes take effect:
++
+.(Debian / Ubuntu Xenial / Ubuntu Bionic) Starting ejabberd
[source, bash]
---------------------------------------------------------------------------
systemctl start ejabberd.service
+
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:
+Websockets installation instructions
+------------------------------------
-1. Install git if not already present:
-+
-[source, bash]
----------------------------------------------------------------------------
-apt-get install git-core
----------------------------------------------------------------------------
+1. Install websocketd (latest stable release from http://websocketd.com/)
+
-2. Install the apache-websocket module:
-+
-[source, bash]
+.(Debian, Ubuntu)
+[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
+wget 'https://github.com/joewalnes/websocketd/releases/download/v0.3.0/websocketd-0.3.0-linux_amd64.zip'
+unzip websocketd-0.3.0-linux_amd64.zip
+sudo cp websocketd /usr/local/bin/
---------------------------------------------------------------------------
+
-3. Create the websocket Apache instance (more information about this in
- `/usr/share/doc/apache2/README.multiple-instances`)
+2. Run websocketd
+
-.(Debian)
-[source, bash]
----------------------------------------------------------------------------
-sh /usr/share/doc/apache2.2-common/examples/setup-instance websockets
----------------------------------------------------------------------------
+Choose option a or b, below.
+
-.(Ubuntu Trusty / Xenial)
-[source, bash]
----------------------------------------------------------------------------
-sh /usr/share/doc/apache2/examples/setup-instance websockets
----------------------------------------------------------------------------
+[NOTE]
+===========================================================================
+websocketd does not offer a configurable inactivity timeout, meaning
+websocket client connections will persist until each client disconnects
+or the service is restarted. However, a timeout can be achieved with
+the use of a proxy (option 'a' below). A proxy also allows websocketd
+to be exposed to web clients on port 443 instead of its internal port,
+which may simplify firewall configuration.
+===========================================================================
+
-4. Remove from the main apache instance
+a. Run websocketd as 'opensrf'
+
-[source, bash]
+[NOTE]
+===========================================================================
+This choice requires one of the proxy configurations mentioned below.
+===========================================================================
++
+.(Debian, Ubuntu)
+[source,bash]
---------------------------------------------------------------------------
-a2dismod websocket
+/usr/local/bin/websocketd --port 7682 /openils/bin/osrf-websocket-stdio &
+
+# Other useful command line parameters include:
+# --loglevel debug|trace|access|info|error|fatal
+# --maxforks <n>
+# --sameorigin=true
+# --origin=host[:port][,host[:port]...]
+
+# See https://github.com/joewalnes/websocketd/blob/master/help.go
---------------------------------------------------------------------------
+
-5. Change to the directory into which you unpacked OpenSRF, then copy into
- place the config files
+b. Run websocketd without a proxy
+
-.(Debian)
-[source, bash]
+.(Debian, Ubuntu)
+[source,bash]
---------------------------------------------------------------------------
-cd /path/to/opensrf-OSRFVERSION
-cp examples/apache2/websockets/apache2.conf /etc/apache2-websockets/
+sudo -b /usr/local/bin/websocketd --port 7682 --ssl --sslcert=/etc/apache2/ssl/server.crt \
+ --sslkey=/etc/apache2/ssl/server.key /openils/bin/osrf-websocket-stdio
---------------------------------------------------------------------------
+
+Optional: Using a web proxy (Apache 2.4 and above)
+--------------------------------------------------
+When the OpenSRF HTTP Translator runs behind a proxy, Apache must be
+configured to read the IP address of the originating client instead
+of the proxy IP address.
+
+1. Enable mod_remoteip
+
-.(Ubuntu Trusty / Xenial)
-[source, bash]
+[source,bash]
---------------------------------------------------------------------------
-cd /path/to/opensrf-OSRFVERSION
-cp examples/apache_24/websockets/apache2.conf /etc/apache2-websockets/
+sudo a2enmod remoteip
---------------------------------------------------------------------------
+
-6. OPTIONAL: add these configuration variables to `/etc/apache2-websockets/envvars`
- and adjust as needed.
+2. Enable remote IP settings by uncommenting and modifying as needed the
+ Apache configuration variables starting with RemoteIP* in the sample Apache
+ configuration file opensrf.conf.
+
-[source, bash]
+3. Configure Apache to listen on port 7080 for HTTP and port 7443 for HTTPS
+ and ensure that it is not listening on ports 80 and 443, then restart Apache.
++
+4. If you didn't run `configure` with the `--with-websockets-port=443` option,
+ edit `<PREFIX>/javascript/opensrf_ws.js` and `<PREFIX>/javascript/opensrf_ws_shared.js`
+ and change
++
+[source, javascript]
+---------------------------------------------------------------------------
+var WEBSOCKET_PORT_SSL = 7682;
---------------------------------------------------------------------------
-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]
+to
++
+[source, javascript]
---------------------------------------------------------------------------
-/etc/init.d/apache2-websockets start
+var WEBSOCKET_PORT_SSL = 443;
---------------------------------------------------------------------------
+
Optional: Using NGINX as a proxy
--------------------------------
NGINX can be used to proxy HTTP, HTTPS, and WebSockets traffic. Among other
apt-get install nginx
---------------------------------------------------------------------------
+
-2. Configure the main Apache instance to listen on port 7080 for HTTP and
- port 7443 for HTTPS and ensure that it is not listening on ports 80
- and 443, then restart Apache.
-3. Copy the example NGINX configuration file into place.
+2. Copy the example NGINX configuration file into place and remove default.
+
[source, bash]
---------------------------------------------------------------------------
cd /path/to/opensrf-OSRFVERSION
cp examples/nginx/osrf-ws-http-proxy /etc/nginx/sites-available/
ln -s /etc/nginx/sites-available/osrf-ws-http-proxy /etc/nginx/sites-enabled/osrf-ws-http-proxy
+rm /etc/nginx/sites-enabled/default
---------------------------------------------------------------------------
+
-4. Edit `/etc/nginx/sites-available/osrf-ws-http-proxy` to set the location
+3. Edit `/etc/nginx/sites-available/osrf-ws-http-proxy` to set the location
of the SSL certificate and private key.
-5. Start NGINX
+4. Generate a dhparam file in the directory specified in the nginx config.
+
[source, bash]
---------------------------------------------------------------------------
-/etc/init.d/nginx start
+# Default config stores dhparam.pem in the Apache2 ssl directory.
+openssl dhparam -out /etc/apache2/ssl/dhparam.pem 2048
---------------------------------------------------------------------------
+
-6. If you didn't run `configure` with the `--with-websockets-port=443` option,
-edit `<PREFIX>/javascript/opensrf_ws.js` and `<PREFIX>/javascript/opensrf_ws_shared.js`
- and change
-+
-[source, javascript]
----------------------------------------------------------------------------
-var WEBSOCKET_PORT_SSL = 7682;
----------------------------------------------------------------------------
-+
-to
+5. Start NGINX
+
-[source, javascript]
+[source, bash]
---------------------------------------------------------------------------
-var WEBSOCKET_PORT_SSL = 443;
+/etc/init.d/nginx start
---------------------------------------------------------------------------
Optional: Using HAProxy as a proxy
apt-get install haproxy
---------------------------------------------------------------------------
+
-2. Configure the main Apache instance to listen on port 7080 for HTTP and
- port 7443 for HTTPS and ensure that it is not listening on ports 80
- and 443, then restart Apache.
-3. Append the example HAProxy to `haproxy.cfg`.
+2. Append the example HAProxy to `haproxy.cfg`.
+
[source, bash]
---------------------------------------------------------------------------
cat examples/haproxy/osrf-ws-http-proxy >> /etc/haproxy/haproxy.cfg
---------------------------------------------------------------------------
+
-4. Edit `/etc/haproxy/haproxy.cfg` to set the location
+3. Edit `/etc/haproxy/haproxy.cfg` to set the location
of the PEM file containing the SSL certificate and private key.
-5. Start HAProxy.
+4. Start HAProxy.
+
[source, bash]
---------------------------------------------------------------------------
/etc/init.d/haproxy start
---------------------------------------------------------------------------
-+
-6. Edit `<PREFIX>/javascript/opensrf_ws.js` and `<PREFIX>/javascript/opensrf_ws_shared.js`
- and change
-+
-[source, javascript]
----------------------------------------------------------------------------
-var WEBSOCKET_PORT_SSL = 7682;
----------------------------------------------------------------------------
-+
-to
-+
-[source, javascript]
----------------------------------------------------------------------------
-var WEBSOCKET_PORT_SSL = 443;
----------------------------------------------------------------------------
Troubleshooting note for Python users
-------------------------------------
entry for localhost, and point your local DNS resolver to `dnsmasq`. For example,
on Ubuntu you can issue the following commands as the *root* Linux account:
-.(Debian / Ubuntu) Installing and starting `dnsmasq`
+.Installing and starting `dnsmasq`
[source, bash]
---------------------------------------------------------------------------
aptitude install dnsmasq
projects / opensrf-equinox.git / blobdiff