Differences between revisions 1 and 19 (spanning 18 versions)
Revision 1 as of 2011-12-01 21:42:50
Size: 7524
Editor: ?markus tornow
Comment:
Revision 19 as of 2016-09-26 06:28:20
Size: 12194
Editor: Praveen A
Comment:
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
~-[[fr/DebianWiki/EditorGuide#translation|Translation(s)]] :English - [[fr/InstallingProsody|Francais]] -~ ~-[[fr/DebianWiki/EditorGuide#translation|Translation(s)]]: English - [[fr/InstallingProsody|Francais]] -~
Line 5: Line 5:
This page provides information about the installation and configuration of the '''xmpp server prosody''' ( a jabber server) on Debian.
## Si votre article est assez long, dé-commentez la table des matières
This page provides information about the installation and configuration of the '''xmpp server prosody''' (a jabber server) on Debian.

## If your page gets really long, uncomment this Table of Contents
Line 10: Line 11:
The XMPP service will be offered on the host named'''im.example.org''' with TLS encryption.

Before starting make sure im.example.org actually points to the public IP of the host (cf. [[#Enregistrements_DNS|Enregistrements DNS]])

In addition, the port'''5222'''and'''5269''' are open to the public IP.
}}}
= Squeeze =
The XMPP service will be offered on the host named '''im.example.org''' with TLS encryption.

Before starting make sure im.example.org actually points to the public IP of the host (cf. [[#DNS_records|DNS records]]).

In addition, the port '''5222''' and '''5269''' are open to the public IP.
}}}
= Squeeze, Lenny =
Line 37: Line 38:
 Configuration is done in the « / etc / prosody ». Similar to the model of apache there is a global configuration file « prosody.cfg.lua » and different files for each ''!VirtualHosts'' in the directory « conf.avail/ ».

By default two examples of hosts configurations files are to be found in that directory: « ''localhost.cfg.lua'' » and « ''example.com.cfg.lua'' ». However, only''localhost''is activated upon installation.
Configuration is done in the « / etc / prosody ». Similar to the model of apache there is a global configuration file « prosody.cfg.lua » and different files for each ''!VirtualHosts'' in the directory « conf.avail/ ».

By default two examples of hosts configurations files are to be found in that directory: « ''localhost.cfg.lua'' » and « ''example.com.cfg.lua'' ». However, only ''localhost'' is activated upon installation.
Line 42: Line 43:
'''A configuration file must have the extension lua. ''' '''A configuration file must have the extension lua.'''
Line 50: Line 51:
=== Installing modules ===
 [[https://prosody.im/doc/installing_modules|Follow official documentation on installing modules]].
Line 53: Line 56:
The couple key / certificate for encryption between client / server and server / server is in « /etc/prosody/certs/ ». During installation the files localhost.cert and localhost.key are created, which are valid only for '''localhost''',  since you do not have a specific configuration for openssl yet  ("/etc/ssl/openssl.cnf").

If you already have the files  for '''im.example.org''' Just point the configuration above. Else you will have to create them

The creation of a couple key / certificate is not the subject of this page, for that refer to the documentation for of openssl (TODO add link).
The key / certificate pair for encryption between client / server and server / server is in « /etc/prosody/certs/ ». During installation the files localhost.cert and localhost.key are created, which are valid only for '''localhost''', since you do not have a specific configuration for openssl yet ("/etc/ssl/openssl.cnf").

If you already have the files for '''im.example.org''' just point the configuration above. Else you will have to create them.

The creation of a key / certificate pair is not the subject of this page, for that refer to the documentation of [[http://wiki.openssl.org/index.php/Main_Page|OpenSSL]].
Line 71: Line 74:
{{{#!wiki note
If you are using a certificate that is valid only for a short term like those provided by LetsEncrypt.org (3 month validity), you may want to enable reload_modules module and add reload_modules = { "tls" } to your config. this should reload the cert when you reload prosody.
}}}
Line 77: Line 84:
With your favorite editor change the settings for '''! VirtualHost''' and'''enabled''' so you have: With your favorite editor change the settings for '''!VirtualHost''' and '''enabled''' so you have:
Line 82: Line 89:
The line "- enabled = [...]" can also be removed, instead of of removing the comment like above. The line "- enabled = [...]" can also be removed, instead of adding the comment like above.
Line 91: Line 98:
If you already have a couple key / cert on the same domain name (Common Name), for example for apache, point to it instead of the files listed above. If you already have a key / certificate pair on the same domain name (Common Name), for example for apache, point to it instead of the files listed above.
Line 106: Line 113:
=== Create users (single)=== === Create users (single) ===
Line 112: Line 119:
=== Other authentication methods (Advanced)  ===
==== Cyrus SASL avec LDAP ====
The advantage of this method is to be able to configure the user accounts reported/managed independently of prosody,
L'avantage de cette méthode est de permettre l'utilisation de comptes utilisateurs déclarés/gérés indépendamment de
prosody, namely via LDAP. The official documentation officielle is to be found at [[http://prosody.im/doc/cyrus_sasl|disponible of the prosody site]].
=== Other authentication methods (Advanced) ===
==== Cyrus SASL with LDAP ====
The advantage of this method is to be able to configure the user accounts reported/managed independently of prosody, namely via LDAP. The official documentation is to be found at [[http://prosody.im/doc/cyrus_sasl|the prosody site]].
Line 119: Line 125:
# squeeze
Line 120: Line 127:
# lenny
aptitude install sasl2-bin lua-cyrussasl libsasl2-modules-ldap
Line 124: Line 133:
sasl_backend = "cyrus" -- 0.7 (different in 0.8) sasl_backend = "cyrus" -- squeeze (0.7 or 0.8)
authentication = "cyrus" -- lenny (0.9+)
Line 131: Line 141:
Then it is necessary to configure options for the ''mechanisms'' of authentication. This is done in the file indicated by ''' MECH_OPTIONS ''' (generally in « /etc/default/saslautd »). To do this edit the file and insert the following: Then it is necessary to configure options for the ''mechanisms'' of authentication. This is done in the file indicated by '''MECH_OPTIONS''' (generally in « /etc/default/saslautd »). To do this edit the file and insert the following:
Line 148: Line 158:
Then declare a service used sasl xmpp used by prosody in the file « /usr/lib/sasl2/xmpp.conf ». The name of the file depends on the file you entered for the "cyrus_application_name" in the configuration of prosody. Hint: first run the above command as the sasl user (or root) to make sure that sasl is configured correctly. Then run as the prosody user to make sure that prosody can authenticate using sasl (add prosody to sasl group).

For 0.7 (?):Then declare a service used sasl xmpp used by prosody in the file « /usr/lib/sasl2/xmpp.conf ». The name of the file depends on the file you entered for the "cyrus_application_name" in the configuration of prosody.

For 0.8/Wheezy and Squeeze: Declare the service in «/etc/sasl/xmpp.conf». The directory /etc/sasl might not yet exist. The filename corresponds to the value entered for the "cyrus_application_name" in the configuration of prosody.
Line 154: Line 169:
If this file does not exist or has the wrong filename, then /var/log/auth.log outputs messages like "NTLM server step 1" which indicate that the above mech_list is not used.

=== Useful Modules (Mobile support) ===
There are many [[http://modules.prosody.im/|modules]] available for prosody that adds more useful features. Namely

 * mod_carbons -- XEP 0280 Message carbons (multi devise sync)
 * mod_smacks, mod_smacks_offline -- XEP 198 stream management (keep online)
 * mod_csi, mod_filter_chatstates, mod_throttle_presence -- XEP 0352 Client State Indication (save battery)
 * mod_http_upload -- share images in chatrooms
 * mod_blocking -- XEP 0191 block users

With prosody 0.10 (via nightly builds from https://prosody.im/nightly/)
Note: These modules need sql storage backend
 * mod_mam - XEP 0313 message archive management (go back in message history)

Add sql backend for storage module, and storage == "sql" should be uncommented and a storage driver for postgresql or mysql or sqlite3 should be configured.

{{{
storage = "sql";
modules_enabled {
    storage = {
       archive2 = "sql";
    };
}
}}}
 * mod_mam_muc - MAM for conferences
 * mod_blocklist instead of mod_privacy and mod_blocking

=== Chatroom ===
To allow xmpp conferences, [[https://prosody.im/doc/chatrooms|enable chatroom component]]. To allow outsiders to see the conferences, make sure you [[https://prosody.im/doc/dns#subdomains|add the appropriate DNS record]]. Make sure you update your ssl/tls certificates to include the new domain.

{{{
Component "conference.im.example.org" "muc"
    name = "im.example.org chatrooms Server"
    modules_enabled = {
       "muc_limits";
       "mam_muc";
       storage = {
           muc_log = "sql";
       }
    };
}}}

=== XMPP over HTTPS ===

To allow connecting to XMPP service over HTTPS port (work around for firewalls that block all ports except 80 and 443),
 * You should install sslh with ALPN support (>= 1.18). You can get the deb from http://mahishasura.pxq.in or compile it yourself.
 * Configure your web server to listen to 127.0.0.1:443
 * Add legacy_ssl_ports = 5223 to /etc/prosody/prosody.cfg.lua
 * Update /etc/default/sslh and change RUN=yes
 * Create /etc/sslh/sslh.cfg
{{{
verbose: false;
foreground: false;
inetd: false;
numeric: false;
transparent: false;
timeout: 2;
user: "nobody";
pidfile: "/var/run/sslh/sslh.pid";


# Change hostname with your external address name. Note: It should not be resolving to 127.0.0.1
listen:
(
    { host: "im.example.org"; port: "443"; }
);

protocols:
(
   { name: "tls"; host: "localhost"; port: "5223"; alpn_protocols: [ "xmpp-client" ]; log_level: 0;},
   # catch anything else TLS
   { name: "tls"; host: "localhost"; port: "443";},
   { name: "xmpp"; host: "localhost"; port: "5222"; },
   { name: "timeout"; host: "localhost"; port: "443";}
);
 
on-timeout: "timeout";
                                    
}}}
 * Change DAEMON_OPTIONS to just "-F /etc/sslh/sslh.cfg"
 * You should add new SRV records.

{{{
# Try the following order, 5222/xmpp, 5223/tls, 443/xmpp, 443/tls
_xmpp-client._tcp.im.example.org. 86400 IN SRV 5 1 5222 im.example.org.
_xmpps-client._tcp.im.example.org. 86400 IN SRV 10 1 5223 im.example.org.
_xmpp-client._tcp.im.example.org. 86400 IN SRV 15 1 443 im.example.org.
_xmpps-client._tcp.im.example.org. 86400 IN SRV 20 1 443 im.example.org.
}}}

Check if you can connect to the xmpp port correctly.

{{{
openssl s_client -connect im.example.org:443 -alpn xmpp-client -servername im.example.org
}}}
Line 163: Line 275:
The extension munin is available at [[http://exchange.munin-monitoring.org/plugins/prosody/details|munin exchange]].

The use of this extension requires the prosody module console. So, remove the comment in front of '''console''' in the list of '''modules_enabled''' in the file « /etc/prosody/prosody.cfg.lua » .
The munin extension is available at [[https://github.com/munin-monitoring/contrib/tree/master/plugins/prosody|munin contributed stuff git repository]].

The use of this extension requires the console prosody module. So, remove the comment in front of '''console''' in the list of '''modules_enabled''' in the file « /etc/prosody/prosody.cfg.lua » .
Line 168: Line 280:
The XMPP protocol manages the records of type SRV , for example for the domain '''im.example.org''', you might want to make the following records: The XMPP protocol manages the records of type SRV, for example for the domain '''im.example.org''', you might want to make the following records:
Line 177: Line 289:
== Using Prosody with Diaspora ==

 * [[Diaspora/XMPP| Steps to configure prosody as chat provider for diaspora social network]]

## You can add other _helpful_ links here.
##== See also ==
Line 179: Line 297:
## Vous pouvez ajouter d'autres articles utiles ici.
##Voir aussi:
## Si cette article correspond à certaines catégories (qui existent!), ajoutez les ici.
## ["CategorySomething"] | ["CategorySomethingElse"]
## If this page belongs to an existing Category, add it below.
## CategorySomething | CategoryAnother

Translation(s): English - Francais


This page provides information about the installation and configuration of the xmpp server prosody (a jabber server) on Debian.

The XMPP service will be offered on the host named im.example.org with TLS encryption.

Before starting make sure im.example.org actually points to the public IP of the host (cf. DNS records).

In addition, the port 5222 and 5269 are open to the public IP.

Squeeze, Lenny

Installation of prosody

is with aptitude or apt, for example:

aptitude install prosody

Configuration

The files

Are in /etc/prosody

/etc/prosody/prosody.cfg.lua
/etc/prosody/README
/etc/prosody/certs/
/etc/prosody/conf.avail/
/etc/prosody/conf.d/

Configuration is done in the « / etc / prosody ». Similar to the model of apache there is a global configuration file « prosody.cfg.lua » and different files for each VirtualHosts in the directory « conf.avail/ ».

By default two examples of hosts configurations files are to be found in that directory: « localhost.cfg.lua » and « example.com.cfg.lua ». However, only localhost is activated upon installation.

A configuration file must have the extension lua.

Keep the extension if you rename or create files.

The configuration files which are actually read by prosody are in « /etc/prosody/conf.d/ ».

Typically the files in « conf.d » are symbolic links to a file in « conf.avail ».

Installing modules

SSL Encryption

The key / certificate pair for encryption between client / server and server / server is in « /etc/prosody/certs/ ». During installation the files localhost.cert and localhost.key are created, which are valid only for localhost, since you do not have a specific configuration for openssl yet ("/etc/ssl/openssl.cnf").

If you already have the files for im.example.org just point the configuration above. Else you will have to create them.

The creation of a key / certificate pair is not the subject of this page, for that refer to the documentation of OpenSSL.

For example for a self-signed certificate:

openssl genrsa -out /etc/prosody/certs/im.example.org.key 2048
openssl req -new -x509 -key /etc/prosody/certs/im.example.org.key -out /etc/prosody/certs/im.example.org.cert -days 1095

The footprint md5/sha1 (to distribute to your users to control the identity of the server during the first connection)

openssl x509 -fingerprint -md5 -in /etc/prosody/certs/im.example.org.cert
openssl x509 -fingerprint -sha1 -in /etc/prosody/certs/im.example.org.cert

If you are using a certificate that is valid only for a short term like those provided by LetsEncrypt.org (3 month validity), you may want to enable reload_modules module and add reload_modules = { "tls" } to your config. this should reload the cert when you reload prosody.

Declaring host

The configuration of the host im.example.org will be done in the file « /etc/prosody/conf.avail/im.example.org.cfg.lua », the file example.com.cfg.lua may serve as a model:

cp -a /etc/prosody/conf.avail/example.com.cfg.lua /etc/prosody/conf.avail/.cfg.lua

With your favorite editor change the settings for VirtualHost and enabled so you have:

VirtualHost "im.example.org"
          --enabled = false -- Remove this line to enable this host

The line "- enabled = [...]" can also be removed, instead of adding the comment like above.

Also represent the key and the SSL certificate:

          ssl = {
                  key = "/etc/prosody/certs/im.example.org.key";
                  certificate = "/etc/prosody/certs/im.example.org.cert";
                  }

If you already have a key / certificate pair on the same domain name (Common Name), for example for apache, point to it instead of the files listed above.

Now create the symbolic link in« /etc/prosody/conf.d/ » with:

ln -sf /etc/prosody/conf.avail/im.example.org.cfg.lua /etc/prosody/conf.d/im.example.org.cfg.lua

Several host by one configuration

Here is an example to declare a single configuration for multiple hosts (thank you MattJ):

for _, host in ipairs { "example.net", "example.org" } do
   VirtualHost (host)
      option1 = "foo"
      option2 = "bar"
end

Create users (single)

Creating user accounts is done with the command « prosodyctl »

prosodyctl adduser romeo@im.example.org

Other authentication methods (Advanced)

Cyrus SASL with LDAP

The advantage of this method is to be able to configure the user accounts reported/managed independently of prosody, namely via LDAP. The official documentation is to be found at the prosody site.

First install the packages required for authentication with sasl prosody.

# squeeze
aptitude install sasl2-bin liblua5.1-cyrussasl0 libsasl2-modules-ldap
# lenny
aptitude install sasl2-bin lua-cyrussasl libsasl2-modules-ldap

Declare the use of Cyrus SASL as authentication method in « /etc/prosody/prosody.cfg.lua »:

sasl_backend = "cyrus" -- squeeze (0.7 or 0.8)
authentication = "cyrus" -- lenny (0.9+)                    
cyrus_application_name = "xmpp"

In « /etc/default/saslautd » change START=no to START=yes and control it by MECHANISMS="ldap". Also MECH_OPTIONS must point to a file, probably « /etc/default/saslautd ».

Then it is necessary to configure options for the mechanisms of authentication. This is done in the file indicated by MECH_OPTIONS (generally in « /etc/default/saslautd »). To do this edit the file and insert the following:

ldap_servers: ldap://ldap.example.org/
ldap_search_base: ou=user,dc=example,dc=org

Restart the service:

invoke-rc.d saslauthd restart

Test if it works correct:

$ testsaslauthd -u utilisateur -p mot_de_passe
0: OK "Success."

Hint: first run the above command as the sasl user (or root) to make sure that sasl is configured correctly. Then run as the prosody user to make sure that prosody can authenticate using sasl (add prosody to sasl group).

For 0.7 (?):Then declare a service used sasl xmpp used by prosody in the file « /usr/lib/sasl2/xmpp.conf ». The name of the file depends on the file you entered for the "cyrus_application_name" in the configuration of prosody.

For 0.8/Wheezy and Squeeze: Declare the service in «/etc/sasl/xmpp.conf». The directory /etc/sasl might not yet exist. The filename corresponds to the value entered for the "cyrus_application_name" in the configuration of prosody.

pwcheck_method: saslauthd
mech_list: PLAIN

If this file does not exist or has the wrong filename, then /var/log/auth.log outputs messages like "NTLM server step 1" which indicate that the above mech_list is not used.

Useful Modules (Mobile support)

There are many modules available for prosody that adds more useful features. Namely

  • mod_carbons -- XEP 0280 Message carbons (multi devise sync)
  • mod_smacks, mod_smacks_offline -- XEP 198 stream management (keep online)
  • mod_csi, mod_filter_chatstates, mod_throttle_presence -- XEP 0352 Client State Indication (save battery)
  • mod_http_upload -- share images in chatrooms
  • mod_blocking -- XEP 0191 block users

With prosody 0.10 (via nightly builds from https://prosody.im/nightly/) Note: These modules need sql storage backend

  • mod_mam - XEP 0313 message archive management (go back in message history)

Add sql backend for storage module, and storage == "sql" should be uncommented and a storage driver for postgresql or mysql or sqlite3 should be configured.

storage = "sql";
modules_enabled {
    storage = {
       archive2 = "sql";           
    };
}
  • mod_mam_muc - MAM for conferences
  • mod_blocklist instead of mod_privacy and mod_blocking

Chatroom

To allow xmpp conferences, enable chatroom component. To allow outsiders to see the conferences, make sure you add the appropriate DNS record. Make sure you update your ssl/tls certificates to include the new domain.

Component "conference.im.example.org" "muc"
    name = "im.example.org chatrooms Server"
    modules_enabled = {
       "muc_limits";
       "mam_muc";
       storage = {                
           muc_log = "sql";
       }
    };

XMPP over HTTPS

To allow connecting to XMPP service over HTTPS port (work around for firewalls that block all ports except 80 and 443),

  • You should install sslh with ALPN support (>= 1.18). You can get the deb from http://mahishasura.pxq.in or compile it yourself.

  • Configure your web server to listen to 127.0.0.1:443
  • Add legacy_ssl_ports = 5223 to /etc/prosody/prosody.cfg.lua
  • Update /etc/default/sslh and change RUN=yes
  • Create /etc/sslh/sslh.cfg

verbose: false;
foreground: false;
inetd: false;
numeric: false;
transparent: false;
timeout: 2;
user: "nobody";
pidfile: "/var/run/sslh/sslh.pid";


# Change hostname with your external address name. Note: It should not be resolving to 127.0.0.1
listen:
( 
    { host: "im.example.org"; port: "443"; } 
);

protocols:  
(
   { name: "tls"; host: "localhost"; port: "5223"; alpn_protocols: [ "xmpp-client" ]; log_level: 0;},
   # catch anything else TLS
   { name: "tls"; host: "localhost"; port: "443";},
   { name: "xmpp";    host: "localhost"; port: "5222"; },
   { name: "timeout"; host: "localhost"; port: "443";}
);
 
on-timeout: "timeout";
  • Change DAEMON_OPTIONS to just "-F /etc/sslh/sslh.cfg"
  • You should add new SRV records.

# Try the following order, 5222/xmpp, 5223/tls, 443/xmpp, 443/tls
_xmpp-client._tcp.im.example.org. 86400 IN SRV 5 1 5222 im.example.org.
_xmpps-client._tcp.im.example.org. 86400 IN SRV 10 1 5223 im.example.org.
_xmpp-client._tcp.im.example.org. 86400 IN SRV 15 1 443 im.example.org.
_xmpps-client._tcp.im.example.org. 86400 IN SRV 20 1 443 im.example.org.

Check if you can connect to the xmpp port correctly.

openssl s_client -connect im.example.org:443 -alpn xmpp-client -servername im.example.org

Test

invoke-rc.d prosody restart

And check the log files « /var/log/prosody/prosody.err » and « /var/log/prosody/prosody.log ».

More

Munin

The munin extension is available at munin contributed stuff git repository.

The use of this extension requires the console prosody module. So, remove the comment in front of console in the list of modules_enabled in the file « /etc/prosody/prosody.cfg.lua » .

DNS records

The XMPP protocol manages the records of type SRV, for example for the domain im.example.org, you might want to make the following records:

_xmpp-client._tcp.example.org. SRV  10 100 5222 im.example.org.
_xmpp-server._tcp.example.org. SRV  10 100 5269 im.example.org.
im.example.org.            A    192.0.2.12

In this example 192.0.2.12 is the IP of the public server.

Using Prosody with Diaspora