Table of contents ================= 1. Running. 1.1. Using privileged TCP ports 1.2. Custom options for Erlang emulator 1.3. Backups 1.4. Using IPv6 1.5. Using captcha 2. Hostname issues 3. PAM authentication 4. Using DBMS for data storage 5. External modules 6. Upgrading from 2.0.x series 6.1 Changes in ejabberdctl program 6.2 Changes in logging 7. Using SCRAM-SHA-1 authentication mechanism 1. Running ========== 1.1. Using privileged TCP ports ------------------------------- The ejabberd daemon which is run in init.d script is owned by user ejabberd, so it cannot bind to privileged ports (below 1024). The error message in /var/log/ejabberd/ejabberd.log looks similar to the following: E(<0.242.0>:ejabberd_listener:80): Failed to open socket for {443, ejabberd_c2s, [{access,c2s}, {max_stanza_size, 65536}, starttls, {certfile, "/etc/ejabberd/ejabberd.pem"}, {shaper, c2s_shaper}]}: eacces If you want ejabberd to listen for example port 443 you could redirect it to port 5222 (the default XMPP port) by a firewall rule. For example: iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 5222 1.2. Custom options for Erlang emulator --------------------------------------- You can add extra options to the erl command line like -pa /usr/local/lib/ejabberd/ebin by adding them to ERL_OPTIONS in /etc/default/ejabberd. 1.3. Backups ------------ The package always makes a backup of the ejabberd database if it's running when it is upgraded or removed. The backup files are stored in the /var/backups/ejabberd-.* directory. 1.4. Using IPv6 --------------- Since ejabberd 14.07-2, IPv6 is enabled by default, as it is for the Debian kernel. The IPv6 listeners also handle IPv4, so all is well. If you want to go back to IPv4 only, replace 'ip: "::"' with 'ip: "0.0.0.0"' for all listeners in ejabberd.yml. 1.5. Using captcha ------------------ The captcha generation script uses the "convert" program from the "imagemagick" package. As it depends on a lot of packages related to graphics and X Window System, it is listed as suggested. Therefore, if you intend to enable captcha support for your multi-user conferences be sure to install imagemagick besides enabling captcha in the ejabberd configuration file. Also the "graphicsmagick-imagemagick-compat" package can be installed instead of "imagemagick" -- it provides the "convert" program compatible with that of imagemagick. 2. Hostname issues =================== The Mnesia database used by ejabberd is tightly bound to the hostname it runs on. Special care is needed if for some reason the hostname changes. In that case, please read the ejabberd Installation and Operation Guide, chapter 4.5 "Change Computer Hostname", which can be found as PDF and HTML in /usr/share/doc/ejabberd/. 3. PAM authentication ======================= Ejabberd uses the "epam" binary from the erlang-p1-pam package as a helper program to perform PAM authentication. Depending on the PAM plugins used, the process accessing these plugins might have to be run with elevated privileges. The official ejabberd Installation and Operation Guide simplemindedly suggests to make epam setuid root which would make it work for any possible case. Debian's erlang-p1-pam package, on the other hand, ships the epam program with the setuid and setgid bits cleared, and here is why: * Setuid and setgid programs present a serious potential security risk and are a target for exploitation attempts (especially programs which are made setuid root). * Different PAM plugins have different requirements for the privileges of the user working with them, for instance, to use the shadow passwords database for authentication, it is sufficient for the accessing process to be in the group "shadow"; to use LDAP backend, no elevation of privileges is needed at all. Taking into account the fact that ejabberd uses internal authentication by default (using its own private database), the decision of what special access rights to set for the epam program is left to the system administrator. To maintain non-standard access rights for the epam binary, it is advised to use dpkg-statoverride, as suggested by the Debian policy (section 10.9 "Permissions and owners") -- ejabberd package configuration scripts honor this setting so it survives upgrades. As an example, to make epam setgid shadow, you can use: dpkg-statoverride --add root shadow 02755 /usr/lib/erlang/p1_pam/bin/epam and to make epam setuid root you can do: dpkg-statoverride --add root ejabberd 04754 /usr/lib/erlang/p1_pam/bin/epam (Note that we set o-x there so that only users in the ejabberd group are able to elevate their privileges by executing this program.) When ejabberd is started via systemd, you will have to edit the ejabberd.service file and set the following: [Service] PrivateDevices=false NoNewPrivileges=false Otherwise it will be impossible for the epam helper program to gain the configured setuid and/or setgid privileges. With systemd >= 218 you can simply create an override with `systemctl edit ejabberd.service` and put [Service] PrivateDevices= PrivateDevices=false NoNewPrivileges= NoNewPrivileges=false in there. With systemd < 218 the changes must be made manually. In order to not loose the changes upon upgrades, remove the symlink /etc/systemd/system/multi-user.target.wants/ejabberd.service and replace it with a copy of /lib/systemd/system/ejabberd.service before making the changes. Remember to do a `systemctl daemon-reload` afterwards. 4. Using DBMS for data storage =============================== The ejabberd Installation and Operation Guide mentions that ejabberd is able to use various DBMS engines to manage most of ejabberd's data, such as user accounts, rosters, offline messages, pubsub storage etc. Starting with ejabberd 14.07-1, all officially supported DBMS engines are supported through the Debian package, as ejabberd is now compiled and installed with support for ODBC, MySQL and PostgreSQL. You have to install the according erlang-* package listed in the "Suggests" section of ejabberd though. Note that it appears that currently the only way to use Microsoft SQL Server as a database backend is via ODBC (and the FreeTDS ODBC driver). 5. External modules =================== Some 3rd-party modules from https://github.com/processone/ejabberd-contrib are available through the ejabberd-contrib package. It only includes selected modules from the github repository, if you need more, please contact the package maintainer. If you want to develop your own module, the ejabberd-contrib repository is the best place to start. Please see the Readme.md or scroll downwards on https://github.com/processone/ejabberd-contrib All header files are available there as well as through the debian packages. To install a custom module, copy the resulting beam file(s) to a directory in which the Erlang emulator running ejabberd looks for compiled files. The best way to handle external modules is to maintain a special directory for them under "/usr/local", e.g. "/usr/local/lib/ejabberd/ebin". To make Erlang emulator know about this directory, add an appropriate option to the ERL_OPTIONS variable in the "/etc/default/ejabberd" file. For the location proposed, you will probably want to add -pa /usr/local/lib/ejabberd/ebin to that variable. See the erl(1) manual page for more info on the "-pa" Erlang emnulator command line option. 6. Upgrading from 2.0.x series ============================== Certain changes were made in version 2.1.0 which are incompatible with 2.0.x series packaged in Debian. While upgrading of the database should occur fully automatically, there are changes in the infrastructure, which you might need to take into account, 6.1 Changes in ejabberdctl program ---------------------------------- 1) The calling format of the ejabberdctl program was changed: a special prefix "vhost HOSTNAME" which selected operation on the specified virtual host was dropped; now previously vhost-specific commands gained one extra argument specifying a virtual host (such as "ban-users") or come in pairs, such as "delete-old-users" with "delete-old-users-vhost". 2) Some ejabberdctl commands were renamed (see below). 3) ejabberd in Debian was shipped with the mod_ctlextra module which provided several advanced commands for the ejabberdctl program. mod_ctlextra is not supported since 2.1.0 anymore and so it was replaced my its successor, mod_admin_extra. This resulted in renaming of several commands previously provided by mod_ctlextra. Note that for mod_admin_extra module to be loaded, it must be mentioned in the appropriate section of the ejabberd configuration file. As this file is not upgraded automatically, make sure you have replaced the request to load mod_ctlextra with the request to load mod_admin_extra. Refer to the ejabberdctl(8) manual page for more details. The summary of changes in ejabberdctl commands is given below. Renamed: "set-password" to "change-password"; "delete-older-messages" to "delete-old-messages"; "delete-older-users" to "delete-old-users"; "rem-rosteritem" to "delete-rosteritem"; "killsession" to "kick-session"; Renamed and calling convention changed: "vcard-get" to "get-vcard" and "get-vcard2"; "vcard-set" to "set-vcard" and "set-vcard2"; Deleted: "rosteritem-purge" Virtual-host specific commands which now accept a virtual host to operate on as their extra argument: "ban-account" "num-active-users" "registered-users" 4) The ejabberdctl program was changed not to generate unique node names by default for the Erlang process it starts; to enable generation of unique node names you now has to pass the "--concurrent" command-line option to the ejabberdctl program. This was made to prevent overflows of atom table in the ejabberd process which may occur if ejabberdctl is started many times during the ejabberd process lifetime, which is not uncommon on some high-profile sites. Now, ejabberdctl assumes you take care of ensuring all invocations of ejabberdctl are done in a sequence and uses constant names for the nodes of the Erlang processes it starts. If you can not (or don't want to) guarantee sequential invocations, pass the "--concurrent" command-line option to the ejabberdctl program. In this case, it will append the PID of the shell process executing the ejabberdctl code to the node name of the Erlang process ejabberdctl starts. This will inevitably grow the ejabberd process's atom table but the maximum theoretical number of the entries added will be no more than twice the maximum number of unique PIDs configured for the system (kernel.pid_max sysctl variable). See http://lists.jabber.ru/pipermail/ejabberd/2009-September/005337.html and http://lists.jabber.ru/pipermail/ejabberd/2009-November/005456.html threads for more info on this issue. 6.2 Changes in logging ---------------------- Erlang emulator log was renamed from "sasl.log" to "erlang.log" to remove confusion (some people interpreted "sasl" as standing for "Simple Authentication and Security Layer" instead of Erlang runtime's logging mechanism). The "--sasl-log" command-line option of the ejabberd program was renamed to "--erlang-log" to match the change above. 7. Using SCRAM-SHA-1 authentication mechanism ============================================= Since version 2.1.9 ejabberd supports the SCRAM-SHA-1 authentication mechanism (which, among other things, allows one to not store passwords of XMPP accounts in clear text if the internal database backend is used for storage). This authentication process implemented by this mechanism includes the client sending a so-called "digest URI" which includes the server's identity as perceived by the connecting client. The SCRAM-SHA-1 RFC document requires this identity to be the fully-qualified host name of the server. This hostname is typically obtained by the client by looking up a server-specific DNS record of type SRV for the XMPP domain the client wants to register in. Unfortunately, the current implementation of SCRAM-SHA-1 in ejabberd is not able to perform the same kind of DNS query as used by the clients to know its "canonical" fully-qualified host name. Consequently, if the actual hostname of the server differs from the name of the XMPP domain it serves, a special option should be included in the configuration file to let the server know its hostname as seen by its clients. This configuration option is called "fqdn" and it expects a single argument -- the fully-qualified hostname of the server, as recorded in the appropriate DNS SRV record for the server. An example of its usage: {fqdn, "foo.example.com"}. It worth repeating that if the server's hostname is not different from the name of XMPP domain it servers (for instance, the XMPP domain is "example.com" and the server's hostname is also "example.com") the usage of this configuration option is not necessary as ejabberd will just use the domain name in the indicated case. It should be noted that while certain clients faithfully implement the SCRAM-SHA-1 specification, some other clients diverge and use the XMPP domain instead of the fully-qualified hostname of the server in the digest URI strings they send. Ejabberd implements relaxed rules for interpreting digest URIs to be interoperable with broken client implementations. Authors ======= Torsten Werner Sergei Golovan Konstantin Khomoutov Philipp Huebner Thu, 18 Feb 2016 08:24:33 +0100