?HowTo - Setup a prosody server for modern instant messaging

Contents

  1. Domain, Ports and DNS
  2. Modules
  3. Configuration
    1. Configuration rate limiting
    2. Configuration account register (XEP-0077)
    3. Configuration Server Contact Information (XEP-0157)
    4. Configuration Server-to-Server
    5. Configuration Logging
    6. Configuration registration watcher
    7. Configuration for Support contact
    8. Configuration for invite-based account registration
    9. Configuration for Message archiving (XEP-0313)
    10. Configuration for Message archiving for Multi-User Chat
    11. Component for Groupchat service (XEP-0045)
    12. Configuration share files (XEP-0363)
  4. Apache
    1. webpresence
  5. turn Server
  6. Links

Nowadays instant messaging is more than throwing messages. Users are expecting voice messages, encryption, audio- / video calls and multi device support. A server has to be configured proper to have those features available. Keep in mind, various people may have different requirements.

This guild will help to setup an instant messaging server for family and friends based on our experience.

We assume we own the domain domain.tld. The chat service shall run on the main domain domain.tld. User accounts will be on the main domain and account's ID (JIDs) will be like user@domain.tld.

Furthermore, we are going to provide a place for group chats (called multi user chat "MUC") and a service to share files:

Domain, Ports and DNS

The server is listing on following ports:

The Domain Name Service (DNS) has to be configured proper. Information can be found on https://prosody.im/doc/dns

Setup the SRV records for: 

 _xmpp-client._tcp.domain.tld.          3600    IN      SRV     0       5 5222  domain.tld.
 _xmpps-client._tcp.domain.tld.         3600    IN      SRV     0       5 5223  domain.tld.
 _xmpps-server._tcp.domain.tld.         3600    IN      SRV     0       5 5270  domain.tld.
 _xmpp-server._tcp.domain.tld.          3600    IN      SRV     0       5 5269  domain.tld.
 _xmpp-server._tcp.chat.domain.tld.     3600    IN      SRV     0       5 5269  domain.tld.
 _xmpp-server._tcp.file.domain.tld.     3600    IN      SRV     0       5 5269  domain.tld.

In case your service is not running on domain.tld replace the target domain.tld with somewhere.domain.tld.

Check your settings with: 

dig SRV _xmpp-server._tcp.domain.tld

Modules

Modules you may want. 

modules_enabled = {
  "roster";    -- Allow users to have a roster.
  "saslauth";  -- Authentication for clients and servers.
  "tls";       -- Add support for secure TLS on c2s/s2s connections
  "dialback";  -- s2s dialback support
  "disco";     -- Service discovery
  "carbons";   -- Keep multiple clients in sync
  "pep";       -- Enables users to publish their avatar, mood, activity, playing music and more
  "private";   -- Private XML storage (for room bookmarks, etc.)
  "blocklist"; -- Allow users to block communications with other users
  "vcard4";    -- User profiles (stored in PEP)
  "vcard_legacy"; -- Conversion between legacy vCard and PEP Avatar, vcard
  "time";      -- Let others know the time here on this server
  "ping";      -- Replies to XMPP pings with pongs
  "register";  -- Allow users to register on this server using a client and change passwords
  "mam";       -- Store messages in an archive and allow users to access it
  "csi";
  "csi_battery_saver";
  "cloud_notify";
  "smacks";
  "admin_adhoc"; -- Allows administration via an XMPP client that supports ad-hoc commands
  "bosh";      -- Enable BOSH clients, aka "Jabber over HTTP"
  "websocket"; -- XMPP over WebSockets
  "http";
  "posix";     -- POSIX functionality, sends server to background, enables syslog, etc.
  "groups";    -- Shared roster support
  "server_contact_info"; -- Publish contact information for this service
  "announce";  -- Send announcement to all online users
  "welcome";   -- Welcome users who register accounts
  "register_web"; -- Alert admins of registrations
  "watchregistrations"; -- Alert admins of registrations
  "motd";      -- Send a message to users when they log in
  "bookmarks";
  "lastactivity";
  "invites";
  "invites_adhoc";
  "invites_register";
  "invites_register_web";
  "firewall";
  "webpresence";
  "support_contact";
  "turncredentials";
  "limits";
  "http_file_share";
}

Note: The webpresence module is not necessary for a modern chat service, but nice if you want publish your Jabber status to your blog or website. (see https://modules.prosody.im/mod_webpresence.html)

Configuration

The configuration files can be split in separated files

where prosody will include files conf.d/*.cfg.lua. Those files are symlinks to /etc/prosody/conf.avail/. Those separated files can be used to define a ?VirtualHost. 

VirtualHost "domain.tld"

Configuration rate limiting

-- -----------------------------------------------------------------
-- Connection-level rate limiting
-- -----------------------------------------------------------------

limits = {
  c2s = {
    rate = "10kb/s";
  };
  s2sin = {
    rate = "30kb/s";
  };
}

Configuration account register (XEP-0077)

In-band registration and password change. 

-- -----------------------------------------------------------------
-- mod_register - Enabling this module allows users to register
-- new accounts and change passwords
-- -----------------------------------------------------------------

-- Disabled, because invite will be used
allow_registration = false

-- -----------------------------------------------------------------
-- mod_welcome - Send a custom message to new users.
-- -----------------------------------------------------------------

welcome_message = "Hallo $username auf $host."

Configuration Server Contact Information (XEP-0157)

Contact addresses for your XMPP service. 

-- -----------------------------------------------------------------
-- mod_server_contact_info - contact addresses for your XMPP service via XEP-0157
-- -----------------------------------------------------------------

contact_info = {
          abuse = { "xmpp:support@domain.tld" };
          admin = { "xmpp:support@domain.tld" };
};

daemonize = false;
pidfile = "/run/prosody/prosody.pid";
authentication = "internal_hashed"

Configuration Server-to-Server

s2s_require_encryption = true
s2s_secure_auth = true

Configuration Logging

log = {
        -- Log files (change 'info' to 'debug' for debug logs):
        info = "/var/log/prosody/prosody.log";
        error = "/var/log/prosody/prosody.err";
        { levels = { "error" }; to = "syslog";  };
}

legacy_ssl_ports = { 5223 }
min_seconds_between_registrations = 1200;

Configuration registration watcher

registration_notification = "User $username just registered on $host"
registration_watchers = { "user@domain.tld" }

consider_bosh_secure = true
consider_websocket_secure = true

http_paths = {
  bosh = "/http-bind"; -- Serve BOSH at /http-bind
  websocket = "/ws";
}

http_ports = { 5280 }
http_interfaces = { "*" }

https_ports = { 5281 }
https_interfaces = { "*" }

firewall_scripts = { "/etc/prosody/blacklist.pfw" }

Configuration for Support contact

Adds a default contact to newly registered accounts. 

-- -----------------------------------------------------------------
-- Support contact
-- -----------------------------------------------------------------

support_contact = "support@domain.tld"
support_contact_nick = "XMPP Support"
support_contact_group = "Support"

Allow administrators to create virtual groups of users that automatically see each other in their contact lists. 

-- -----------------------------------------------------------------
-- mod_groups - Groups (‘shared roster’) support
-- -----------------------------------------------------------------

groups_file = "/etc/prosody/sharedgroups.txt"

Configuration for invite-based account registration

Creation and consumption of invite codes 

http_external_url = "https://domain.tld"

-- -----------------------------------------------------------------
-- invite-based account registration
-- https://prosody.im/doc/modules/mod_invites
-- -----------------------------------------------------------------
invites_page = "https://domain.tld/invite?{invite.token}"
invites_page_template_dir = "/var/www/invites"
allow_user_invites = true
invite_expiry = 86400 * 7

http_paths = {
  invites_page = "/invite";
  invites_register_web = "/register";
}

Configuration for Message archiving (XEP-0313)

This can be used to synchronize conversations between multiple clients. 

-- -----------------------------------------------------------------
-- mod_mam - Message archiving (XEP-0313)
-- -----------------------------------------------------------------

default_archive_policy = true
archive_cleanup_interval=4*60*60
archive_expires_after = "2w"
max_archive_query_results = 20

Configuration for Message archiving for Multi-User Chat

MAM for Multi-user chat (MUC) 

-- -----------------------------------------------------------------
-- muc_mam - Message archiving for Multi-User Chat - XEP-0313
-- -----------------------------------------------------------------

muc_log_by_default = false
muc_log_presences = false
log_all_rooms = false
muc_log_expires_after = "2w"
muc_log_cleanup_interval = 4 * 60 * 60

Component for Groupchat service (XEP-0045)

-- -----------------------------------------------------------------
--- Set up a MUC (multi-user chat) room server
-- -----------------------------------------------------------------
Component "chat.domain.tld" "muc"
  modules_enabled = { "muc_mam", "vcard_muc","pastebin" }
  name = "Chaträume - Konferenzen"
  restrict_room_creation = "local"
  muc_room_default_public = false
  muc_room_default_persistent = false
  muc_room_default_members_only = true
  muc_room_default_moderated = true
  muc_room_default_public_jids = false
  muc_room_default_change_subject = false
  muc_room_default_history_length = 20
  muc_room_default_language = "de"
  pastebin_line_threshold = 60
  pastebin_threshold = 5000

Configuration share files (XEP-0363)

Let users share files via HTTP. 

-- -----------------------------------------------------------------
-- Share files via http_file_share component
-- -----------------------------------------------------------------

http_file_share_size_limit = 100*1024*1024 -- 100 MiB

Component "file.domain.tld" "http_file_share"
  http_external_url = "https://file.domain.tld"
  http_file_share_expires_after = 7 * 86400 -- One week
  http_file_share_size_limit = 100*1024*1024 -- 100 MiB
  http_file_share_safe_file_types = { "image/*","video/*","audio/*","text/plain" }
  http_file_share_access = {
        "domain.tld" -- anyone with a @example.org address
  }

Component "proxy.domain.tld" "proxy65"

Apache

webpresence

Use another URL ("nickname") for myuser@domain.tld - to hide you JID on public websites. 

RewriteRule ^/chat/nickname/(.*) https://domain.tld:5281/status/myuser/$1 [P,L]

Display Online status and status message on a website: 

<img src="https://domain.tld/chat/nickname/"/> Nickname
<div>                              
<iframe src="https://domain.tld/chat/nickname/html" frameborder=1 height="100" width="500" ></iframe>
</div>

turn Server

TODO: turn server configuration.

CategoryXmpp