mod_muc

Multi-user chat (MUC) is Prosody’s module for allowing you to create hosted chatrooms/conferences for XMPP users.

General information on setting up and using MUC chatrooms can be found in our ‘Chatrooms’ documentation, which you should read if you are new to XMPP chatrooms.

Details

mod_muc implements XEP-0045, which is supported by most XMPP clients to some degree. Rooms are identified by their address, which will be along the lines of room_name@conference.example.com.

Usage

    Component "conference.example.com" "muc"

Replace ‘conference.example.com’ with the address you want to use for the MUC service. It must be different to any other host/server on Prosody, and is usually a subdomain of a normal host. Using ‘conference’ is a common convention, but is completely up to you.

Configuration

Here follows all configuration options. Examples show the default values that are used if the option is not present in the config file.

Note that each room has its own configuration which can be configured by room owners using supporting clients.

Service name

name = "Prosody Chatrooms"

The name to return in service discovery responses for the MUC service itself.

Room creation restrictions

restrict_room_creation = false

If true will only allow admins to create new chatrooms otherwise anyone can create a room.

false: The default. No restrictions, anyone can create rooms.
true or "admin": Restricts room creation to service administrators only.
"local": Restricts room creation to users on the service’s parent domain. E.g. user@example.com can create rooms on rooms.example.com.

Admin privileges

Admins are automatically given ownership of any room they enter, and any attempt at changing the affiliation of an admin to anything other than room owner is denied. This behavior can be disabled with the component_admins_as_room_owners setting:

component_admins_as_room_owners = false

History

max_history_messages = 20

The setting max_history_messages specifies a limit on what each room can be configured to keep. This does not directly affect how many messages are send when a client joins a room. Each room carries its own setting for how much recent history to keep, which defaults to 20. Clients can specify how much history they wish to receive, which is taken into account when deciding how much of available history to send.

Locking

muc_room_locking = true
muc_room_lock_timeout = 300 -- 5 minutes

Room locking is enabled by default, which means that a room must be configured before it can be used. Locked rooms are invisible and cannot be entered by anyone but the creator. If the room has not been configured after the timeout, it is either destroyed or unlocked.

Setting this setting to false might break some clients which expect to be able to “create” the room. It also introduces a race condition where other users might enter a room expected to be private before it is configured so.

Tombstones

When a room is destroyed, it leaves behind a tombstone which prevents the room being entered or recreated. It also allows anyone who was not in the room at the time it was destroyed to learn about it, and to update their bookmarks. Tombstones prevents the case where someone could recreate a previously semi-anonymous room in order to learn the real JIDs of those who often join there.

There are two related settings:

muc_tombstones = true

Setting this to false disables the tombstone behavior.

muc_tombstone_expiry = 86400 * 31

This settings controls how long a tombstone is considered valid. It defaults to 31 days. After this time, the room in question can be created again.

Room configuration defaults

Prosody supports these settings that influence the defaults for newly created rooms.

muc_room_default_public = true
muc_room_default_persistent = false
muc_room_default_members_only = false
muc_room_default_moderated = false
muc_room_default_public_jids = false
muc_room_default_change_subject = false
muc_room_default_history_length = 20
muc_room_default_language = "en"

Limit on number of rooms in-memory

Prosody keeps recently active rooms cached in memory for faster access. The size of this cache defaults to 100 rooms and can be configured like this:

muc_room_cache_size = 100 -- the default

When a room is pushed out of this cache by other more recently active rooms, its complete state is serialized to storage and removed from memory.

Public servers may want to monitor and possibly increase this setting if rooms are moved in and out of memory very often.

Hard room count limit

The behavior of writing inactive rooms out to storage can be disabled by setting a hard limit on number of rooms to keep in memory:

muc_max_rooms = 100 -- no default

Any attempt to create a new room or retrieve one that has been written out to storage that takes the number of rooms currently in memory over this limit will fail.

Example

Component "conference.example.com" "muc"
    name = "The example.com chatrooms server"
    restrict_room_creation = true