diff --git a/content/archive/24.06/admin-api.md b/content/archive/24.06/admin-api.md new file mode 100644 index 00000000..e0cbff82 --- /dev/null +++ b/content/archive/24.06/admin-api.md @@ -0,0 +1,7118 @@ +--- +search: + exclude: true +--- + +# API Reference + +> This section describes API commands of ejabberd [24.06](../../archive/24.06/index.md). If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the [Archive](../../archive/index.md). The commands that changed in this version are marked with 🟤. + + + +## abort_delete_old_mam_messages + + + +Abort currently running delete old MAM messages operation + +__Arguments:__ + +- *host* :: string : Name of host where operation should be aborted + +__Result:__ + +- *status* :: string : Status text + +__Tags:__ +[purge](admin-tags.md#purge) + +__Module:__ +[mod_mam](modules.md#mod_mam) + +__Examples:__ + + +~~~ json +POST /api/abort_delete_old_mam_messages +{ + "host": "localhost" +} + +HTTP/1.1 200 OK +"Operation aborted" +~~~ + + + + +## abort_delete_old_messages + + + +Abort currently running delete old offline messages operation + +__Arguments:__ + +- *host* :: string : Name of host where operation should be aborted + +__Result:__ + +- *status* :: string : Status text + +__Tags:__ +[purge](admin-tags.md#purge) + +__Examples:__ + + +~~~ json +POST /api/abort_delete_old_messages +{ + "host": "localhost" +} + +HTTP/1.1 200 OK +"Operation aborted" +~~~ + + + + +## add_rosteritem 🟤 + + + +Add an item to a user's roster (supports ODBC) + +__Arguments:__ + +- *localuser* :: string : User name +- *localhost* :: string : Server name +- *user* :: string : Contact user name +- *host* :: string : Contact server name +- *nick* :: string : Nickname +- *groups* :: [group::string] : Groups +- *subs* :: string : Subscription + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[roster](admin-tags.md#roster), [v1](admin-tags.md#v1) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/add_rosteritem +{ + "localuser": "user1", + "localhost": "myserver.com", + "user": "user2", + "host": "myserver.com", + "nick": "User 2", + "groups": [ + "Friends", + "Team 1" + ], + "subs": "both" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## backup + + +Backup the Mnesia database to a binary file + +__Arguments:__ + +- *file* :: string : Full path for the destination backup file + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/backup +{ + "file": "/var/lib/ejabberd/database.backup" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## ban_account + + + +Ban an account + + +This command kicks the account sessions, sets a random password, and stores ban details in the account private storage. This command requires mod_private to be enabled. Check also [get_ban_details](#get_ban_details) API and `_unban_account`_ API. + +__Arguments:__ + +- *user* :: string : User name to ban +- *host* :: string : Server name +- *reason* :: string : Reason for banning user + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[accounts](admin-tags.md#accounts), [v2](admin-tags.md#v2) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/ban_account +{ + "user": "attacker", + "host": "myserver.com", + "reason": "Spaming other users" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## bookmarks_to_pep + + +Export private XML storage bookmarks to PEP + +__Arguments:__ + +- *user* :: string : Username +- *host* :: string : Server + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[private](admin-tags.md#private) + +__Module:__ +[mod_private](modules.md#mod_private) + +__Examples:__ + + +~~~ json +POST /api/bookmarks_to_pep +{ + "user": "bob", + "host": "example.com" +} + +HTTP/1.1 200 OK +"Bookmarks exported" +~~~ + + + + +## change_password + + +Change the password of an account + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name +- *newpass* :: string : New password for user + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[accounts](admin-tags.md#accounts) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/change_password +{ + "user": "peter", + "host": "myserver.com", + "newpass": "blank" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## change_room_option + + +Change an option in a MUC room + +__Arguments:__ + +- *name* :: string : Room name +- *service* :: string : MUC service +- *option* :: string : Option name +- *value* :: string : Value to assign + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[muc_room](admin-tags.md#muc_room) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/change_room_option +{ + "name": "room1", + "service": "conference.example.com", + "option": "members_only", + "value": "true" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## check_account + + +Check if an account exists or not + +__Arguments:__ + +- *user* :: string : User name to check +- *host* :: string : Server to check + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[accounts](admin-tags.md#accounts) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/check_account +{ + "user": "peter", + "host": "myserver.com" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## check_password + + +Check if a password is correct + +__Arguments:__ + +- *user* :: string : User name to check +- *host* :: string : Server to check +- *password* :: string : Password to check + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[accounts](admin-tags.md#accounts) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/check_password +{ + "user": "peter", + "host": "myserver.com", + "password": "secret" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## check_password_hash + + +Check if the password hash is correct + + +Allows hash methods from the Erlang/OTP [crypto](https://www.erlang.org/doc/man/crypto) application. + +__Arguments:__ + +- *user* :: string : User name to check +- *host* :: string : Server to check +- *passwordhash* :: string : Password's hash value +- *hashmethod* :: string : Name of hash method + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[accounts](admin-tags.md#accounts) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/check_password_hash +{ + "user": "peter", + "host": "myserver.com", + "passwordhash": "5ebe2294ecd0e0f08eab7690d2a6ee69", + "hashmethod": "md5" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## clear_cache + + +Clear database cache on all nodes + +__Arguments:__ + + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[server](admin-tags.md#server) + +__Examples:__ + + +~~~ json +POST /api/clear_cache +{ + +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## compile + + +Recompile and reload Erlang source code file + +__Arguments:__ + +- *file* :: string : Filename of erlang source file to compile + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[erlang](admin-tags.md#erlang) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/compile +{ + "file": "/home/me/srcs/ejabberd/mod_example.erl" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## connected_users + + +List all established sessions + +__Arguments:__ + + +__Result:__ + +- *connected_users* :: [sessions::string] : List of users sessions + +__Tags:__ +[session](admin-tags.md#session) + +__Examples:__ + + +~~~ json +POST /api/connected_users +{ + +} + +HTTP/1.1 200 OK +[ + "user1@example.com", + "user2@example.com" +] +~~~ + + + + +## connected_users_info + + +List all established sessions and their information + +__Arguments:__ + + +__Result:__ + +- *connected_users_info* :: [{jid::string, connection::string, ip::string, port::integer, priority::integer, node::string, uptime::integer, status::string, resource::string, statustext::string}] + +__Tags:__ +[session](admin-tags.md#session) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/connected_users_info +{ + +} + +HTTP/1.1 200 OK +[ + { + "jid": "user1@myserver.com/tka", + "connection": "c2s", + "ip": "127.0.0.1", + "port": 42656, + "priority": 8, + "node": "ejabberd@localhost", + "uptime": 231, + "status": "dnd", + "resource": "tka", + "statustext": "" + } +] +~~~ + + + + +## connected_users_number + + +Get the number of established sessions + +__Arguments:__ + + +__Result:__ + +- *num_sessions* :: integer + +__Tags:__ +[session](admin-tags.md#session), [statistics](admin-tags.md#statistics) + +__Examples:__ + + +~~~ json +POST /api/connected_users_number +{ + +} + +HTTP/1.1 200 OK +2 +~~~ + + + + +## connected_users_vhost + + +Get the list of established sessions in a vhost + +__Arguments:__ + +- *host* :: string : Server name + +__Result:__ + +- *connected_users_vhost* :: [sessions::string] + +__Tags:__ +[session](admin-tags.md#session) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/connected_users_vhost +{ + "host": "myexample.com" +} + +HTTP/1.1 200 OK +[ + "user1@myserver.com/tka", + "user2@localhost/tka" +] +~~~ + + + + +## convert_to_scram + + +Convert the passwords of users to SCRAM + +__Arguments:__ + +- *host* :: string : Vhost which users' passwords will be scrammed + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[sql](admin-tags.md#sql) + +__Examples:__ + + +~~~ json +POST /api/convert_to_scram +{ + "host": "example.com" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## convert_to_yaml + + +Convert the input file from Erlang to YAML format + +__Arguments:__ + +- *in* :: string : Full path to the original configuration file +- *out* :: string : And full path to final file + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[config](admin-tags.md#config) + +__Examples:__ + + +~~~ json +POST /api/convert_to_yaml +{ + "in": "/etc/ejabberd/ejabberd.cfg", + "out": "/etc/ejabberd/ejabberd.yml" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## create_room + + +Create a MUC room name@service in host + +__Arguments:__ + +- *name* :: string : Room name +- *service* :: string : MUC service +- *host* :: string : Server host + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[muc_room](admin-tags.md#muc_room) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/create_room +{ + "name": "room1", + "service": "conference.example.com", + "host": "example.com" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## create_room_with_opts + + +Create a MUC room name@service in host with given options + + +The syntax of `affiliations` is: `Type:JID,Type:JID`. The syntax of `subscribers` is: `JID:Nick:Node:Node2:Node3,JID:Nick:Node`. + +__Arguments:__ + +- *name* :: string : Room name +- *service* :: string : MUC service +- *host* :: string : Server host +- *options* :: [{name::string, value::string}] : List of options + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[muc_room](admin-tags.md#muc_room), [muc_sub](admin-tags.md#muc_sub) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/create_room_with_opts +{ + "name": "room1", + "service": "conference.example.com", + "host": "localhost", + "options": [ + { + "name": "members_only", + "value": "true" + }, + { + "name": "affiliations", + "value": "owner:bob@example.com,member:peter@example.com" + }, + { + "name": "subscribers", + "value": "bob@example.com:Bob:messages:subject,anne@example.com:Anne:messages" + } + ] +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## create_rooms_file + + +Create the rooms indicated in file + + +Provide one room JID per line. Rooms will be created after restart. + +__Arguments:__ + +- *file* :: string : Path to the text file with one room JID per line + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[muc](admin-tags.md#muc) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/create_rooms_file +{ + "file": "/home/ejabberd/rooms.txt" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## delete_expired_messages + + +Delete expired offline messages from database + +__Arguments:__ + + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[purge](admin-tags.md#purge) + +__Examples:__ + + +~~~ json +POST /api/delete_expired_messages +{ + +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## delete_expired_pubsub_items + + + +Delete expired PubSub items + +__Arguments:__ + + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[purge](admin-tags.md#purge) + +__Module:__ +[mod_pubsub](modules.md#mod_pubsub) + +__Examples:__ + + +~~~ json +POST /api/delete_expired_pubsub_items +{ + +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## delete_mnesia + + +Delete elements in Mnesia database for a given vhost + +__Arguments:__ + +- *host* :: string : Vhost which content will be deleted in Mnesia database + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/delete_mnesia +{ + "host": "example.com" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## delete_old_mam_messages + + +Delete MAM messages older than DAYS + + +Valid message TYPEs: `chat`, `groupchat`, `all`. + +__Arguments:__ + +- *type* :: string : Type of messages to delete (`chat`, `groupchat`, `all`) +- *days* :: integer : Days to keep messages + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[purge](admin-tags.md#purge) + +__Module:__ +[mod_mam](modules.md#mod_mam) + +__Examples:__ + + +~~~ json +POST /api/delete_old_mam_messages +{ + "type": "all", + "days": 31 +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## delete_old_mam_messages_batch + + + +Delete MAM messages older than DAYS + + +Valid message TYPEs: `chat`, `groupchat`, `all`. + +__Arguments:__ + +- *host* :: string : Name of host where messages should be deleted +- *type* :: string : Type of messages to delete (`chat`, `groupchat`, `all`) +- *days* :: integer : Days to keep messages +- *batch_size* :: integer : Number of messages to delete per batch +- *rate* :: integer : Desired rate of messages to delete per minute + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[purge](admin-tags.md#purge) + +__Module:__ +[mod_mam](modules.md#mod_mam) + +__Examples:__ + + +~~~ json +POST /api/delete_old_mam_messages_batch +{ + "host": "localhost", + "type": "all", + "days": 31, + "batch_size": 1000, + "rate": 10000 +} + +HTTP/1.1 200 OK +"Removal of 5000 messages in progress" +~~~ + + + + +## delete_old_mam_messages_status + + + +Status of delete old MAM messages operation + +__Arguments:__ + +- *host* :: string : Name of host where messages should be deleted + +__Result:__ + +- *status* :: string : Status test + +__Tags:__ +[purge](admin-tags.md#purge) + +__Module:__ +[mod_mam](modules.md#mod_mam) + +__Examples:__ + + +~~~ json +POST /api/delete_old_mam_messages_status +{ + "host": "localhost" +} + +HTTP/1.1 200 OK +"Operation in progress, delete 5000 messages" +~~~ + + + + +## delete_old_messages + + +Delete offline messages older than DAYS + +__Arguments:__ + +- *days* :: integer : Number of days + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[purge](admin-tags.md#purge) + +__Examples:__ + + +~~~ json +POST /api/delete_old_messages +{ + "days": 31 +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## delete_old_messages_batch + + + +Delete offline messages older than DAYS + +__Arguments:__ + +- *host* :: string : Name of host where messages should be deleted +- *days* :: integer : Days to keep messages +- *batch_size* :: integer : Number of messages to delete per batch +- *rate* :: integer : Desired rate of messages to delete per minute + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[purge](admin-tags.md#purge) + +__Examples:__ + + +~~~ json +POST /api/delete_old_messages_batch +{ + "host": "localhost", + "days": 31, + "batch_size": 1000, + "rate": 10000 +} + +HTTP/1.1 200 OK +"Removal of 5000 messages in progress" +~~~ + + + + +## delete_old_messages_status + + + +Status of delete old offline messages operation + +__Arguments:__ + +- *host* :: string : Name of host where messages should be deleted + +__Result:__ + +- *status* :: string : Status test + +__Tags:__ +[purge](admin-tags.md#purge) + +__Examples:__ + + +~~~ json +POST /api/delete_old_messages_status +{ + "host": "localhost" +} + +HTTP/1.1 200 OK +"Operation in progress, delete 5000 messages" +~~~ + + + + +## delete_old_pubsub_items + + + +Keep only NUMBER of PubSub items per node + +__Arguments:__ + +- *number* :: integer : Number of items to keep per node + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[purge](admin-tags.md#purge) + +__Module:__ +[mod_pubsub](modules.md#mod_pubsub) + +__Examples:__ + + +~~~ json +POST /api/delete_old_pubsub_items +{ + "number": 1000 +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## delete_old_push_sessions + + +Remove push sessions older than DAYS + +__Arguments:__ + +- *days* :: integer + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[purge](admin-tags.md#purge) + +__Module:__ +[mod_push](modules.md#mod_push) + +__Examples:__ + + +~~~ json +POST /api/delete_old_push_sessions +{ + "days": 1 +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## delete_old_users + + +Delete users that didn't log in last days, or that never logged + + +To protect admin accounts, configure this for example: +``` yaml +access_rules: + protect_old_users: + - allow: admin + - deny: all +``` + + +__Arguments:__ + +- *days* :: integer : Last login age in days of accounts that should be removed + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[accounts](admin-tags.md#accounts), [purge](admin-tags.md#purge) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/delete_old_users +{ + "days": 30 +} + +HTTP/1.1 200 OK +"Deleted 2 users: ["oldman@myserver.com", "test@myserver.com"]" +~~~ + + + + +## delete_old_users_vhost + + +Delete users that didn't log in last days in vhost, or that never logged + + +To protect admin accounts, configure this for example: +``` yaml +access_rules: + delete_old_users: + - deny: admin + - allow: all +``` + + +__Arguments:__ + +- *host* :: string : Server name +- *days* :: integer : Last login age in days of accounts that should be removed + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[accounts](admin-tags.md#accounts), [purge](admin-tags.md#purge) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/delete_old_users_vhost +{ + "host": "myserver.com", + "days": 30 +} + +HTTP/1.1 200 OK +"Deleted 2 users: ["oldman@myserver.com", "test@myserver.com"]" +~~~ + + + + +## delete_rosteritem + + +Delete an item from a user's roster (supports ODBC) + +__Arguments:__ + +- *localuser* :: string : User name +- *localhost* :: string : Server name +- *user* :: string : Contact user name +- *host* :: string : Contact server name + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[roster](admin-tags.md#roster) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/delete_rosteritem +{ + "localuser": "user1", + "localhost": "myserver.com", + "user": "user2", + "host": "myserver.com" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## destroy_room + + +Destroy a MUC room + +__Arguments:__ + +- *name* :: string : Room name +- *service* :: string : MUC service + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[muc_room](admin-tags.md#muc_room) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/destroy_room +{ + "name": "room1", + "service": "conference.example.com" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## destroy_rooms_file + + +Destroy the rooms indicated in file + + +Provide one room JID per line. + +__Arguments:__ + +- *file* :: string : Path to the text file with one room JID per line + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[muc](admin-tags.md#muc) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/destroy_rooms_file +{ + "file": "/home/ejabberd/rooms.txt" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## dump + + +Dump the Mnesia database to a text file + +__Arguments:__ + +- *file* :: string : Full path for the text file + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/dump +{ + "file": "/var/lib/ejabberd/database.txt" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## dump_config + + +Dump configuration in YAML format as seen by ejabberd + +__Arguments:__ + +- *out* :: string : Full path to output file + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[config](admin-tags.md#config) + +__Examples:__ + + +~~~ json +POST /api/dump_config +{ + "out": "/tmp/ejabberd.yml" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## dump_table + + +Dump a Mnesia table to a text file + +__Arguments:__ + +- *file* :: string : Full path for the text file +- *table* :: string : Table name + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/dump_table +{ + "file": "/var/lib/ejabberd/table-muc-registered.txt", + "table": "muc_registered" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## export2sql + + +Export virtual host information from Mnesia tables to SQL file + + +Configure the modules to use SQL, then call this command. After correctly exported the database of a vhost, you may want to delete from mnesia with the [delete_mnesia](#delete_mnesia) API. + +__Arguments:__ + +- *host* :: string : Vhost +- *file* :: string : Full path to the destination SQL file + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/export2sql +{ + "host": "example.com", + "file": "/var/lib/ejabberd/example.com.sql" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## export_piefxis + + +Export data of all users in the server to PIEFXIS files (XEP-0227) + +__Arguments:__ + +- *dir* :: string : Full path to a directory + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/export_piefxis +{ + "dir": "/var/lib/ejabberd/" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## export_piefxis_host + + +Export data of users in a host to PIEFXIS files (XEP-0227) + +__Arguments:__ + +- *dir* :: string : Full path to a directory +- *host* :: string : Vhost to export + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/export_piefxis_host +{ + "dir": "/var/lib/ejabberd/", + "host": "example.com" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## gc + + + +Force full garbage collection + +__Arguments:__ + + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[server](admin-tags.md#server) + +__Examples:__ + + +~~~ json +POST /api/gc +{ + +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## gen_html_doc_for_commands + + +Generates html documentation for ejabberd_commands + +__Arguments:__ + +- *file* :: string : Path to file where generated documentation should be stored +- *regexp* :: string : Regexp matching names of commands or modules that will be included inside generated document +- *examples* :: string : Comma separated list of languages (chosen from `java`, `perl`, `xmlrpc`, `json`) that will have example invocation include in markdown document + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[documentation](admin-tags.md#documentation) + +__Examples:__ + + +~~~ json +POST /api/gen_html_doc_for_commands +{ + "file": "/home/me/docs/api.html", + "regexp": "mod_admin", + "examples": "java,json" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## gen_markdown_doc_for_commands + + +Generates markdown documentation for ejabberd_commands + +__Arguments:__ + +- *file* :: string : Path to file where generated documentation should be stored +- *regexp* :: string : Regexp matching names of commands or modules that will be included inside generated document, or `runtime` to get commands registered at runtime +- *examples* :: string : Comma separated list of languages (chosen from `java`, `perl`, `xmlrpc`, `json`) that will have example invocation include in markdown document + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[documentation](admin-tags.md#documentation) + +__Examples:__ + + +~~~ json +POST /api/gen_markdown_doc_for_commands +{ + "file": "/home/me/docs/api.html", + "regexp": "mod_admin", + "examples": "java,json" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## gen_markdown_doc_for_tags + + + +Generates markdown documentation for ejabberd_commands + +__Arguments:__ + +- *file* :: string : Path to file where generated documentation should be stored + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[documentation](admin-tags.md#documentation) + +__Examples:__ + + +~~~ json +POST /api/gen_markdown_doc_for_tags +{ + "file": "/home/me/docs/tags.md" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## get_ban_details + + + +Get ban details about an account + + +Check [ban_account](#ban_account) API. + +__Arguments:__ + +- *user* :: string : User name to unban +- *host* :: string : Server name + +__Result:__ + +- *ban_details* :: [{name::string, value::string}] + +__Tags:__ +[accounts](admin-tags.md#accounts), [v2](admin-tags.md#v2) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/get_ban_details +{ + "user": "attacker", + "host": "myserver.com" +} + +HTTP/1.1 200 OK +[ + { + "name": "reason", + "value": "Spamming other users" + }, + { + "name": "bandate", + "value": "2024-04-22T09:16:47.975312Z" + }, + { + "name": "lastdate", + "value": "2024-04-22T08:39:12Z" + }, + { + "name": "lastreason", + "value": "Connection reset by peer" + } +] +~~~ + + + + +## get_cookie + + +Get the Erlang cookie of this node + +__Arguments:__ + + +__Result:__ + +- *cookie* :: string : Erlang cookie used for authentication by ejabberd + +__Tags:__ +[erlang](admin-tags.md#erlang) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/get_cookie +{ + +} + +HTTP/1.1 200 OK +"MWTAVMODFELNLSMYXPPD" +~~~ + + + + +## get_last + + +Get last activity information + + +Timestamp is UTC and [XEP-0082](https://xmpp.org/extensions/xep-0082.html) format, for example: `2017-02-23T22:25:28.063062Z ONLINE` + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name + +__Result:__ + +- *last_activity* :: {timestamp::string, status::string} : Last activity timestamp and status + +__Tags:__ +[last](admin-tags.md#last) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/get_last +{ + "user": "user1", + "host": "myserver.com" +} + +HTTP/1.1 200 OK +{ + "timestamp": "2017-06-30T14:32:16.060684Z", + "status": "ONLINE" +} +~~~ + + + + +## get_loglevel + + +Get the current loglevel + +__Arguments:__ + + +__Result:__ + +- *levelatom* :: string : Tuple with the log level number, its keyword and description + +__Tags:__ +[logs](admin-tags.md#logs) + +__Examples:__ + + +~~~ json +POST /api/get_loglevel +{ + +} + +HTTP/1.1 200 OK +"warning" +~~~ + + + + +## get_master + + + +Get master node of the clustered Mnesia tables + + +If there is no master, returns `none`. + +__Arguments:__ + + +__Result:__ + +- *nodename* :: string + +__Tags:__ +[cluster](admin-tags.md#cluster) + +__Examples:__ + + +~~~ json +POST /api/get_master +{ + +} + +HTTP/1.1 200 OK +"aaaaa" +~~~ + + + + +## get_offline_count + + +Get the number of unread offline messages + +__Arguments:__ + +- *user* :: string +- *host* :: string + +__Result:__ + +- *value* :: integer : Number + +__Tags:__ +[offline](admin-tags.md#offline) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/get_offline_count +{ + "user": "aaaaa", + "host": "bbbbb" +} + +HTTP/1.1 200 OK +5 +~~~ + + + + +## get_presence + + +Retrieve the resource with highest priority, and its presence (show and status message) for a given user. + + +The `jid` value contains the user JID with resource. + +The `show` value contains the user presence flag. It can take limited values: + + - `available` + - `chat` (Free for chat) + - `away` + - `dnd` (Do not disturb) + - `xa` (Not available, extended away) + - `unavailable` (Not connected) + +`status` is a free text defined by the user client. + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name + +__Result:__ + +- *presence* :: {jid::string, show::string, status::string} + +__Tags:__ +[session](admin-tags.md#session) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/get_presence +{ + "user": "peter", + "host": "myexample.com" +} + +HTTP/1.1 200 OK +{ + "jid": "user1@myserver.com/tka", + "show": "dnd", + "status": "Busy" +} +~~~ + + + + +## get_room_affiliation + + +Get affiliation of a user in MUC room + +__Arguments:__ + +- *name* :: string : Room name +- *service* :: string : MUC service +- *jid* :: string : User JID + +__Result:__ + +- *affiliation* :: string : Affiliation of the user + +__Tags:__ +[muc_room](admin-tags.md#muc_room) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/get_room_affiliation +{ + "name": "room1", + "service": "conference.example.com", + "jid": "user1@example.com" +} + +HTTP/1.1 200 OK +"member" +~~~ + + + + +## get_room_affiliations + + +Get the list of affiliations of a MUC room + +__Arguments:__ + +- *name* :: string : Room name +- *service* :: string : MUC service + +__Result:__ + +- *affiliations* :: [{username::string, domain::string, affiliation::string, reason::string}] : The list of affiliations with username, domain, affiliation and reason + +__Tags:__ +[muc_room](admin-tags.md#muc_room) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/get_room_affiliations +{ + "name": "room1", + "service": "conference.example.com" +} + +HTTP/1.1 200 OK +[ + { + "username": "user1", + "domain": "example.com", + "affiliation": "member", + "reason": "member" + } +] +~~~ + + + + +## get_room_history + + + +Get history of messages stored inside MUC room state + +__Arguments:__ + +- *name* :: string : Room name +- *service* :: string : MUC service + +__Result:__ + +- *history* :: [{timestamp::string, message::string}] + +__Tags:__ +[muc_room](admin-tags.md#muc_room) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/get_room_history +{ + "name": "room1", + "service": "conference.example.com" +} + +HTTP/1.1 200 OK +[ + { + "timestamp": "aaaaa", + "message": "bbbbb" + }, + { + "timestamp": "ccccc", + "message": "ddddd" + } +] +~~~ + + + + +## get_room_occupants + + +Get the list of occupants of a MUC room + +__Arguments:__ + +- *name* :: string : Room name +- *service* :: string : MUC service + +__Result:__ + +- *occupants* :: [{jid::string, nick::string, role::string}] : The list of occupants with JID, nick and affiliation + +__Tags:__ +[muc_room](admin-tags.md#muc_room) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/get_room_occupants +{ + "name": "room1", + "service": "conference.example.com" +} + +HTTP/1.1 200 OK +[ + { + "jid": "user1@example.com/psi", + "nick": "User 1", + "role": "owner" + } +] +~~~ + + + + +## get_room_occupants_number + + +Get the number of occupants of a MUC room + +__Arguments:__ + +- *name* :: string : Room name +- *service* :: string : MUC service + +__Result:__ + +- *occupants* :: integer : Number of room occupants + +__Tags:__ +[muc_room](admin-tags.md#muc_room) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/get_room_occupants_number +{ + "name": "room1", + "service": "conference.example.com" +} + +HTTP/1.1 200 OK +7 +~~~ + + + + +## get_room_options + + +Get options from a MUC room + +__Arguments:__ + +- *name* :: string : Room name +- *service* :: string : MUC service + +__Result:__ + +- *options* :: [{name::string, value::string}] : List of room options tuples with name and value + +__Tags:__ +[muc_room](admin-tags.md#muc_room) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/get_room_options +{ + "name": "room1", + "service": "conference.example.com" +} + +HTTP/1.1 200 OK +[ + { + "name": "members_only", + "value": "true" + } +] +~~~ + + + + +## get_roster + + + +Get list of contacts in a local user roster + + +`subscription` can be: `none`, `from`, `to`, `both`. + +`pending` can be: `in`, `out`, `none`. + +__Arguments:__ + +- *user* :: string +- *host* :: string + +__Result:__ + +- *contacts* :: [{jid::string, nick::string, subscription::string, pending::string, groups::[group::string]}] + +__Tags:__ +[roster](admin-tags.md#roster) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/get_roster +{ + "user": "aaaaa", + "host": "bbbbb" +} + +HTTP/1.1 200 OK +[ + { + "jid": "aaaaa", + "nick": "bbbbb", + "subscription": "ccccc", + "pending": "ddddd", + "groups": [ + "eeeee", + "fffff" + ] + }, + { + "jid": "ggggg", + "nick": "hhhhh", + "subscription": "iiiii", + "pending": "jjjjj", + "groups": [ + "kkkkk", + "lllll" + ] + } +] +~~~ + + + + +## get_roster_count + + + +Get number of contacts in a local user roster + +__Arguments:__ + +- *user* :: string +- *host* :: string + +__Result:__ + +- *value* :: integer : Number + +__Tags:__ +[roster](admin-tags.md#roster) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/get_roster_count +{ + "user": "aaaaa", + "host": "bbbbb" +} + +HTTP/1.1 200 OK +5 +~~~ + + + + +## get_subscribers + + +List subscribers of a MUC conference + +__Arguments:__ + +- *name* :: string : Room name +- *service* :: string : MUC service + +__Result:__ + +- *subscribers* :: [jid::string] : The list of users that are subscribed to that room + +__Tags:__ +[muc_room](admin-tags.md#muc_room), [muc_sub](admin-tags.md#muc_sub) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/get_subscribers +{ + "name": "room1", + "service": "conference.example.com" +} + +HTTP/1.1 200 OK +[ + "user2@example.com", + "user3@example.com" +] +~~~ + + + + +## get_user_rooms + + +Get the list of rooms where this user is occupant + +__Arguments:__ + +- *user* :: string : Username +- *host* :: string : Server host + +__Result:__ + +- *rooms* :: [room::string] + +__Tags:__ +[muc](admin-tags.md#muc) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/get_user_rooms +{ + "user": "tom", + "host": "example.com" +} + +HTTP/1.1 200 OK +[ + "room1@conference.example.com", + "room2@conference.example.com" +] +~~~ + + + + +## get_user_subscriptions + + + +Get the list of rooms where this user is subscribed + +__Arguments:__ + +- *user* :: string : Username +- *host* :: string : Server host + +__Result:__ + +- *rooms* :: [{roomjid::string, usernick::string, nodes::[node::string]}] + +__Tags:__ +[muc](admin-tags.md#muc), [muc_sub](admin-tags.md#muc_sub) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/get_user_subscriptions +{ + "user": "tom", + "host": "example.com" +} + +HTTP/1.1 200 OK +[ + { + "roomjid": "room1@conference.example.com", + "usernick": "Tommy", + "nodes": [ + "mucsub:config" + ] + } +] +~~~ + + + + +## get_vcard + + +Get content from a vCard field + + +Some vcard field names in `get`/`set_vcard` are: + +* FN - Full Name +* NICKNAME - Nickname +* BDAY - Birthday +* TITLE - Work: Position +* ROLE - Work: Role + +For a full list of vCard fields check [XEP-0054: vcard-temp](https://xmpp.org/extensions/xep-0054.html) + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name +- *name* :: string : Field name + +__Result:__ + +- *content* :: string : Field content + +__Tags:__ +[vcard](admin-tags.md#vcard) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/get_vcard +{ + "user": "user1", + "host": "myserver.com", + "name": "NICKNAME" +} + +HTTP/1.1 200 OK +"User 1" +~~~ + + + + +## get_vcard2 + + +Get content from a vCard subfield + + +Some vcard field names and subnames in `get`/`set_vcard2` are: + +* N FAMILY - Family name +* N GIVEN - Given name +* N MIDDLE - Middle name +* ADR CTRY - Address: Country +* ADR LOCALITY - Address: City +* TEL HOME - Telephone: Home +* TEL CELL - Telephone: Cellphone +* TEL WORK - Telephone: Work +* TEL VOICE - Telephone: Voice +* EMAIL USERID - E-Mail Address +* ORG ORGNAME - Work: Company +* ORG ORGUNIT - Work: Department + +For a full list of vCard fields check [XEP-0054: vcard-temp](https://xmpp.org/extensions/xep-0054.html) + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name +- *name* :: string : Field name +- *subname* :: string : Subfield name + +__Result:__ + +- *content* :: string : Field content + +__Tags:__ +[vcard](admin-tags.md#vcard) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/get_vcard2 +{ + "user": "user1", + "host": "myserver.com", + "name": "N", + "subname": "FAMILY" +} + +HTTP/1.1 200 OK +"Schubert" +~~~ + + + + +## get_vcard2_multi + + +Get multiple contents from a vCard field + + +Some vcard field names and subnames in `get`/`set_vcard2` are: + +* N FAMILY - Family name +* N GIVEN - Given name +* N MIDDLE - Middle name +* ADR CTRY - Address: Country +* ADR LOCALITY - Address: City +* TEL HOME - Telephone: Home +* TEL CELL - Telephone: Cellphone +* TEL WORK - Telephone: Work +* TEL VOICE - Telephone: Voice +* EMAIL USERID - E-Mail Address +* ORG ORGNAME - Work: Company +* ORG ORGUNIT - Work: Department + +For a full list of vCard fields check [XEP-0054: vcard-temp](https://xmpp.org/extensions/xep-0054.html) + +__Arguments:__ + +- *user* :: string +- *host* :: string +- *name* :: string +- *subname* :: string + +__Result:__ + +- *contents* :: [value::string] + +__Tags:__ +[vcard](admin-tags.md#vcard) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/get_vcard2_multi +{ + "user": "aaaaa", + "host": "bbbbb", + "name": "ccccc", + "subname": "ddddd" +} + +HTTP/1.1 200 OK +[ + "aaaaa", + "bbbbb" +] +~~~ + + + + +## halt + + + +Halt ejabberd abruptly with status code 1 + +__Arguments:__ + + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[server](admin-tags.md#server) + +__Examples:__ + + +~~~ json +POST /api/halt +{ + +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## help + + +Get list of commands, or help of a command (only ejabberdctl) + + +This command is exclusive for the ejabberdctl command-line script, don't attempt to execute it using any other API frontend. + +__Arguments:__ + + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[ejabberdctl](admin-tags.md#ejabberdctl) + +__Examples:__ + + +~~~ json +POST /api/help +{ + +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## import_dir + + +Import users data from jabberd14 spool dir + +__Arguments:__ + +- *file* :: string : Full path to the jabberd14 spool directory + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/import_dir +{ + "file": "/var/lib/ejabberd/jabberd14/" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## import_file + + +Import user data from jabberd14 spool file + +__Arguments:__ + +- *file* :: string : Full path to the jabberd14 spool file + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/import_file +{ + "file": "/var/lib/ejabberd/jabberd14.spool" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## import_piefxis + + +Import users data from a PIEFXIS file (XEP-0227) + +__Arguments:__ + +- *file* :: string : Full path to the PIEFXIS file + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/import_piefxis +{ + "file": "/var/lib/ejabberd/example.com.xml" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## import_prosody + + +Import data from Prosody + + +Note: this requires ejabberd to be compiled with `./configure --enable-lua` (which installs the `luerl` library). + +__Arguments:__ + +- *dir* :: string : Full path to the Prosody data directory + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[mnesia](admin-tags.md#mnesia), [sql](admin-tags.md#sql) + +__Examples:__ + + +~~~ json +POST /api/import_prosody +{ + "dir": "/var/lib/prosody/datadump/" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## incoming_s2s_number + + +Number of incoming s2s connections on the node + +__Arguments:__ + + +__Result:__ + +- *s2s_incoming* :: integer + +__Tags:__ +[statistics](admin-tags.md#statistics), [s2s](admin-tags.md#s2s) + +__Examples:__ + + +~~~ json +POST /api/incoming_s2s_number +{ + +} + +HTTP/1.1 200 OK +1 +~~~ + + + + +## install_fallback + + +Install Mnesia database from a binary backup file + + +The binary backup file is installed as fallback: it will be used to restore the database at the next ejabberd start. This means that, after running this command, you have to restart ejabberd. This command requires less memory than [restore](#restore) API. + +__Arguments:__ + +- *file* :: string : Full path to the fallback file + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/install_fallback +{ + "file": "/var/lib/ejabberd/database.fallback" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## join_cluster + + + +Join our local node into the cluster handled by Node + +__Arguments:__ + +- *node* :: string : Nodename of the node to join + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[cluster](admin-tags.md#cluster) + +__Examples:__ + + +~~~ json +POST /api/join_cluster +{ + "node": "ejabberd1@machine7" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## join_cluster_here + + + +Join a remote Node here, into our cluster + +__Arguments:__ + +- *node* :: string : Nodename of the node to join here + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[cluster](admin-tags.md#cluster) + +__Examples:__ + + +~~~ json +POST /api/join_cluster_here +{ + "node": "ejabberd1@machine7" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## kick_session + + +Kick a user session + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name +- *resource* :: string : User's resource +- *reason* :: string : Reason for closing session + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[session](admin-tags.md#session) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/kick_session +{ + "user": "peter", + "host": "myserver.com", + "resource": "Psi", + "reason": "Stuck connection" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## kick_user + + + +Disconnect user's active sessions + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[session](admin-tags.md#session), [v2](admin-tags.md#v2) + +__Examples:__ + + +~~~ json +POST /api/kick_user +{ + "user": "user1", + "host": "example.com" +} + +HTTP/1.1 200 OK +"Kicked sessions: 2" +~~~ + + + + +## leave_cluster + + +Remove and shutdown Node from the running cluster + + +This command can be run from any running node of the cluster, even the node to be removed. In the removed node, this command works only when using ejabberdctl, not mod_http_api or other code that runs inside the same ejabberd node that will leave. + +__Arguments:__ + +- *node* :: string : Nodename of the node to kick from the cluster + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[cluster](admin-tags.md#cluster) + +__Examples:__ + + +~~~ json +POST /api/leave_cluster +{ + "node": "ejabberd1@machine8" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## list_certificates + + +Lists all ACME certificates + +__Arguments:__ + + +__Result:__ + +- *certificates* :: [{domain::string, file::string, used::string}] + +__Tags:__ +[acme](admin-tags.md#acme) + +__Examples:__ + + +~~~ json +POST /api/list_certificates +{ + +} + +HTTP/1.1 200 OK +[ + { + "domain": "aaaaa", + "file": "bbbbb", + "used": "ccccc" + }, + { + "domain": "ddddd", + "file": "eeeee", + "used": "fffff" + } +] +~~~ + + + + +## list_cluster + + +List running nodes that are part of this cluster + +__Arguments:__ + + +__Result:__ + +- *nodes* :: [node::string] + +__Tags:__ +[cluster](admin-tags.md#cluster) + +__Examples:__ + + +~~~ json +POST /api/list_cluster +{ + +} + +HTTP/1.1 200 OK +[ + "ejabberd1@machine7", + "ejabberd1@machine8" +] +~~~ + + + + +## list_cluster_detailed + + + +List nodes (both running and known) and some stats + +__Arguments:__ + + +__Result:__ + +- *nodes* :: [{name::string, running::string, status::string, online_users::integer, processes::integer, uptime_seconds::integer, master_node::string}] + +__Tags:__ +[cluster](admin-tags.md#cluster) + +__Examples:__ + + +~~~ json +POST /api/list_cluster_detailed +{ + +} + +HTTP/1.1 200 OK +[ + { + "name": "ejabberd@localhost", + "running": "true", + "status": "The node ejabberd is started. Status...", + "online_users": 7, + "processes": 348, + "uptime_seconds": 60, + "master_node": "none" + } +] +~~~ + + + + +## load + + +Restore Mnesia database from a text dump file + + +Restore immediately. This is not recommended for big databases, as it will consume much time, memory and processor. In that case it's preferable to use [backup](#backup) API and [install_fallback](#install_fallback) API. + +__Arguments:__ + +- *file* :: string : Full path to the text file + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/load +{ + "file": "/var/lib/ejabberd/database.txt" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## man + + + +Generate Unix manpage for current ejabberd version + +__Arguments:__ + + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[documentation](admin-tags.md#documentation) + +__Examples:__ + + +~~~ json +POST /api/man +{ + +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## mnesia_change_nodename + + +Change the erlang node name in a backup file + +__Arguments:__ + +- *oldnodename* :: string : Name of the old erlang node +- *newnodename* :: string : Name of the new node +- *oldbackup* :: string : Path to old backup file +- *newbackup* :: string : Path to the new backup file + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/mnesia_change_nodename +{ + "oldnodename": "ejabberd@machine1", + "newnodename": "ejabberd@machine2", + "oldbackup": "/var/lib/ejabberd/old.backup", + "newbackup": "/var/lib/ejabberd/new.backup" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## mnesia_info + + +Dump info on global Mnesia state + +__Arguments:__ + + +__Result:__ + +- *res* :: string + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/mnesia_info +{ + +} + +HTTP/1.1 200 OK +"aaaaa" +~~~ + + + + +## mnesia_info_ctl 🟤 + + + +Show information of Mnesia system (only ejabberdctl) + + +This command is exclusive for the ejabberdctl command-line script, don't attempt to execute it using any other API frontend. + +__Arguments:__ + + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[ejabberdctl](admin-tags.md#ejabberdctl), [mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/mnesia_info_ctl +{ + +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## mnesia_table_info + + +Dump info on Mnesia table state + +__Arguments:__ + +- *table* :: string : Mnesia table name + +__Result:__ + +- *res* :: string + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/mnesia_table_info +{ + "table": "roster" +} + +HTTP/1.1 200 OK +"aaaaa" +~~~ + + + + +## module_check + + +Check the contributed module repository compliance + +__Arguments:__ + +- *module* :: string : Module name + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[modules](admin-tags.md#modules) + +__Examples:__ + + +~~~ json +POST /api/module_check +{ + "module": "mod_rest" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## module_install + + +Compile, install and start an available contributed module + +__Arguments:__ + +- *module* :: string : Module name + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[modules](admin-tags.md#modules) + +__Examples:__ + + +~~~ json +POST /api/module_install +{ + "module": "mod_rest" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## module_uninstall + + +Uninstall a contributed module + +__Arguments:__ + +- *module* :: string : Module name + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[modules](admin-tags.md#modules) + +__Examples:__ + + +~~~ json +POST /api/module_uninstall +{ + "module": "mod_rest" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## module_upgrade + + +Upgrade the running code of an installed module + + +In practice, this uninstalls and installs the module + +__Arguments:__ + +- *module* :: string : Module name + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[modules](admin-tags.md#modules) + +__Examples:__ + + +~~~ json +POST /api/module_upgrade +{ + "module": "mod_rest" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## modules_available + + +List the contributed modules available to install + +__Arguments:__ + + +__Result:__ + +- *modules* :: [{name::string, summary::string}] : List of tuples with module name and description + +__Tags:__ +[modules](admin-tags.md#modules) + +__Examples:__ + + +~~~ json +POST /api/modules_available +{ + +} + +HTTP/1.1 200 OK +{ + "mod_cron": "Execute scheduled commands", + "mod_rest": "ReST frontend" +} +~~~ + + + + +## modules_installed + + +List the contributed modules already installed + +__Arguments:__ + + +__Result:__ + +- *modules* :: [{name::string, summary::string}] : List of tuples with module name and description + +__Tags:__ +[modules](admin-tags.md#modules) + +__Examples:__ + + +~~~ json +POST /api/modules_installed +{ + +} + +HTTP/1.1 200 OK +{ + "mod_cron": "Execute scheduled commands", + "mod_rest": "ReST frontend" +} +~~~ + + + + +## modules_update_specs + + +Update the module source code from Git + + +A connection to Internet is required + +__Arguments:__ + + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[modules](admin-tags.md#modules) + +__Examples:__ + + +~~~ json +POST /api/modules_update_specs +{ + +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## muc_online_rooms + + +List existing rooms + + +Ask for a specific host, or `global` to use all vhosts. + +__Arguments:__ + +- *service* :: string : MUC service, or `global` for all + +__Result:__ + +- *rooms* :: [room::string] : List of rooms + +__Tags:__ +[muc](admin-tags.md#muc) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/muc_online_rooms +{ + "service": "conference.example.com" +} + +HTTP/1.1 200 OK +[ + "room1@conference.example.com", + "room2@conference.example.com" +] +~~~ + + + + +## muc_online_rooms_by_regex + + +List existing rooms filtered by regexp + + +Ask for a specific host, or `global` to use all vhosts. + +__Arguments:__ + +- *service* :: string : MUC service, or `global` for all +- *regex* :: string : Regex pattern for room name + +__Result:__ + +- *rooms* :: [{jid::string, public::string, participants::integer}] : List of rooms with summary + +__Tags:__ +[muc](admin-tags.md#muc) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/muc_online_rooms_by_regex +{ + "service": "conference.example.com", + "regex": "^prefix" +} + +HTTP/1.1 200 OK +[ + { + "jid": "room1@conference.example.com", + "public": "true", + "participants": 10 + }, + { + "jid": "room2@conference.example.com", + "public": "false", + "participants": 10 + } +] +~~~ + + + + +## muc_register_nick + + +Register a nick to a User JID in a MUC service + +__Arguments:__ + +- *nick* :: string : Nick +- *jid* :: string : User JID +- *service* :: string : Service + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[muc](admin-tags.md#muc) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/muc_register_nick +{ + "nick": "Tim", + "jid": "tim@example.org", + "service": "conference.example.org" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## muc_unregister_nick + + +Unregister the nick registered by that account in the MUC service + +__Arguments:__ + +- *jid* :: string : User JID +- *service* :: string : MUC service + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[muc](admin-tags.md#muc) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/muc_unregister_nick +{ + "jid": "tim@example.org", + "service": "conference.example.org" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## num_resources + + +Get the number of resources of a user + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name + +__Result:__ + +- *resources* :: integer : Number of active resources for a user + +__Tags:__ +[session](admin-tags.md#session) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/num_resources +{ + "user": "peter", + "host": "myserver.com" +} + +HTTP/1.1 200 OK +5 +~~~ + + + + +## oauth_add_client_implicit + + +Add [OAuth](../../developer/ejabberd-api/oauth.md) client_id with implicit grant type + +__Arguments:__ + +- *client_id* :: string +- *client_name* :: string +- *redirect_uri* :: string + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[oauth](admin-tags.md#oauth) + +__Examples:__ + + +~~~ json +POST /api/oauth_add_client_implicit +{ + "client_id": "aaaaa", + "client_name": "bbbbb", + "redirect_uri": "ccccc" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## oauth_add_client_password + + +Add [OAuth](../../developer/ejabberd-api/oauth.md) client_id with password grant type + +__Arguments:__ + +- *client_id* :: string +- *client_name* :: string +- *secret* :: string + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[oauth](admin-tags.md#oauth) + +__Examples:__ + + +~~~ json +POST /api/oauth_add_client_password +{ + "client_id": "aaaaa", + "client_name": "bbbbb", + "secret": "ccccc" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## oauth_issue_token 🟤 + + + +Issue an [OAuth](../../developer/ejabberd-api/oauth.md) optionredir token for the given jid + +__Arguments:__ + +- *jid* :: string : Jid for which issue token +- *ttl* :: integer : Time to live of generated token in seconds +- *scopes* :: [scope::string] : List of scopes to allow + +__Result:__ + +- *result* :: {token::string, scopes::[scope::string], expires_in::string} + +__Tags:__ +[oauth](admin-tags.md#oauth), [v1](admin-tags.md#v1) + +__Examples:__ + + +~~~ json +POST /api/oauth_issue_token +{ + "jid": "user@server.com", + "ttl": 3600, + "scopes": [ + "connected_users_number", + "muc_online_rooms" + ] +} + +HTTP/1.1 200 OK +{ + "token": "aaaaa", + "scopes": [ + "bbbbb", + "ccccc" + ], + "expires_in": "ddddd" +} +~~~ + + + + +## oauth_list_tokens + + +List [OAuth](../../developer/ejabberd-api/oauth.md) tokens, user, scope, and seconds to expire (only Mnesia) + + +List OAuth tokens, their user and scope, and how many seconds remain until expirity + +__Arguments:__ + + +__Result:__ + +- *tokens* :: [{token::string, user::string, scope::string, expires_in::string}] + +__Tags:__ +[oauth](admin-tags.md#oauth) + +__Examples:__ + + +~~~ json +POST /api/oauth_list_tokens +{ + +} + +HTTP/1.1 200 OK +[ + { + "token": "aaaaa", + "user": "bbbbb", + "scope": "ccccc", + "expires_in": "ddddd" + }, + { + "token": "eeeee", + "user": "fffff", + "scope": "ggggg", + "expires_in": "hhhhh" + } +] +~~~ + + + + +## oauth_remove_client + + +Remove [OAuth](../../developer/ejabberd-api/oauth.md) client_id + +__Arguments:__ + +- *client_id* :: string + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[oauth](admin-tags.md#oauth) + +__Examples:__ + + +~~~ json +POST /api/oauth_remove_client +{ + "client_id": "aaaaa" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## oauth_revoke_token + + + +Revoke authorization for an [OAuth](../../developer/ejabberd-api/oauth.md) token + +__Arguments:__ + +- *token* :: string + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[oauth](admin-tags.md#oauth) + +__Examples:__ + + +~~~ json +POST /api/oauth_revoke_token +{ + "token": "aaaaa" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## outgoing_s2s_number + + +Number of outgoing s2s connections on the node + +__Arguments:__ + + +__Result:__ + +- *s2s_outgoing* :: integer + +__Tags:__ +[statistics](admin-tags.md#statistics), [s2s](admin-tags.md#s2s) + +__Examples:__ + + +~~~ json +POST /api/outgoing_s2s_number +{ + +} + +HTTP/1.1 200 OK +1 +~~~ + + + + +## print_sql_schema 🟤 + + + +Print SQL schema for the given RDBMS (only ejabberdctl) + + +This command is exclusive for the ejabberdctl command-line script, don't attempt to execute it using any other API frontend. + +__Arguments:__ + +- *db_type* :: string : Database type: pgsql | mysql | sqlite +- *db_version* :: string : Your database version: 16.1, 8.2.0... +- *new_schema* :: string : Use new schema: 0, false, 1 or true + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[ejabberdctl](admin-tags.md#ejabberdctl), [sql](admin-tags.md#sql) + +__Examples:__ + + +~~~ json +POST /api/print_sql_schema +{ + "db_type": "pgsql", + "db_version": "16.1", + "new_schema": "true" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## privacy_set + + +Send a IQ set privacy stanza for a local account + +__Arguments:__ + +- *user* :: string : Username +- *host* :: string : Server name +- *xmlquery* :: string : Query XML element + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[stanza](admin-tags.md#stanza) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/privacy_set +{ + "user": "user1", + "host": "myserver.com", + "xmlquery": "..." +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## private_get + + +Get some information from a user private storage + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name +- *element* :: string : Element name +- *ns* :: string : Namespace + +__Result:__ + +- *res* :: string + +__Tags:__ +[private](admin-tags.md#private) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/private_get +{ + "user": "user1", + "host": "myserver.com", + "element": "storage", + "ns": "storage:rosternotes" +} + +HTTP/1.1 200 OK +"aaaaa" +~~~ + + + + +## private_set + + +Set to the user private storage + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name +- *element* :: string : XML storage element + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[private](admin-tags.md#private) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/private_set +{ + "user": "user1", + "host": "myserver.com", + "element": "" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## process_rosteritems + + +List/delete rosteritems that match filter + + +Explanation of each argument: + +* `action`: what to do with each rosteritem that matches all the filtering options +* `subs`: subscription type +* `asks`: pending subscription +* `users`: the JIDs of the local user +* `contacts`: the JIDs of the contact in the roster + +**Mnesia backend:** + +Allowed values in the arguments: + +* `action` = `list` | `delete` +* `subs` = `any` | SUB[:SUB]* +* `asks` = `any` | ASK[:ASK]* +* `users` = `any` | JID[:JID]* +* `contacts` = `any` | JID[:JID]* + +where + +* SUB = `none` | `from `| `to` | `both` +* ASK = `none` | `out` | `in` +* JID = characters valid in a JID, and can use the globs: `*`, `?`, `!` and `[...]` + +This example will list roster items with subscription `none`, `from` or `to` that have any ask property, of local users which JID is in the virtual host `example.org` and that the contact JID is either a bare server name (without user part) or that has a user part and the server part contains the word `icq`: + `list none:from:to any *@example.org *:*@*icq*` + +**SQL backend:** + +Allowed values in the arguments: + +* `action` = `list` | `delete` +* `subs` = `any` | SUB +* `asks` = `any` | ASK +* `users` = JID +* `contacts` = JID + +where + +* SUB = `none` | `from` | `to` | `both` +* ASK = `none` | `out` | `in` +* JID = characters valid in a JID, and can use the globs: `_` and `%` + +This example will list roster items with subscription `to` that have any ask property, of local users which JID is in the virtual host `example.org` and that the contact JID's server part contains the word `icq`: + `list to any %@example.org %@%icq%` + +__Arguments:__ + +- *action* :: string +- *subs* :: string +- *asks* :: string +- *users* :: string +- *contacts* :: string + +__Result:__ + +- *response* :: [{user::string, contact::string}] + +__Tags:__ +[roster](admin-tags.md#roster) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/process_rosteritems +{ + "action": "aaaaa", + "subs": "bbbbb", + "asks": "ccccc", + "users": "ddddd", + "contacts": "eeeee" +} + +HTTP/1.1 200 OK +[ + { + "user": "aaaaa", + "contact": "bbbbb" + }, + { + "user": "ccccc", + "contact": "ddddd" + } +] +~~~ + + + + +## push_alltoall + + +Add all the users to all the users of Host in Group + +__Arguments:__ + +- *host* :: string : Server name +- *group* :: string : Group name + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[roster](admin-tags.md#roster) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/push_alltoall +{ + "host": "myserver.com", + "group": "Everybody" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## push_roster + + +Push template roster from file to a user + + +The text file must contain an erlang term: a list of tuples with username, servername, group and nick. For example: +`[{"user1", "localhost", "Workers", "User 1"}, + {"user2", "localhost", "Workers", "User 2"}].` + +If there are problems parsing UTF8 character encoding, provide the corresponding string with the `<<"STRING"/utf8>>` syntax, for example: +`[{"user2", "localhost", "Workers", <<"User 2"/utf8>>}]`. + +__Arguments:__ + +- *file* :: string : File path +- *user* :: string : User name +- *host* :: string : Server name + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[roster](admin-tags.md#roster) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/push_roster +{ + "file": "/home/ejabberd/roster.txt", + "user": "user1", + "host": "localhost" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## push_roster_all + + +Push template roster from file to all those users + + +The text file must contain an erlang term: a list of tuples with username, servername, group and nick. Example: +`[{"user1", "localhost", "Workers", "User 1"}, + {"user2", "localhost", "Workers", "User 2"}].` + +__Arguments:__ + +- *file* :: string : File path + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[roster](admin-tags.md#roster) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/push_roster_all +{ + "file": "/home/ejabberd/roster.txt" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## register + + +Register a user + +__Arguments:__ + +- *user* :: string : Username +- *host* :: string : Local vhost served by ejabberd +- *password* :: string : Password + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[accounts](admin-tags.md#accounts) + +__Examples:__ + + +~~~ json +POST /api/register +{ + "user": "bob", + "host": "example.com", + "password": "SomEPass44" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## registered_users + + +List all registered users in HOST + +__Arguments:__ + +- *host* :: string : Local vhost + +__Result:__ + +- *users* :: [username::string] : List of registered accounts usernames + +__Tags:__ +[accounts](admin-tags.md#accounts) + +__Examples:__ + + +~~~ json +POST /api/registered_users +{ + "host": "example.com" +} + +HTTP/1.1 200 OK +[ + "user1", + "user2" +] +~~~ + + + + +## registered_vhosts + + +List all registered vhosts in SERVER + +__Arguments:__ + + +__Result:__ + +- *vhosts* :: [vhost::string] : List of available vhosts + +__Tags:__ +[server](admin-tags.md#server) + +__Examples:__ + + +~~~ json +POST /api/registered_vhosts +{ + +} + +HTTP/1.1 200 OK +[ + "example.com", + "anon.example.com" +] +~~~ + + + + +## reload_config + + +Reload config file in memory + +__Arguments:__ + + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[config](admin-tags.md#config) + +__Examples:__ + + +~~~ json +POST /api/reload_config +{ + +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## remove_mam_for_user + + +Remove mam archive for user + +__Arguments:__ + +- *user* :: string : Username +- *host* :: string : Server + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[mam](admin-tags.md#mam) + +__Module:__ +[mod_mam](modules.md#mod_mam) + +__Examples:__ + + +~~~ json +POST /api/remove_mam_for_user +{ + "user": "bob", + "host": "example.com" +} + +HTTP/1.1 200 OK +"MAM archive removed" +~~~ + + + + +## remove_mam_for_user_with_peer + + +Remove mam archive for user with peer + +__Arguments:__ + +- *user* :: string : Username +- *host* :: string : Server +- *with* :: string : Peer + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[mam](admin-tags.md#mam) + +__Module:__ +[mod_mam](modules.md#mod_mam) + +__Examples:__ + + +~~~ json +POST /api/remove_mam_for_user_with_peer +{ + "user": "bob", + "host": "example.com", + "with": "anne@example.com" +} + +HTTP/1.1 200 OK +"MAM archive removed" +~~~ + + + + +## reopen_log + + +Reopen maybe the log files after being renamed + + +Has no effect on ejabberd main log files, only on log files generated by some modules. +This can be useful when an external tool is used for log rotation. See [Log Files](../../admin/guide/troubleshooting.md#log-files). + +__Arguments:__ + + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[logs](admin-tags.md#logs) + +__Examples:__ + + +~~~ json +POST /api/reopen_log +{ + +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## request_certificate + + +Requests certificates for all or some domains + + +Domains can be `all`, or a list of domains separared with comma characters + +__Arguments:__ + +- *domains* :: string : Domains for which to acquire a certificate + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[acme](admin-tags.md#acme) + +__Examples:__ + + +~~~ json +POST /api/request_certificate +{ + "domains": "example.com,domain.tld,conference.domain.tld" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## resource_num + + +Resource string of a session number + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name +- *num* :: integer : ID of resource to return + +__Result:__ + +- *resource* :: string : Name of user resource + +__Tags:__ +[session](admin-tags.md#session) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/resource_num +{ + "user": "peter", + "host": "myserver.com", + "num": 2 +} + +HTTP/1.1 200 OK +"Psi" +~~~ + + + + +## restart + + +Restart ejabberd gracefully + +__Arguments:__ + + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[server](admin-tags.md#server) + +__Examples:__ + + +~~~ json +POST /api/restart +{ + +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## restart_module + + +Stop an ejabberd module, reload code and start + +__Arguments:__ + +- *host* :: string : Server name +- *module* :: string : Module to restart + +__Result:__ + +- *res* :: integer : Returns integer code: + - `0`: code reloaded, module restarted + - `1`: error: module not loaded + - `2`: code not reloaded, but module restarted + +__Tags:__ +[erlang](admin-tags.md#erlang) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/restart_module +{ + "host": "myserver.com", + "module": "mod_admin_extra" +} + +HTTP/1.1 200 OK +0 +~~~ + + + + +## restore + + +Restore the Mnesia database from a binary backup file + + +This restores immediately from a binary backup file the internal Mnesia database. This will consume a lot of memory if you have a large database, you may prefer [install_fallback](#install_fallback) API. + +__Arguments:__ + +- *file* :: string : Full path to the backup file + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[mnesia](admin-tags.md#mnesia) + +__Examples:__ + + +~~~ json +POST /api/restore +{ + "file": "/var/lib/ejabberd/database.backup" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## revoke_certificate + + +Revokes the selected ACME certificate + +__Arguments:__ + +- *file* :: string : Filename of the certificate + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[acme](admin-tags.md#acme) + +__Examples:__ + + +~~~ json +POST /api/revoke_certificate +{ + "file": "aaaaa" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## rooms_empty_destroy + + + +Destroy the rooms that have no messages in archive + + +The MUC service argument can be `global` to get all hosts. + +__Arguments:__ + +- *service* :: string : MUC service, or `global` for all + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[muc](admin-tags.md#muc), [v2](admin-tags.md#v2) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/rooms_empty_destroy +{ + "service": "conference.example.com" +} + +HTTP/1.1 200 OK +"Destroyed rooms: 2" +~~~ + + + + +## rooms_empty_list + + +List the rooms that have no messages in archive + + +The MUC service argument can be `global` to get all hosts. + +__Arguments:__ + +- *service* :: string : MUC service, or `global` for all + +__Result:__ + +- *rooms* :: [room::string] : List of empty rooms + +__Tags:__ +[muc](admin-tags.md#muc) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/rooms_empty_list +{ + "service": "conference.example.com" +} + +HTTP/1.1 200 OK +[ + "room1@conference.example.com", + "room2@conference.example.com" +] +~~~ + + + + +## rooms_unused_destroy + + +Destroy the rooms that are unused for many days in the service + + +The room recent history is used, so it's recommended to wait a few days after service start before running this. The MUC service argument can be `global` to get all hosts. + +__Arguments:__ + +- *service* :: string : MUC service, or `global` for all +- *days* :: integer : Number of days + +__Result:__ + +- *rooms* :: [room::string] : List of unused rooms that has been destroyed + +__Tags:__ +[muc](admin-tags.md#muc) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/rooms_unused_destroy +{ + "service": "conference.example.com", + "days": 31 +} + +HTTP/1.1 200 OK +[ + "room1@conference.example.com", + "room2@conference.example.com" +] +~~~ + + + + +## rooms_unused_list + + +List the rooms that are unused for many days in the service + + +The room recent history is used, so it's recommended to wait a few days after service start before running this. The MUC service argument can be `global` to get all hosts. + +__Arguments:__ + +- *service* :: string : MUC service, or `global` for all +- *days* :: integer : Number of days + +__Result:__ + +- *rooms* :: [room::string] : List of unused rooms + +__Tags:__ +[muc](admin-tags.md#muc) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/rooms_unused_list +{ + "service": "conference.example.com", + "days": 31 +} + +HTTP/1.1 200 OK +[ + "room1@conference.example.com", + "room2@conference.example.com" +] +~~~ + + + + +## rotate_log + + +Rotate maybe log file of some module + + +Has no effect on ejabberd main log files, only on log files generated by some modules. + +__Arguments:__ + + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[logs](admin-tags.md#logs) + +__Examples:__ + + +~~~ json +POST /api/rotate_log +{ + +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## send_direct_invitation 🟤 + + + +Send a direct invitation to several destinations + + +Since ejabberd [20.12](../../archive/20.12/index.md), this command is asynchronous: the API call may return before the server has send all the invitations. + +`password` and `message` can be set to `none`. + +__Arguments:__ + +- *name* :: string : Room name +- *service* :: string : MUC service +- *password* :: string : Password, or `none` +- *reason* :: string : Reason text, or `none` +- *users* :: [jid::string] : List of users JIDs + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[muc_room](admin-tags.md#muc_room), [v1](admin-tags.md#v1) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/send_direct_invitation +{ + "name": "room1", + "service": "conference.example.com", + "password": "", + "reason": "Check this out!", + "users": [ + "user2@localhost", + "user3@example.com" + ] +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## send_message + + +Send a message to a local or remote bare of full JID + + +When sending a groupchat message to a MUC room, `from` must be the full JID of a room occupant, or the bare JID of a MUC service admin, or the bare JID of a MUC/Sub subscribed user. + +__Arguments:__ + +- *type* :: string : Message type: `normal`, `chat`, `headline`, `groupchat` +- *from* :: string : Sender JID +- *to* :: string : Receiver JID +- *subject* :: string : Subject, or empty string +- *body* :: string : Body + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[stanza](admin-tags.md#stanza) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/send_message +{ + "type": "headline", + "from": "admin@localhost", + "to": "user1@localhost", + "subject": "Restart", + "body": "In 5 minutes" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## send_stanza + + +Send a stanza; provide From JID and valid To JID + +__Arguments:__ + +- *from* :: string : Sender JID +- *to* :: string : Destination JID +- *stanza* :: string : Stanza + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[stanza](admin-tags.md#stanza) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/send_stanza +{ + "from": "admin@localhost", + "to": "user1@localhost", + "stanza": "" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## send_stanza_c2s + + +Send a stanza from an existing C2S session + + +`user`@`host`/`resource` must be an existing C2S session. As an alternative, use [send_stanza](#send_stanza) API instead. + +__Arguments:__ + +- *user* :: string : Username +- *host* :: string : Server name +- *resource* :: string : Resource +- *stanza* :: string : Stanza + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[stanza](admin-tags.md#stanza) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/send_stanza_c2s +{ + "user": "admin", + "host": "myserver.com", + "resource": "bot", + "stanza": "" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## set_last + + +Set last activity information + + +Timestamp is the seconds since `1970-01-01 00:00:00 UTC`. For example value see `date +%s` + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name +- *timestamp* :: integer : Number of seconds since epoch +- *status* :: string : Status message + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[last](admin-tags.md#last) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/set_last +{ + "user": "user1", + "host": "myserver.com", + "timestamp": 1500045311, + "status": "GoSleeping" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## set_loglevel + + +Set the loglevel + + +Possible loglevels: `none`, `emergency`, `alert`, `critical`, + `error`, `warning`, `notice`, `info`, `debug`. + +__Arguments:__ + +- *loglevel* :: string : Desired logging level + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[logs](admin-tags.md#logs) + +__Examples:__ + + +~~~ json +POST /api/set_loglevel +{ + "loglevel": "debug" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## set_master + + +Set master node of the clustered Mnesia tables + + +If `nodename` is set to `self`, then this node will be set as its own master. + +__Arguments:__ + +- *nodename* :: string : Name of the erlang node that will be considered master of this node + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[cluster](admin-tags.md#cluster) + +__Examples:__ + + +~~~ json +POST /api/set_master +{ + "nodename": "ejabberd@machine7" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## set_nickname + + +Set nickname in a user's vCard + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name +- *nickname* :: string : Nickname + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[vcard](admin-tags.md#vcard) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/set_nickname +{ + "user": "user1", + "host": "myserver.com", + "nickname": "User 1" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## set_presence 🟤 + + + +Set presence of a session + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name +- *resource* :: string : Resource +- *type* :: string : Type: `available`, `error`, `probe`... +- *show* :: string : Show: `away`, `chat`, `dnd`, `xa`. +- *status* :: string : Status text +- *priority* :: integer : Priority, provide this value as an integer + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[session](admin-tags.md#session), [v1](admin-tags.md#v1) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/set_presence +{ + "user": "user1", + "host": "myserver.com", + "resource": "tka1", + "type": "available", + "show": "away", + "status": "BB", + "priority": 7 +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## set_room_affiliation + + +Change an affiliation in a MUC room + +__Arguments:__ + +- *name* :: string : Room name +- *service* :: string : MUC service +- *jid* :: string : User JID +- *affiliation* :: string : Affiliation to set + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[muc_room](admin-tags.md#muc_room) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/set_room_affiliation +{ + "name": "room1", + "service": "conference.example.com", + "jid": "user2@example.com", + "affiliation": "member" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## set_vcard + + +Set content in a vCard field + + +Some vcard field names in `get`/`set_vcard` are: + +* FN - Full Name +* NICKNAME - Nickname +* BDAY - Birthday +* TITLE - Work: Position +* ROLE - Work: Role + +For a full list of vCard fields check [XEP-0054: vcard-temp](https://xmpp.org/extensions/xep-0054.html) + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name +- *name* :: string : Field name +- *content* :: string : Value + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[vcard](admin-tags.md#vcard) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/set_vcard +{ + "user": "user1", + "host": "myserver.com", + "name": "URL", + "content": "www.example.com" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## set_vcard2 + + +Set content in a vCard subfield + + +Some vcard field names and subnames in `get`/`set_vcard2` are: + +* N FAMILY - Family name +* N GIVEN - Given name +* N MIDDLE - Middle name +* ADR CTRY - Address: Country +* ADR LOCALITY - Address: City +* TEL HOME - Telephone: Home +* TEL CELL - Telephone: Cellphone +* TEL WORK - Telephone: Work +* TEL VOICE - Telephone: Voice +* EMAIL USERID - E-Mail Address +* ORG ORGNAME - Work: Company +* ORG ORGUNIT - Work: Department + +For a full list of vCard fields check [XEP-0054: vcard-temp](https://xmpp.org/extensions/xep-0054.html) + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name +- *name* :: string : Field name +- *subname* :: string : Subfield name +- *content* :: string : Value + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[vcard](admin-tags.md#vcard) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/set_vcard2 +{ + "user": "user1", + "host": "myserver.com", + "name": "TEL", + "subname": "NUMBER", + "content": "123456" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## set_vcard2_multi + + +Set multiple contents in a vCard subfield + + +Some vcard field names and subnames in `get`/`set_vcard2` are: + +* N FAMILY - Family name +* N GIVEN - Given name +* N MIDDLE - Middle name +* ADR CTRY - Address: Country +* ADR LOCALITY - Address: City +* TEL HOME - Telephone: Home +* TEL CELL - Telephone: Cellphone +* TEL WORK - Telephone: Work +* TEL VOICE - Telephone: Voice +* EMAIL USERID - E-Mail Address +* ORG ORGNAME - Work: Company +* ORG ORGUNIT - Work: Department + +For a full list of vCard fields check [XEP-0054: vcard-temp](https://xmpp.org/extensions/xep-0054.html) + +__Arguments:__ + +- *user* :: string +- *host* :: string +- *name* :: string +- *subname* :: string +- *contents* :: [value::string] + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[vcard](admin-tags.md#vcard) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/set_vcard2_multi +{ + "user": "aaaaa", + "host": "bbbbb", + "name": "ccccc", + "subname": "ddddd", + "contents": [ + "eeeee", + "fffff" + ] +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## srg_add + + + +Add/Create a Shared Roster Group (without details) + +__Arguments:__ + +- *group* :: string : Group identifier +- *host* :: string : Group server name + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[shared_roster_group](admin-tags.md#shared_roster_group) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/srg_add +{ + "group": "group3", + "host": "myserver.com" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## srg_add_displayed + + + +Add a group to displayed_groups of a Shared Roster Group + +__Arguments:__ + +- *group* :: string : Group identifier +- *host* :: string : Group server name +- *add* :: string : Group to add to displayed_groups + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[shared_roster_group](admin-tags.md#shared_roster_group) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/srg_add_displayed +{ + "group": "group3", + "host": "myserver.com", + "add": "group1" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## srg_create 🟤 + + + +Create a Shared Roster Group + +__Arguments:__ + +- *group* :: string : Group identifier +- *host* :: string : Group server name +- *label* :: string : Group name +- *description* :: string : Group description +- *display* :: [group::string] : List of groups to display + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[shared_roster_group](admin-tags.md#shared_roster_group), [v1](admin-tags.md#v1) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/srg_create +{ + "group": "group3", + "host": "myserver.com", + "label": "Group3", + "description": "Third group", + "display": [ + "group1", + "group2" + ] +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## srg_del_displayed + + + +Delete a group from displayed_groups of a Shared Roster Group + +__Arguments:__ + +- *group* :: string : Group identifier +- *host* :: string : Group server name +- *del* :: string : Group to delete from displayed_groups + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[shared_roster_group](admin-tags.md#shared_roster_group) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/srg_del_displayed +{ + "group": "group3", + "host": "myserver.com", + "del": "group1" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## srg_delete + + +Delete a Shared Roster Group + +__Arguments:__ + +- *group* :: string : Group identifier +- *host* :: string : Group server name + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[shared_roster_group](admin-tags.md#shared_roster_group) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/srg_delete +{ + "group": "group3", + "host": "myserver.com" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## srg_get_displayed + + + +Get displayed groups of a Shared Roster Group + +__Arguments:__ + +- *group* :: string : Group identifier +- *host* :: string : Group server name + +__Result:__ + +- *display* :: [group::string] : List of groups to display + +__Tags:__ +[shared_roster_group](admin-tags.md#shared_roster_group) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/srg_get_displayed +{ + "group": "group3", + "host": "myserver.com" +} + +HTTP/1.1 200 OK +[ + "group1", + "group2" +] +~~~ + + + + +## srg_get_info + + +Get info of a Shared Roster Group + +__Arguments:__ + +- *group* :: string : Group identifier +- *host* :: string : Group server name + +__Result:__ + +- *informations* :: [{key::string, value::string}] : List of group information, as key and value + +__Tags:__ +[shared_roster_group](admin-tags.md#shared_roster_group) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/srg_get_info +{ + "group": "group3", + "host": "myserver.com" +} + +HTTP/1.1 200 OK +[ + { + "key": "name", + "value": "Group 3" + }, + { + "key": "displayed_groups", + "value": "group1" + } +] +~~~ + + + + +## srg_get_members + + +Get members of a Shared Roster Group + +__Arguments:__ + +- *group* :: string : Group identifier +- *host* :: string : Group server name + +__Result:__ + +- *members* :: [member::string] : List of group identifiers + +__Tags:__ +[shared_roster_group](admin-tags.md#shared_roster_group) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/srg_get_members +{ + "group": "group3", + "host": "myserver.com" +} + +HTTP/1.1 200 OK +[ + "user1@localhost", + "user2@localhost" +] +~~~ + + + + +## srg_list + + +List the Shared Roster Groups in Host + +__Arguments:__ + +- *host* :: string : Server name + +__Result:__ + +- *groups* :: [id::string] : List of group identifiers + +__Tags:__ +[shared_roster_group](admin-tags.md#shared_roster_group) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/srg_list +{ + "host": "myserver.com" +} + +HTTP/1.1 200 OK +[ + "group1", + "group2" +] +~~~ + + + + +## srg_set_info + + + +Set info of a Shared Roster Group + +__Arguments:__ + +- *group* :: string : Group identifier +- *host* :: string : Group server name +- *key* :: string : Information key: label, description +- *value* :: string : Information value + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[shared_roster_group](admin-tags.md#shared_roster_group) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/srg_set_info +{ + "group": "group3", + "host": "myserver.com", + "key": "label", + "value": "Family" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## srg_user_add + + +Add the JID user@host to the Shared Roster Group + +__Arguments:__ + +- *user* :: string : Username +- *host* :: string : User server name +- *group* :: string : Group identifier +- *grouphost* :: string : Group server name + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[shared_roster_group](admin-tags.md#shared_roster_group) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/srg_user_add +{ + "user": "user1", + "host": "myserver.com", + "group": "group3", + "grouphost": "myserver.com" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## srg_user_del + + +Delete this JID user@host from the Shared Roster Group + +__Arguments:__ + +- *user* :: string : Username +- *host* :: string : User server name +- *group* :: string : Group identifier +- *grouphost* :: string : Group server name + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[shared_roster_group](admin-tags.md#shared_roster_group) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/srg_user_del +{ + "user": "user1", + "host": "myserver.com", + "group": "group3", + "grouphost": "myserver.com" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## stats + + +Get some statistical value for the whole ejabberd server + + +Allowed statistics `name` are: `registeredusers`, `onlineusers`, `onlineusersnode`, `uptimeseconds`, `processes`. + +__Arguments:__ + +- *name* :: string : Statistic name + +__Result:__ + +- *stat* :: integer : Integer statistic value + +__Tags:__ +[statistics](admin-tags.md#statistics) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/stats +{ + "name": "registeredusers" +} + +HTTP/1.1 200 OK +6 +~~~ + + + + +## stats_host + + +Get some statistical value for this host + + +Allowed statistics `name` are: `registeredusers`, `onlineusers`. + +__Arguments:__ + +- *name* :: string : Statistic name +- *host* :: string : Server JID + +__Result:__ + +- *stat* :: integer : Integer statistic value + +__Tags:__ +[statistics](admin-tags.md#statistics) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/stats_host +{ + "name": "registeredusers", + "host": "example.com" +} + +HTTP/1.1 200 OK +6 +~~~ + + + + +## status + + +Get status of the ejabberd server + +__Arguments:__ + + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[server](admin-tags.md#server) + +__Examples:__ + + +~~~ json +POST /api/status +{ + +} + +HTTP/1.1 200 OK +"The node ejabberd@localhost is started with status: startedejabberd X.X is running in that node" +~~~ + + + + +## status_list + + +List of logged users with this status + +__Arguments:__ + +- *status* :: string : Status type to check + +__Result:__ + +- *users* :: [{user::string, host::string, resource::string, priority::integer, status::string}] + +__Tags:__ +[session](admin-tags.md#session) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/status_list +{ + "status": "dnd" +} + +HTTP/1.1 200 OK +[ + { + "user": "peter", + "host": "myserver.com", + "resource": "tka", + "priority": 6, + "status": "Busy" + } +] +~~~ + + + + +## status_list_host + + +List of users logged in host with their statuses + +__Arguments:__ + +- *host* :: string : Server name +- *status* :: string : Status type to check + +__Result:__ + +- *users* :: [{user::string, host::string, resource::string, priority::integer, status::string}] + +__Tags:__ +[session](admin-tags.md#session) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/status_list_host +{ + "host": "myserver.com", + "status": "dnd" +} + +HTTP/1.1 200 OK +[ + { + "user": "peter", + "host": "myserver.com", + "resource": "tka", + "priority": 6, + "status": "Busy" + } +] +~~~ + + + + +## status_num + + +Number of logged users with this status + +__Arguments:__ + +- *status* :: string : Status type to check + +__Result:__ + +- *users* :: integer : Number of connected sessions with given status type + +__Tags:__ +[session](admin-tags.md#session), [statistics](admin-tags.md#statistics) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/status_num +{ + "status": "dnd" +} + +HTTP/1.1 200 OK +23 +~~~ + + + + +## status_num_host + + +Number of logged users with this status in host + +__Arguments:__ + +- *host* :: string : Server name +- *status* :: string : Status type to check + +__Result:__ + +- *users* :: integer : Number of connected sessions with given status type + +__Tags:__ +[session](admin-tags.md#session), [statistics](admin-tags.md#statistics) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/status_num_host +{ + "host": "myserver.com", + "status": "dnd" +} + +HTTP/1.1 200 OK +23 +~~~ + + + + +## stop + + +Stop ejabberd gracefully + +__Arguments:__ + + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[server](admin-tags.md#server) + +__Examples:__ + + +~~~ json +POST /api/stop +{ + +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## stop_kindly + + +Inform users and rooms, wait, and stop the server + + +Provide the delay in seconds, and the announcement quoted, for example: +`ejabberdctl stop_kindly 60 \"The server will stop in one minute.\"` + +__Arguments:__ + +- *delay* :: integer : Seconds to wait +- *announcement* :: string : Announcement to send, with quotes + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[server](admin-tags.md#server) + +__Examples:__ + + +~~~ json +POST /api/stop_kindly +{ + "delay": 60, + "announcement": "Server will stop now." +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## stop_s2s_connections + + +Stop all s2s outgoing and incoming connections + +__Arguments:__ + + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[s2s](admin-tags.md#s2s) + +__Examples:__ + + +~~~ json +POST /api/stop_s2s_connections +{ + +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## subscribe_room 🟤 + + + +Subscribe to a MUC conference + +__Arguments:__ + +- *user* :: string : User JID +- *nick* :: string : a user's nick +- *room* :: string : the room to subscribe +- *nodes* :: [node::string] : list of nodes + +__Result:__ + +- *nodes* :: [node::string] : The list of nodes that has subscribed + +__Tags:__ +[muc_room](admin-tags.md#muc_room), [muc_sub](admin-tags.md#muc_sub), [v1](admin-tags.md#v1) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/subscribe_room +{ + "user": "tom@localhost", + "nick": "Tom", + "room": "room1@conference.localhost", + "nodes": [ + "urn:xmpp:mucsub:nodes:messages", + "urn:xmpp:mucsub:nodes:affiliations" + ] +} + +HTTP/1.1 200 OK +[ + "urn:xmpp:mucsub:nodes:messages", + "urn:xmpp:mucsub:nodes:affiliations" +] +~~~ + + + + +## subscribe_room_many 🟤 + + + +Subscribe several users to a MUC conference + + +This command accepts up to 50 users at once (this is configurable with the [mod_muc_admin](modules.md#mod_muc_admin) option `subscribe_room_many_max_users`) + +__Arguments:__ + +- *users* :: [{jid::string, nick::string}] : Users JIDs and nicks +- *room* :: string : the room to subscribe +- *nodes* :: [node::string] : nodes separated by commas: `,` + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[muc_room](admin-tags.md#muc_room), [muc_sub](admin-tags.md#muc_sub), [v1](admin-tags.md#v1) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/subscribe_room_many +{ + "users": [ + { + "jid": "tom@localhost", + "nick": "Tom" + }, + { + "jid": "jerry@localhost", + "nick": "Jerry" + } + ], + "room": "room1@conference.localhost", + "nodes": [ + "urn:xmpp:mucsub:nodes:messages", + "urn:xmpp:mucsub:nodes:affiliations" + ] +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## unban_account + + + +Revert the ban from an account: set back the old password + + +Check [ban_account](#ban_account) API. + +__Arguments:__ + +- *user* :: string : User name to unban +- *host* :: string : Server name + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[accounts](admin-tags.md#accounts), [v2](admin-tags.md#v2) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/unban_account +{ + "user": "gooduser", + "host": "myserver.com" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## unban_ip + + +Remove banned IP addresses from the fail2ban table + + +Accepts an IP address with a network mask. Returns the number of unbanned addresses, or a negative integer if there were any error. + +__Arguments:__ + +- *address* :: string : IP address, optionally with network mask. + +__Result:__ + +- *unbanned* :: integer : Amount of unbanned entries, or negative in case of error. + +__Tags:__ +[accounts](admin-tags.md#accounts) + +__Module:__ +[mod_fail2ban](modules.md#mod_fail2ban) + +__Examples:__ + + +~~~ json +POST /api/unban_ip +{ + "address": "::FFFF:127.0.0.1/128" +} + +HTTP/1.1 200 OK +3 +~~~ + + + + +## unregister + + +Unregister a user + + +This deletes the authentication and all the data associated to the account (roster, vcard...). + +__Arguments:__ + +- *user* :: string : Username +- *host* :: string : Local vhost served by ejabberd + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[accounts](admin-tags.md#accounts) + +__Examples:__ + + +~~~ json +POST /api/unregister +{ + "user": "bob", + "host": "example.com" +} + +HTTP/1.1 200 OK +"Success" +~~~ + + + + +## unsubscribe_room + + +Unsubscribe from a MUC conference + +__Arguments:__ + +- *user* :: string : User JID +- *room* :: string : the room to subscribe + +__Result:__ + +- *res* :: integer : Status code (`0` on success, `1` otherwise) + +__Tags:__ +[muc_room](admin-tags.md#muc_room), [muc_sub](admin-tags.md#muc_sub) + +__Module:__ +[mod_muc_admin](modules.md#mod_muc_admin) + +__Examples:__ + + +~~~ json +POST /api/unsubscribe_room +{ + "user": "tom@localhost", + "room": "room1@conference.localhost" +} + +HTTP/1.1 200 OK +"" +~~~ + + + + +## update + + +Update the given module + + +To update all the possible modules, use `all`. + +__Arguments:__ + +- *module* :: string + +__Result:__ + +- *res* :: string : Raw result string + +__Tags:__ +[server](admin-tags.md#server) + +__Examples:__ + + +~~~ json +POST /api/update +{ + "module": "all" +} + +HTTP/1.1 200 OK +"Updated modules: mod_configure, mod_vcard" +~~~ + + + + +## update_list + + +List modified modules that can be updated + +__Arguments:__ + + +__Result:__ + +- *modules* :: [module::string] + +__Tags:__ +[server](admin-tags.md#server) + +__Examples:__ + + +~~~ json +POST /api/update_list +{ + +} + +HTTP/1.1 200 OK +[ + "mod_configure", + "mod_vcard" +] +~~~ + + + + +## user_resources + + +List user's connected resources + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name + +__Result:__ + +- *resources* :: [resource::string] + +__Tags:__ +[session](admin-tags.md#session) + +__Examples:__ + + +~~~ json +POST /api/user_resources +{ + "user": "user1", + "host": "example.com" +} + +HTTP/1.1 200 OK +[ + "tka1", + "Gajim", + "mobile-app" +] +~~~ + + + + +## user_sessions_info + + +Get information about all sessions of a user + +__Arguments:__ + +- *user* :: string : User name +- *host* :: string : Server name + +__Result:__ + +- *sessions_info* :: [{connection::string, ip::string, port::integer, priority::integer, node::string, uptime::integer, status::string, resource::string, statustext::string}] + +__Tags:__ +[session](admin-tags.md#session) + +__Module:__ +[mod_admin_extra](modules.md#mod_admin_extra) + +__Examples:__ + + +~~~ json +POST /api/user_sessions_info +{ + "user": "peter", + "host": "myserver.com" +} + +HTTP/1.1 200 OK +[ + { + "connection": "c2s", + "ip": "127.0.0.1", + "port": 42656, + "priority": 8, + "node": "ejabberd@localhost", + "uptime": 231, + "status": "dnd", + "resource": "tka", + "statustext": "" + } +] +~~~ + + diff --git a/content/archive/24.06/admin-tags.md b/content/archive/24.06/admin-tags.md new file mode 100644 index 00000000..87090a53 --- /dev/null +++ b/content/archive/24.06/admin-tags.md @@ -0,0 +1,726 @@ +--- +search: + exclude: true +--- + +# API Tags + +> This section enumerates the API tags of ejabberd [24.06](../../archive/24.06/index.md). If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the [Archive](../../archive/index.md). + + + +## accounts + + +* [ban_account](admin-api.md#ban_account) + + +* [change_password](admin-api.md#change_password) + + +* [check_account](admin-api.md#check_account) + + +* [check_password](admin-api.md#check_password) + + +* [check_password_hash](admin-api.md#check_password_hash) + + +* [delete_old_users](admin-api.md#delete_old_users) + + +* [delete_old_users_vhost](admin-api.md#delete_old_users_vhost) + + +* [get_ban_details](admin-api.md#get_ban_details) + + +* [register](admin-api.md#register) + + +* [registered_users](admin-api.md#registered_users) + + +* [unban_account](admin-api.md#unban_account) + + +* [unban_ip](admin-api.md#unban_ip) + + +* [unregister](admin-api.md#unregister) + + +## acme + + +* [list_certificates](admin-api.md#list_certificates) + + +* [request_certificate](admin-api.md#request_certificate) + + +* [revoke_certificate](admin-api.md#revoke_certificate) + + +## cluster + + +* [get_master](admin-api.md#get_master) + + +* [join_cluster](admin-api.md#join_cluster) + + +* [join_cluster_here](admin-api.md#join_cluster_here) + + +* [leave_cluster](admin-api.md#leave_cluster) + + +* [list_cluster](admin-api.md#list_cluster) + + +* [list_cluster_detailed](admin-api.md#list_cluster_detailed) + + +* [set_master](admin-api.md#set_master) + + +## config + + +* [convert_to_yaml](admin-api.md#convert_to_yaml) + + +* [dump_config](admin-api.md#dump_config) + + +* [reload_config](admin-api.md#reload_config) + + +## documentation + + +* [gen_html_doc_for_commands](admin-api.md#gen_html_doc_for_commands) + + +* [gen_markdown_doc_for_commands](admin-api.md#gen_markdown_doc_for_commands) + + +* [gen_markdown_doc_for_tags](admin-api.md#gen_markdown_doc_for_tags) + + +* [man](admin-api.md#man) + + +## ejabberdctl + + +* [help](admin-api.md#help) + + +* [mnesia_info_ctl](admin-api.md#mnesia_info_ctl) + + +* [print_sql_schema](admin-api.md#print_sql_schema) + + +## erlang + + +* [compile](admin-api.md#compile) + + +* [get_cookie](admin-api.md#get_cookie) + + +* [restart_module](admin-api.md#restart_module) + + +## last + + +* [get_last](admin-api.md#get_last) + + +* [set_last](admin-api.md#set_last) + + +## logs + + +* [get_loglevel](admin-api.md#get_loglevel) + + +* [reopen_log](admin-api.md#reopen_log) + + +* [rotate_log](admin-api.md#rotate_log) + + +* [set_loglevel](admin-api.md#set_loglevel) + + +## mam + + +* [remove_mam_for_user](admin-api.md#remove_mam_for_user) + + +* [remove_mam_for_user_with_peer](admin-api.md#remove_mam_for_user_with_peer) + + +## mnesia + + +* [backup](admin-api.md#backup) + + +* [delete_mnesia](admin-api.md#delete_mnesia) + + +* [dump](admin-api.md#dump) + + +* [dump_table](admin-api.md#dump_table) + + +* [export2sql](admin-api.md#export2sql) + + +* [export_piefxis](admin-api.md#export_piefxis) + + +* [export_piefxis_host](admin-api.md#export_piefxis_host) + + +* [import_dir](admin-api.md#import_dir) + + +* [import_file](admin-api.md#import_file) + + +* [import_piefxis](admin-api.md#import_piefxis) + + +* [import_prosody](admin-api.md#import_prosody) + + +* [install_fallback](admin-api.md#install_fallback) + + +* [load](admin-api.md#load) + + +* [mnesia_change_nodename](admin-api.md#mnesia_change_nodename) + + +* [mnesia_info](admin-api.md#mnesia_info) + + +* [mnesia_info_ctl](admin-api.md#mnesia_info_ctl) + + +* [mnesia_table_info](admin-api.md#mnesia_table_info) + + +* [restore](admin-api.md#restore) + + +## modules + + +* [module_check](admin-api.md#module_check) + + +* [module_install](admin-api.md#module_install) + + +* [module_uninstall](admin-api.md#module_uninstall) + + +* [module_upgrade](admin-api.md#module_upgrade) + + +* [modules_available](admin-api.md#modules_available) + + +* [modules_installed](admin-api.md#modules_installed) + + +* [modules_update_specs](admin-api.md#modules_update_specs) + + +## muc + + +* [create_rooms_file](admin-api.md#create_rooms_file) + + +* [destroy_rooms_file](admin-api.md#destroy_rooms_file) + + +* [get_user_rooms](admin-api.md#get_user_rooms) + + +* [get_user_subscriptions](admin-api.md#get_user_subscriptions) + + +* [muc_online_rooms](admin-api.md#muc_online_rooms) + + +* [muc_online_rooms_by_regex](admin-api.md#muc_online_rooms_by_regex) + + +* [muc_register_nick](admin-api.md#muc_register_nick) + + +* [muc_unregister_nick](admin-api.md#muc_unregister_nick) + + +* [rooms_empty_destroy](admin-api.md#rooms_empty_destroy) + + +* [rooms_empty_list](admin-api.md#rooms_empty_list) + + +* [rooms_unused_destroy](admin-api.md#rooms_unused_destroy) + + +* [rooms_unused_list](admin-api.md#rooms_unused_list) + + +## muc_room + + +* [change_room_option](admin-api.md#change_room_option) + + +* [create_room](admin-api.md#create_room) + + +* [create_room_with_opts](admin-api.md#create_room_with_opts) + + +* [destroy_room](admin-api.md#destroy_room) + + +* [get_room_affiliation](admin-api.md#get_room_affiliation) + + +* [get_room_affiliations](admin-api.md#get_room_affiliations) + + +* [get_room_history](admin-api.md#get_room_history) + + +* [get_room_occupants](admin-api.md#get_room_occupants) + + +* [get_room_occupants_number](admin-api.md#get_room_occupants_number) + + +* [get_room_options](admin-api.md#get_room_options) + + +* [get_subscribers](admin-api.md#get_subscribers) + + +* [send_direct_invitation](admin-api.md#send_direct_invitation) + + +* [set_room_affiliation](admin-api.md#set_room_affiliation) + + +* [subscribe_room](admin-api.md#subscribe_room) + + +* [subscribe_room_many](admin-api.md#subscribe_room_many) + + +* [unsubscribe_room](admin-api.md#unsubscribe_room) + + +## muc_sub + + +* [create_room_with_opts](admin-api.md#create_room_with_opts) + + +* [get_subscribers](admin-api.md#get_subscribers) + + +* [get_user_subscriptions](admin-api.md#get_user_subscriptions) + + +* [subscribe_room](admin-api.md#subscribe_room) + + +* [subscribe_room_many](admin-api.md#subscribe_room_many) + + +* [unsubscribe_room](admin-api.md#unsubscribe_room) + + +## oauth + + +* [oauth_add_client_implicit](admin-api.md#oauth_add_client_implicit) + + +* [oauth_add_client_password](admin-api.md#oauth_add_client_password) + + +* [oauth_issue_token](admin-api.md#oauth_issue_token) + + +* [oauth_list_tokens](admin-api.md#oauth_list_tokens) + + +* [oauth_remove_client](admin-api.md#oauth_remove_client) + + +* [oauth_revoke_token](admin-api.md#oauth_revoke_token) + + +## offline + + +* [get_offline_count](admin-api.md#get_offline_count) + + +## private + + +* [bookmarks_to_pep](admin-api.md#bookmarks_to_pep) + + +* [private_get](admin-api.md#private_get) + + +* [private_set](admin-api.md#private_set) + + +## purge + + +* [abort_delete_old_mam_messages](admin-api.md#abort_delete_old_mam_messages) + + +* [abort_delete_old_messages](admin-api.md#abort_delete_old_messages) + + +* [delete_expired_messages](admin-api.md#delete_expired_messages) + + +* [delete_expired_pubsub_items](admin-api.md#delete_expired_pubsub_items) + + +* [delete_old_mam_messages](admin-api.md#delete_old_mam_messages) + + +* [delete_old_mam_messages_batch](admin-api.md#delete_old_mam_messages_batch) + + +* [delete_old_mam_messages_status](admin-api.md#delete_old_mam_messages_status) + + +* [delete_old_messages](admin-api.md#delete_old_messages) + + +* [delete_old_messages_batch](admin-api.md#delete_old_messages_batch) + + +* [delete_old_messages_status](admin-api.md#delete_old_messages_status) + + +* [delete_old_pubsub_items](admin-api.md#delete_old_pubsub_items) + + +* [delete_old_push_sessions](admin-api.md#delete_old_push_sessions) + + +* [delete_old_users](admin-api.md#delete_old_users) + + +* [delete_old_users_vhost](admin-api.md#delete_old_users_vhost) + + +## roster + + +* [add_rosteritem](admin-api.md#add_rosteritem) + + +* [delete_rosteritem](admin-api.md#delete_rosteritem) + + +* [get_roster](admin-api.md#get_roster) + + +* [get_roster_count](admin-api.md#get_roster_count) + + +* [process_rosteritems](admin-api.md#process_rosteritems) + + +* [push_alltoall](admin-api.md#push_alltoall) + + +* [push_roster](admin-api.md#push_roster) + + +* [push_roster_all](admin-api.md#push_roster_all) + + +## s2s + + +* [incoming_s2s_number](admin-api.md#incoming_s2s_number) + + +* [outgoing_s2s_number](admin-api.md#outgoing_s2s_number) + + +* [stop_s2s_connections](admin-api.md#stop_s2s_connections) + + +## server + + +* [clear_cache](admin-api.md#clear_cache) + + +* [gc](admin-api.md#gc) + + +* [halt](admin-api.md#halt) + + +* [registered_vhosts](admin-api.md#registered_vhosts) + + +* [restart](admin-api.md#restart) + + +* [status](admin-api.md#status) + + +* [stop](admin-api.md#stop) + + +* [stop_kindly](admin-api.md#stop_kindly) + + +* [update](admin-api.md#update) + + +* [update_list](admin-api.md#update_list) + + +## session + + +* [connected_users](admin-api.md#connected_users) + + +* [connected_users_info](admin-api.md#connected_users_info) + + +* [connected_users_number](admin-api.md#connected_users_number) + + +* [connected_users_vhost](admin-api.md#connected_users_vhost) + + +* [get_presence](admin-api.md#get_presence) + + +* [kick_session](admin-api.md#kick_session) + + +* [kick_user](admin-api.md#kick_user) + + +* [num_resources](admin-api.md#num_resources) + + +* [resource_num](admin-api.md#resource_num) + + +* [set_presence](admin-api.md#set_presence) + + +* [status_list](admin-api.md#status_list) + + +* [status_list_host](admin-api.md#status_list_host) + + +* [status_num](admin-api.md#status_num) + + +* [status_num_host](admin-api.md#status_num_host) + + +* [user_resources](admin-api.md#user_resources) + + +* [user_sessions_info](admin-api.md#user_sessions_info) + + +## shared_roster_group + + +* [srg_add](admin-api.md#srg_add) + + +* [srg_add_displayed](admin-api.md#srg_add_displayed) + + +* [srg_create](admin-api.md#srg_create) + + +* [srg_del_displayed](admin-api.md#srg_del_displayed) + + +* [srg_delete](admin-api.md#srg_delete) + + +* [srg_get_displayed](admin-api.md#srg_get_displayed) + + +* [srg_get_info](admin-api.md#srg_get_info) + + +* [srg_get_members](admin-api.md#srg_get_members) + + +* [srg_list](admin-api.md#srg_list) + + +* [srg_set_info](admin-api.md#srg_set_info) + + +* [srg_user_add](admin-api.md#srg_user_add) + + +* [srg_user_del](admin-api.md#srg_user_del) + + +## sql + + +* [convert_to_scram](admin-api.md#convert_to_scram) + + +* [import_prosody](admin-api.md#import_prosody) + + +* [print_sql_schema](admin-api.md#print_sql_schema) + + +## stanza + + +* [privacy_set](admin-api.md#privacy_set) + + +* [send_message](admin-api.md#send_message) + + +* [send_stanza](admin-api.md#send_stanza) + + +* [send_stanza_c2s](admin-api.md#send_stanza_c2s) + + +## statistics + + +* [connected_users_number](admin-api.md#connected_users_number) + + +* [incoming_s2s_number](admin-api.md#incoming_s2s_number) + + +* [outgoing_s2s_number](admin-api.md#outgoing_s2s_number) + + +* [stats](admin-api.md#stats) + + +* [stats_host](admin-api.md#stats_host) + + +* [status_num](admin-api.md#status_num) + + +* [status_num_host](admin-api.md#status_num_host) + + +## v1 + + +* [add_rosteritem](admin-api.md#add_rosteritem) + + +* [oauth_issue_token](admin-api.md#oauth_issue_token) + + +* [send_direct_invitation](admin-api.md#send_direct_invitation) + + +* [set_presence](admin-api.md#set_presence) + + +* [srg_create](admin-api.md#srg_create) + + +* [subscribe_room](admin-api.md#subscribe_room) + + +* [subscribe_room_many](admin-api.md#subscribe_room_many) + + +## v2 + + +* [ban_account](admin-api.md#ban_account) + + +* [get_ban_details](admin-api.md#get_ban_details) + + +* [kick_user](admin-api.md#kick_user) + + +* [rooms_empty_destroy](admin-api.md#rooms_empty_destroy) + + +* [unban_account](admin-api.md#unban_account) + + +## vcard + + +* [get_vcard](admin-api.md#get_vcard) + + +* [get_vcard2](admin-api.md#get_vcard2) + + +* [get_vcard2_multi](admin-api.md#get_vcard2_multi) + + +* [set_nickname](admin-api.md#set_nickname) + + +* [set_vcard](admin-api.md#set_vcard) + + +* [set_vcard2](admin-api.md#set_vcard2) + + +* [set_vcard2_multi](admin-api.md#set_vcard2_multi) diff --git a/content/archive/24.06/index.md b/content/archive/24.06/index.md new file mode 100644 index 00000000..6de53229 --- /dev/null +++ b/content/archive/24.06/index.md @@ -0,0 +1,11 @@ +# Archived Documentation for 24.06 + +This section contains some archived sections for ejabberd 24.06. + +If you are upgrading ejabberd from a previous release, you can check: + +* [Specific version upgrade notes](upgrade.md) +* [ejabberd 24.06 release announcement](https://www.process-one.net/blog/ejabberd-24-06/) +* [Docs Github Compare from 24.02](https://github.com/processone/docs.ejabberd.im/compare/24.02..24.06) +* [ejabberd Github Compare from 24.02](https://github.com/processone/ejabberd/compare/24.02..24.06) + diff --git a/content/archive/24.06/listen-options.md b/content/archive/24.06/listen-options.md new file mode 100644 index 00000000..ab590b37 --- /dev/null +++ b/content/archive/24.06/listen-options.md @@ -0,0 +1,399 @@ +--- +search: + exclude: true +--- + +# Listen Options + +> This section describes the most recent ejabberd version. If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the [Archive](../../archive/index.md). + +This is a detailed description of each option allowed by the listening +modules: + +## access + +*AccessName* + +This option defines access to the port. The default value is `all`. + +## backlog + +*Value* + +The backlog value defines the maximum length that the queue of + pending connections may grow to. This should be increased if the + server is going to handle lots of new incoming connections as they + may be dropped if there is no space in the queue (and ejabberd was + not able to accept them immediately). Default value is 5. + +## cafile + +*Path* + +Path to a file of CA root certificates. +The default is to use system defined file if possible. + +This option is useful to define the file for a specific port listener. +To set a file for all client listeners or for specific vhosts, you can use the +[`c2s_cafile`](toplevel.md#c2s_cafile) top-level option. +To set a file for all server connections, you can use the +[`s2s_cafile`](toplevel.md#s2s_cafile) top-level option +or the +[`ca_file`](toplevel.md#ca_file) top-level option. + +Please note: if this option is set in +[`ejabberd_c2s`](listen.md#ejabberd_c2s) +or [`ejabberd_s2s_in`](listen.md#ejabberd_s2s_in) +and the corresponding top-level option is also set +([`c2s_cafile`](toplevel.md#c2s_cafile), +[`s2s_cafile`](toplevel.md#s2s_cafile)), +then the top-level option is used, not this one. + +## certfile + +*Path* + +Path to the certificate file. +Only makes sense when the [`tls`](#tls) +options is set. +If this option is not set, you should set the +[`certfiles`](toplevel.md#certfiles) top-level option +or configure [ACME](../../admin/configuration/basic.md#acme). + +## check_from + +*true | false* + +This option can be used with +[`ejabberd_service`](listen.md#ejabberd_service) only. + [`XEP-0114`](https://xmpp.org/extensions/xep-0114.html) requires that + the domain must match the hostname of the component. If this option + is set to `false`, `ejabberd` will allow the component to send + stanzas with any arbitrary domain in the ’from’ attribute. Only use + this option if you are completely sure about it. The default value + is `true`, to be compliant with + [`XEP-0114`](https://xmpp.org/extensions/xep-0114.html). + +## ciphers + +*Ciphers* + +OpenSSL ciphers list in the same format accepted by + ‘`openssl ciphers`’ command. + +Please note: if this option is set in +[`ejabberd_c2s`](listen.md#ejabberd_c2s) +or [`ejabberd_s2s_in`](listen.md#ejabberd_s2s_in) +and the corresponding top-level option is also set +([`c2s_ciphers`](toplevel.md#c2s_ciphers), +[`s2s_ciphers`](toplevel.md#s2s_ciphers)), +then the top-level option is used, not this one. + +## custom_headers + +*{Name: Value}* + +Specify additional HTTP headers to be included in all HTTP responses. +Default value is: `[]` + +## default_host + +*undefined | HostName* + +If the HTTP request received by ejabberd contains the HTTP header + `Host` with an ambiguous virtual host that doesn’t match any one + defined in ejabberd (see + [Host Names](../../admin/configuration/basic.md#host_names)), + then this configured HostName + is set as the request Host. The default value of this option is: + `undefined`. + +## dhfile + +*Path* + +Full path to a file containing custom parameters for Diffie-Hellman key + exchange. Such a file could be created with the command + `openssl dhparam -out dh.pem 2048`. If this option is not specified, + default parameters will be used, which might not provide the same level + of security as using custom parameters. + +Please note: if this option is set in +[`ejabberd_c2s`](listen.md#ejabberd_c2s) +or [`ejabberd_s2s_in`](listen.md#ejabberd_s2s_in) +and the corresponding top-level option is also set +([`c2s_dhfile`](toplevel.md#c2s_dhfile), +[`s2s_dhfile`](toplevel.md#s2s_dhfile)), +then the top-level option is used, not this one. + +## global_routes + +*true | false* + +This option emulates legacy behaviour which registers all routes +defined in [`hosts`](toplevel.md#hosts) +on a component connected. This behaviour +is considered harmful in the case when it's desired to multiplex +different components on the same port, so, to disable it, +set `global_routes` to `false`. + +The default value is `true`, +e.g. legacy behaviour is emulated: the only reason for this is +to maintain backward compatibility with existing deployments. + +## hosts + +*{Hostname: [HostOption, ...]}* + +The external Jabber component that connects to this +[`ejabberd_service`](listen.md#ejabberd_service) +can serve one or more hostnames. As `HostOption` + you can define options for the component; currently the only allowed + option is the password required to the component when attempt to + connect to ejabberd: `password: Secret`. Note that you + cannot define in a single `ejabberd_service` components of different + services: add an `ejabberd_service` for each service, as seen in an + example below. This option may not be necessary if the component + already provides the host in its packets; in that case, you can simply + provide the password option that will be used for all the hosts + (see port 5236 definition in the example below). + +## max_fsm_queue + +*Size* + +This option specifies the maximum number of elements in the queue of + the FSM (Finite State Machine). Roughly speaking, each message in + such queues represents one XML stanza queued to be sent into its + relevant outgoing stream. If queue size reaches the limit (because, + for example, the receiver of stanzas is too slow), the FSM and the + corresponding connection (if any) will be terminated and error + message will be logged. The reasonable value for this option depends + on your hardware configuration. This option can be specified for + [`ejabberd_service`](listen.md#ejabberd_service) + and [`ejabberd_c2s`](listen.md#ejabberd_c2s) + listeners, or also globally for + [`ejabberd_s2s_out`](listen.md#ejabberd_s2s_out). + If the option is not specified for + `ejabberd_service` or `ejabberd_c2s` listeners, the globally + configured value is used. The allowed values are integers and + ’undefined’. Default value: ’10000’. + +## max_payload_size + +*Size* + +Specify the maximum payload size in bytes. +It can be either an integer or the word `infinity`. +The default value is `infinity`. + +## max_stanza_size + +*Size* + +This option specifies an approximate maximum size in bytes of XML + stanzas. Approximate, because it is calculated with the precision of + one block of read data. For example `{max_stanza_size, 65536}`. The + default value is `infinity`. Recommended values are 65536 for c2s + connections and 131072 for s2s connections. s2s max stanza size must + always much higher than c2s limit. Change this value with extreme + care as it can cause unwanted disconnect if set too low. + +## password + +*Secret* + +Specify the password to verify an external component that connects to the port. + +## port + +*Port number, or unix domain socket path* + + + +Declares at which port/unix domain socket should be listening. + +Can be set to number between `1` and `65535` to listen on TCP or UDP socket, +or can be set to string in form `"unix:/path/to/socket"` to create and listen +on unix domain socket `/path/to/socket`. + +## protocol_options + +*ProtocolOpts* + +List of general options relating to SSL/TLS. These map to + [`OpenSSL’s set_options()`](https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_options.html). + The default entry is: `"no_sslv3|cipher_server_preference|no_compression"` + +Please note: if this option is set in +[`ejabberd_c2s`](listen.md#ejabberd_c2s) +or [`ejabberd_s2s_in`](listen.md#ejabberd_s2s_in) +and the corresponding top-level option is also set +([`c2s_protocol_options`](toplevel.md#c2s_protocol_options), +[`s2s_protocol_options`](toplevel.md#s2s_protocol_options)), +then the top-level option is used, not this one. + +## request_handlers + +*{Path: Module}* + +To define one or several handlers that will serve HTTP requests in +[`ejabberd_http`](listen.md#ejabberd_http). The + Path is a string; so the URIs that start with that Path will be + served by Module. For example, if you want `mod_foo` to serve the + URIs that start with `/a/b/`, and you also want `mod_bosh` to + serve the URIs `/bosh/`, use this option: + +``` yaml +request_handlers: + /a/b: mod_foo + /bosh: mod_bosh + /mqtt: mod_mqtt +``` + +## send_timeout + +*Integer | infinity* + + + +Sets the longest time that data can wait to be accepted to sent by OS socket. Triggering this timeout will cause the server to close it. By default it's set to 15 seconds, expressed in milliseconds: 15000 + +## shaper + +*none | ShaperName* + +This option defines a shaper for the port (see section +[Shapers](../../admin/configuration/basic.md#shapers)). + The default value is `none`. + +## shaper_rule + +*none | ShaperRule* + +This option defines a shaper rule for +[`ejabberd_service`](listen.md#ejabberd_service) (see +section [Shapers](../../admin/configuration/basic.md#shapers)). +The recommended value is `fast`. + +## starttls + +*true | false* + +This option specifies that STARTTLS encryption is available on +connections to the port. You should also set the +[`certfiles`](toplevel.md#certfiles) top-level option +or configure [ACME](../../admin/configuration/basic.md#acme). + +This option gets implicitly enabled when enabling +[`starttls_required`](#starttls_required) or [`tls_verify`](#tls_verify). + +## starttls_required + +*true | false* + +This option specifies that STARTTLS encryption is required on connections to the port. No unencrypted connections will be allowed. +You should also set the [`certfiles`](toplevel.md#certfiles) top-level option or configure [ACME](../../admin/configuration/basic.md#acme). + +Enabling this option implicitly enables also the [`starttls`](#starttls) option. + +## tag + +*String* + +Allow specifying a tag in a `listen` section and later use it to have a special [`api_permissions`](toplevel.md#api_permissions) just for it. + +For example: + +``` yaml +listen: + - + port: 4000 + module: ejabberd_http + tag: "magic_listener" + +api_permissions: + "magic_access": + from: + - tag: "magic_listener" + who: all + what: "*" +``` + +The default value is the empty string: `""`. + +## timeout + +*Integer* + +Timeout of the connections, expressed in milliseconds. Default: 5000 + +## tls + +*true | false* + +This option specifies that traffic on the port will be encrypted + using SSL immediately after connecting. This was the traditional + encryption method in the early Jabber software, commonly on port + 5223 for client-to-server communications. But this method is + nowadays deprecated and not recommended. The preferable encryption + method is STARTTLS on port 5222, as defined + [`RFC 6120: XMPP Core`](https://xmpp.org/rfcs/rfc6120.html#tls), + which can be enabled in `ejabberd` with the option + [`starttls`](#starttls). + +If this option is set, you should also set the + [`certfiles`](toplevel.md#certfiles) top-level + option or configure [ACME](../../admin/configuration/basic.md#acme). + +The option `tls` can also be used in + [`ejabberd_http`](listen.md#ejabberd_http) + to support HTTPS. + +Enabling this option implicitly disables the [`starttls`](#starttls) option. + +## tls_compression + +*true | false* + +Whether to enable or disable TLS compression. The default value is + `false`. + +Please note: if this option is set in +[`ejabberd_c2s`](listen.md#ejabberd_c2s) +or [`ejabberd_s2s_in`](listen.md#ejabberd_s2s_in) +and the corresponding top-level option is also set +([`c2s_tls_compression`](toplevel.md#c2s_tls_compression), +[`s2s_tls_compression`](toplevel.md#s2s_tls_compression)), +then the top-level option is used, not this one. + +## tls_verify + +*false | true* + +This option specifies whether to verify the certificate or not when TLS is enabled. + +The default value is `false`, which means no checks are performed. + +The certificate will be checked against trusted CA roots, either defined at the operation system level or defined in the + listener [`cafile`](#cafile). If trusted, it will accept the jid that is embedded in the certificate in the + `subjectAltName` field of that certificate. + +Enabling this option implicitly enables also the [`starttls`](#starttls) option. + +## use_proxy_protocol + +*true | false* + +Is this listener accessed by proxy service that is using + proxy protocol for supplying real IP addresses to ejabberd server. You can read about this protocol + in [Proxy protocol specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt). + The default value of this option is`false`. + +## zlib + +*true | false* + +This option specifies that Zlib stream compression (as defined in + [`XEP-0138`](https://xmpp.org/extensions/xep-0138.html)) is available + on connections to the port. diff --git a/content/archive/24.06/listen.md b/content/archive/24.06/listen.md new file mode 100644 index 00000000..546ad971 --- /dev/null +++ b/content/archive/24.06/listen.md @@ -0,0 +1,822 @@ +--- +search: + exclude: true +--- + +# Listen Modules + +> This section describes the most recent ejabberd version. If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the [Archive](../../archive/index.md). + +## Listen Options + +The `listen` option defines for which ports, addresses and network +protocols `ejabberd` will listen and what services will be run on them. + +Each element of the list is an associative array with the following +elements: + +- **port**: *Number* + + Defines which port number to listen for incoming connections: + it can be a Jabber/XMPP standard port or any other valid port number. + + Alternatively, set the option to a string in form `"unix:/path/to/socket"` + to create and listen on a unix domain socket `/path/to/socket`. + +- **ip**: *IpAddress* + + The socket will listen only in that network interface. + Depending on the type of the IP address, IPv4 or IPv6 will be used. + + It is possible to specify a generic address + (`"0.0.0.0"` for IPv4 or `"::"` for IPv6), + so `ejabberd` will listen in all addresses. + Note that on some operating systems and/or OS configurations, listening + on `"::"` will mean listening for IPv4 traffic as well as IPv6 traffic. + + Some example values for IP address: + + - `"0.0.0.0"` to listen in all IPv4 network interfaces. This is the + default value when the option is not specified. + + - `"::"` to listen in all IPv6 network interfaces + + - `"10.11.12.13"` is the IPv4 address `10.11.12.13` + + - `"::FFFF:127.0.0.1"` is the IPv6 address `::FFFF:127.0.0.1/128` + +- **transport**: *tcp|udp* + + Defines the transport protocol. Default is `tcp`. + +- **module**: *ModuleName* + + Listening module that serves this port + +- Any other options for the socket and for the listening module, described later. + +For example: + +``` yaml +listen: + - + port: 5222 + ip: 127.0.0.1 + module: ejabberd_c2s + starttls: true + - + port: 5269 + transport: tcp + module: ejabberd_s2s_in +``` + +## ejabberd_c2s + +Handles c2s connections. + +General listen options supported: +[access](listen-options.md#access), +[cafile](listen-options.md#cafile), +[ciphers](listen-options.md#ciphers), +[dhfile](listen-options.md#dhfile), +[max_fsm_queue](listen-options.md#max_fsm_queue), +[max_stanza_size](listen-options.md#max_stanza_size), +[protocol_options](listen-options.md#protocol_options), +[send_timeout](listen-options.md#send_timeout), +[shaper](listen-options.md#shaper), +[starttls](listen-options.md#starttls), +[starttls_required](listen-options.md#starttls_required), +[tls](listen-options.md#tls), +[tls_compression](listen-options.md#tls-compression), +[tls_verify](listen-options.md#tls_verify), +[zlib](listen-options.md#zlib). + +## ejabberd_s2s_in + +Handles incoming s2s connections. + +General listen options supported: +[cafile](listen-options.md#cafile), +[ciphers](listen-options.md#ciphers), +[dhfile](listen-options.md#dhfile), +[max_fsm_queue](listen-options.md#max_fsm_queue), +[max_stanza_size](listen-options.md#max_stanza_size), +[protocol_options](listen-options.md#protocol_options), +[send_timeout](listen-options.md#send_timeout), +[shaper](listen-options.md#shaper), +[tls](listen-options.md#tls), +[tls_compression](listen-options.md#tls-compression). + +## ejabberd_service + +Interacts with an [`external component`](https://ejabberd.im/tutorials-transports) +as defined in [XEP-0114: Jabber Component Protocol](https://xmpp.org/extensions/xep-0114.html). + +General listen options supported: +[access](listen-options.md#access), +[cafile](listen-options.md#cafile), +[certfile](listen-options.md#certfile), +[check_from](listen-options.md#check_from), +[ciphers](listen-options.md#ciphers), +[dhfile](listen-options.md#dhfile), +[global_routes](listen-options.md#global_routes), +[hosts](listen-options.md#hosts), +[max_fsm_queue](listen-options.md#max_fsm_queue), +[max_stanza_size](listen-options.md#max_stanza_size), +[password](listen-options.md#password), +[protocol_options](listen-options.md#protocol_options), +[send_timeout](listen-options.md#send_timeout), +[shaper](listen-options.md#shaper), +[shaper_rule](listen-options.md#shaper-rule), +[tls](listen-options.md#tls), +[tls_compression](listen-options.md#tls-compression). + +## mod_mqtt + +Support for MQTT requires configuring `mod_mqtt` both in the +[listen](toplevel.md#listen) and the +[modules](toplevel.md#modules) sections. +Check the [mod_mqtt module](modules.md#mod_mqtt) options, +and the [MQTT Support](../../admin/guide/mqtt/index.md) section. + +General listen options supported: +[backlog](listen-options.md#backlog), +[max_fsm_queue](listen-options.md#max_fsm_queue), +[max_payload_size](listen-options.md#max_payload_size), +[send_timeout](listen-options.md#send_timeout), +[tls](listen-options.md#tls), +[tls_verify](listen-options.md#tls_verify). + + + +## ejabberd_stun + +`ejabberd` can act as a stand-alone STUN/TURN server, +and this module handles STUN/TURN requests as defined in +([`RFC 5389`](https://tools.ietf.org/html/rfc5389)/[`RFC 5766`](https://tools.ietf.org/html/rfc5766). +In that role `ejabberd` helps clients with ICE +([`RFC 5245`](https://tools.ietf.org/html/rfc5245) or Jingle ICE +([`XEP-0176`](https://xmpp.org/extensions/xep-0176.html) support to +discover their external addresses and ports and to relay media traffic +when it is impossible to establish direct peer-to-peer connection. + +General listen options supported: +[certfile](listen-options.md#certfile), +[send_timeout](listen-options.md#send_timeout), +[shaper](listen-options.md#shaper), +[tls](listen-options.md#tls), + +The specific `ejabberd_stun` configurable options are: + +- **auth_realm**: *String* + + When `auth_type` is set to `user` and you have several virtual hosts + configured you should set this option explicitly to the virtual host + you want to serve on this particular listening port. + Implies `use_turn`. + +- **auth_type**: *user|anonymous* + + Which authentication type to use for TURN allocation requests. + When type `user` is set, ejabberd authentication backend is used. + For `anonymous` type no authentication is performed (not recommended for public services). + The default is `user`. + Implies `use_turn`. + +- **shaper**: *Atom* + + For `tcp` transports defines shaper to use. + The default is `none`. + +- **server_name**: *String* + + Defines software version to return with every response. + The default is the STUN library version. + +- **turn_blacklist**: *String | [String,...]* + + Specify one or more IP addresses and/or subnet addresses/masks. + The TURN server will refuse to relay traffic from/to blacklisted IP addresses. + By default, loopback addresses (`127.0.0.0/8` and `::1/128`) are blacklisted. + +- **turn_ipv4_address**: *String* + + The IPv4 address advertised by your TURN server. + The address should not be NAT’ed or firewalled. + There is not default, so you should set this option explicitly. + Implies `use_turn`. + +- **turn_ipv6_address**: *String* + + The IPv6 address advertised by your TURN server. + The address should not be NAT’ed or firewalled. + There is not default, so you should set this option explicitly. + Implies `use_turn`. + +- **turn_max_allocations**: *Integer|infinity* + + Maximum number of TURN allocations available from the particular IP address. + The default value is 10. Implies `use_turn`. + +- **turn_max_permissions**: *Integer|infinity* + + Maximum number of TURN permissions available from the particular IP address. + The default value is 10. + Implies `use_turn`. + +- **turn_max_port**: *Integer* + + Together with `turn_min_port` forms port range to allocate from. + The default is 65535. + Implies `use_turn`. + +- **turn_min_port**: *Integer* + + Together with `turn_max_port` forms port range to allocate from. + The default is 49152. + Implies `use_turn`. + +- **use_turn**: *true|false* + + Enables/disables TURN (media relay) functionality. + The default is `false`. + +Example configuration with disabled TURN functionality (STUN only): + +``` yaml +listen: + - + port: 3478 + transport: udp + module: ejabberd_stun + - + port: 3478 + module: ejabberd_stun + - + port: 5349 + module: ejabberd_stun + certfile: /etc/ejabberd/server.pem +``` + +Example configuration with TURN functionality. Note that STUN is always +enabled if TURN is enabled. Here, only UDP section is shown: + +``` yaml +listen: + - + port: 3478 + transport: udp + use_turn: true + turn_ipv4_address: 10.20.30.1 + module: ejabberd_stun +``` + +You also need to configure DNS SRV records properly so clients can +easily discover a STUN/TURN server serving your XMPP domain. Refer to +section +[`DNS Discovery of a Server`](https://tools.ietf.org/html/rfc5389#section-9) +of [`RFC 5389`](https://tools.ietf.org/html/rfc5389) and section +[`Creating an Allocation`](https://tools.ietf.org/html/rfc5766#section-6) +of [`RFC 5766`](https://tools.ietf.org/html/rfc5766) for details. + +Example DNS SRV configuration for STUN only: + +``` sh +_stun._udp IN SRV 0 0 3478 stun.example.com. +_stun._tcp IN SRV 0 0 3478 stun.example.com. +_stuns._tcp IN SRV 0 0 5349 stun.example.com. +``` + +And you should also add these in the case if TURN is enabled: + +``` sh +_turn._udp IN SRV 0 0 3478 turn.example.com. +_turn._tcp IN SRV 0 0 3478 turn.example.com. +_turns._tcp IN SRV 0 0 5349 turn.example.com. +``` + +## ejabberd_sip + + +`ejabberd` has built-in support to handle SIP requests +as defined in [`RFC 3261`](https://tools.ietf.org/html/rfc3261). + +To activate this feature, +add the [`ejabberd_sip`](#ejabberd_sip) listen module, enable +[`mod_sip`](modules.md#mod_sip) module +for the desired virtual host, and configure DNS properly. + +To add a listener you should configure `ejabberd_sip` listening module +as described in [Listen](#listen-options) section. +If option [`tls`](listen-options.md#tls) is specified, +option [`certfile`](listen-options.md#certfile) +must be specified as well, otherwise incoming TLS connections +would fail. + +General listen options supported: +[certfile](listen-options.md#certfile), +[send_timeout](listen-options.md#send_timeout), +[tls](listen-options.md#tls). + +Example configuration with standard ports (as per +[`RFC 3261`](https://tools.ietf.org/html/rfc3261)): + +``` yaml +listen: + - + port: 5060 + transport: udp + module: ejabberd_sip + - + port: 5060 + module: ejabberd_sip + - + port: 5061 + module: ejabberd_sip + tls: true + certfile: /etc/ejabberd/server.pem +``` + +Note that there is no StartTLS support in SIP and +[`SNI`](https://en.wikipedia.org/wiki/Server_Name_Indication) support is +somewhat tricky, so for TLS you have to configure different virtual +hosts on different ports if you have different certificate files for +them. + +Next you need to configure DNS SIP records for your virtual domains. +Refer to [`RFC 3263`](https://tools.ietf.org/html/rfc3263) for the +detailed explanation. Simply put, you should add NAPTR and SRV records +for your domains. Skip NAPTR configuration if your DNS provider doesn't +support this type of records. It’s not fatal, however, highly +recommended. + +Example configuration of NAPTR records: + +``` sh +example.com IN NAPTR 10 0 "s" "SIPS+D2T" "" _sips._tcp.example.com. +example.com IN NAPTR 20 0 "s" "SIP+D2T" "" _sip._tcp.example.com. +example.com IN NAPTR 30 0 "s" "SIP+D2U" "" _sip._udp.example.com. +``` + +Example configuration of SRV records with standard ports (as per +[`RFC 3261`](https://tools.ietf.org/html/rfc3261): + +``` sh +_sip._udp IN SRV 0 0 5060 sip.example.com. +_sip._tcp IN SRV 0 0 5060 sip.example.com. +_sips._tcp IN SRV 0 0 5061 sip.example.com. +``` + +!!! warning + + SIP authentication does not support SCRAM. As such, it is not possible + to use `mod_sip` to authenticate when ejabberd has been set to encrypt + password with SCRAM. + +## ejabberd_http + +Handles incoming HTTP connections. + +With the proper request handlers configured, this serves HTTP services like +[ACME](../../admin/configuration/basic.md#acme), +[API](modules.md#mod_http_api), +[BOSH](modules.md#mod_bosh), +[CAPTCHA](../../admin/configuration/basic.md#captcha), +[Fileserver](modules.md#mod_http_fileserver), +[OAuth](../../developer/ejabberd-api/../../developer/ejabberd-api/oauth.md), +[RegisterWeb](modules.md#mod_register_web), +[Upload](modules.md#mod_http_upload), +[WebAdmin](../../admin/guide/managing.md#web_admin), +[WebSocket](#ejabberd_http_ws), +[XML-RPC](#ejabberd_xmlrpc). + +Options: +[cafile](listen-options.md#cafile), +[ciphers](listen-options.md#ciphers), +[custom_headers](listen-options.md#custom_headers), +[default_host](listen-options.md#default_host), +[dhfile](listen-options.md#dhfile), +[protocol_options](listen-options.md#protocol_options), +[request_handlers](listen-options.md#request_handlers), +[send_timeout](listen-options.md#send_timeout), +[tag](listen-options.md#tag), +[tls](listen-options.md#tls), +[tls_compression](listen-options.md#tls-compression), +and the [trusted_proxies](toplevel.md#trusted_proxies) top-level option. + +### ejabberd_http_ws + +This module enables XMPP communication over WebSocket connection as +described in [`RFC 7395`](https://tools.ietf.org/html/rfc7395). + +#### WebSocket Config + +To enable WebSocket, simply add a handler to the `request_handlers` +section of an `ejabberd_http` listener: + +``` yaml +listen: + - + port: 5280 + module: ejabberd_http + request_handlers: + /xmpp: ejabberd_http_ws +``` + +This module can be configured using those top-level options: + +- [websocket\_origin](toplevel.md#websocket_origin) +- [websocket\_ping\_interval](toplevel.md#websocket_ping_interval) +- [websocket\_timeout](toplevel.md#websocket_timeout) + +#### WebSocket Discovery + +With the example configuration previously mentioned, +the WebSocket URL would be: `ws://localhost:5280/xmpp` + +You may want to provide a `host-meta` file so clients can +easily discover WebSocket service for your XMPP domain +(see [XEP-0156](https://xmpp.org/extensions/xep-0156.html#http)). +One easy way to provide that file is using +[`mod_host_meta`](modules.md#mod_host_meta). + +#### Testing WebSocket + +A test client can be found on Github: [WebSocket test client](https://github.com/processone/xmpp-websocket-client) + +There is an example configuration for WebSocket and Converse.js in the +ejabberd [21.12](../../archive/21.12/index.md) release notes. + + + +### ejabberd_xmlrpc + +Handles XML-RPC requests to execute +[ejabberd commands](../../admin/guide/managing.md#ejabberd_commands). +It is configured as a request handler in +[ejabberd_http](#ejabberd_http). + +This is the minimum configuration required to enable the feature: + +``` yaml +listen: + - + port: 5280 + module: ejabberd_http + request_handlers: + /xmlrpc: ejabberd_xmlrpc + +api_permissions: + "public commands": + who: + ip: 127.0.0.1/8 + what: + - connected_users_number +``` + +Example Python3 script: + +``` python +import xmlrpc.client +server = xmlrpc.client.ServerProxy("http://127.0.0.1:5280/xmlrpc/"); +print(server.connected_users_number()) +``` + +By default there is no restriction to who can execute what commands, +so it is strongly recommended that you configure restrictions using +[API Permissions](../../developer/ejabberd-api/permissions.md). + +This example configuration adds some restrictions (only requests from localhost are accepted, the XML-RPC query must include authentication credentials of a specific account registered in ejabberd, and only two commands are accepted): + +``` yaml +listen: + - + port: 5280 + ip: "::" + module: ejabberd_http + request_handlers: + /xmlrpc: ejabberd_xmlrpc + +api_permissions: + "some XMLRPC commands": + from: ejabberd_xmlrpc + who: + - ip: 127.0.0.1 + - user: user1@localhost + what: + - registered_users + - connected_users_number +``` + +Example Python3 script for that restricted configuration: + +``` python +import xmlrpc.client +server = xmlrpc.client.ServerProxy("http://127.0.0.1:5280/xmlrpc/"); + +params = {} +params['host'] = 'localhost' + +auth = {'user': 'user1', + 'server': 'localhost', + 'password': 'mypass11', + 'admin': True} + +def calling(command, data): + fn = getattr(server, command) + return fn(auth, data) + +print(calling('registered_users', params)) +``` + +Please notice, when using the old Python2, replace the two first lines with: + +``` python +import xmlrpclib +server = xmlrpclib.Server("http://127.0.0.1:5280/xmlrpc/"); +``` + +It's possible to use OAuth for authentication instead of plain password, see +[OAuth Support](../../developer/ejabberd-api/../../developer/ejabberd-api/oauth.md). + +In ejabberd [20.03](../../archive/20.03/index.md) and older, +it was possible to configure `ejabberd_xmlrpc` as a +listener, see the old document for reference and example configuration: +[Listening Module](../../archive/../../admin/configuration/old.md#listening_module). + +Just for reference, there's also the old +[`ejabberd_xmlrpc documentation`](https://ejabberd.im/ejabberd_xmlrpc) +with example clients in other languages. + +## Examples + +For example, the following simple configuration defines: + +- There are three domains. The default certificate file is `server.pem`. However, the c2s and s2s connections to the domain `example.com` use the file `example_com.pem`. + +- Port 5222 listens for c2s connections with STARTTLS, and also allows plain connections for old clients. + +- Port 5223 listens for c2s connections with the old SSL. + +- Port 5269 listens for s2s connections with STARTTLS. The socket is set for IPv6 instead of IPv4. + +- Port 3478 listens for STUN requests over UDP. + +- Port 5280 listens for HTTP requests, and serves the HTTP-Bind (BOSH) service. + +- Port 5281 listens for HTTP requests, using HTTPS to serve HTTP-Bind (BOSH) and the Web Admin as explained in [Managing: Web Admin](../../admin/guide/managing.md#web_admin). The socket only listens connections to the IP address 127.0.0.1. + +``` yaml +hosts: + - example.com + - example.org + - example.net + +certfiles: + - /etc/ejabberd/server.pem + - /etc/ejabberd/example_com.pem + +listen: + - + port: 5222 + module: ejabberd_c2s + access: c2s + shaper: c2s_shaper + starttls: true + max_stanza_size: 65536 + - + port: 5223 + module: ejabberd_c2s + access: c2s + shaper: c2s_shaper + tls: true + max_stanza_size: 65536 + - + port: 5269 + ip: "::" + module: ejabberd_s2s_in + shaper: s2s_shaper + max_stanza_size: 131072 + - + port: 3478 + transport: udp + module: ejabberd_stun + - + port: 5280 + module: ejabberd_http + request_handlers: + /bosh: mod_bosh + - + port: 5281 + ip: 127.0.0.1 + module: ejabberd_http + tls: true + request_handlers: + /admin: ejabberd_web_admin + /bosh: mod_bosh + +s2s_use_starttls: optional +outgoing_s2s_families: + - ipv4 + - ipv6 +outgoing_s2s_timeout: 10000 +trusted_proxies: [127.0.0.1, 192.168.1.11] +``` + +In this example, the following configuration defines that: + +- c2s connections are listened for on port 5222 (all IPv4 addresses) + and on port 5223 (SSL, IP 192.168.0.1 and fdca:8ab6:a243:75ef::1) + and denied for the user called ‘`bad`’. + +- s2s connections are listened for on port 5269 (all IPv4 addresses) + with STARTTLS for secured traffic strictly required, and the + certificates are verified. Incoming and outgoing connections of + remote XMPP servers are denied, only two servers can connect: + “jabber.example.org” and “example.com”. + +- Port 5280 is serving the Web Admin and the HTTP-Bind (BOSH) service in + all the IPv4 addresses. Note that it is also possible to serve them + on different ports. The second example in section [Managing: Web Admin](../../admin/guide/managing.md#web_admin) shows + how exactly this can be done. A request handler to serve MQTT over WebSocket is also defined. + +- All users except for the administrators have a traffic of limit + 1,000Bytes/second + +- The [`AIM transport`](https://ejabberd.im/pyaimt) + `aim.example.org` is connected to port 5233 on localhost IP + addresses (127.0.0.1 and ::1) with password ‘`aimsecret`’. + +- The ICQ transport JIT (`icq.example.org` and `sms.example.org`) is + connected to port 5234 with password ‘`jitsecret`’. + +- The [`MSN transport`](https://ejabberd.im/pymsnt) + `msn.example.org` is connected to port 5235 with password + ‘`msnsecret`’. + +- The [`Yahoo! transport`](https://ejabberd.im/yahoo-transport-2) + `yahoo.example.org` is connected to port 5236 with password + ‘`yahoosecret`’. + +- The + [`Gadu-Gadu transport`](https://ejabberd.im/jabber-gg-transport) + `gg.example.org` is connected to port 5237 with password + ‘`ggsecret`’. + +- The [`Jabber Mail Component`](https://ejabberd.im/jmc) + `jmc.example.org` is connected to port 5238 with password + ‘`jmcsecret`’. + +- The service custom has enabled the special option to avoiding + checking the `from` attribute in the packets send by this component. + The component can send packets in behalf of any users from the + server, or even on behalf of any server. + +``` yaml +acl: + blocked: + user: bad + trusted_servers: + server: + - example.com + - jabber.example.org + xmlrpc_bot: + user: + - xmlrpc-robot@example.org +shaper: + normal: 1000 +shaper_rules: + c2s_shaper: + - none: admin + - normal +access_rules: + c2s: + - deny: blocked + - allow + xmlrpc_access: + - allow: xmlrpc_bot + s2s: + - allow: trusted_servers +certfiles: + - /path/to/ssl.pem +s2s_access: s2s +s2s_use_starttls: required_trusted +listen: + - + port: 5222 + module: ejabberd_c2s + shaper: c2s_shaper + access: c2s + - + ip: 192.168.0.1 + port: 5223 + module: ejabberd_c2s + tls: true + access: c2s + - + ip: "FDCA:8AB6:A243:75EF::1" + port: 5223 + module: ejabberd_c2s + tls: true + access: c2s + - + port: 5269 + module: ejabberd_s2s_in + - + port: 5280 + module: ejabberd_http + request_handlers: + /admin: ejabberd_web_admin + /bosh: mod_bosh + /mqtt: mod_mqtt + - + port: 4560 + module: ejabberd_xmlrpc + access_commands: {} + - + ip: 127.0.0.1 + port: 5233 + module: ejabberd_service + hosts: + aim.example.org: + password: aimsecret + - + ip: "::1" + port: 5233 + module: ejabberd_service + hosts: + aim.example.org: + password: aimsecret + - + port: 5234 + module: ejabberd_service + hosts: + icq.example.org: + password: jitsecret + sms.example.org: + password: jitsecret + - + port: 5235 + module: ejabberd_service + hosts: + msn.example.org: + password: msnsecret + - + port: 5236 + module: ejabberd_service + password: yahoosecret + - + port: 5237 + module: ejabberd_service + hosts: + gg.example.org: + password: ggsecret + - + port: 5238 + module: ejabberd_service + hosts: + jmc.example.org: + password: jmcsecret + - + port: 5239 + module: ejabberd_service + check_from: false + hosts: + custom.example.org: + password: customsecret +``` + +Note, that for services based in jabberd14 or WPJabber you have to make +the transports log and do XDB by themselves: + +``` xml + + + + + + %d: [%t] (%h): %s + /var/log/jabber/service.log + + + + + + + + + /usr/lib/jabber/xdb_file.so + + + /var/spool/jabber + + +``` diff --git a/content/archive/24.06/modules.md b/content/archive/24.06/modules.md new file mode 100644 index 00000000..fe55087f --- /dev/null +++ b/content/archive/24.06/modules.md @@ -0,0 +1,3956 @@ +--- +search: + exclude: true +--- + +# Modules Options + +> This section describes modules options of ejabberd [24.06](../../archive/24.06/index.md). If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the [Archive](../../archive/index.md). The +modules that changed in this version are marked with 🟤. + +mod\_adhoc +---------- + +This module implements [XEP-0050: Ad-Hoc +Commands](https://xmpp.org/extensions/xep-0050.html). It’s an auxiliary +module and is only needed by some of the other modules. + +__Available options:__ + +- **report\_commands\_node**: *true | false* +Provide the Commands item in the Service Discovery. Default value: +*false*. + +mod\_admin\_extra +----------------- + +This module provides additional administrative commands. + +Details for some commands: + +- *ban\_account*: This command kicks all the connected sessions of the + account from the server. It also changes their password to a + randomly generated one, so they can’t login anymore unless a server + administrator changes their password again. It is possible to define + the reason of the ban. The new password also includes the reason and + the date and time of the ban. See an example below. + +- *pushroster*: (and *pushroster-all*) The roster file must be placed, + if using Windows, on the directory where you installed ejabberd: + `C:/Program Files/ejabberd` or similar. If you use other Operating + System, place the file on the same directory where the .beam files + are installed. See below an example roster file. + +- *srg\_create*: If you want to put a group Name with blank spaces, + use the characters "' and '" to define when the Name starts and + ends. See an example below. + +The module has no options. + +__Examples:__ + +With this configuration, vCards can only be modified with +mod\_admin\_extra commands: + +~~~ yaml +acl: + adminextraresource: + - resource: "modadminextraf8x,31ad" +access_rules: + vcard_set: + - allow: adminextraresource +modules: + mod_admin_extra: {} + mod_vcard: + access_set: vcard_set +~~~ + +Content of roster file for *pushroster* command: + +~~~ yaml +[{<<"bob">>, <<"example.org">>, <<"workers">>, <<"Bob">>}, +{<<"mart">>, <<"example.org">>, <<"workers">>, <<"Mart">>}, +{<<"Rich">>, <<"example.org">>, <<"bosses">>, <<"Rich">>}]. +~~~ + +With this call, the sessions of the local account which JID is + will be kicked, and its password will be set to +something like +*BANNED\_ACCOUNT—20080425T21:45:07—2176635—Spammed\_rooms* + +~~~ yaml +ejabberdctl vhost example.org ban_account boby "Spammed rooms" +~~~ + +Call to srg\_create using double-quotes and single-quotes: + +~~~ yaml +ejabberdctl srg_create g1 example.org "'Group number 1'" this_is_g1 g1 +~~~ + +mod\_admin\_update\_sql +----------------------- + +This module can be used to update existing SQL database from the default +to the new schema. Check the section +[Default and New Schemas](../../admin/configuration/database.md#default-and-new-schemas) for +details. Please note that only MS SQL, MySQL, and PostgreSQL are +supported. When the module is loaded use [update_sql](../../developer/ejabberd-api/admin-api.md#update_sql) API. + +The module has no options. + +mod\_announce +------------- + +This module enables configured users to broadcast announcements and to +set the message of the day (MOTD). Configured users can perform these +actions with an XMPP client either using Ad-hoc Commands or sending +messages to specific JIDs. + +Note that this module can be resource intensive on large deployments as +it may broadcast a lot of messages. This module should be disabled for +instances of ejabberd with hundreds of thousands users. + +The Ad-hoc Commands are listed in the Server Discovery. For this feature +to work, [mod_adhoc](#mod_adhoc) must be enabled. + +The specific JIDs where messages can be sent are listed below. The first +JID in each entry will apply only to the specified virtual host +example.org, while the JID between brackets will apply to all virtual +hosts in ejabberd: + +- example.org/announce/all (example.org/announce/all-hosts/all):: The + message is sent to all registered users. If the user is online and + connected to several resources, only the resource with the highest + priority will receive the message. If the registered user is not + connected, the message will be stored offline in assumption that + offline storage (see [mod_offline](#mod_offline)) is enabled. + +- example.org/announce/online + (example.org/announce/all-hosts/online):: The message is sent to all + connected users. If the user is online and connected to several + resources, all resources will receive the message. + +- example.org/announce/motd (example.org/announce/all-hosts/motd):: + The message is set as the message of the day (MOTD) and is sent to + users when they login. In addition the message is sent to all + connected users (similar to announce/online). + +- example.org/announce/motd/update + (example.org/announce/all-hosts/motd/update):: The message is set as + message of the day (MOTD) and is sent to users when they login. The + message is not sent to any currently connected user. + +- example.org/announce/motd/delete + (example.org/announce/all-hosts/motd/delete):: Any message sent to + this JID removes the existing message of the day (MOTD). + +__Available options:__ + +- **access**: *AccessName* +This option specifies who is allowed to send announcements and to set +the message of the day. The default value is *none* (i.e. nobody is able +to send such messages). + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed**: *true | false* +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +mod\_avatar +----------- + +The purpose of the module is to cope with legacy and modern XMPP clients +posting avatars. The process is described in [XEP-0398: User Avatar to +vCard-Based Avatars +Conversion](https://xmpp.org/extensions/xep-0398.html). + +Also, the module supports conversion between avatar image formats on the +fly. + +The module depends on [mod_vcard](#mod_vcard), [mod_vcard_xupdate](#mod_vcard_xupdate) and +[mod_pubsub](#mod_pubsub). + +__Available options:__ + +- **convert**: *{From: To}* +Defines image conversion rules: the format in *From* will be converted +to format in *To*. The value of *From* can also be *default*, which is +match-all rule. NOTE: the list of supported formats is detected at +compile time depending on the image libraries installed in the system. + + **Example**: + + ~~~ yaml + convert: + webp: jpg + default: png + ~~~ + +- **rate\_limit**: *Number* +Limit any given JID by the number of avatars it is able to convert per +minute. This is to protect the server from image conversion DoS. The +default value is *10*. + +mod\_block\_strangers +--------------------- + +This module blocks and logs any messages coming from an unknown entity. +If a writing entity is not in your roster, you can let this module drop +and/or log the message. By default you’ll just not receive message from +that entity. Enable this module if you want to drop SPAM messages. + +__Available options:__ + +- **access**: *AccessName* +The option is supposed to be used when *allow\_local\_users* and +*allow\_transports* are not enough. It’s an ACL where *deny* means the +message will be rejected (or a CAPTCHA would be generated for a +presence, if configured), and *allow* means the sender is whitelisted +and the stanza will pass through. The default value is *none*, which +means nothing is whitelisted. + +- **allow\_local\_users**: *true | false* +This option specifies if strangers from the same local host should be +accepted or not. The default value is *true*. + +- **allow\_transports**: *true | false* +If set to *true* and some server’s JID is in user’s roster, then +messages from any user of this server are accepted even if no +subscription present. The default value is *true*. + +- **captcha**: *true | false* +Whether to generate CAPTCHA or not in response to messages from +strangers. See also section [CAPTCHA](../../admin/configuration/basic.md#captcha) of the +Configuration Guide. The default value is *false*. + +- **drop**: *true | false* +This option specifies if strangers messages should be dropped or not. +The default value is *true*. + +- **log**: *true | false* +This option specifies if strangers' messages should be logged (as info +message) in ejabberd.log. The default value is *false*. + +mod\_blocking +------------- + +The module implements [XEP-0191: Blocking +Command](https://xmpp.org/extensions/xep-0191.html). + +This module depends on *mod\_privacy* where all the configuration is +performed. + +The module has no options. + +mod\_bosh +--------- + +This module implements XMPP over BOSH as defined in +[XEP-0124](https://xmpp.org/extensions/xep-0124.html) and +[XEP-0206](https://xmpp.org/extensions/xep-0206.html). BOSH stands for +Bidirectional-streams Over Synchronous HTTP. It makes it possible to +simulate long lived connections required by XMPP over the HTTP protocol. +In practice, this module makes it possible to use XMPP in a browser +without WebSocket support and more generally to have a way to use XMPP +while having to get through an HTTP proxy. + +__Available options:__ + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed**: *true | false* +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **json**: *true | false* +This option has no effect. + +- **max\_concat**: *pos\_integer() | infinity* +This option limits the number of stanzas that the server will send in a +single bosh request. The default value is *unlimited*. + +- **max\_inactivity**: *timeout()* +The option defines the maximum inactivity period. The default value is +*30* seconds. + +- **max\_pause**: *pos\_integer()* +Indicate the maximum length of a temporary session pause (in seconds) +that a client can request. The default value is *120*. + +- **prebind**: *true | false* +If enabled, the client can create the session without going through +authentication. Basically, it creates a new session with anonymous +authentication. The default value is *false*. + +- **queue\_type**: *ram | file* +Same as top-level [queue_type](toplevel.md#queue_type) option, but applied to this module +only. + +- **ram\_db\_type**: *mnesia | sql | redis* +Same as top-level [default_ram_db](toplevel.md#default_ram_db) option, but applied to this module +only. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +__**Example**:__ + +~~~ yaml +listen: + - + port: 5222 + module: ejabberd_c2s + - + port: 5443 + module: ejabberd_http + request_handlers: + /bosh: mod_bosh + +modules: + mod_bosh: {} +~~~ + +mod\_caps +--------- + +This module implements [XEP-0115: Entity +Capabilities](https://xmpp.org/extensions/xep-0115.html). The main +purpose of the module is to provide PEP functionality (see +[mod_pubsub](#mod_pubsub)). + +__Available options:__ + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed**: *true | false* +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +mod\_carboncopy +--------------- + +The module implements [XEP-0280: Message +Carbons](https://xmpp.org/extensions/xep-0280.html). The module +broadcasts messages on all connected user resources (devices). + +The module has no options. + +mod\_client\_state +------------------ + +This module allows for queueing certain types of stanzas when a client +indicates that the user is not actively using the client right now (see +[XEP-0352: Client State +Indication](https://xmpp.org/extensions/xep-0352.html)). This can save +bandwidth and resources. + +A stanza is dropped from the queue if it’s effectively obsoleted by a +new one (e.g., a new presence stanza would replace an old one from the +same client). The queue is flushed if a stanza arrives that won’t be +queued, or if the queue size reaches a certain limit (currently 100 +stanzas), or if the client becomes active again. + +__Available options:__ + +- **queue\_chat\_states**: *true | false* +Queue "standalone" chat state notifications (as defined in [XEP-0085: +Chat State Notifications](https://xmpp.org/extensions/xep-0085.html)) +while a client indicates inactivity. The default value is *true*. + +- **queue\_pep**: *true | false* +Queue PEP notifications while a client is inactive. When the queue is +flushed, only the most recent notification of a given PEP node is +delivered. The default value is *true*. + +- **queue\_presence**: *true | false* +While a client is inactive, queue presence stanzas that indicate +(un)availability. The default value is *true*. + +mod\_configure +-------------- + +The module provides server configuration functionality via [XEP-0050: +Ad-Hoc Commands](https://xmpp.org/extensions/xep-0050.html). Implements +many commands as defined in [XEP-0133: Service +Administration](https://xmpp.org/extensions/xep-0133.html). This module +requires [mod_adhoc](#mod_adhoc) to be loaded. + +The module has no options. + +mod\_conversejs +--------------- + + + + +This module serves a simple page for the +[Converse](https://conversejs.org/) XMPP web browser client. + +To use this module, in addition to adding it to the *modules* section, +you must also enable it in *listen* → *ejabberd\_http* → +[request_handlers](listen-options.md#request_handlers). + +Make sure either *mod\_bosh* or *ejabberd\_http\_ws* +[request_handlers](listen-options.md#request_handlers) are enabled. + +When *conversejs\_css* and *conversejs\_script* are *auto*, by default +they point to the public Converse client. + +__Available options:__ + +- **bosh\_service\_url**: *auto | BoshURL* +BOSH service URL to which Converse can connect to. The keyword *@HOST@* +is replaced with the real virtual host name. If set to *auto*, it will +build the URL of the first configured BOSH request handler. The default +value is *auto*. + +- **conversejs\_css**: *auto | URL* +Converse CSS URL. The keyword *@HOST@* is replaced with the hostname. +The default value is *auto*. + +- **conversejs\_options**: *{Name: Value}* + + Specify additional options to +be passed to Converse. See [Converse +configuration](https://conversejs.org/docs/html/configuration.html). +Only boolean, integer and string values are supported; lists are not +supported. + +- **conversejs\_resources**: *Path* + + Local path to the Converse +files. If not set, the public Converse client will be used instead. + +- **conversejs\_script**: *auto | URL* +Converse main script URL. The keyword *@HOST@* is replaced with the +hostname. The default value is *auto*. + +- **default\_domain**: *Domain* +Specify a domain to act as the default for user JIDs. The keyword +*@HOST@* is replaced with the hostname. The default value is *@HOST@*. + +- **websocket\_url**: *auto | WebSocketURL* +A WebSocket URL to which Converse can connect to. The keyword *@HOST@* +is replaced with the real virtual host name. If set to *auto*, it will +build the URL of the first configured WebSocket request handler. The +default value is *auto*. + +__Examples:__ + +Manually setup WebSocket url, and use the public Converse client: + +~~~ yaml +listen: + - + port: 5280 + module: ejabberd_http + request_handlers: + /bosh: mod_bosh + /websocket: ejabberd_http_ws + /conversejs: mod_conversejs + +modules: + mod_bosh: {} + mod_conversejs: + websocket_url: "ws://@HOST@:5280/websocket" +~~~ + +Host Converse locally and let auto detection of WebSocket and Converse +URLs: + +~~~ yaml +listen: + - + port: 443 + module: ejabberd_http + tls: true + request_handlers: + /websocket: ejabberd_http_ws + /conversejs: mod_conversejs + +modules: + mod_conversejs: + conversejs_resources: "/home/ejabberd/conversejs-9.0.0/package/dist" +~~~ + +Configure some additional options for Converse + +~~~ yaml +modules: + mod_conversejs: + websocket_url: auto + conversejs_options: + auto_away: 30 + clear_cache_on_logout: true + i18n: "pt" + locked_domain: "@HOST@" + message_archiving: always + theme: dracula +~~~ + +mod\_delegation +--------------- + +This module is an implementation of [XEP-0355: Namespace +Delegation](https://xmpp.org/extensions/xep-0355.html). Only admin mode +has been implemented by now. Namespace delegation allows external +services to handle IQ using specific namespace. This may be applied for +external PEP service. + +> **Warning** +> +> Security issue: Namespace delegation gives components access to +> sensitive data, so permission should be granted carefully, only if you +> trust the component. + +> **Note** +> +> This module is complementary to [mod_privilege](#mod_privilege) but can also be used +> separately. + +__Available options:__ + +- **namespaces**: *{Namespace: Options}* +If you want to delegate namespaces to a component, specify them in this +option, and associate them to an access rule. The *Options* are: + + - **access**: *AccessName* + The option defines which components are + allowed for namespace delegation. The default value is *none*. + + - **filtering**: *Attributes* + The list of attributes. Currently not + used. + +__Examples:__ + +Make sure you do not delegate the same namespace to several services at +the same time. As in the example provided later, to have the +*sat-pubsub.example.org* component perform correctly disable the +*mod\_pubsub* module. + +~~~ yaml +access_rules: + external_pubsub: + allow: external_component + external_mam: + allow: external_component + +acl: + external_component: + server: sat-pubsub.example.org + +modules: + mod_delegation: + namespaces: + urn:xmpp:mam:1: + access: external_mam + http://jabber.org/protocol/pubsub: + access: external_pubsub +~~~ + +mod\_disco +---------- + +This module adds support for [XEP-0030: Service +Discovery](https://xmpp.org/extensions/xep-0030.html). With this module +enabled, services on your server can be discovered by XMPP clients. + +__Available options:__ + +- **extra\_domains**: *\[Domain, ...\]* +With this option, you can specify a list of extra domains that are added +to the Service Discovery item list. The default value is an empty list. + +- **name**: *Name* +A name of the server in the Service Discovery. This will only be +displayed by special XMPP clients. The default value is *ejabberd*. + +- **server\_info**: *\[Info, ...\]* +Specify additional information about the server, as described in +[XEP-0157: Contact Addresses for XMPP +Services](https://xmpp.org/extensions/xep-0157.html). Every *Info* +element in the list is constructed from the following options: + + - **modules**: *all | \[Module, ...\]* + The value can be the keyword + *all*, in which case the information is reported in all the + services, or a list of ejabberd modules, in which case the + information is only specified for the services provided by those + modules. + + - **name**: *Name* + The field *var* name that will be defined. See + XEP-0157 for some standardized names. + + - **urls**: *\[URI, ...\]* + A list of contact URIs, such as HTTP URLs, + XMPP URIs and so on. + + **Example**: + + ~~~ yaml + server_info: + - + modules: all + name: abuse-addresses + urls: ["mailto:abuse@shakespeare.lit"] + - + modules: [mod_muc] + name: "Web chatroom logs" + urls: ["http://www.example.org/muc-logs"] + - + modules: [mod_disco] + name: feedback-addresses + urls: + - http://shakespeare.lit/feedback.php + - mailto:feedback@shakespeare.lit + - xmpp:feedback@shakespeare.lit + - + modules: + - mod_disco + - mod_vcard + name: admin-addresses + urls: + - mailto:xmpp@shakespeare.lit + - xmpp:admins@shakespeare.lit + ~~~ + +mod\_fail2ban +------------- + +The module bans IPs that show the malicious signs. Currently only C2S +authentication failures are detected. + +Unlike the standalone program, *mod\_fail2ban* clears the record of +authentication failures after some time since the first failure or on a +successful authentication. It also does not simply block network +traffic, but provides the client with a descriptive error message. + +> **Warning** +> +> You should not use this module behind a proxy or load balancer. +> ejabberd will see the failures as coming from the load balancer and, +> when the threshold of auth failures is reached, will reject all +> connections coming from the load balancer. You can lock all your user +> base out of ejabberd when using this module behind a proxy. + +__Available options:__ + +- **access**: *AccessName* +Specify an access rule for whitelisting IP addresses or networks. If the +rule returns *allow* for a given IP address, that address will never be +banned. The *AccessName* should be of type *ip*. The default value is +*none*. + +- **c2s\_auth\_ban\_lifetime**: *timeout()* +The lifetime of the IP ban caused by too many C2S authentication +failures. The default value is *1* hour. + +- **c2s\_max\_auth\_failures**: *Number* +The number of C2S authentication failures to trigger the IP ban. The +default value is *20*. + +mod\_host\_meta +--------------- + + + + +This module serves small *host-meta* files as described in [XEP-0156: +Discovering Alternative XMPP Connection +Methods](https://xmpp.org/extensions/xep-0156.html). + +To use this module, in addition to adding it to the *modules* section, +you must also enable it in *listen* → *ejabberd\_http* → +[request_handlers](listen-options.md#request_handlers). + +Notice it only works if ejabberd\_http has tls enabled. + +__Available options:__ + +- **bosh\_service\_url**: *undefined | auto | BoshURL* +BOSH service URL to announce. The keyword *@HOST@* is replaced with the +real virtual host name. If set to *auto*, it will build the URL of the +first configured BOSH request handler. The default value is *auto*. + +- **websocket\_url**: *undefined | auto | WebSocketURL* +WebSocket URL to announce. The keyword *@HOST@* is replaced with the +real virtual host name. If set to *auto*, it will build the URL of the +first configured WebSocket request handler. The default value is *auto*. + +__**Example**:__ + +~~~ yaml +listen: + - + port: 443 + module: ejabberd_http + tls: true + request_handlers: + /bosh: mod_bosh + /ws: ejabberd_http_ws + /.well-known/host-meta: mod_host_meta + /.well-known/host-meta.json: mod_host_meta + +modules: + mod_bosh: {} + mod_host_meta: + bosh_service_url: "https://@HOST@:5443/bosh" + websocket_url: "wss://@HOST@:5443/ws" +~~~ + +mod\_http\_api +-------------- + +This module provides a ReST interface to call +[ejabberd API](../../developer/ejabberd-api/index.md) commands using +JSON data. + +To use this module, in addition to adding it to the *modules* section, +you must also enable it in *listen* → *ejabberd\_http* → +[request_handlers](listen-options.md#request_handlers). + +To use a specific API version N, when defining the URL path in the +request\_handlers, add a *vN*. For example: */api/v2: mod\_http\_api* + +To run a command, send a POST request to the corresponding URL: +*http://localhost:5280/api/<command\_name>* + +The module has no options. + +__**Example**:__ + +~~~ yaml +listen: + - + port: 5280 + module: ejabberd_http + request_handlers: + /api: mod_http_api + +modules: + mod_http_api: {} +~~~ + +mod\_http\_fileserver +--------------------- + +This simple module serves files from the local disk over HTTP. + +__Available options:__ + +- **accesslog**: *Path* +File to log accesses using an Apache-like format. No log will be +recorded if this option is not specified. + +- **content\_types**: *{Extension: Type}* +Specify mappings of extension to content type. There are several content +types already defined. With this option you can add new definitions or +modify existing ones. The default values are: + + **Example**: + + ~~~ yaml + content_types: + .css: text/css + .gif: image/gif + .html: text/html + .jar: application/java-archive + .jpeg: image/jpeg + .jpg: image/jpeg + .js: text/javascript + .png: image/png + .svg: image/svg+xml + .txt: text/plain + .xml: application/xml + .xpi: application/x-xpinstall + .xul: application/vnd.mozilla.xul+xml + ~~~ + +- **custom\_headers**: *{Name: Value}* +Indicate custom HTTP headers to be included in all responses. There are +no custom headers by default. + +- **default\_content\_type**: *Type* +Specify the content type to use for unknown extensions. The default +value is *application/octet-stream*. + +- **directory\_indices**: *\[Index, ...\]* +Indicate one or more directory index files, similarly to Apache’s +*DirectoryIndex* variable. When an HTTP request hits a directory instead +of a regular file, those directory indices are looked in order, and the +first one found is returned. The default value is an empty list. + +- **docroot**: *Path* +Directory to serve the files from. This is a mandatory option. + +- **must\_authenticate\_with**: *\[{Username, Hostname}, ...\]* +List of accounts that are allowed to use this service. Default value: +*\[\]*. + +__Examples:__ + +This example configuration will serve the files from the local directory +*/var/www* in the address *http://example.org:5280/pub/content/*. In +this example a new content type *ogg* is defined, *png* is redefined, +and *jpg* definition is deleted: + +~~~ yaml +listen: + - + port: 5280 + module: ejabberd_http + request_handlers: + /pub/content: mod_http_fileserver + +modules: + mod_http_fileserver: + docroot: /var/www + accesslog: /var/log/ejabberd/access.log + directory_indices: + - index.html + - main.htm + custom_headers: + X-Powered-By: Erlang/OTP + X-Fry: "It's a widely-believed fact!" + content_types: + .ogg: audio/ogg + .png: image/png + default_content_type: text/html +~~~ + +mod\_http\_upload +----------------- + +This module allows for requesting permissions to upload a file via HTTP +as described in [XEP-0363: HTTP File +Upload](https://xmpp.org/extensions/xep-0363.html). If the request is +accepted, the client receives a URL for uploading the file and another +URL from which that file can later be downloaded. + +In order to use this module, it must be enabled in *listen* → +*ejabberd\_http* → +[request_handlers](listen-options.md#request_handlers). + +__Available options:__ + +- **access**: *AccessName* +This option defines the access rule to limit who is permitted to use the +HTTP upload service. The default value is *local*. If no access rule of +that name exists, no user will be allowed to use the service. + +- **custom\_headers**: *{Name: Value}* +This option specifies additional header fields to be included in all +HTTP responses. By default no custom headers are included. + +- **dir\_mode**: *Permission* +This option defines the permission bits of the *docroot* directory and +any directories created during file uploads. The bits are specified as +an octal number (see the chmod(1) manual page) within double quotes. For +example: "0755". The default is undefined, which means no explicit +permissions will be set. + +- **docroot**: *Path* +Uploaded files are stored below the directory specified (as an absolute +path) with this option. The keyword @HOME@ is replaced with the home +directory of the user running ejabberd, and the keyword @HOST@ with the +virtual host name. The default value is "@HOME@/upload". + +- **external\_secret**: *Text* +This option makes it possible to offload all HTTP Upload processing to a +separate HTTP server. Both ejabberd and the HTTP server should share +this secret and behave exactly as described at [Prosody’s +mod\_http\_upload\_external](https://modules.prosody.im/mod_http_upload_external.html) +in the *Implementation* section. There is no default value. + +- **file\_mode**: *Permission* +This option defines the permission bits of uploaded files. The bits are +specified as an octal number (see the chmod(1) manual page) within +double quotes. For example: "0644". The default is undefined, which +means no explicit permissions will be set. + +- **get\_url**: *URL* +This option specifies the initial part of the GET URLs used for +downloading the files. The default value is *undefined*. When this +option is *undefined*, this option is set to the same value as +*put\_url*. The keyword @HOST@ is replaced with the virtual host name. +NOTE: if GET requests are handled by *mod\_http\_upload*, the *get\_url* +must match the *put\_url*. Setting it to a different value only makes +sense if an external web server or [mod_http_fileserver](#mod_http_fileserver) is used to +serve the uploaded files. + +- **host** +Deprecated. Use *hosts* instead. + +- **hosts**: *\[Host, ...\]* +This option defines the Jabber IDs of the service. If the *hosts* option +is not specified, the only Jabber ID will be the hostname of the virtual +host with the prefix "upload.". The keyword *@HOST@* is replaced with +the real virtual host name. + +- **jid\_in\_url**: *node | sha1* +When this option is set to *node*, the node identifier of the user’s JID +(i.e., the user name) is included in the GET and PUT URLs generated by +*mod\_http\_upload*. Otherwise, a SHA-1 hash of the user’s bare JID is +included instead. The default value is *sha1*. + +- **max\_size**: *Size* +This option limits the acceptable file size. Either a number of bytes +(larger than zero) or *infinity* must be specified. The default value is +*104857600*. + +- **name**: *Name* +A name of the service in the Service Discovery. This will only be +displayed by special XMPP clients. The default value is "HTTP File +Upload". + +- **put\_url**: *URL* +This option specifies the initial part of the PUT URLs used for file +uploads. The keyword @HOST@ is replaced with the virtual host name. +NOTE: different virtual hosts cannot use the same PUT URL. The default +value is "https://@HOST@:5443/upload". + +- **rm\_on\_unregister**: *true | false* +This option specifies whether files uploaded by a user should be removed +when that user is unregistered. The default value is *true*. + +- **secret\_length**: *Length* +This option defines the length of the random string included in the GET +and PUT URLs generated by *mod\_http\_upload*. The minimum length is 8 +characters, but it is recommended to choose a larger value. The default +value is *40*. + +- **service\_url** +Deprecated. + +- **thumbnail**: *true | false* +This option specifies whether ejabberd should create thumbnails of +uploaded images. If a thumbnail is created, a <thumbnail/> element +that contains the download <uri/> and some metadata is returned +with the PUT response. The default value is *false*. + +- **vcard**: *vCard* +A custom vCard of the service that will be displayed by some XMPP +clients in Service Discovery. The value of *vCard* is a YAML map +constructed from an XML representation of vCard. Since the +representation has no attributes, the mapping is straightforward. + + **Example**: + + ~~~ yaml + # This XML representation of vCard: + # + # Conferences + # + # + # Elm Street + # + # + # + # is translated to: + vcard: + fn: Conferences + adr: + - + work: true + street: Elm Street + ~~~ + +__**Example**:__ + +~~~ yaml +listen: + - + port: 5443 + module: ejabberd_http + tls: true + request_handlers: + /upload: mod_http_upload + +modules: + mod_http_upload: + docroot: /ejabberd/upload + put_url: "https://@HOST@:5443/upload" +~~~ + +mod\_http\_upload\_quota +------------------------ + +This module adds quota support for mod\_http\_upload. + +This module depends on *mod\_http\_upload*. + +__Available options:__ + +- **access\_hard\_quota**: *AccessName* +This option defines which access rule is used to specify the "hard +quota" for the matching JIDs. That rule must yield a positive number for +any JID that is supposed to have a quota limit. This is the number of +megabytes a corresponding user may upload. When this threshold is +exceeded, ejabberd deletes the oldest files uploaded by that user until +their disk usage equals or falls below the specified soft quota (see +*access\_soft\_quota*). The default value is *hard\_upload\_quota*. + +- **access\_soft\_quota**: *AccessName* +This option defines which access rule is used to specify the "soft +quota" for the matching JIDs. That rule must yield a positive number of +megabytes for any JID that is supposed to have a quota limit. See the +description of the *access\_hard\_quota* option for details. The default +value is *soft\_upload\_quota*. + +- **max\_days**: *Days* +If a number larger than zero is specified, any files (and directories) +older than this number of days are removed from the subdirectories of +the *docroot* directory, once per day. The default value is *infinity*. + +__Examples:__ + +Please note that it’s not necessary to specify the *access\_hard\_quota* +and *access\_soft\_quota* options in order to use the quota feature. You +can stick to the default names and just specify access rules such as +those in this example: + +~~~ yaml +shaper_rules: + soft_upload_quota: + 1000: all # MiB + hard_upload_quota: + 1100: all # MiB + +modules: + mod_http_upload: {} + mod_http_upload_quota: + max_days: 100 +~~~ + +mod\_jidprep +------------ + +This module allows XMPP clients to ask the server to normalize a JID as +per the rules specified in [RFC 6122: XMPP Address +Format](https://tools.ietf.org/html/rfc6122). This might be useful for +clients in certain constrained environments, or for testing purposes. + +__Available options:__ + +- **access**: *AccessName* +This option defines which access rule will be used to control who is +allowed to use this service. The default value is *local*. + +mod\_last +--------- + +This module adds support for [XEP-0012: Last +Activity](https://xmpp.org/extensions/xep-0012.html). It can be used to +discover when a disconnected user last accessed the server, to know when +a connected user was last active on the server, or to query the uptime +of the ejabberd server. + +__Available options:__ + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed**: *true | false* +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +mod\_legacy\_auth +----------------- + +The module implements [XEP-0078: Non-SASL +Authentication](https://xmpp.org/extensions/xep-0078.html). + +> **Note** +> +> This type of authentication was obsoleted in 2008 and you unlikely +> need this module unless you have something like outdated Jabber bots. + +The module has no options. + +mod\_mam +-------- + +This module implements [XEP-0313: Message Archive +Management](https://xmpp.org/extensions/xep-0313.html) and [XEP-0441: +Message Archive Management +Preferences](https://xmpp.org/extensions/xep-0441.html). Compatible XMPP +clients can use it to store their chat history on the server. + +__Available options:__ + +- **access\_preferences**: *AccessName* +This access rule defines who is allowed to modify the MAM preferences. +The default value is *all*. + +- **assume\_mam\_usage**: *true | false* +This option determines how ejabberd’s stream management code (see +[mod_stream_mgmt](#mod_stream_mgmt)) handles unacknowledged messages when the connection +is lost. Usually, such messages are either bounced or resent. However, +neither is done for messages that were stored in the user’s MAM archive +if this option is set to *true*. In this case, ejabberd assumes those +messages will be retrieved from the archive. The default value is +*false*. + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed**: *true | false* +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **clear\_archive\_on\_room\_destroy**: *true | false* +Whether to destroy message archive of a room (see [mod_muc](#mod_muc)) when it +gets destroyed. The default value is *true*. + +- **compress\_xml**: *true | false* +When enabled, new messages added to archives are compressed using a +custom compression algorithm. This feature works only with SQL backends. +The default value is *false*. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **default**: *always | never | roster* +The option defines default policy for chat history. When *always* is set +every chat message is stored. With *roster* only chat history with +contacts from user’s roster is stored. And *never* fully disables chat +history. Note that a client can change its policy via protocol commands. +The default value is *never*. + +- **request\_activates\_archiving**: *true | false* +If the value is *true*, no messages are stored for a user until their +client issue a MAM request, regardless of the value of the *default* +option. Once the server received a request, that user’s messages are +archived as usual. The default value is *false*. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +- **user\_mucsub\_from\_muc\_archive**: *true | false* +When this option is disabled, for each individual subscriber a separate +mucsub message is stored. With this option enabled, when a user fetches +archive virtual mucsub, messages are generated from muc archives. The +default value is *false*. + +mod\_matrix\_gw 🟤 +------------------ + + + + +[Matrix](https://matrix.org/) gateway. + +__Available options:__ + +- **host**: *Host* +This option defines the Jabber IDs of the service. If the *host* option +is not specified, the Jabber ID will be the hostname of the virtual host +with the prefix *"matrix."*. The keyword *@HOST@* is replaced with the +real virtual host name. + +- **key**: *string()* +Value of the matrix signing key, in base64. + +- **key\_name**: *string()* +Name of the matrix signing key. + +- **matrix\_domain**: *Domain* +Specify a domain in the Matrix federation. The keyword *@HOST@* is +replaced with the hostname. The default value is *@HOST@*. + +- **matrix\_id\_as\_jid**: *true | false* +If set to *false*, all packets failing to be delivered via an XMPP +server-to-server connection will then be routed to the Matrix gateway by +translating a Jabber ID *user@matrixdomain.tld* to a Matrix user +identifier *@user:matrixdomain.tld*. When set to *true*, messages must +be explicitly sent to the matrix gateway service Jabber ID to be routed +to a remote Matrix server. In this case, to send a message to Matrix +user *@user:matrixdomain.tld*, the client must send a message to the JID +*user%.tld*, where +*matrix.myxmppdomain.tld* is the JID of the gateway service as set by +the *host* option. The default is *false*. + +__**Example**:__ + +~~~ yaml +listen: + - + port: 8448 + module: ejabberd_http + tls: true + request_handlers: + "/_matrix": mod_matrix_gw + +modules: + mod_matrix_gw: + key_name: "key1" + key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" + matrix_id_as_jid: true +~~~ + +mod\_metrics +------------ + +This module sends events to external backend (by now only +[grapherl](https://github.com/processone/grapherl) is supported). +Supported events are: + +- sm\_register\_connection + +- sm\_remove\_connection + +- user\_send\_packet + +- user\_receive\_packet + +- s2s\_send\_packet + +- s2s\_receive\_packet + +- register\_user + +- remove\_user + +- offline\_message + +When enabled, every call to these hooks triggers a counter event to be +sent to the external backend. + +__Available options:__ + +- **ip**: *IPv4Address* +IPv4 address where the backend is located. The default value is +*127.0.0.1*. + +- **port**: *Port* +An internet port number at which the backend is listening for incoming +connections/packets. The default value is *11111*. + +mod\_mix +-------- + + + + +This module is an experimental implementation of [XEP-0369: Mediated +Information eXchange (MIX)](https://xmpp.org/extensions/xep-0369.html). +It’s asserted that the MIX protocol is going to replace the MUC protocol +in the future (see [mod_muc](#mod_muc)). + +To learn more about how to use that feature, you can refer to our +tutorial: [Getting started with MIX](../../tutorials/mix-010.md) + +The module depends on [mod_mam](#mod_mam). + +__Available options:__ + +- **access\_create**: *AccessName* +An access rule to control MIX channels creations. The default value is +*all*. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **host** +Deprecated. Use *hosts* instead. + +- **hosts**: *\[Host, ...\]* +This option defines the Jabber IDs of the service. If the *hosts* option +is not specified, the only Jabber ID will be the hostname of the virtual +host with the prefix "mix.". The keyword *@HOST@* is replaced with the +real virtual host name. + +- **name**: *Name* +A name of the service in the Service Discovery. This will only be +displayed by special XMPP clients. The default value is *Channels*. + +mod\_mix\_pam +------------- + +This module implements [XEP-0405: Mediated Information eXchange (MIX): +Participant Server +Requirements](https://xmpp.org/extensions/xep-0405.html). The module is +needed if MIX compatible clients on your server are going to join MIX +channels (either on your server or on any remote servers). + +> **Note** +> +> *mod\_mix* is not required for this module to work, however, without +> *mod\_mix\_pam* the MIX functionality of your local XMPP clients will +> be impaired. + +__Available options:__ + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed**: *true | false* +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +mod\_mqtt +--------- + +This module adds [support for the MQTT](../../admin/guide/mqtt/index.md) +protocol version *3.1.1* and *5.0*. Remember to configure *mod\_mqtt* in +*modules* and *listen* sections. + +__Available options:__ + +- **access\_publish**: *{TopicFilter: AccessName}* +Access rules to restrict access to topics for publishers. By default +there are no restrictions. + +- **access\_subscribe**: *{TopicFilter: AccessName}* +Access rules to restrict access to topics for subscribers. By default +there are no restrictions. + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed**: *true | false* +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **match\_retained\_limit**: *pos\_integer() | infinity* +The option limits the number of retained messages returned to a client +when it subscribes to some topic filter. The default value is *1000*. + +- **max\_queue**: *Size* +Maximum queue size for outgoing packets. The default value is *5000*. + +- **max\_topic\_aliases**: *0..65535* +The maximum number of aliases a client is able to associate with the +topics. The default value is *100*. + +- **max\_topic\_depth**: *Depth* +The maximum topic depth, i.e. the number of slashes (*/*) in the topic. +The default value is *8*. + +- **queue\_type**: *ram | file* +Same as top-level [queue_type](toplevel.md#queue_type) option, but applied to this module +only. + +- **ram\_db\_type**: *mnesia* +Same as top-level [default_ram_db](toplevel.md#default_ram_db) option, but applied to this module +only. + +- **session\_expiry**: *timeout()* +The option specifies how long to wait for an MQTT session resumption. +When *0* is set, the session gets destroyed when the underlying client +connection is closed. The default value is *5* minutes. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +mod\_mqtt\_bridge +----------------- + +This module adds ability to synchronize local MQTT topics with data on +remote servers It can update topics on remote servers when local user +updates local topic, or can subscribe for changes on remote server, and +update local copy when remote data is updated. It is available since +ejabberd [23.01](../../archive/23.01/index.md). + +__Available options:__ + +- **replication\_user**: *JID* +Identifier of a user that will be assigned as owner of local changes. + +- **servers**: *{ServerUrl: {publish: \[TopicPairs, subscribe: \[TopicPairs\], authentication: \[AuthInfo\]}}\]* +Declaration of data to share, must contain *publish* or *subscribe* or +both, and *authentication* section with username/password field or +certfile pointing to client certificate. Accepted urls can use schema +mqtt, mqtts (mqtt with tls), mqtt5, mqtt5s (both to trigger v5 +protocol), ws, wss, ws5, wss5. Certificate authentication can be only +used with mqtts, mqtt5s, wss, wss5. + +__**Example**:__ + +~~~ yaml +modules: + mod_mqtt_bridge: + servers: + "mqtt://server.com": + publish: + "localA": "remoteA" # local changes to 'localA' will be replicated on remote server as 'remoteA' + "topicB": "topicB" + subscribe: + "remoteB": "localB" # changes to 'remoteB' on remote server will be stored as 'localB' on local server + authentication: + certfile: "/etc/ejabberd/mqtt_server.pem" + replication_user: "mqtt@xmpp.server.com" +~~~ + +mod\_muc +-------- + +This module provides support for [XEP-0045: Multi-User +Chat](https://xmpp.org/extensions/xep-0045.html). Users can discover +existing rooms, join or create them. Occupants of a room can chat in +public or have private chats. + +The MUC service allows any Jabber ID to register a nickname, so nobody +else can use that nickname in any room in the MUC service. To register a +nickname, open the Service Discovery in your XMPP client and register in +the MUC service. + +It is also possible to register a nickname in a room, so nobody else can +use that nickname in that room. If a nick is registered in the MUC +service, that nick cannot be registered in any room, and vice versa: a +nick that is registered in a room cannot be registered at the MUC +service. + +This module supports clustering and load balancing. One module can be +started per cluster node. Rooms are distributed at creation time on all +available MUC module instances. The multi-user chat module is clustered +but the rooms themselves are not clustered nor fault-tolerant: if the +node managing a set of rooms goes down, the rooms disappear and they +will be recreated on an available node on first connection attempt. + +__Available options:__ + +- **access**: *AccessName* +You can specify who is allowed to use the Multi-User Chat service. By +default everyone is allowed to use it. + +- **access\_admin**: *AccessName* +This option specifies who is allowed to administrate the Multi-User Chat +service. The default value is *none*, which means that only the room +creator can administer their room. The administrators can send a normal +message to the service JID, and it will be shown in all active rooms as +a service message. The administrators can send a groupchat message to +the JID of an active room, and the message will be shown in the room as +a service message. + +- **access\_create**: *AccessName* +To configure who is allowed to create new rooms at the Multi-User Chat +service, this option can be used. The default value is *all*, which +means everyone is allowed to create rooms. + +- **access\_mam**: *AccessName* +To configure who is allowed to modify the *mam* room option. The default +value is *all*, which means everyone is allowed to modify that option. + +- **access\_persistent**: *AccessName* +To configure who is allowed to modify the *persistent* room option. The +default value is *all*, which means everyone is allowed to modify that +option. + +- **access\_register**: *AccessName* + + This option specifies who +is allowed to register nickname within the Multi-User Chat service and +rooms. The default is *all* for backward compatibility, which means that +any user is allowed to register any free nick in the MUC service and in +the rooms. + +- **cleanup\_affiliations\_on\_start**: *true | false* + + Remove affiliations for +non-existing local users on startup. The default value is *false*. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **default\_room\_options**: *Options* +Define the default room options. Note that the creator of a room can +modify the options of his room at any time using an XMPP client with MUC +capability. The *Options* are: + + - **allow\_change\_subj**: *true | false* + Allow occupants to change + the subject. The default value is *true*. + + - **allow\_private\_messages\_from\_visitors**: *anyone | moderators | + nobody* Visitors can send private messages to other occupants. The + default value is *anyone* which means visitors can send private + messages to any occupant. + + - **allow\_query\_users**: *true | false* + Occupants can send IQ + queries to other occupants. The default value is *true*. + + - **allow\_subscription**: *true | false* + Allow users to subscribe to + room events as described in + [Multi-User Chat Subscriptions](../../developer/xmpp-clients-bots/extensions/muc-sub.md). + The default value is *false*. + + - **allow\_user\_invites**: *true | false* + Allow occupants to send + invitations. The default value is *false*. + + - **allow\_visitor\_nickchange**: *true | false* + Allow visitors to + change nickname. The default value is *true*. + + - **allow\_visitor\_status**: *true | false* + Allow visitors to send + status text in presence updates. If disallowed, the status text is + stripped before broadcasting the presence update to all the room + occupants. The default value is *true*. + + - **allow\_voice\_requests**: *true | false* + Allow visitors in a + moderated room to request voice. The default value is *true*. + + - **allowpm**: *anyone | participants | moderators | none* + Who can + send private messages. The default value is *anyone*. + + - **anonymous**: *true | false* + The room is anonymous: occupants don’t + see the real JIDs of other occupants. Note that the room moderators + can always see the real JIDs of the occupants. The default value is + *true*. + + - **captcha\_protected**: *true | false* + When a user tries to join a + room where they have no affiliation (not owner, admin or member), + the room requires them to fill a CAPTCHA challenge (see section + [CAPTCHA](../../admin/configuration/basic.md#captcha) in order to accept their join in the + room. The default value is *false*. + + - **description**: *Room Description* + Short description of the room. + The default value is an empty string. + + - **enable\_hats**: *true | false* + Allow extended roles as defined in + XEP-0317 Hats. The default value is *false*. + + - **lang**: *Language* + Preferred language for the discussions in the + room. The language format should conform to RFC 5646. There is no + value by default. + + - **logging**: *true | false* + The public messages are logged using + [mod_muc_log](#mod_muc_log). The default value is *false*. + + - **mam**: *true | false* + Enable message archiving. Implies mod\_mam + is enabled. The default value is *false*. + + - **max\_users**: *Number* + Maximum number of occupants in the room. + The default value is *200*. + + - **members\_by\_default**: *true | false* + The occupants that enter + the room are participants by default, so they have "voice". The + default value is *true*. + + - **members\_only**: *true | false* + Only members of the room can + enter. The default value is *false*. + + - **moderated**: *true | false* + Only occupants with "voice" can send + public messages. The default value is *true*. + + - **password**: *Password* + Password of the room. Implies option + *password\_protected* set to *true*. There is no default value. + + - **password\_protected**: *true | false* + The password is required to + enter the room. The default value is *false*. + + - **persistent**: *true | false* + The room persists even if the last + participant leaves. The default value is *false*. + + - **presence\_broadcast**: *\[moderator | participant | visitor, + ...\]* List of roles for which presence is broadcasted. The list can + contain one or several of: *moderator*, *participant*, *visitor*. + The default value is shown in the example below: + + **Example**: + + ~~~ yaml + presence_broadcast: + - moderator + - participant + - visitor + ~~~ + + - **public**: *true | false* + The room is public in the list of the MUC + service, so it can be discovered. MUC admins and room participants + will see private rooms in Service Discovery if their XMPP client + supports this feature. The default value is *true*. + + - **public\_list**: *true | false* + The list of participants is public, + without requiring to enter the room. The default value is *true*. + + - **pubsub**: *PubSub Node* + XMPP URI of associated Publish/Subscribe + node. The default value is an empty string. + + - **title**: *Room Title* + A human-readable title of the room. There is + no default value + + - **vcard**: *vCard* + A custom vCard for the room. See the equivalent + mod\_muc option.The default value is an empty string. + + - **voice\_request\_min\_interval**: *Number* + Minimum interval between + voice requests, in seconds. The default value is *1800*. + +- **hibernation\_timeout**: *infinity | Seconds* +Timeout before hibernating the room process, expressed in seconds. The +default value is *infinity*. + +- **history\_size**: *Size* +A small history of the current discussion is sent to users when they +enter the room. With this option you can define the number of history +messages to keep and send to users joining the room. The value is a +non-negative integer. Setting the value to 0 disables the history +feature and, as a result, nothing is kept in memory. The default value +is 20. This value affects all rooms on the service. NOTE: modern XMPP +clients rely on Message Archives (XEP-0313), so feel free to disable the +history feature if you’re only using modern clients and have *mod\_mam* +module loaded. + +- **host** +Deprecated. Use *hosts* instead. + +- **hosts**: *\[Host, ...\]* +This option defines the Jabber IDs of the service. If the *hosts* option +is not specified, the only Jabber ID will be the hostname of the virtual +host with the prefix "conference.". The keyword *@HOST@* is replaced +with the real virtual host name. + +- **max\_captcha\_whitelist**: *Number* + + This option defines the +maximum number of characters that Captcha Whitelist can have when +configuring the room. The default value is *infinity*. + +- **max\_password**: *Number* + + This option defines the +maximum number of characters that Password can have when configuring the +room. The default value is *infinity*. + +- **max\_room\_desc**: *Number* +This option defines the maximum number of characters that Room +Description can have when configuring the room. The default value is +*infinity*. + +- **max\_room\_id**: *Number* +This option defines the maximum number of characters that Room ID can +have when creating a new room. The default value is *infinity*. + +- **max\_room\_name**: *Number* +This option defines the maximum number of characters that Room Name can +have when configuring the room. The default value is *infinity*. + +- **max\_rooms\_discoitems**: *Number* +When there are more rooms than this *Number*, only the non-empty ones +are returned in a Service Discovery query. The default value is *100*. + +- **max\_user\_conferences**: *Number* +This option defines the maximum number of rooms that any given user can +join. The default value is *100*. This option is used to prevent +possible abuses. Note that this is a soft limit: some users can +sometimes join more conferences in cluster configurations. + +- **max\_users**: *Number* +This option defines at the service level, the maximum number of users +allowed per room. It can be lowered in each room configuration but +cannot be increased in individual room configuration. The default value +is *200*. + +- **max\_users\_admin\_threshold**: *Number* +This option defines the number of service admins or room owners allowed +to enter the room when the maximum number of allowed occupants was +reached. The default limit is *5*. + +- **max\_users\_presence**: *Number* +This option defines after how many users in the room, it is considered +overcrowded. When a MUC room is considered overcrowded, presence +broadcasts are limited to reduce load, traffic and excessive presence +"storm" received by participants. The default value is *1000*. + +- **min\_message\_interval**: *Number* +This option defines the minimum interval between two messages send by an +occupant in seconds. This option is global and valid for all rooms. A +decimal value can be used. When this option is not defined, message rate +is not limited. This feature can be used to protect a MUC service from +occupant abuses and limit number of messages that will be broadcasted by +the service. A good value for this minimum message interval is 0.4 +second. If an occupant tries to send messages faster, an error is send +back explaining that the message has been discarded and describing the +reason why the message is not acceptable. + +- **min\_presence\_interval**: *Number* +This option defines the minimum of time between presence changes coming +from a given occupant in seconds. This option is global and valid for +all rooms. A decimal value can be used. When this option is not defined, +no restriction is applied. This option can be used to protect a MUC +service for occupants abuses. If an occupant tries to change its +presence more often than the specified interval, the presence is cached +by ejabberd and only the last presence is broadcasted to all occupants +in the room after expiration of the interval delay. Intermediate +presence packets are silently discarded. A good value for this option is +4 seconds. + +- **name**: *string()* +The value of the service name. This name is only visible in some clients +that support [XEP-0030: Service +Discovery](https://xmpp.org/extensions/xep-0030.html). The default is +*Chatrooms*. + +- **preload\_rooms**: *true | false* +Whether to load all persistent rooms in memory on startup. If disabled, +the room is only loaded on first participant join. The default is +*true*. It makes sense to disable room preloading when the number of +rooms is high: this will improve server startup time and memory +consumption. + +- **queue\_type**: *ram | file* +Same as top-level [queue_type](toplevel.md#queue_type) option, but applied to this module +only. + +- **ram\_db\_type**: *mnesia | sql* +Same as top-level [default_ram_db](toplevel.md#default_ram_db) option, but applied to this module +only. + +- **regexp\_room\_id**: *string()* +This option defines the regular expression that a Room ID must satisfy +to allow the room creation. The default value is the empty string. + +- **room\_shaper**: *none | ShaperName* +This option defines shaper for the MUC rooms. The default value is +*none*. + +- **user\_message\_shaper**: *none | ShaperName* +This option defines shaper for the users messages. The default value is +*none*. + +- **user\_presence\_shaper**: *none | ShaperName* +This option defines shaper for the users presences. The default value is +*none*. + +- **vcard**: *vCard* +A custom vCard of the service that will be displayed by some XMPP +clients in Service Discovery. The value of *vCard* is a YAML map +constructed from an XML representation of vCard. Since the +representation has no attributes, the mapping is straightforward. + + **Example**: + + ~~~ yaml + # This XML representation of vCard: + # + # Conferences + # + # + # Elm Street + # + # + # + # is translated to: + vcard: + fn: Conferences + adr: + - + work: true + street: Elm Street + ~~~ + +mod\_muc\_admin +--------------- + +This module provides commands to administer local MUC services and their +MUC rooms. It also provides simple WebAdmin pages to view the existing +rooms. + +This module depends on [mod_muc](#mod_muc). + +__Available options:__ + +- **subscribe\_room\_many\_max\_users**: *Number* + + How many users can be +subscribed to a room at once using the *subscribe\_room\_many* command. +The default value is *50*. + +mod\_muc\_log +------------- + +This module enables optional logging of Multi-User Chat (MUC) public +conversations to HTML. Once you enable this module, users can join a +room using a MUC capable XMPP client, and if they have enough +privileges, they can request the configuration form in which they can +set the option to enable room logging. + +Features: + +- Room details are added on top of each page: room title, JID, author, + subject and configuration. + +- The room JID in the generated HTML is a link to join the room (using + XMPP URI). + +- Subject and room configuration changes are tracked and displayed. + +- Joins, leaves, nick changes, kicks, bans and */me* are tracked and + displayed, including the reason if available. + +- Generated HTML files are XHTML 1.0 Transitional and CSS compliant. + +- Timestamps are self-referencing links. + +- Links on top for quicker navigation: Previous day, Next day, Up. + +- CSS is used for style definition, and a custom CSS file can be used. + +- URLs on messages and subjects are converted to hyperlinks. + +- Timezone used on timestamps is shown on the log files. + +- A custom link can be added on top of each page. + +The module depends on [mod_muc](#mod_muc). + +__Available options:__ + +- **access\_log**: *AccessName* +This option restricts which occupants are allowed to enable or disable +room logging. The default value is *muc\_admin*. NOTE: for this default +setting you need to have an access rule for *muc\_admin* in order to +take effect. + +- **cssfile**: *Path | URL* +With this option you can set whether the HTML files should have a custom +CSS file or if they need to use the embedded CSS. Allowed values are +either *Path* to local file or an *URL* to a remote file. By default a +predefined CSS will be embedded into the HTML page. + +- **dirname**: *room\_jid | room\_name* +Configure the name of the room directory. If set to *room\_jid*, the +room directory name will be the full room JID. Otherwise, the room +directory name will be only the room name, not including the MUC service +name. The default value is *room\_jid*. + +- **dirtype**: *subdirs | plain* +The type of the created directories can be specified with this option. +If set to *subdirs*, subdirectories are created for each year and month. +Otherwise, the names of the log files contain the full date, and there +are no subdirectories. The default value is *subdirs*. + +- **file\_format**: *html | plaintext* +Define the format of the log files: *html* stores in HTML format, +*plaintext* stores in plain text. The default value is *html*. + +- **file\_permissions**: *{mode: Mode, group: Group}* +Define the permissions that must be used when creating the log files: +the number of the mode, and the numeric id of the group that will own +the files. The default value is shown in the example below: + + **Example**: + + ~~~ yaml + file_permissions: + mode: 644 + group: 33 + ~~~ + +- **outdir**: *Path* +This option sets the full path to the directory in which the HTML files +should be stored. Make sure the ejabberd daemon user has write access on +that directory. The default value is *www/muc*. + +- **spam\_prevention**: *true | false* +If set to *true*, a special attribute is added to links that prevent +their indexation by search engines. The default value is *true*, which +mean that *nofollow* attributes will be added to user submitted links. + +- **timezone**: *local | universal* +The time zone for the logs is configurable with this option. If set to +*local*, the local time, as reported to Erlang emulator by the operating +system, will be used. Otherwise, UTC time will be used. The default +value is *local*. + +- **top\_link**: *{URL: Text}* +With this option you can customize the link on the top right corner of +each log file. The default value is shown in the example below: + + **Example**: + + ~~~ yaml + top_link: + /: Home + ~~~ + +- **url**: *URL* +A top level *URL* where a client can access logs of a particular +conference. The conference name is appended to the URL if *dirname* +option is set to *room\_name* or a conference JID is appended to the +*URL* otherwise. There is no default value. + +mod\_muc\_occupantid +-------------------- + + + + +This module implements [XEP-0421: Anonymous unique occupant identifiers +for MUCs](https://xmpp.org/extensions/xep-0421.html). + +When the module is enabled, the feature is enabled in all semi-anonymous +rooms. + +The module has no options. + +mod\_muc\_rtbl +-------------- + + + + +This module implement Real-time blocklists for MUC rooms. + +It works by observing remote pubsub node conforming with specification +described in . + +__Available options:__ + +- **rtbl\_node**: *PubsubNodeName* +Name of pubsub node that should be used to track blocked users. The +default value is *muc\_bans\_sha256*. + +- **rtbl\_server**: *Domain* +Domain of xmpp server that serves block list. The default value is +*xmppbl.org* + +mod\_multicast +-------------- + +This module implements a service for [XEP-0033: Extended Stanza +Addressing](https://xmpp.org/extensions/xep-0033.html). + +__Available options:__ + +- **access**: *Access* +The access rule to restrict who can send packets to the multicast +service. Default value: *all*. + +- **host** +Deprecated. Use *hosts* instead. + +- **hosts**: *\[Host, ...\]* +This option defines the Jabber IDs of the service. If the *hosts* option +is not specified, the only Jabber ID will be the hostname of the virtual +host with the prefix "multicast.". The keyword *@HOST@* is replaced with +the real virtual host name. The default value is *multicast.@HOST@*. + +- **limits**: *Sender: Stanza: Number* +Specify a list of custom limits which override the default ones defined +in XEP-0033. Limits are defined per sender type and stanza type, where: + + - *sender* can be: *local* or *remote*. + + - *stanza* can be: *message* or *presence*. + + - *number* can be a positive integer or *infinite*. + + **Example**: + + ~~~ yaml + # Default values: + local: + message: 100 + presence: 100 + remote: + message: 20 + presence: 20 + ~~~ + +- **name** +Service name to provide in the Info query to the Service Discovery. +Default is *"Multicast"*. + +- **vcard** +vCard element to return when queried. Default value is *undefined*. + +__**Example**:__ + +~~~ yaml +# Only admins can send packets to multicast service +access_rules: + multicast: + - allow: admin + +# If you want to allow all your users: +access_rules: + multicast: + - allow + +# This allows both admins and remote users to send packets, +# but does not allow local users +acl: + allservers: + server_glob: "*" +access_rules: + multicast: + - allow: admin + - deny: local + - allow: allservers + +modules: + mod_multicast: + host: multicast.example.org + access: multicast + limits: + local: + message: 40 + presence: infinite + remote: + message: 150 +~~~ + +mod\_offline +------------ + +This module implements [XEP-0160: Best Practices for Handling Offline +Messages](https://xmpp.org/extensions/xep-0160.html) and [XEP-0013: +Flexible Offline Message +Retrieval](https://xmpp.org/extensions/xep-0013.html). This means that +all messages sent to an offline user will be stored on the server until +that user comes online again. Thus it is very similar to how email +works. A user is considered offline if no session presence priority > +0 are currently open. + +> **Note** +> +> *ejabberdctl* has a command to delete expired messages (see chapter +> [Managing an ejabberd server](../../admin/guide/managing.md) in online +> documentation. + +__Available options:__ + +- **access\_max\_user\_messages**: *AccessName* +This option defines which access rule will be enforced to limit the +maximum number of offline messages that a user can have (quota). When a +user has too many offline messages, any new messages that they receive +are discarded, and a <resource-constraint/> error is returned to +the sender. The default value is *max\_user\_offline\_messages*. + +- **bounce\_groupchat**: *true | false* +This option is use the disable an optimization that avoids bouncing +error messages when groupchat messages could not be stored as offline. +It will reduce chat room load, without any drawback in standard use +cases. You may change default value only if you have a custom module +which uses offline hook after *mod\_offline*. This option can be useful +for both standard MUC and MucSub, but the bounce is much more likely to +happen in the context of MucSub, so it is even more important to have it +on large MucSub services. The default value is *false*, meaning the +optimization is enabled. + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **store\_empty\_body**: *true | false | unless\_chat\_state* +Whether or not to store messages that lack a <body/> element. The +default value is *unless\_chat\_state*, which tells ejabberd to store +messages even if they lack the <body/> element, unless they only +contain a chat state notification (as defined in [XEP-0085: Chat State +Notifications](https://xmpp.org/extensions/xep-0085.html). + +- **store\_groupchat**: *true | false* +Whether or not to store groupchat messages. The default value is +*false*. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +- **use\_mam\_for\_storage**: *true | false* +This is an experimental option. Enabling this option, *mod\_offline* +uses the *mod\_mam* archive table instead of its own spool table to +retrieve the messages received when the user was offline. This allows +client developers to slowly drop XEP-0160 and rely on XEP-0313 instead. +It also further reduces the storage required when you enable MucSub. +Enabling this option has a known drawback for the moment: most of +flexible message retrieval queries don’t work (those that allow +retrieval/deletion of messages by id), but this specification is not +widely used. The default value is *false* to keep former behaviour as +default. + +__Examples:__ + +This example allows power users to have as much as 5000 offline +messages, administrators up to 2000, and all the other users up to 100: + +~~~ yaml +acl: + admin: + user: + - admin1@localhost + - admin2@example.org + poweruser: + user: + - bob@example.org + - jane@example.org + +shaper_rules: + max_user_offline_messages: + - 5000: poweruser + - 2000: admin + - 100 + +modules: + ... + mod_offline: + access_max_user_messages: max_user_offline_messages + ... +~~~ + +mod\_ping +--------- + +This module implements support for [XEP-0199: XMPP +Ping](https://xmpp.org/extensions/xep-0199.html) and periodic +keepalives. When this module is enabled ejabberd responds correctly to +ping requests, as defined by the protocol. + +__Available options:__ + +- **ping\_ack\_timeout**: *timeout()* +How long to wait before deeming that a client has not answered a given +server ping request. NOTE: when [mod_stream_mgmt](#mod_stream_mgmt) is loaded and stream +management is enabled by a client, this value is ignored, and the +`ack_timeout` applies instead. The default value is *undefined*. + +- **ping\_interval**: *timeout()* +How often to send pings to connected clients, if option *send\_pings* is +set to *true*. If a client connection does not send or receive any +stanza within this interval, a ping request is sent to the client. The +default value is *1* minute. + +- **send\_pings**: *true | false* +If this option is set to *true*, the server sends pings to connected +clients that are not active in a given interval defined in +*ping\_interval* option. This is useful to keep client connections alive +or checking availability. The default value is *false*. + +- **timeout\_action**: *none | kill* +What to do when a client does not answer to a server ping request in +less than period defined in *ping\_ack\_timeout* option: *kill* means +destroying the underlying connection, *none* means to do nothing. NOTE: +when [mod_stream_mgmt](#mod_stream_mgmt) is loaded and stream management is enabled by a +client, killing the client connection doesn’t mean killing the client +session - the session will be kept alive in order to give the client a +chance to resume it. The default value is *none*. + +__**Example**:__ + +~~~ yaml +modules: + mod_ping: + send_pings: true + ping_interval: 4 min + timeout_action: kill +~~~ + +mod\_pres\_counter +------------------ + +This module detects flood/spam in presence subscriptions traffic. If a +user sends or receives more of those stanzas in a given time interval, +the exceeding stanzas are silently dropped, and a warning is logged. + +__Available options:__ + +- **count**: *Number* +The number of subscription presence stanzas (subscribe, unsubscribe, +subscribed, unsubscribed) allowed for any direction (input or output) +per time defined in *interval* option. Please note that two users +subscribing to each other usually generate 4 stanzas, so the recommended +value is *4* or more. The default value is *5*. + +- **interval**: *timeout()* +The time interval. The default value is *1* minute. + +__**Example**:__ + +~~~ yaml +modules: + mod_pres_counter: + count: 5 + interval: 30 secs +~~~ + +mod\_privacy +------------ + +This module implements [XEP-0016: Privacy +Lists](https://xmpp.org/extensions/xep-0016.html). + +> **Note** +> +> Nowadays modern XMPP clients rely on [XEP-0191: Blocking +> Command](https://xmpp.org/extensions/xep-0191.html) which is +> implemented by *mod\_blocking* module. However, you still need +> *mod\_privacy* loaded in order for [mod_blocking](#mod_blocking) to work. + +__Available options:__ + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed**: *true | false* +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +mod\_private +------------ + +This module adds support for [XEP-0049: Private XML +Storage](https://xmpp.org/extensions/xep-0049.html). + +Using this method, XMPP entities can store private data on the server, +retrieve it whenever necessary and share it between multiple connected +clients of the same user. The data stored might be anything, as long as +it is a valid XML. One typical usage is storing a bookmark of all user’s +conferences ([XEP-0048: +Bookmarks](https://xmpp.org/extensions/xep-0048.html)). + +It also implements the bookmark conversion described in [XEP-0402: PEP +Native Bookmarks](https://xmpp.org/extensions/xep-0402.html), see the +command [bookmarks_to_pep](../../developer/ejabberd-api/admin-api.md#bookmarks_to_pep) API. + +__Available options:__ + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed**: *true | false* +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +mod\_privilege +-------------- + +This module is an implementation of [XEP-0356: Privileged +Entity](https://xmpp.org/extensions/xep-0356.html). This extension +allows components to have privileged access to other entity data (send +messages on behalf of the server or on behalf of a user, get/set user +roster, access presence information, etc.). This may be used to write +powerful external components, for example implementing an external +[PEP](https://xmpp.org/extensions/xep-0163.html) or +[MAM](https://xmpp.org/extensions/xep-0313.html) service. + +By default a component does not have any privileged access. It is worth +noting that the permissions grant access to the component to a specific +data type for all users of the virtual host on which *mod\_privilege* is +loaded. + +Make sure you have a listener configured to connect your component. +Check the section about listening ports for more information. + +> **Warning** +> +> Security issue: Privileged access gives components access to sensitive +> data, so permission should be granted carefully, only if you trust a +> component. + +> **Note** +> +> This module is complementary to [mod_delegation](#mod_delegation), but can also be +> used separately. + +__Available options:__ + +- **message**: *Options* +This option defines permissions for messages. By default no permissions +are given. The *Options* are: + + - **outgoing**: *AccessName* + The option defines an access rule for + sending outgoing messages by the component. The default value is + *none*. + +- **presence**: *Options* +This option defines permissions for presences. By default no permissions +are given. The *Options* are: + + - **managed\_entity**: *AccessName* + An access rule that gives + permissions to the component to receive server presences. The + default value is *none*. + + - **roster**: *AccessName* + An access rule that gives permissions to + the component to receive the presence of both the users and the + contacts in their roster. The default value is *none*. + +- **roster**: *Options* +This option defines roster permissions. By default no permissions are +given. The *Options* are: + + - **both**: *AccessName* + Sets read/write access to a user’s roster. + The default value is *none*. + + - **get**: *AccessName* + Sets read access to a user’s roster. The + default value is *none*. + + - **set**: *AccessName* + Sets write access to a user’s roster. The + default value is *none*. + +__**Example**:__ + +~~~ yaml +modules: + mod_privilege: + roster: + get: all + presence: + managed_entity: all + message: + outgoing: all +~~~ + +mod\_proxy65 +------------ + +This module implements [XEP-0065: SOCKS5 +Bytestreams](https://xmpp.org/extensions/xep-0065.html). It allows +ejabberd to act as a file transfer proxy between two XMPP clients. + +__Available options:__ + +- **access**: *AccessName* +Defines an access rule for file transfer initiators. The default value +is *all*. You may want to restrict access to the users of your server +only, in order to avoid abusing your proxy by the users of remote +servers. + +- **auth\_type**: *anonymous | plain* +SOCKS5 authentication type. The default value is *anonymous*. If set to +*plain*, ejabberd will use authentication backend as it would for SASL +PLAIN. + +- **host** +Deprecated. Use *hosts* instead. + +- **hostname**: *Host* +Defines a hostname offered by the proxy when establishing a session with +clients. This is useful when you run the proxy behind a NAT. The keyword +*@HOST@* is replaced with the virtual host name. The default is to use +the value of *ip* option. Examples: *proxy.mydomain.org*, +*200.150.100.50*. + +- **hosts**: *\[Host, ...\]* +This option defines the Jabber IDs of the service. If the *hosts* option +is not specified, the only Jabber ID will be the hostname of the virtual +host with the prefix "proxy.". The keyword *@HOST@* is replaced with the +real virtual host name. + +- **ip**: *IPAddress* +This option specifies which network interface to listen for. The default +value is an IP address of the service’s DNS name, or, if fails, +*127.0.0.1*. + +- **max\_connections**: *pos\_integer() | infinity* +Maximum number of active connections per file transfer initiator. The +default value is *infinity*. + +- **name**: *Name* +The value of the service name. This name is only visible in some clients +that support [XEP-0030: Service +Discovery](https://xmpp.org/extensions/xep-0030.html). The default is +"SOCKS5 Bytestreams". + +- **port**: *1..65535* +A port number to listen for incoming connections. The default value is +*7777*. + +- **ram\_db\_type**: *mnesia | redis | sql* +Same as top-level [default_ram_db](toplevel.md#default_ram_db) option, but applied to this module +only. + +- **recbuf**: *Size* +A size of the buffer for incoming packets. If you define a shaper, set +the value of this option to the size of the shaper in order to avoid +traffic spikes in file transfers. The default value is *65536* bytes. + +- **shaper**: *Shaper* +This option defines a shaper for the file transfer peers. A shaper with +the maximum bandwidth will be selected. The default is *none*, i.e. no +shaper. + +- **sndbuf**: *Size* +A size of the buffer for outgoing packets. If you define a shaper, set +the value of this option to the size of the shaper in order to avoid +traffic spikes in file transfers. The default value is *65536* bytes. + +- **vcard**: *vCard* +A custom vCard of the service that will be displayed by some XMPP +clients in Service Discovery. The value of *vCard* is a YAML map +constructed from an XML representation of vCard. Since the +representation has no attributes, the mapping is straightforward. + +__**Example**:__ + +~~~ yaml +acl: + admin: + user: admin@example.org + proxy_users: + server: example.org + +access_rules: + proxy65_access: + allow: proxy_users + +shaper_rules: + proxy65_shaper: + none: admin + proxyrate: proxy_users + +shaper: + proxyrate: 10240 + +modules: + mod_proxy65: + host: proxy1.example.org + name: "File Transfer Proxy" + ip: 200.150.100.1 + port: 7778 + max_connections: 5 + access: proxy65_access + shaper: proxy65_shaper + recbuf: 10240 + sndbuf: 10240 +~~~ + +mod\_pubsub +----------- + +This module offers a service for [XEP-0060: +Publish-Subscribe](https://xmpp.org/extensions/xep-0060.html). The +functionality in *mod\_pubsub* can be extended using plugins. The plugin +that implements PEP ([XEP-0163: Personal Eventing via +Pubsub](https://xmpp.org/extensions/xep-0163.html)) is enabled in the +default ejabberd configuration file, and it requires [mod_caps](#mod_caps). + +__Available options:__ + +- **access\_createnode**: *AccessName* +This option restricts which users are allowed to create pubsub nodes +using *acl* and *access*. By default any account in the local ejabberd +server is allowed to create pubsub nodes. The default value is: *all*. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **default\_node\_config**: *List of Key:Value* +To override default node configuration, regardless of node plugin. Value +is a list of key-value definition. Node configuration still uses default +configuration defined by node plugin, and overrides any items by value +defined in this configurable list. + +- **force\_node\_config**: *List of Node and the list of its Key:Value* +Define the configuration for given nodes. The default value is: *\[\]*. + + **Example**: + + ~~~ yaml + force_node_config: + ## Avoid buggy clients to make their bookmarks public + storage:bookmarks: + access_model: whitelist + ~~~ + +- **host** +Deprecated. Use *hosts* instead. + +- **hosts**: *\[Host, ...\]* +This option defines the Jabber IDs of the service. If the *hosts* option +is not specified, the only Jabber ID will be the hostname of the virtual +host with the prefix "pubsub.". The keyword *@HOST@* is replaced with +the real virtual host name. + +- **ignore\_pep\_from\_offline**: *false | true* +To specify whether or not we should get last published PEP items from +users in our roster which are offline when we connect. Value is *true* +or *false*. If not defined, pubsub assumes true so we only get last +items of online contacts. + +- **last\_item\_cache**: *false | true* +To specify whether or not pubsub should cache last items. Value is +*true* or *false*. If not defined, pubsub does not cache last items. On +systems with not so many nodes, caching last items speeds up pubsub and +allows you to raise the user connection rate. The cost is memory usage, +as every item is stored in memory. + +- **max\_item\_expire\_node**: *timeout() | infinity* + + Specify the maximum item epiry +time. Default value is: *infinity*. + +- **max\_items\_node**: *non\_neg\_integer() | infinity* +Define the maximum number of items that can be stored in a node. Default +value is: *1000*. + +- **max\_nodes\_discoitems**: *pos\_integer() | infinity* +The maximum number of nodes to return in a discoitem response. The +default value is: *100*. + +- **max\_subscriptions\_node**: *MaxSubs* +Define the maximum number of subscriptions managed by a node. Default +value is no limitation: *undefined*. + +- **name**: *Name* +The value of the service name. This name is only visible in some clients +that support [XEP-0030: Service +Discovery](https://xmpp.org/extensions/xep-0030.html). The default is +*vCard User Search*. + +- **nodetree**: *Nodetree* +To specify which nodetree to use. If not defined, the default pubsub +nodetree is used: *tree*. Only one nodetree can be used per host, and is +shared by all node plugins. + + - *tree* nodetree store node configuration and relations on the + database. *flat* nodes are stored without any relationship, and + *hometree* nodes can have child nodes. + + - *virtual* nodetree does not store nodes on database. This saves + resources on systems with tons of nodes. If using the *virtual* + nodetree, you can only enable those node plugins: *\[flat, pep\]* or + *\[flat\]*; any other plugins configuration will not work. Also, all + nodes will have the default configuration, and this can not be + changed. Using *virtual* nodetree requires to start from a clean + database, it will not work if you used the default *tree* nodetree + before. + +- **pep\_mapping**: *List of Key:Value* +In this option you can provide a list of key-value to choose defined +node plugins on given PEP namespace. The following example will use +*node\_tune* instead of *node\_pep* for every PEP node with the tune +namespace: + + **Example**: + + ~~~ yaml + modules: + ... + mod_pubsub: + pep_mapping: + http://jabber.org/protocol/tune: tune + ... + ~~~ + +- **plugins**: *\[Plugin, ...\]* +To specify which pubsub node plugins to use. The first one in the list +is used by default. If this option is not defined, the default plugins +list is: *\[flat\]*. PubSub clients can define which plugin to use when +creating a node: add *type='plugin-name*' attribute to the *create* +stanza element. + + - *flat* plugin handles the default behaviour and follows standard + XEP-0060 implementation. + + - *pep* plugin adds extension to handle Personal Eventing Protocol + (XEP-0163) to the PubSub engine. When enabled, PEP is handled + automatically. + +- **vcard**: *vCard* +A custom vCard of the server that will be displayed by some XMPP clients +in Service Discovery. The value of *vCard* is a YAML map constructed +from an XML representation of vCard. Since the representation has no +attributes, the mapping is straightforward. + + **Example**: + + ~~~ yaml + # This XML representation of vCard: + # + # Conferences + # + # + # Elm Street + # + # + # + # is translated to: + vcard: + fn: Conferences + adr: + - + work: true + street: Elm Street + ~~~ + +__Examples:__ + +Example of configuration that uses flat nodes as default, and allows use +of flat, hometree and pep nodes: + +~~~ yaml +modules: + mod_pubsub: + access_createnode: pubsub_createnode + max_subscriptions_node: 100 + default_node_config: + notification_type: normal + notify_retract: false + max_items: 4 + plugins: + - flat + - pep +~~~ + +Using relational database requires using mod\_pubsub with db\_type +*sql*. Only flat, hometree and pep plugins supports SQL. The following +example shows previous configuration with SQL usage: + +~~~ yaml +modules: + mod_pubsub: + db_type: sql + access_createnode: pubsub_createnode + ignore_pep_from_offline: true + last_item_cache: false + plugins: + - flat + - pep +~~~ + +mod\_push +--------- + +This module implements the XMPP server’s part of the push notification +solution specified in [XEP-0357: Push +Notifications](https://xmpp.org/extensions/xep-0357.html). It does not +generate, for example, APNS or FCM notifications directly. Instead, it’s +designed to work with so-called "app servers" operated by third-party +vendors of mobile apps. Those app servers will usually trigger +notification delivery to the user’s mobile device using +platform-dependent backend services such as FCM or APNS. + +__Available options:__ + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed**: *true | false* +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **include\_body**: *true | false | Text* +If this option is set to *true*, the message text is included with push +notifications generated for incoming messages with a body. The option +can instead be set to a static *Text*, in which case the specified text +will be included in place of the actual message body. This can be useful +to signal the app server whether the notification was triggered by a +message with body (as opposed to other types of traffic) without leaking +actual message contents. The default value is "New message". + +- **include\_sender**: *true | false* +If this option is set to *true*, the sender’s JID is included with push +notifications generated for incoming messages with a body. The default +value is *false*. + +- **notify\_on**: *messages | all* + + If this option is set to +*messages*, notifications are generated only for actual chat messages +with a body text (or some encrypted payload). If it’s set to *all*, any +kind of XMPP stanza will trigger a notification. If unsure, it’s +strongly recommended to stick to *all*, which is the default value. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +mod\_push\_keepalive +-------------------- + +This module tries to keep the stream management session (see +[mod_stream_mgmt](#mod_stream_mgmt)) of a disconnected mobile client alive if the client +enabled push notifications for that session. However, the normal session +resumption timeout is restored once a push notification is issued, so +the session will be closed if the client doesn’t respond to push +notifications. + +The module depends on [mod_push](#mod_push). + +__Available options:__ + +- **resume\_timeout**: *timeout()* +This option specifies the period of time until the session of a +disconnected push client times out. This timeout is only in effect as +long as no push notification is issued. Once that happened, the +resumption timeout configured for [mod_stream_mgmt](#mod_stream_mgmt) is restored. The +default value is *72* hours. + +- **wake\_on\_start**: *true | false* +If this option is set to *true*, notifications are generated for **all** +registered push clients during server startup. This option should not be +enabled on servers with many push clients as it can generate significant +load on the involved push services and the server itself. The default +value is *false*. + +- **wake\_on\_timeout**: *true | false* +If this option is set to *true*, a notification is generated shortly +before the session would time out as per the *resume\_timeout* option. +The default value is *true*. + +mod\_register +------------- + +This module adds support for [XEP-0077: In-Band +Registration](https://xmpp.org/extensions/xep-0077.html). This protocol +enables end users to use an XMPP client to: + +- Register a new account on the server. + +- Change the password from an existing account on the server. + +- Delete an existing account on the server. + +This module reads also the top-level [registration_timeout](toplevel.md#registration_timeout) option +defined globally for the server, so please check that option +documentation too. + +__Available options:__ + +- **access**: *AccessName* +Specify rules to restrict what usernames can be registered. If a rule +returns *deny* on the requested username, registration of that user name +is denied. There are no restrictions by default. + +- **access\_from**: *AccessName* +By default, *ejabberd* doesn’t allow the client to register new accounts +from s2s or existing c2s sessions. You can change it by defining access +rule in this option. Use with care: allowing registration from s2s leads +to uncontrolled massive accounts creation by rogue users. + +- **access\_remove**: *AccessName* +Specify rules to restrict access for user unregistration. By default any +user is able to unregister their account. + +- **allow\_modules**: *all | \[Module, ...\]* + + List of modules that can +register accounts, or *all*. The default value is *all*, which is +equivalent to something like *\[mod\_register, mod\_register\_web\]*. + +- **captcha\_protected**: *true | false* +Protect registrations with [CAPTCHA](../../admin/configuration/basic.md#captcha). The default is +*false*. + +- **ip\_access**: *AccessName* +Define rules to allow or deny account registration depending on the IP +address of the XMPP client. The *AccessName* should be of type *ip*. The +default value is *all*. + +- **password\_strength**: *Entropy* +This option sets the minimum [Shannon +entropy](https://en.wikipedia.org/wiki/Entropy_(information_theory)) for +passwords. The value *Entropy* is a number of bits of entropy. The +recommended minimum is 32 bits. The default is *0*, i.e. no checks are +performed. + +- **redirect\_url**: *URL* +This option enables registration redirection as described in [XEP-0077: +In-Band Registration: +Redirection](https://xmpp.org/extensions/xep-0077.html#redirect). + +- **registration\_watchers**: *\[JID, ...\]* +This option defines a list of JIDs which will be notified each time a +new account is registered. + +- **welcome\_message**: *{subject: Subject, body: Body}* +Set a welcome message that is sent to each newly registered account. The +message will have subject *Subject* and text *Body*. + +mod\_register\_web +------------------ + +This module provides a web page where users can: + +- Register a new account on the server. + +- Change the password from an existing account on the server. + +- Unregister an existing account on the server. + +This module supports [CAPTCHA](../../admin/configuration/basic.md#captcha) to register a new +account. To enable this feature, configure the top-level [captcha_cmd](toplevel.md#captcha_cmd) +and top-level [captcha_url](toplevel.md#captcha_url) options. + +As an example usage, the users of the host *localhost* can visit the +page: *https://localhost:5280/register/* It is important to include the +last / character in the URL, otherwise the subpages URL will be +incorrect. + +This module is enabled in *listen* → *ejabberd\_http* → +[request_handlers](listen-options.md#request_handlers), no need to +enable in *modules*. The module depends on [mod_register](#mod_register) where all +the configuration is performed. + +The module has no options. + +__**Example**:__ + +~~~ yaml +listen: + - + port: 5280 + module: ejabberd_http + request_handlers: + /register: mod_register_web + +modules: + mod_register: {} +~~~ + +mod\_roster +----------- + +This module implements roster management as defined in [RFC6121 Section +2](https://tools.ietf.org/html/rfc6121#section-2). The module also adds +support for [XEP-0237: Roster +Versioning](https://xmpp.org/extensions/xep-0237.html). + +__Available options:__ + +- **access**: *AccessName* +This option can be configured to specify rules to restrict roster +management. If the rule returns *deny* on the requested user name, that +user cannot modify their personal roster, i.e. they cannot +add/remove/modify contacts or send presence subscriptions. The default +value is *all*, i.e. no restrictions. + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed**: *true | false* +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **store\_current\_id**: *true | false* +If this option is set to *true*, the current roster version number is +stored on the database. If set to *false*, the roster version number is +calculated on the fly each time. Enabling this option reduces the load +for both ejabberd and the database. This option does not affect the +client in any way. This option is only useful if option *versioning* is +set to *true*. The default value is *false*. IMPORTANT: if you use +[mod_shared_roster](#mod_shared_roster) or [mod_shared_roster_ldap](#mod_shared_roster_ldap), you must set the +value of the option to *false*. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +- **versioning**: *true | false* +Enables/disables Roster Versioning. The default value is *false*. + +__**Example**:__ + +~~~ yaml +modules: + mod_roster: + versioning: true + store_current_id: false +~~~ + +mod\_s2s\_dialback +------------------ + +The module adds support for [XEP-0220: Server +Dialback](https://xmpp.org/extensions/xep-0220.html) to provide server +identity verification based on DNS. + +> **Warning** +> +> DNS-based verification is vulnerable to [DNS cache +> poisoning](https://en.wikipedia.org/wiki/DNS_spoofing), so modern +> servers rely on verification based on PKIX certificates. Thus this +> module is only recommended for backward compatibility with servers +> running outdated software or non-TLS servers, or those with invalid +> certificates (as long as you accept the risks, e.g. you assume that +> the remote server has an invalid certificate due to poor +> administration and not because it’s compromised). + +__Available options:__ + +- **access**: *AccessName* +An access rule that can be used to restrict dialback for some servers. +The default value is *all*. + +__**Example**:__ + +~~~ yaml +modules: + mod_s2s_dialback: + access: + allow: + server: legacy.domain.tld + server: invalid-cert.example.org + deny: all +~~~ + +mod\_service\_log +----------------- + +This module forwards copies of all stanzas to remote XMPP servers or +components. Every stanza is encapsulated into <forwarded/> element +as described in [XEP-0297: Stanza +Forwarding](https://xmpp.org/extensions/xep-0297.html). + +__Available options:__ + +- **loggers**: *\[Domain, ...\]* +A list of servers or connected components to which stanzas will be +forwarded. + +__**Example**:__ + +~~~ yaml +modules: + mod_service_log: + loggers: + - xmpp-server.tld + - component.domain.tld +~~~ + +mod\_shared\_roster +------------------- + +This module enables you to create shared roster groups: groups of +accounts that can see members from (other) groups in their rosters. + +The big advantages of this feature are that end users do not need to +manually add all users to their rosters, and that they cannot +permanently delete users from the shared roster groups. A shared roster +group can have members from any XMPP server, but the presence will only +be available from and to members of the same virtual host where the +group is created. It still allows the users to have / add their own +contacts, as it does not replace the standard roster. Instead, the +shared roster contacts are merged to the relevant users at retrieval +time. The standard user rosters thus stay unmodified. + +Shared roster groups can be edited via the Web Admin, and some API +commands called *srg\_\**. Each group has a unique name and those +parameters: + +- Label: Used in the rosters where this group is displayed. + +- Description: of the group, which has no effect. + +- Members: A list of JIDs of group members, entered one per line in + the Web Admin. The special member directive *@all@* represents all + the registered users in the virtual host; which is only recommended + for a small server with just a few hundred users. The special member + directive *@online@* represents the online users in the virtual + host. With those two directives, the actual list of members in those + shared rosters is generated dynamically at retrieval time. + +- Displayed: A list of groups that will be in the rosters of this + group’s members. A group of other vhost can be identified with + *groupid@vhost*. + +This module depends on [mod_roster](#mod_roster). If not enabled, roster queries +will return 503 errors. + +__Available options:__ + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed**: *true | false* +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **db\_type**: *mnesia | sql* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +__Examples:__ + +Take the case of a computer club that wants all its members seeing each +other in their rosters. To achieve this, they need to create a shared +roster group similar to this one: + +~~~ yaml +Name: club_members +Label: Club Members +Description: Members from the computer club +Members: member1@example.org, member2@example.org, member3@example.org +Displayed Groups: club_members +~~~ + +In another case we have a company which has three divisions: Management, +Marketing and Sales. All group members should see all other members in +their rosters. Additionally, all managers should have all marketing and +sales people in their roster. Simultaneously, all marketeers and the +whole sales team should see all managers. This scenario can be achieved +by creating shared roster groups as shown in the following lists: + +~~~ yaml +First list: +Name: management +Label: Management +Description: Management +Members: manager1@example.org, manager2@example.org +Displayed: management, marketing, sales + +Second list: +Name: marketing +Label: Marketing +Description: Marketing +Members: marketeer1@example.org, marketeer2@example.org, marketeer3@example.org +Displayed: management, marketing + +Third list: +Name: sales +Label: Sales +Description: Sales +Members: salesman1@example.org, salesman2@example.org, salesman3@example.org +Displayed: management, sales +~~~ + +mod\_shared\_roster\_ldap +------------------------- + +This module lets the server administrator automatically populate users' +rosters (contact lists) with entries based on users and groups defined +in an LDAP-based directory. + +> **Note** +> +> *mod\_shared\_roster\_ldap* depends on *mod\_roster* being enabled. +> Roster queries will return *503* errors if *mod\_roster* is not +> enabled. + +The module accepts many configuration options. Some of them, if +unspecified, default to the values specified for the top level of +configuration. This lets you avoid specifying, for example, the bind +password in multiple places. + +- Filters: *ldap\_rfilter*, *ldap\_ufilter*, *ldap\_gfilter*, + *ldap\_filter*. These options specify LDAP filters used to query for + shared roster information. All of them are run against the + ldap\_base. + +- Attributes: *ldap\_groupattr*, *ldap\_groupdesc*, + *ldap\_memberattr*, *ldap\_userdesc*, *ldap\_useruid*. These options + specify the names of the attributes which hold interesting data in + the entries returned by running filters specified with the filter + options. + +- Control parameters: *ldap\_auth\_check*, + *ldap\_group\_cache\_validity*, *ldap\_memberattr\_format*, + *ldap\_memberattr\_format\_re*, *ldap\_user\_cache\_validity*. These + parameters control the behaviour of the module. + +- Connection parameters: The module also accepts the connection + parameters, all of which default to the top-level parameter of the + same name, if unspecified. See + [LDAP Connection](../../admin/configuration/ldap.md#ldap-connection) section for more + information about them. + +Check also the [Configuration examples](../../admin/configuration/ldap.md#ldap-examples) section +to get details about retrieving the roster, and configuration examples +including Flat DIT and Deep DIT. + +__Available options:__ + +- **cache\_life\_time** +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed** +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size** +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **ldap\_auth\_check**: *true | false* +Whether the module should check (via the ejabberd authentication +subsystem) for existence of each user in the shared LDAP roster. Set to +*false* if you want to disable the check. Default value is *true*. + +- **ldap\_backups** +Same as top-level [ldap_backups](toplevel.md#ldap_backups) option, but applied to this module +only. + +- **ldap\_base** +Same as top-level [ldap_base](toplevel.md#ldap_base) option, but applied to this module only. + +- **ldap\_deref\_aliases** +Same as top-level [ldap_deref_aliases](toplevel.md#ldap_deref_aliases) option, but applied to this +module only. + +- **ldap\_encrypt** +Same as top-level [ldap_encrypt](toplevel.md#ldap_encrypt) option, but applied to this module +only. + +- **ldap\_filter** +Additional filter which is AND-ed together with "User Filter" and "Group +Filter". For more information check the LDAP [Filters](../../admin/configuration/ldap.md#filters) +section. + +- **ldap\_gfilter** +"Group Filter", used when retrieving human-readable name (a.k.a. +"Display Name") and the members of a group. See also the parameters +*ldap\_groupattr*, *ldap\_groupdesc* and *ldap\_memberattr*. If +unspecified, defaults to the top-level parameter of the same name. If +that one also is unspecified, then the filter is constructed exactly +like "User Filter". + +- **ldap\_groupattr** +The name of the attribute that holds the group name, and that is used to +differentiate between them. Retrieved from results of the "Roster +Filter" and "Group Filter". Defaults to *cn*. + +- **ldap\_groupdesc** +The name of the attribute which holds the human-readable group name in +the objects you use to represent groups. Retrieved from results of the +"Group Filter". Defaults to whatever *ldap\_groupattr* is set. + +- **ldap\_memberattr** +The name of the attribute which holds the IDs of the members of a group. +Retrieved from results of the "Group Filter". Defaults to *memberUid*. +The name of the attribute differs depending on the objectClass you use +for your group objects, for example: *posixGroup* → *memberUid*; +*groupOfNames* → *member*; *groupOfUniqueNames* → *uniqueMember*. + +- **ldap\_memberattr\_format** +A globbing format for extracting user ID from the value of the attribute +named by *ldap\_memberattr*. Defaults to *%u*, which means that the +whole value is the member ID. If you change it to something different, +you may also need to specify the User and Group Filters manually; see +section Filters. + +- **ldap\_memberattr\_format\_re** +A regex for extracting user ID from the value of the attribute named by +*ldap\_memberattr*. Check the LDAP +[Control Parameters](../../admin/configuration/ldap.md#control-parameters) section. + +- **ldap\_password** +Same as top-level [ldap_password](toplevel.md#ldap_password) option, but applied to this module +only. + +- **ldap\_port** +Same as top-level [ldap_port](toplevel.md#ldap_port) option, but applied to this module only. + +- **ldap\_rfilter** +So called "Roster Filter". Used to find names of all "shared roster" +groups. See also the *ldap\_groupattr* parameter. If unspecified, +defaults to the top-level parameter of the same name. You must specify +it in some place in the configuration, there is no default. + +- **ldap\_rootdn** +Same as top-level [ldap_rootdn](toplevel.md#ldap_rootdn) option, but applied to this module +only. + +- **ldap\_servers** +Same as top-level [ldap_servers](toplevel.md#ldap_servers) option, but applied to this module +only. + +- **ldap\_tls\_cacertfile** +Same as top-level [ldap_tls_cacertfile](toplevel.md#ldap_tls_cacertfile) option, but applied to this +module only. + +- **ldap\_tls\_certfile** +Same as top-level [ldap_tls_certfile](toplevel.md#ldap_tls_certfile) option, but applied to this +module only. + +- **ldap\_tls\_depth** +Same as top-level [ldap_tls_depth](toplevel.md#ldap_tls_depth) option, but applied to this module +only. + +- **ldap\_tls\_verify** +Same as top-level [ldap_tls_verify](toplevel.md#ldap_tls_verify) option, but applied to this module +only. + +- **ldap\_ufilter** +"User Filter", used for retrieving the human-readable name of roster +entries (usually full names of people in the roster). See also the +parameters *ldap\_userdesc* and *ldap\_useruid*. For more information +check the LDAP [Filters](../../admin/configuration/ldap.md#filters) section. + +- **ldap\_uids** +Same as top-level [ldap_uids](toplevel.md#ldap_uids) option, but applied to this module only. + +- **ldap\_userdesc** +The name of the attribute which holds the human-readable user name. +Retrieved from results of the "User Filter". Defaults to *cn*. + +- **ldap\_userjidattr** +The name of the attribute which is used to map user id to XMPP jid. If +not specified (and that is default value of this option), user jid will +be created from user id and this module host. + +- **ldap\_useruid** +The name of the attribute which holds the ID of a roster item. Value of +this attribute in the roster item objects needs to match the ID +retrieved from the *ldap\_memberattr* attribute of a group object. +Retrieved from results of the "User Filter". Defaults to *cn*. + +- **use\_cache** +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +mod\_sic +-------- + +This module adds support for [XEP-0279: Server IP +Check](https://xmpp.org/extensions/xep-0279.html). This protocol enables +a client to discover its external IP address. + +> **Warning** +> +> The protocol extension is deferred and seems like there are no clients +> supporting it, so using this module is not recommended and, +> furthermore, the module might be removed in the future. + +The module has no options. + +mod\_sip +-------- + +This module adds SIP proxy/registrar support for the corresponding +virtual host. + +> **Note** +> +> It is not enough to just load this module. You should also configure +> listeners and DNS records properly. For details see the section about +> the [ejabberd_sip](listen.md#ejabberd_sip) listen module in the +> ejabberd Documentation. + +__Available options:__ + +- **always\_record\_route**: *true | false* +Always insert "Record-Route" header into SIP messages. With this +approach it is possible to bypass NATs/firewalls a bit more easily. The +default value is *true*. + +- **flow\_timeout\_tcp**: *timeout()* +The option sets a keep-alive timer for [SIP +outbound](https://tools.ietf.org/html/rfc5626) TCP connections. The +default value is *2* minutes. + +- **flow\_timeout\_udp**: *timeout()* +The options sets a keep-alive timer for [SIP +outbound](https://tools.ietf.org/html/rfc5626) UDP connections. The +default value is *29* seconds. + +- **record\_route**: *URI* +When the option *always\_record\_route* is set to *true* or when [SIP +outbound](https://tools.ietf.org/html/rfc5626) is utilized, ejabberd +inserts "Record-Route" header field with this *URI* into a SIP message. +The default is a SIP URI constructed from the virtual host on which the +module is loaded. + +- **routes**: *\[URI, ...\]* +You can set a list of SIP URIs of routes pointing to this SIP proxy +server. The default is a list containing a single SIP URI constructed +from the virtual host on which the module is loaded. + +- **via**: *\[URI, ...\]* +A list to construct "Via" headers for inserting them into outgoing SIP +messages. This is useful if you’re running your SIP proxy in a +non-standard network topology. Every *URI* element in the list must be +in the form of "scheme://host:port", where "transport" must be *tls*, +*tcp*, or *udp*, "host" must be a domain name or an IP address and +"port" must be an internet port number. Note that all parts of the *URI* +are mandatory (e.g. you cannot omit "port" or "scheme"). + +__**Example**:__ + +~~~ yaml +modules: + mod_sip: + always_record_route: false + record_route: "sip:example.com;lr" + routes: + - "sip:example.com;lr" + - "sip:sip.example.com;lr" + flow_timeout_udp: 30 sec + flow_timeout_tcp: 1 min + via: + - tls://sip-tls.example.com:5061 + - tcp://sip-tcp.example.com:5060 + - udp://sip-udp.example.com:5060 +~~~ + +mod\_stats +---------- + +This module adds support for [XEP-0039: Statistics +Gathering](https://xmpp.org/extensions/xep-0039.html). This protocol +allows you to retrieve the following statistics from your ejabberd +server: + +- Total number of registered users on the current virtual host + (users/total). + +- Total number of registered users on all virtual hosts + (users/all-hosts/total). + +- Total number of online users on the current virtual host + (users/online). + +- Total number of online users on all virtual hosts + (users/all-hosts/online). + +> **Note** +> +> The protocol extension is deferred and seems like even a few clients +> that were supporting it are now abandoned. So using this module makes +> very little sense. + +The module has no options. + +mod\_stream\_mgmt +----------------- + +This module adds support for [XEP-0198: Stream +Management](https://xmpp.org/extensions/xep-0198.html). This protocol +allows active management of an XML stream between two XMPP entities, +including features for stanza acknowledgments and stream resumption. + +__Available options:__ + +- **ack\_timeout**: *timeout()* +A time to wait for stanza acknowledgments. Setting it to *infinity* +effectively disables the timeout. The default value is *1* minute. + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. The default value is *48 hours*. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **max\_ack\_queue**: *Size* +This option specifies the maximum number of unacknowledged stanzas +queued for possible retransmission. When the limit is exceeded, the +client session is terminated. The allowed values are positive integers +and *infinity*. You should be careful when setting this value as it +should not be set too low, otherwise, you could kill sessions in a loop, +before they get the chance to finish proper session initiation. It +should definitely be set higher that the size of the offline queue (for +example at least 3 times the value of the max offline queue and never +lower than *1000*). The default value is *5000*. + +- **max\_resume\_timeout**: *timeout()* +A client may specify the period of time until a session times out if the +connection is lost. During this period of time, the client may resume +its session. This option limits the period of time a client is permitted +to request. It must be set to a timeout equal to or larger than the +default *resume\_timeout*. By default, it is set to the same value as +the *resume\_timeout* option. + +- **queue\_type**: *ram | file* +Same as top-level [queue_type](toplevel.md#queue_type) option, but applied to this module +only. + +- **resend\_on\_timeout**: *true | false | if\_offline* +If this option is set to *true*, any message stanzas that weren’t +acknowledged by the client will be resent on session timeout. This +behavior might often be desired, but could have unexpected results under +certain circumstances. For example, a message that was sent to two +resources might get resent to one of them if the other one timed out. +Therefore, the default value for this option is *false*, which tells +ejabberd to generate an error message instead. As an alternative, the +option may be set to *if\_offline*. In this case, unacknowledged +messages are resent only if no other resource is online when the session +times out. Otherwise, error messages are generated. + +- **resume\_timeout**: *timeout()* +This option configures the (default) period of time until a session +times out if the connection is lost. During this period of time, a +client may resume its session. Note that the client may request a +different timeout value, see the *max\_resume\_timeout* option. Setting +it to *0* effectively disables session resumption. The default value is +*5* minutes. + +mod\_stun\_disco +---------------- + + + + +This module allows XMPP clients to discover STUN/TURN services and to +obtain temporary credentials for using them as per [XEP-0215: External +Service Discovery](https://xmpp.org/extensions/xep-0215.html). + +__Available options:__ + +- **access**: *AccessName* +This option defines which access rule will be used to control who is +allowed to discover STUN/TURN services and to request temporary +credentials. The default value is *local*. + +- **credentials\_lifetime**: *timeout()* +The lifetime of temporary credentials offered to clients. If ejabberd’s +built-in TURN service is used, TURN relays allocated using temporary +credentials will be terminated shortly after the credentials expired. +The default value is *12 hours*. Note that restarting the ejabberd node +invalidates any temporary credentials offered before the restart unless +a *secret* is specified (see below). + +- **offer\_local\_services**: *true | false* +This option specifies whether local STUN/TURN services configured as +ejabberd listeners should be announced automatically. Note that this +will not include TLS-enabled services, which must be configured manually +using the *services* option (see below). For non-anonymous TURN +services, temporary credentials will be offered to the client. The +default value is *true*. + +- **secret**: *Text* +The secret used for generating temporary credentials. If this option +isn’t specified, a secret will be auto-generated. However, a secret must +be specified explicitly if non-anonymous TURN services running on other +ejabberd nodes and/or external TURN *services* are configured. Also note +that auto-generated secrets are lost when the node is restarted, which +invalidates any credentials offered before the restart. Therefore, it’s +recommended to explicitly specify a secret if clients cache retrieved +credentials (for later use) across service restarts. + +- **services**: *\[Service, ...\]* +The list of services offered to clients. This list can include STUN/TURN +services running on any ejabberd node and/or external services. However, +if any listed TURN service not running on the local ejabberd node +requires authentication, a *secret* must be specified explicitly, and +must be shared with that service. This will only work with ejabberd’s +built-in STUN/TURN server and with external servers that support the +same [REST API For Access To TURN +Services](https://tools.ietf.org/html/draft-uberti-behave-turn-rest-00). +Unless the *offer\_local\_services* is set to *false*, the explicitly +listed services will be offered in addition to those announced +automatically. + + - **host**: *Host* + The hostname or IP address the STUN/TURN service is + listening on. For non-TLS services, it’s recommended to specify an + IP address (to avoid additional DNS lookup latency on the client + side). For TLS services, the hostname (or IP address) should match + the certificate. Specifying the *host* option is mandatory. + + - **port**: *1..65535* + The port number the STUN/TURN service is + listening on. The default port number is 3478 for non-TLS services + and 5349 for TLS services. + + - **restricted**: *true | false* + This option determines whether + temporary credentials for accessing the service are offered. The + default is *false* for STUN/STUNS services and *true* for TURN/TURNS + services. + + - **transport**: *tcp | udp* + The transport protocol supported by the + service. The default is *udp* for non-TLS services and *tcp* for TLS + services. + + - **type**: *stun | turn | stuns | turns* + The type of service. Must be + *stun* or *turn* for non-TLS services, *stuns* or *turns* for TLS + services. The default type is *stun*. + + **Example**: + + ~~~ yaml + services: + - + host: 203.0.113.3 + port: 3478 + type: stun + transport: udp + restricted: false + - + host: 203.0.113.3 + port: 3478 + type: turn + transport: udp + restricted: true + - + host: 2001:db8::3 + port: 3478 + type: stun + transport: udp + restricted: false + - + host: 2001:db8::3 + port: 3478 + type: turn + transport: udp + restricted: true + - + host: server.example.com + port: 5349 + type: turns + transport: tcp + restricted: true + ~~~ + +mod\_time +--------- + +This module adds support for [XEP-0202: Entity +Time](https://xmpp.org/extensions/xep-0202.html). In other words, the +module reports server’s system time. + +The module has no options. + +mod\_vcard +---------- + +This module allows end users to store and retrieve their vCard, and to +retrieve other users vCards, as defined in [XEP-0054: +vcard-temp](https://xmpp.org/extensions/xep-0054.html). The module also +implements an uncomplicated Jabber User Directory based on the vCards of +these users. Moreover, it enables the server to send its vCard when +queried. + +__Available options:__ + +- **allow\_return\_all**: *true | false* +This option enables you to specify if search operations with empty input +fields should return all users who added some information to their +vCard. The default value is *false*. + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed**: *true | false* +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **db\_type**: *mnesia | sql | ldap* +Same as top-level [default_db](toplevel.md#default_db) option, but applied to this module +only. + +- **host** +Deprecated. Use *hosts* instead. + +- **hosts**: *\[Host, ...\]* +This option defines the Jabber IDs of the service. If the *hosts* option +is not specified, the only Jabber ID will be the hostname of the virtual +host with the prefix "vjud.". The keyword *@HOST@* is replaced with the +real virtual host name. + +- **matches**: *pos\_integer() | infinity* +With this option, the number of reported search results can be limited. +If the option’s value is set to *infinity*, all search results are +reported. The default value is *30*. + +- **name**: *Name* +The value of the service name. This name is only visible in some clients +that support [XEP-0030: Service +Discovery](https://xmpp.org/extensions/xep-0030.html). The default is +*vCard User Search*. + +- **search**: *true | false* +This option specifies whether the search functionality is enabled or +not. If disabled, the options *hosts*, *name* and *vcard* will be +ignored and the Jabber User Directory service will not appear in the +Service Discovery item list. The default value is *false*. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +- **vcard**: *vCard* +A custom vCard of the server that will be displayed by some XMPP clients +in Service Discovery. The value of *vCard* is a YAML map constructed +from an XML representation of vCard. Since the representation has no +attributes, the mapping is straightforward. + + **Example**: + + ~~~ yaml + # This XML representation of vCard: + # + # + # Conferences + # + # + # Elm Street + # + # + # + # is translated to: + # + vcard: + fn: Conferences + adr: + - + work: true + street: Elm Street + ~~~ + +__Available options for *ldap* backend:__ + +- **ldap\_backups** +Same as top-level [ldap_backups](toplevel.md#ldap_backups) option, but applied to this module +only. + +- **ldap\_base** +Same as top-level [ldap_base](toplevel.md#ldap_base) option, but applied to this module only. + +- **ldap\_deref\_aliases** +Same as top-level [ldap_deref_aliases](toplevel.md#ldap_deref_aliases) option, but applied to this +module only. + +- **ldap\_encrypt** +Same as top-level [ldap_encrypt](toplevel.md#ldap_encrypt) option, but applied to this module +only. + +- **ldap\_filter** +Same as top-level [ldap_filter](toplevel.md#ldap_filter) option, but applied to this module +only. + +- **ldap\_password** +Same as top-level [ldap_password](toplevel.md#ldap_password) option, but applied to this module +only. + +- **ldap\_port** +Same as top-level [ldap_port](toplevel.md#ldap_port) option, but applied to this module only. + +- **ldap\_rootdn** +Same as top-level [ldap_rootdn](toplevel.md#ldap_rootdn) option, but applied to this module +only. + +- **ldap\_search\_fields**: *{Name: Attribute, ...}* +This option defines the search form and the LDAP attributes to search +within. *Name* is the name of a search form field which will be +automatically translated by using the translation files (see +*msgs/\*.msg* for available words). *Attribute* is the LDAP attribute or +the pattern *%u*. + + **Examples**: + + The default is: + + ~~~ yaml + User: "%u" + "Full Name": displayName + "Given Name": givenName + "Middle Name": initials + "Family Name": sn + Nickname: "%u" + Birthday: birthDay + Country: c + City: l + Email: mail + "Organization Name": o + "Organization Unit": ou + ~~~ + +- **ldap\_search\_reported**: *{SearchField: VcardField}, ...}* +This option defines which search fields should be reported. +*SearchField* is the name of a search form field which will be +automatically translated by using the translation files (see +*msgs/\*.msg* for available words). *VcardField* is the vCard field name +defined in the *ldap\_vcard\_map* option. + + **Examples**: + + The default is: + + ~~~ yaml + "Full Name": FN + "Given Name": FIRST + "Middle Name": MIDDLE + "Family Name": LAST + "Nickname": NICKNAME + "Birthday": BDAY + "Country": CTRY + "City": LOCALITY + "Email": EMAIL + "Organization Name": ORGNAME + "Organization Unit": ORGUNIT + ~~~ + +- **ldap\_servers** +Same as top-level [ldap_servers](toplevel.md#ldap_servers) option, but applied to this module +only. + +- **ldap\_tls\_cacertfile** +Same as top-level [ldap_tls_cacertfile](toplevel.md#ldap_tls_cacertfile) option, but applied to this +module only. + +- **ldap\_tls\_certfile** +Same as top-level [ldap_tls_certfile](toplevel.md#ldap_tls_certfile) option, but applied to this +module only. + +- **ldap\_tls\_depth** +Same as top-level [ldap_tls_depth](toplevel.md#ldap_tls_depth) option, but applied to this module +only. + +- **ldap\_tls\_verify** +Same as top-level [ldap_tls_verify](toplevel.md#ldap_tls_verify) option, but applied to this module +only. + +- **ldap\_uids** +Same as top-level [ldap_uids](toplevel.md#ldap_uids) option, but applied to this module only. + +- **ldap\_vcard\_map**: *{Name: {Pattern, LDAPattributes}, ...}* +With this option you can set the table that maps LDAP attributes to +vCard fields. *Name* is the type name of the vCard as defined in [RFC +2426](https://tools.ietf.org/html/rfc2426). *Pattern* is a string which +contains pattern variables *%u*, *%d* or *%s*. *LDAPattributes* is the +list containing LDAP attributes. The pattern variables *%s* will be +sequentially replaced with the values of LDAP attributes from +*List\_of\_LDAP\_attributes*, *%u* will be replaced with the user part +of a JID, and *%d* will be replaced with the domain part of a JID. + + **Examples**: + + The default is: + + ~~~ yaml + NICKNAME: {"%u": []} + FN: {"%s": [displayName]} + LAST: {"%s": [sn]} + FIRST: {"%s": [givenName]} + MIDDLE: {"%s": [initials]} + ORGNAME: {"%s": [o]} + ORGUNIT: {"%s": [ou]} + CTRY: {"%s": [c]} + LOCALITY: {"%s": [l]} + STREET: {"%s": [street]} + REGION: {"%s": [st]} + PCODE: {"%s": [postalCode]} + TITLE: {"%s": [title]} + URL: {"%s": [labeleduri]} + DESC: {"%s": [description]} + TEL: {"%s": [telephoneNumber]} + EMAIL: {"%s": [mail]} + BDAY: {"%s": [birthDay]} + ROLE: {"%s": [employeeType]} + PHOTO: {"%s": [jpegPhoto]} + ~~~ + +__Available options for *mnesia* backend:__ + +- **search\_all\_hosts**: *true | false* +Whether to perform search on all virtual hosts or not. The default value +is *true*. + +mod\_vcard\_xupdate +------------------- + +The user’s client can store an avatar in the user vCard. The vCard-Based +Avatars protocol ([XEP-0153](https://xmpp.org/extensions/xep-0153.html)) +provides a method for clients to inform the contacts what is the avatar +hash value. However, simple or small clients may not implement that +protocol. + +If this module is enabled, all the outgoing client presence stanzas get +automatically the avatar hash on behalf of the client. So, the contacts +receive the presence stanzas with the *Update Data* described in +[XEP-0153](https://xmpp.org/extensions/xep-0153.html) as if the client +would had inserted it itself. If the client had already included such +element in the presence stanza, it is replaced with the element +generated by ejabberd. + +By enabling this module, each vCard modification produces a hash +recalculation, and each presence sent by a client produces hash +retrieval and a presence stanza rewrite. For this reason, enabling this +module will introduce a computational overhead in servers with clients +that change frequently their presence. However, the overhead is +significantly reduced by the use of caching, so you probably don’t want +to set *use\_cache* to *false*. + +The module depends on [mod_vcard](#mod_vcard). + +> **Note** +> +> Nowadays [XEP-0153](https://xmpp.org/extensions/xep-0153.html) is used +> mostly as "read-only", i.e. modern clients don’t publish their avatars +> inside vCards. Thus in the majority of cases the module is only used +> along with [mod_avatar](#mod_avatar) for providing backward compatibility. + +__Available options:__ + +- **cache\_life\_time**: *timeout()* +Same as top-level [cache_life_time](toplevel.md#cache_life_time) option, but applied to this module +only. + +- **cache\_missed**: *true | false* +Same as top-level [cache_missed](toplevel.md#cache_missed) option, but applied to this module +only. + +- **cache\_size**: *pos\_integer() | infinity* +Same as top-level [cache_size](toplevel.md#cache_size) option, but applied to this module +only. + +- **use\_cache**: *true | false* +Same as top-level [use_cache](toplevel.md#use_cache) option, but applied to this module only. + +mod\_version +------------ + +This module implements [XEP-0092: Software +Version](https://xmpp.org/extensions/xep-0092.html). Consequently, it +answers ejabberd’s version when queried. + +__Available options:__ + +- **show\_os**: *true | false* +Should the operating system be revealed or not. The default value is +*true*. + diff --git a/content/archive/24.06/toplevel.md b/content/archive/24.06/toplevel.md new file mode 100644 index 00000000..4055e8db --- /dev/null +++ b/content/archive/24.06/toplevel.md @@ -0,0 +1,1785 @@ +--- +search: + exclude: true +--- + +# Top-Level Options + +> This section describes top level options of ejabberd [24.06](../../archive/24.06/index.md). If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the [Archive](../../archive/index.md). The +options that changed in this version are marked with 🟤. + +## access\_rules + +*{AccessName: {allow|deny: ACLRules|ACLName}}* + +This option defines [Access Rules](../../admin/configuration/basic.md#access-rules). Each access +rule is assigned a name that can be referenced from other parts of the +configuration file (mostly from *access* options of ejabberd modules). +Each rule definition may contain arbitrary number of *allow* or *deny* +sections, and each section may contain any number of ACL rules (see +[acl](#acl) option). There are no access rules defined by default. + +**Example**: + +~~~ yaml +access_rules: + configure: + allow: admin + something: + deny: someone + allow: all + s2s_banned: + deny: problematic_hosts + deny: banned_forever + deny: + ip: 222.111.222.111/32 + deny: + ip: 111.222.111.222/32 + allow: all + xmlrpc_access: + allow: + user: peter@example.com + allow: + user: ivone@example.com + allow: + user: bot@example.com + ip: 10.0.0.0/24 +~~~ + +## acl + +*{ACLName: {ACLType: ACLValue}}* + +The option defines access control lists: named sets of rules which are +used to match against different targets (such as a JID or an IP +address). Every set of rules has name *ACLName*: it can be any string +except *all* or *none* (those are predefined names for the rules that +match all or nothing respectively). The name *ACLName* can be referenced +from other parts of the configuration file, for example in +[access_rules](#access_rules) option. The rules of *ACLName* are represented by +mapping *{ACLType: ACLValue}*. These can be one of the following: + +- **ip**: *Network* + The rule matches any IP address from the + *Network*. + +- **node\_glob**: *Pattern* + Same as *node\_regexp*, but matching is + performed on a specified *Pattern* according to the rules used by + the Unix shell. + +- **node\_regexp**: *user\_regexp@server\_regexp* + The rule matches any + JID with node part matching regular expression *user\_regexp* and + server part matching regular expression *server\_regexp*. + +- **resource**: *Resource* + The rule matches any JID with a resource + *Resource*. + +- **resource\_glob**: *Pattern* + Same as *resource\_regexp*, but + matching is performed on a specified *Pattern* according to the + rules used by the Unix shell. + +- **resource\_regexp**: *Regexp* + The rule matches any JID with a + resource that matches regular expression *Regexp*. + +- **server**: *Server* + The rule matches any JID from server *Server*. + The value of *Server* must be a valid hostname or an IP address. + +- **server\_glob**: *Pattern* + Same as *server\_regexp*, but matching + is performed on a specified *Pattern* according to the rules used by + the Unix shell. + +- **server\_regexp**: *Regexp* + The rule matches any JID from the + server that matches regular expression *Regexp*. + +- **user**: *Username* + If *Username* is in the form of "user@server", + the rule matches a JID against this value. Otherwise, if *Username* + is in the form of "user", the rule matches any JID that has + *Username* in the node part as long as the server part of this JID + is any virtual host served by ejabberd. + +- **user\_glob**: *Pattern* + Same as *user\_regexp*, but matching is + performed on a specified *Pattern* according to the rules used by + the Unix shell. + +- **user\_regexp**: *Regexp* + If *Regexp* is in the form of + "regexp@server", the rule matches any JID with node part matching + regular expression "regexp" as long as the server part of this JID + is equal to "server". If *Regexp* is in the form of "regexp", the + rule matches any JID with node part matching regular expression + "regexp" as long as the server part of this JID is any virtual host + served by ejabberd. + +## acme + +*Options* + +[ACME](../../admin/configuration/basic.md#acme) configuration, to automatically obtain SSL +certificates for the domains served by ejabberd, which means that +certificate requests and renewals are performed to some CA server (aka +"ACME server") in a fully automated mode. The *Options* are: + +- **auto**: *true | false* + Whether to automatically request + certificates for all configured domains (that yet have no a + certificate) on server start or configuration reload. The default is + *true*. + +- **ca\_url**: *URL* + The ACME directory URL used as an entry point for + the ACME server. The default value is + - the directory URL + of Let’s Encrypt authority. + +- **cert\_type**: *rsa | ec* + A type of a certificate key. Available + values are *ec* and *rsa* for EC and RSA certificates respectively. + It’s better to have RSA certificates for the purpose of backward + compatibility with legacy clients and servers, thus the default is + *rsa*. + +- **contact**: *\[Contact, ...\]* + A list of contact addresses + (typically emails) where an ACME server will send notifications when + problems occur. The value of *Contact* must be in the form of + "scheme:address" (e.g. "mailto:user@domain.tld"). The default is an + empty list which means an ACME server will send no notices. + +**Example**: + +~~~ yaml +acme: + ca_url: https://acme-v02.api.letsencrypt.org/directory + contact: + - mailto:admin@domain.tld + - mailto:bot@domain.tld + auto: true + cert_type: rsa +~~~ + +## allow\_contrib\_modules + +*true | false* + +Whether to allow installation of third-party modules or not. See +[ejabberd-contrib](../../developer/extending-ejabberd/modules.md#ejabberd-contrib) +documentation section. The default value is *true*. + +## allow\_multiple\_connections + +*true | false* + +This option is only used when the anonymous mode is enabled. Setting it +to *true* means that the same username can be taken multiple times in +anonymous login mode if different resource are used to connect. This +option is only useful in very special occasions. The default value is +*false*. + +## anonymous\_protocol + +*login\_anon | sasl\_anon | both* + +Define what anonymous protocol will be used: + +- *login\_anon* means that the anonymous login method will be used. + +- *sasl\_anon* means that the SASL Anonymous method will be used. + +- *both* means that SASL Anonymous and login anonymous are both + enabled. + +The default value is *sasl\_anon*. + +## api\_permissions + +*\[Permission, ...\]* + +Define the permissions for API access. Please consult the ejabberd Docs +web → For Developers → ejabberd ReST API → +[API Permissions](../../developer/ejabberd-api/permissions.md). + +## append\_host\_config + +*{Host: Options}* + +To define specific ejabberd modules in a virtual host, you can define +the global *modules* option with the common modules, and later add +specific modules to certain virtual hosts. To accomplish that, +*append\_host\_config* option can be used. + +## auth\_cache\_life\_time + +*timeout()* + +Same as [cache_life_time](#cache_life_time), but applied to authentication cache only. +If not set, the value from [cache_life_time](#cache_life_time) will be used. + +## auth\_cache\_missed + +*true | false* + +Same as [cache_missed](#cache_missed), but applied to authentication cache only. If +not set, the value from [cache_missed](#cache_missed) will be used. + +## auth\_cache\_size + +*pos\_integer() | infinity* + +Same as [cache_size](#cache_size), but applied to authentication cache only. If not +set, the value from [cache_size](#cache_size) will be used. + +## auth\_external\_user\_exists\_check + +*true | false* + + + +Supplement check for user +existence based on *mod\_last* data, for authentication methods that +don’t have a way to reliably tell if a user exists (like is the case for +*jwt* and certificate based authentication). This helps with processing +offline message for those users. The default value is *true*. + +## auth\_method + +*\[mnesia | sql | anonymous | external | jwt | ldap | pam, ...\]* + +A list of authentication methods to use. If several methods are defined, +authentication is considered successful as long as authentication of at +least one of the methods succeeds. The default value is *\[mnesia\]*. + +## auth\_opts + +*\[Option, ...\]* + +This is used by the contributed module *ejabberd\_auth\_http* that can +be installed from the +[ejabberd-contrib](https://github.com/processone/ejabberd-contrib) Git +repository. Please refer to that module’s README file for details. + +## auth\_password\_format + +*plain | scram* + + + +The option defines in what +format the users passwords are stored, plain text or in +[SCRAM](../../admin/configuration/authentication.md#scram) format: + +- *plain*: The password is stored as plain text in the database. This + is risky because the passwords can be read if your database gets + compromised. This is the default value. This format allows clients + to authenticate using: the old Jabber Non-SASL (XEP-0078), SASL + PLAIN, SASL DIGEST-MD5, and SASL SCRAM-SHA-1/256/512(-PLUS). + +- *scram*: The password is not stored, only some information required + to verify the hash provided by the client. It is impossible to + obtain the original plain password from the stored information; for + this reason, when this value is configured it cannot be changed to + plain anymore. This format allows clients to authenticate using: + SASL PLAIN and SASL SCRAM-SHA-1/256/512(-PLUS). The SCRAM variant + depends on the [auth_scram_hash](#auth_scram_hash) option. + +The default value is *plain*. + +## auth\_scram\_hash + +*sha | sha256 | sha512* + +Hash algorithm that should be used to store password in +[SCRAM](../../admin/configuration/authentication.md#scram) format. You shouldn’t change this if +you already have passwords generated with a different algorithm - users +that have such passwords will not be able to authenticate. The default +value is *sha*. + +## auth\_use\_cache + +*true | false* + +Same as [use_cache](#use_cache), but applied to authentication cache only. If not +set, the value from [use_cache](#use_cache) will be used. + +## c2s\_cafile + +*Path* + +Full path to a file containing one or more CA certificates in PEM +format. All client certificates should be signed by one of these root CA +certificates and should contain the corresponding JID(s) in +*subjectAltName* field. There is no default value. + +You can use [host_config](#host_config) to specify this option per-vhost. + +To set a specific file per listener, use the listener’s +[cafile](listen-options.md#cafile) option. Please notice that +*c2s\_cafile* overrides the listener’s *cafile* option. + +## c2s\_ciphers + +*\[Cipher, ...\]* + +A list of OpenSSL ciphers to use for c2s connections. The default value +is shown in the example below: + +**Example**: + +~~~ yaml +c2s_ciphers: + - HIGH + - "!aNULL" + - "!eNULL" + - "!3DES" + - "@STRENGTH" +~~~ + +## c2s\_dhfile + +*Path* + +Full path to a file containing custom DH parameters to use for c2s +connections. Such a file could be created with the command "openssl +dhparam -out dh.pem 2048". If this option is not specified, 2048-bit +MODP Group with 256-bit Prime Order Subgroup will be used as defined in +RFC5114 Section 2.3. + +## c2s\_protocol\_options + +*\[Option, ...\]* + +List of general SSL options to use for c2s connections. These map to +OpenSSL’s *set\_options()*. The default value is shown in the example +below: + +**Example**: + +~~~ yaml +c2s_protocol_options: + - no_sslv3 + - cipher_server_preference + - no_compression +~~~ + +## c2s\_tls\_compression + +*true | false* + +Whether to enable or disable TLS compression for c2s connections. The +default value is *false*. + +## ca\_file + +*Path* + +Path to a file of CA root certificates. The default is to use system +defined file if possible. + +For server connections, this *ca\_file* option is overridden by the +[s2s_cafile](#s2s_cafile) option. + +## cache\_life\_time + +*timeout()* + +The time of a cached item to keep in cache. Once it’s expired, the +corresponding item is erased from cache. The default value is *1 hour*. +Several modules have a similar option; and some core ejabberd parts +support similar options too, see [auth_cache_life_time](#auth_cache_life_time), +[oauth_cache_life_time](#oauth_cache_life_time), [router_cache_life_time](#router_cache_life_time), and +[sm_cache_life_time](#sm_cache_life_time). + +## cache\_missed + +*true | false* + +Whether or not to cache missed lookups. When there is an attempt to +lookup for a value in a database and this value is not found and the +option is set to *true*, this attempt will be cached and no attempts +will be performed until the cache expires (see [cache_life_time](#cache_life_time)). +Usually you don’t want to change it. Default is *true*. Several modules +have a similar option; and some core ejabberd parts support similar +options too, see [auth_cache_missed](#auth_cache_missed), [oauth_cache_missed](#oauth_cache_missed), +[router_cache_missed](#router_cache_missed), and [sm_cache_missed](#sm_cache_missed). + +## cache\_size + +*pos\_integer() | infinity* + +A maximum number of items (not memory!) in cache. The rule of thumb, for +all tables except rosters, you should set it to the number of maximum +online users you expect. For roster multiply this number by 20 or so. If +the cache size reaches this threshold, it’s fully cleared, i.e. all +items are deleted, and the corresponding warning is logged. You should +avoid frequent cache clearance, because this degrades performance. The +default value is *1000*. Several modules have a similar option; and some +core ejabberd parts support similar options too, see +[auth_cache_size](#auth_cache_size), [oauth_cache_size](#oauth_cache_size), [router_cache_size](#router_cache_size), and +[sm_cache_size](#sm_cache_size). + +## captcha\_cmd + +*Path | ModuleName* + + + +Full path to a script that +generates [CAPTCHA](../../admin/configuration/basic.md#captcha) images. *@VERSION@* is replaced +with ejabberd version number in *XX.YY* format. *@SEMVER@* is replaced +with ejabberd version number in semver format when compiled with +Elixir’s mix, or XX.YY format otherwise. Alternatively, it can be the +name of a module that implements ejabberd CAPTCHA support. There is no +default value: when this option is not set, CAPTCHA functionality is +completely disabled. + +**Examples**: + +When using the ejabberd installers or container image, the example +captcha scripts can be used like this: + +~~~ yaml +captcha_cmd: /opt/ejabberd-@VERSION@/lib/ejabberd-@SEMVER@/priv/bin/captcha.sh +~~~ + +## captcha\_host + +*String* + +Deprecated. Use [captcha_url](#captcha_url) instead. + +## captcha\_limit + +*pos\_integer() | infinity* + +Maximum number of [CAPTCHA](../../admin/configuration/basic.md#captcha) generated images per +minute for any given JID. The option is intended to protect the server +from CAPTCHA DoS. The default value is *infinity*. + +## captcha\_url + +*URL | auto | undefined* + + + +An URL where +[CAPTCHA](../../admin/configuration/basic.md#captcha) requests should be sent. NOTE: you need to +configure *request\_handlers* for *ejabberd\_http* listener as well. If +set to *auto*, it builds the URL using a *request\_handler* already +enabled, with encryption if available. If set to *undefined*, it builds +the URL using the deprecated [captcha_host](#captcha_host) + /captcha. The default +value is *auto*. + +## certfiles + +*\[Path, ...\]* + +The option accepts a list of file paths (optionally with wildcards) +containing either PEM certificates or PEM private keys. At startup or +configuration reload, ejabberd reads all certificates from these files, +sorts them, removes duplicates, finds matching private keys and then +rebuilds full certificate chains for the use in TLS connections. Use +this option when TLS is enabled in either of ejabberd listeners: +*ejabberd\_c2s*, *ejabberd\_http* and so on. NOTE: if you modify the +certificate files or change the value of the option, run *ejabberdctl +reload-config* in order to rebuild and reload the certificate chains. + +**Examples**: + +If you use [Let’s Encrypt](https://letsencrypt.org) certificates for +your domain "domain.tld", the configuration will look like this: + +~~~ yaml +certfiles: + - /etc/letsencrypt/live/domain.tld/fullchain.pem + - /etc/letsencrypt/live/domain.tld/privkey.pem +~~~ + +## cluster\_backend + +*Backend* + +A database backend to use for storing information about cluster. The +only available value so far is *mnesia*. + +## cluster\_nodes + +*\[Node, ...\]* + +A list of Erlang nodes to connect on ejabberd startup. This option is +mostly intended for ejabberd customization and sophisticated setups. The +default value is an empty list. + +## default\_db + +*mnesia | sql* + +Default persistent storage for ejabberd. Modules and other components +(e.g. authentication) may have its own value. The default value is +*mnesia*. + +## default\_ram\_db + +*mnesia | redis | sql* + +Default volatile (in-memory) storage for ejabberd. Modules and other +components (e.g. session management) may have its own value. The default +value is *mnesia*. + +## define\_macro + +*{MacroName: MacroValue}* + +Defines a macro. The value can be any valid arbitrary YAML value. For +convenience, it’s recommended to define a *MacroName* in capital +letters. Duplicated macros are not allowed. Macros are processed after +additional configuration files have been included, so it is possible to +use macros that are defined in configuration files included before the +usage. It is possible to use a *MacroValue* in the definition of another +macro. + +**Example**: + +~~~ yaml +define_macro: + DEBUG: debug + LOG_LEVEL: DEBUG + USERBOB: + user: bob@localhost + +loglevel: LOG_LEVEL + +acl: + admin: USERBOB +~~~ + +## disable\_sasl\_mechanisms + +*\[Mechanism, ...\]* + +Specify a list of SASL mechanisms (such as *DIGEST-MD5* or *SCRAM-SHA1*) +that should not be offered to the client. For convenience, the value of +*Mechanism* is case-insensitive. The default value is an empty list, +i.e. no mechanisms are disabled by default. + +## disable\_sasl\_scram\_downgrade\_protection + +*true | false* + +Allows to disable sending data required by *XEP-0474: SASL SCRAM +Downgrade Protection*. There are known buggy clients (like those that +use strophejs 1.6.2) which will not be able to authenticatate when +servers sends data from that specification. This options allows server +to disable it to allow even buggy clients connects, but in exchange +decrease MITM protection. The default value of this option is *false* +which enables this extension. + +## domain\_balancing + +*{Domain: Options}* + +An algorithm to load balance the components that are plugged on an +ejabberd cluster. It means that you can plug one or several instances of +the same component on each ejabberd node and that the traffic will be +automatically distributed. The algorithm to deliver messages to the +component(s) can be specified by this option. For any component +connected as *Domain*, available *Options* are: + +- **component\_number**: *2..1000* + The number of components to + balance. + +- **type**: *random | source | destination | bare\_source | + bare\_destination* How to deliver stanzas to connected components: + *random* - an instance is chosen at random; *destination* - an + instance is chosen by the full JID of the packet’s *to* attribute; + *source* - by the full JID of the packet’s *from* attribute; + *bare\_destination* - by the bare JID (without resource) of the + packet’s *to* attribute; *bare\_source* - by the bare JID (without + resource) of the packet’s *from* attribute is used. The default + value is *random*. + +**Example**: + +~~~ yaml +domain_balancing: + component.domain.tld: + type: destination + component_number: 5 + transport.example.org: + type: bare_source +~~~ + +## ext\_api\_headers + +*Headers* + +String of headers (separated with commas *,*) that will be provided by +ejabberd when sending ReST requests. The default value is an empty +string of headers: *""*. + +## ext\_api\_http\_pool\_size + +*pos\_integer()* + +Define the size of the HTTP pool, that is, the maximum number of +sessions that the ejabberd ReST service will handle simultaneously. The +default value is: *100*. + +## ext\_api\_path\_oauth + +*Path* + +Define the base URI path when performing OAUTH ReST requests. The +default value is: *"/oauth"*. + +## ext\_api\_url + +*URL* + +Define the base URI when performing ReST requests. The default value is: +*"http://localhost/api"*. + +## extauth\_pool\_name + +*Name* + +Define the pool name appendix, so the full pool name will be +*extauth\_pool\_Name*. The default value is the hostname. + +## extauth\_pool\_size + +*Size* + +The option defines the number of instances of the same external program +to start for better load balancing. The default is the number of +available CPU cores. + +## extauth\_program + +*Path* + +Indicate in this option the full path to the external authentication +script. The script must be executable by ejabberd. + +## fqdn + +*Domain* + +A fully qualified domain name that will be used in SASL DIGEST-MD5 +authentication. The default is detected automatically. + +## hide\_sensitive\_log\_data + +*true | false* + +A privacy option to not log sensitive data (mostly IP addresses). The +default value is *false* for backward compatibility. + +## host\_config + +*{Host: Options}* + +The option is used to redefine *Options* for virtual host *Host*. In the +example below LDAP authentication method will be used on virtual host +*domain.tld* and SQL method will be used on virtual host *example.org*. + +**Example**: + +~~~ yaml +hosts: + - domain.tld + - example.org + +auth_method: + - sql + +host_config: + domain.tld: + auth_method: + - ldap +~~~ + +## hosts + +*\[Domain1, Domain2, ...\]* + +The option defines a list containing one or more domains that *ejabberd* +will serve. This is a **mandatory** option. + +## include\_config\_file + +*\[Filename, ...\] | {Filename: Options}* + +Read additional configuration from *Filename*. If the value is provided +in *{Filename: Options}* format, the *Options* must be one of the +following: + +- **allow\_only**: *\[OptionName, ...\]* + Allows only the usage of + those options in the included file *Filename*. The options that do + not match this criteria are not accepted. The default value is to + include all options. + +- **disallow**: *\[OptionName, ...\]* + Disallows the usage of those + options in the included file *Filename*. The options that match this + criteria are not accepted. The default value is an empty list. + +## install\_contrib\_modules + +*\[Module, ...\]* + + + +Modules to install from +[ejabberd-contrib](../../developer/extending-ejabberd/modules.md#ejabberd-contrib) +at start time. The default value is an empty list of modules: *\[\]*. + +## jwt\_auth\_only\_rule + +*AccessName* + +This ACL rule defines accounts that can use only this auth method, even +if others are also defined in the ejabberd configuration file. In other +words: if there are several auth methods enabled for this host (JWT, +SQL, …), users that match this rule can only use JWT. The default value +is *none*. + +## jwt\_jid\_field + +*FieldName* + +By default, the JID is defined in the *"jid"* JWT field. In this option +you can specify other JWT field name where the JID is defined. + +## jwt\_key + +*FilePath* + +Path to the file that contains the JWK Key. The default value is +*undefined*. + +## language + +*Language* + +The option defines the default language of server strings that can be +seen by XMPP clients. If an XMPP client does not possess *xml:lang* +attribute, the specified language is used. The default value is *"en"*. + +## ldap\_backups + +*\[Host, ...\]* + +A list of IP addresses or DNS names of LDAP backup servers. When no +servers listed in [ldap_servers](#ldap_servers) option are reachable, ejabberd will +try to connect to these backup servers. The default is an empty list, +i.e. no backup servers specified. WARNING: ejabberd doesn’t try to +reconnect back to the main servers when they become operational again, +so the only way to restore these connections is to restart ejabberd. +This limitation might be fixed in future releases. + +## ldap\_base + +*Base* + +LDAP base directory which stores users accounts. There is no default +value: you must set the option in order for LDAP connections to work +properly. + +## ldap\_deref\_aliases + +*never | always | finding | searching* + +Whether to dereference aliases or not. The default value is *never*. + +## ldap\_dn\_filter + +*{Filter: FilterAttrs}* + +This filter is applied on the results returned by the main filter. The +filter performs an additional LDAP lookup to make the complete result. +This is useful when you are unable to define all filter rules in +*ldap\_filter*. You can define "%u", "%d", "%s" and "%D" pattern +variables in *Filter*: "%u" is replaced by a user’s part of the JID, +"%d" is replaced by the corresponding domain (virtual host), all "%s" +variables are consecutively replaced by values from the attributes in +*FilterAttrs* and "%D" is replaced by Distinguished Name from the result +set. There is no default value, which means the result is not filtered. +WARNING: Since this filter makes additional LDAP lookups, use it only as +the last resort: try to define all filter rules in [ldap_filter](#ldap_filter) +option if possible. + +**Example**: + +~~~ yaml +ldap_dn_filter: + "(&(name=%s)(owner=%D)(user=%u@%d))": [sn] +~~~ + +## ldap\_encrypt + +*tls | none* + +Whether to encrypt LDAP connection using TLS or not. The default value +is *none*. NOTE: STARTTLS encryption is not supported. + +## ldap\_filter + +*Filter* + +An LDAP filter as defined in +[RFC4515](https://tools.ietf.org/html/rfc4515). There is no default +value. Example: "(&(objectClass=shadowAccount)(memberOf=XMPP Users))". +NOTE: don’t forget to close brackets and don’t use superfluous +whitespaces. Also you must not use "uid" attribute in the filter because +this attribute will be appended to the filter automatically. + +## ldap\_password + +*Password* + +Bind password. The default value is an empty string. + +## ldap\_port + +*1..65535* + +Port to connect to your LDAP server. The default port is *389* if +encryption is disabled and *636* if encryption is enabled. + +## ldap\_rootdn + +*RootDN* + +Bind Distinguished Name. The default value is an empty string, which +means "anonymous connection". + +## ldap\_servers + +*\[Host, ...\]* + +A list of IP addresses or DNS names of your LDAP servers. The default +value is *\[localhost\]*. + +## ldap\_tls\_cacertfile + +*Path* + +A path to a file containing PEM encoded CA certificates. This option is +required when TLS verification is enabled. + +## ldap\_tls\_certfile + +*Path* + +A path to a file containing PEM encoded certificate along with PEM +encoded private key. This certificate will be provided by ejabberd when +TLS enabled for LDAP connections. There is no default value, which means +no client certificate will be sent. + +## ldap\_tls\_depth + +*Number* + +Specifies the maximum verification depth when TLS verification is +enabled, i.e. how far in a chain of certificates the verification +process can proceed before the verification is considered to be failed. +Peer certificate = 0, CA certificate = 1, higher level CA certificate = +2, etc. The value *2* thus means that a chain can at most contain peer +cert, CA cert, next CA cert, and an additional CA cert. The default +value is *1*. + +## ldap\_tls\_verify + +*false | soft | hard* + +This option specifies whether to verify LDAP server certificate or not +when TLS is enabled. When *hard* is set, ejabberd doesn’t proceed if the +certificate is invalid. When *soft* is set, ejabberd proceeds even if +the check has failed. The default is *false*, which means no checks are +performed. + +## ldap\_uids + +*\[Attr\] | {Attr: AttrFormat}* + +LDAP attributes which hold a list of attributes to use as alternatives +for getting the JID, where *Attr* is an LDAP attribute which holds the +user’s part of the JID and *AttrFormat* must contain one and only one +pattern variable "%u" which will be replaced by the user’s part of the +JID. For example, "%.org". If the value is in the form of +*\[Attr\]* then *AttrFormat* is assumed to be "%u". + +## listen + +*\[Options, ...\]* + +The option for listeners configuration. See the +[Listen Modules](listen.md) section for details. + +## log\_burst\_limit\_count + +*Number* + + + +The number of messages to +accept in `log_burst_limit_window_time` period before starting to drop +them. Default 500 + +## log\_burst\_limit\_window\_time + +*Number* + + + +The time period to rate-limit +log messages by. Defaults to 1 second. + +## log\_modules\_fully + +*\[Module, ...\]* + + + +List of modules that will log +everything independently from the general loglevel option. + +## log\_rotate\_count + +*Number* + +The number of rotated log files to keep. The default value is *1*, which +means that only keeps `ejabberd.log.0`, `error.log.0` and `crash.log.0`. + +## log\_rotate\_size + +*pos\_integer() | infinity* + +The size (in bytes) of a log file to trigger rotation. If set to +*infinity*, log rotation is disabled. The default value is *10485760* +(that is, 10 Mb). + +## loglevel + +*none | emergency | alert | critical | error | warning | notice | info | debug* + +Verbosity of log files generated by ejabberd. The default value is +*info*. NOTE: previous versions of ejabberd had log levels defined in +numeric format (*0..5*). The numeric values are still accepted for +backward compatibility, but are not recommended. + +## max\_fsm\_queue + +*Size* + +This option specifies the maximum number of elements in the queue of the +FSM (Finite State Machine). Roughly speaking, each message in such +queues represents one XML stanza queued to be sent into its relevant +outgoing stream. If queue size reaches the limit (because, for example, +the receiver of stanzas is too slow), the FSM and the corresponding +connection (if any) will be terminated and error message will be logged. +The reasonable value for this option depends on your hardware +configuration. The allowed values are positive integers. The default +value is *10000*. + +## modules + +*{Module: Options}* + +The option for modules configuration. See [Modules](modules.md) section +for details. + +## negotiation\_timeout + +*timeout()* + +Time to wait for an XMPP stream negotiation to complete. When timeout +occurs, the corresponding XMPP stream is closed. The default value is +*120* seconds. + +## net\_ticktime + +*timeout()* + +This option can be used to tune tick time parameter of *net\_kernel*. It +tells Erlang VM how often nodes should check if intra-node communication +was not interrupted. This option must have identical value on all nodes, +or it will lead to subtle bugs. Usually leaving default value of this is +option is best, tweak it only if you know what you are doing. The +default value is *1 minute*. + +## new\_sql\_schema + +*true | false* + +Whether to use *new* SQL schema. All schemas are located at +. There are two +schemas available. The default legacy schema stores one XMPP domain into +one ejabberd database. The *new* schema can handle several XMPP domains +in a single ejabberd database. Using this *new* schema is best when +serving several XMPP domains and/or changing domains from time to time. +This avoid need to manage several databases and handle complex +configuration changes. The default depends on configuration flag +*--enable-new-sql-schema* which is set at compile time. + +## oauth\_access + +*AccessName* + +By default creating OAuth tokens is not allowed. To define which users +can create OAuth tokens, you can refer to an ejabberd access rule in the +*oauth\_access* option. Use *all* to allow everyone to create tokens. + +## oauth\_cache\_life\_time + +*timeout()* + +Same as [cache_life_time](#cache_life_time), but applied to OAuth cache only. If not +set, the value from [cache_life_time](#cache_life_time) will be used. + +## oauth\_cache\_missed + +*true | false* + +Same as [cache_missed](#cache_missed), but applied to OAuth cache only. If not set, +the value from [cache_missed](#cache_missed) will be used. + +## oauth\_cache\_rest\_failure\_life\_time + +*timeout()* + + + +The time that a failure in +OAuth ReST is cached. The default value is *infinity*. + +## oauth\_cache\_size + +*pos\_integer() | infinity* + +Same as [cache_size](#cache_size), but applied to OAuth cache only. If not set, the +value from [cache_size](#cache_size) will be used. + +## oauth\_client\_id\_check + +*allow | db | deny* + +Define whether the client authentication is always allowed, denied, or +it will depend if the client ID is present in the database. The default +value is *allow*. + +## oauth\_db\_type + +*mnesia | sql* + +Database backend to use for OAuth authentication. The default value is +picked from [default_db](#default_db) option, or if it’s not set, *mnesia* will be +used. + +## oauth\_expire + +*timeout()* + +Time during which the OAuth token is valid, in seconds. After that +amount of time, the token expires and the delegated credential cannot be +used and is removed from the database. The default is *4294967* seconds. + +## oauth\_use\_cache + +*true | false* + +Same as [use_cache](#use_cache), but applied to OAuth cache only. If not set, the +value from [use_cache](#use_cache) will be used. + +## oom\_killer + +*true | false* + +Enable or disable OOM (out-of-memory) killer. When system memory raises +above the limit defined in [oom_watermark](#oom_watermark) option, ejabberd triggers +OOM killer to terminate most memory consuming Erlang processes. Note +that in order to maintain functionality, ejabberd only attempts to kill +transient processes, such as those managing client sessions, s2s or +database connections. The default value is *true*. + +## oom\_queue + +*Size* + +Trigger OOM killer when some of the running Erlang processes have +messages queue above this *Size*. Note that such processes won’t be +killed if [oom_killer](#oom_killer) option is set to *false* or if *oom\_watermark* +is not reached yet. + +## oom\_watermark + +*Percent* + +A percent of total system memory consumed at which OOM killer should be +activated with some of the processes possibly be killed (see +[oom_killer](#oom_killer) option). Later, when memory drops below this *Percent*, +OOM killer is deactivated. The default value is *80* percents. + +## outgoing\_s2s\_families + +*\[ipv6 | ipv4, ...\]* + + + +Specify which address +families to try, in what order. The default is *\[ipv6, ipv4\]* which +means it first tries connecting with IPv6, if that fails it tries using +IPv4. This option is obsolete and irrelevant when using ejabberd [23.01](../../archive/23.01/index.md) +and Erlang/OTP 22, or newer versions of them. + +## outgoing\_s2s\_ipv4\_address + +*Address* + + + +Specify the IPv4 address that +will be used when establishing an outgoing S2S IPv4 connection, for +example "127.0.0.1". The default value is *undefined*. + +## outgoing\_s2s\_ipv6\_address + +*Address* + + + +Specify the IPv6 address that +will be used when establishing an outgoing S2S IPv6 connection, for +example "::FFFF:127.0.0.1". The default value is *undefined*. + +## outgoing\_s2s\_port + +*1..65535* + +A port number to use for outgoing s2s connections when the target server +doesn’t have an SRV record. The default value is *5269*. + +## outgoing\_s2s\_timeout + +*timeout()* + +The timeout in seconds for outgoing S2S connection attempts. The default +value is *10* seconds. + +## pam\_service + +*Name* + +This option defines the PAM service name. Refer to the PAM documentation +of your operation system for more information. The default value is +*ejabberd*. + +## pam\_userinfotype + +*username | jid* + +This option defines what type of information about the user ejabberd +provides to the PAM service: only the username, or the user’s JID. +Default is *username*. + +## pgsql\_users\_number\_estimate + +*true | false* + +Whether to use PostgreSQL estimation when counting registered users. The +default value is *false*. + +## queue\_dir + +*Directory* + +If [queue_type](#queue_type) option is set to *file*, use this *Directory* to store +file queues. The default is to keep queues inside Mnesia directory. + +## queue\_type + +*ram | file* + +Default type of queues in ejabberd. Modules may have its own value of +the option. The value of *ram* means that queues will be kept in memory. +If value *file* is set, you may also specify directory in [queue_dir](#queue_dir) +option where file queues will be placed. The default value is *ram*. + +## redis\_connect\_timeout + +*timeout()* + +A timeout to wait for the connection to be re-established to the Redis +server. The default is *1 second*. + +## redis\_db + +*Number* + +Redis database number. The default is *0*. + +## redis\_password + +*Password* + +The password to the Redis server. The default is an empty string, i.e. +no password. + +## redis\_pool\_size + +*Number* + +The number of simultaneous connections to the Redis server. The default +value is *10*. + +## redis\_port + +*1..65535* + +The port where the Redis server is accepting connections. The default is +*6379*. + +## redis\_queue\_type + +*ram | file* + +The type of request queue for the Redis server. See description of +[queue_type](#queue_type) option for the explanation. The default value is the +value defined in [queue_type](#queue_type) or *ram* if the latter is not set. + +## redis\_server + +*Hostname* + +A hostname or an IP address of the Redis server. The default is +*localhost*. + +## registration\_timeout + +*timeout()* + +This is a global option for module [mod_register](modules.md#mod_register). It limits the +frequency of registrations from a given IP or username. So, a user that +tries to register a new account from the same IP address or JID during +this time after their previous registration will receive an error with +the corresponding explanation. To disable this limitation, set the value +to *infinity*. The default value is *600 seconds*. + +## resource\_conflict + +*setresource | closeold | closenew* + +NOTE: this option is deprecated and may be removed anytime in the future +versions. The possible values match exactly the three possibilities +described in [XMPP Core: section +7.7.2.2](https://tools.ietf.org/html/rfc6120#section-7.7.2.2). The +default value is *closeold*. If the client uses old Jabber Non-SASL +authentication (XEP-0078), then this option is not respected, and the +action performed is *closeold*. + +## router\_cache\_life\_time + +*timeout()* + +Same as [cache_life_time](#cache_life_time), but applied to routing table cache only. If +not set, the value from [cache_life_time](#cache_life_time) will be used. + +## router\_cache\_missed + +*true | false* + +Same as [cache_missed](#cache_missed), but applied to routing table cache only. If +not set, the value from [cache_missed](#cache_missed) will be used. + +## router\_cache\_size + +*pos\_integer() | infinity* + +Same as [cache_size](#cache_size), but applied to routing table cache only. If not +set, the value from [cache_size](#cache_size) will be used. + +## router\_db\_type + +*mnesia | redis | sql* + +Database backend to use for routing information. The default value is +picked from [default_ram_db](#default_ram_db) option, or if it’s not set, *mnesia* will +be used. + +## router\_use\_cache + +*true | false* + +Same as [use_cache](#use_cache), but applied to routing table cache only. If not +set, the value from [use_cache](#use_cache) will be used. + +## rpc\_timeout + +*timeout()* + +A timeout for remote function calls between nodes in an ejabberd +cluster. You should probably never change this value since those calls +are used for internal needs only. The default value is *5* seconds. + +## s2s\_access + +*Access* + +This [Access Rule](../../admin/configuration/basic.md#access-rules) defines to what remote +servers can s2s connections be established. The default value is *all*; +no restrictions are applied, it is allowed to connect s2s to/from all +remote servers. + +## s2s\_cafile + +*Path* + +A path to a file with CA root certificates that will be used to +authenticate s2s connections. If not set, the value of [ca_file](#ca_file) will +be used. + +You can use [host_config](#host_config) to specify this option per-vhost. + +## s2s\_ciphers + +*\[Cipher, ...\]* + +A list of OpenSSL ciphers to use for s2s connections. The default value +is shown in the example below: + +**Example**: + +~~~ yaml +s2s_ciphers: + - HIGH + - "!aNULL" + - "!eNULL" + - "!3DES" + - "@STRENGTH" +~~~ + +## s2s\_dhfile + +*Path* + +Full path to a file containing custom DH parameters to use for s2s +connections. Such a file could be created with the command "openssl +dhparam -out dh.pem 2048". If this option is not specified, 2048-bit +MODP Group with 256-bit Prime Order Subgroup will be used as defined in +RFC5114 Section 2.3. + +## s2s\_dns\_retries + +*Number* + +DNS resolving retries. The default value is *2*. + +## s2s\_dns\_timeout + +*timeout()* + +The timeout for DNS resolving. The default value is *10* seconds. + +## s2s\_max\_retry\_delay + +*timeout()* + +The maximum allowed delay for s2s connection retry to connect after a +failed connection attempt. The default value is *300* seconds (5 +minutes). + +## s2s\_protocol\_options + +*\[Option, ...\]* + +List of general SSL options to use for s2s connections. These map to +OpenSSL’s *set\_options()*. The default value is shown in the example +below: + +**Example**: + +~~~ yaml +s2s_protocol_options: + - no_sslv3 + - cipher_server_preference + - no_compression +~~~ + +## s2s\_queue\_type + +*ram | file* + +The type of a queue for s2s packets. See description of [queue_type](#queue_type) +option for the explanation. The default value is the value defined in +[queue_type](#queue_type) or *ram* if the latter is not set. + +## s2s\_timeout + +*timeout()* + +A time to wait before closing an idle s2s connection. The default value +is *1* hour. + +## s2s\_tls\_compression + +*true | false* + +Whether to enable or disable TLS compression for s2s connections. The +default value is *false*. + +## s2s\_use\_starttls + +*true | false | optional | required* + +Whether to use STARTTLS for s2s connections. The value of *false* means +STARTTLS is prohibited. The value of *true* or *optional* means STARTTLS +is enabled but plain connections are still allowed. And the value of +*required* means that only STARTTLS connections are allowed. The default +value is *false* (for historical reasons). + +## s2s\_zlib + +*true | false* + +Whether to use *zlib* compression (as defined in +[XEP-0138](https://xmpp.org/extensions/xep-0138.html)) or not. The +default value is *false*. WARNING: this type of compression is nowadays +considered insecure. + +## shaper + +*{ShaperName: Rate}* + +The option defines a set of shapers. Every shaper is assigned a name +*ShaperName* that can be used in other parts of the configuration file, +such as [shaper_rules](#shaper_rules) option. The shaper itself is defined by its +*Rate*, where *Rate* stands for the maximum allowed incoming rate in +**bytes** per second. When a connection exceeds this limit, ejabberd +stops reading from the socket until the average rate is again below the +allowed maximum. In the example below shaper *normal* limits the traffic +speed to 1,000 bytes/sec and shaper *fast* limits the traffic speed to +50,000 bytes/sec: + +**Example**: + +~~~ yaml +shaper: + normal: 1000 + fast: 50000 +~~~ + +## shaper\_rules + +*{ShaperRuleName: {Number|ShaperName: ACLRule|ACLName}}* + +An entry allowing to declaring shaper to use for matching user/hosts. +Semantics is similar to [access_rules](#access_rules) option, the only difference is +that instead using *allow* or *deny*, a name of a shaper (defined in +[shaper](#shaper) option) or a positive number should be used. + +**Example**: + +~~~ yaml +shaper_rules: + connections_limit: + 10: + user: peter@example.com + 100: admin + 5: all + download_speed: + fast: admin + slow: anonymous_users + normal: all + log_days: 30 +~~~ + +## sm\_cache\_life\_time + +*timeout()* + +Same as [cache_life_time](#cache_life_time), but applied to client sessions table cache +only. If not set, the value from [cache_life_time](#cache_life_time) will be used. + +## sm\_cache\_missed + +*true | false* + +Same as [cache_missed](#cache_missed), but applied to client sessions table cache +only. If not set, the value from [cache_missed](#cache_missed) will be used. + +## sm\_cache\_size + +*pos\_integer() | infinity* + +Same as [cache_size](#cache_size), but applied to client sessions table cache only. +If not set, the value from [cache_size](#cache_size) will be used. + +## sm\_db\_type + +*mnesia | redis | sql* + +Database backend to use for client sessions information. The default +value is picked from [default_ram_db](#default_ram_db) option, or if it’s not set, +*mnesia* will be used. + +## sm\_use\_cache + +*true | false* + +Same as [use_cache](#use_cache), but applied to client sessions table cache only. +If not set, the value from [use_cache](#use_cache) will be used. + +## sql\_connect\_timeout + +*timeout()* + +A time to wait for connection to an SQL server to be established. The +default value is *5* seconds. + +## sql\_database + +*Database* + +An SQL database name. For SQLite this must be a full path to a database +file. The default value is *ejabberd*. + +## sql\_flags 🟤 + +*\[mysql\_alternative\_upsert\]* + + + +This option accepts a list of +SQL flags, and is empty by default. *mysql\_alternative\_upsert* forces +the alternative upsert implementation in MySQL. + +## sql\_keepalive\_interval + +*timeout()* + +An interval to make a dummy SQL request to keep alive the connections to +the database. There is no default value, so no keepalive requests are +made. + +## sql\_odbc\_driver + +*Path* + + + +Path to the ODBC driver to use +to connect to a Microsoft SQL Server database. This option only applies +if the [sql_type](#sql_type) option is set to *mssql* and [sql_server](#sql_server) is not +an ODBC connection string. The default value is: *libtdsodbc.so* + +## sql\_password + +*Password* + +The password for SQL authentication. The default is empty string. + +## sql\_pool\_size + +*Size* + +Number of connections to the SQL server that ejabberd will open for each +virtual host. The default value is 10. WARNING: for SQLite this value is +*1* by default and it’s not recommended to change it due to potential +race conditions. + +## sql\_port + +*1..65535* + +The port where the SQL server is accepting connections. The default is +*3306* for MySQL, *5432* for PostgreSQL and *1433* for MS SQL. The +option has no effect for SQLite. + +## sql\_prepared\_statements + +*true | false* + + + +This option is *true* by +default, and is useful to disable prepared statements. The option is +valid for PostgreSQL and MySQL. + +## sql\_query\_timeout + +*timeout()* + +A time to wait for an SQL query response. The default value is *60* +seconds. + +## sql\_queue\_type + +*ram | file* + +The type of a request queue for the SQL server. See description of +[queue_type](#queue_type) option for the explanation. The default value is the +value defined in [queue_type](#queue_type) or *ram* if the latter is not set. + +## sql\_server + +*Host | IP Address | ODBC Connection String | Unix Socket Path* + + + +The hostname or IP address +of the SQL server. For [sql_type](#sql_type) *mssql* or *odbc* this can also be +an ODBC connection string. When [sql_type](#sql_type) is *mysql* or *pgsql*, this +can be the path to a unix domain socket expressed like: +"unix:/path/to/socket".The default value is *localhost*. + +## sql\_ssl + +*true | false* + + + +Whether to use SSL +encrypted connections to the SQL server. The option is only available +for MySQL, MS SQL and PostgreSQL. The default value is *false*. + +## sql\_ssl\_cafile + +*Path* + +A path to a file with CA root certificates that will be used to verify +SQL connections. Implies [sql_ssl](#sql_ssl) and [sql_ssl_verify](#sql_ssl_verify) options are +set to *true*. There is no default which means certificate verification +is disabled. This option has no effect for MS SQL. + +## sql\_ssl\_certfile + +*Path* + +A path to a certificate file that will be used for SSL connections to +the SQL server. Implies [sql_ssl](#sql_ssl) option is set to *true*. There is no +default which means ejabberd won’t provide a client certificate to the +SQL server. This option has no effect for MS SQL. + +## sql\_ssl\_verify + +*true | false* + +Whether to verify SSL connection to the SQL server against CA root +certificates defined in [sql_ssl_cafile](#sql_ssl_cafile) option. Implies [sql_ssl](#sql_ssl) +option is set to *true*. This option has no effect for MS SQL. The +default value is *false*. + +## sql\_start\_interval + +*timeout()* + +A time to wait before retrying to restore failed SQL connection. The +default value is *30* seconds. + +## sql\_type + +*mssql | mysql | odbc | pgsql | sqlite* + +The type of an SQL connection. The default is *odbc*. + +## sql\_username + +*Username* + +A user name for SQL authentication. The default value is *ejabberd*. + +## trusted\_proxies + +*all | \[Network1, Network2, ...\]* + +Specify what proxies are trusted when an HTTP request contains the +header *X-Forwarded-For*. You can specify *all* to allow all proxies, or +specify a list of IPs, possibly with masks. The default value is an +empty list. Using this option you can know the real IP of the request, +for admin purpose, or security configuration (for example using +*mod\_fail2ban*). IMPORTANT: The proxy MUST be configured to set the +*X-Forwarded-For* header if you enable this option as, otherwise, the +client can set it itself and as a result the IP value cannot be trusted +for security rules in ejabberd. + +## update\_sql\_schema + +*true | false* + + + +Allow ejabberd to update SQL +schema. This option was added in ejabberd [23.10](../../archive/23.10/index.md), and enabled by default +since [24.06](../../archive/24.06/index.md). The default value is *true*. + +## use\_cache + +*true | false* + +Enable or disable cache. The default is *true*. Several modules have a +similar option; and some core ejabberd parts support similar options +too, see [auth_use_cache](#auth_use_cache), [oauth_use_cache](#oauth_use_cache), [router_use_cache](#router_use_cache), +and [sm_use_cache](#sm_use_cache). + +## validate\_stream + +*true | false* + +Whether to validate any incoming XML packet according to the schemas of +[supported XMPP +extensions](https://github.com/processone/xmpp#supported-xmpp-elements). +WARNING: the validation is only intended for the use by client +developers - don’t enable it in production environment. The default +value is *false*. + +## version + +*string()* + +The option can be used to set custom ejabberd version, that will be used +by different parts of ejabberd, for example by [mod_version](modules.md#mod_version) module. +The default value is obtained at compile time from the underlying +version control system. + +## websocket\_origin + +*ignore | URL* + +This option enables validation for *Origin* header to protect against +connections from other domains than given in the configuration file. In +this way, the lower layer load balancer can be chosen for a specific +ejabberd implementation while still providing a secure WebSocket +connection. The default value is *ignore*. An example value of the *URL* +is "https://test.example.org:8081". + +## websocket\_ping\_interval + +*timeout()* + +Defines time between pings sent by the server to a client (WebSocket +level protocol pings are used for this) to keep a connection active. If +the client doesn’t respond to two consecutive pings, the connection will +be assumed as closed. The value of *0* can be used to disable the +feature. This option makes the server sending pings only for connections +using the RFC compliant protocol. For older style connections the server +expects that whitespace pings would be used for this purpose. The +default value is *60* seconds. + +## websocket\_timeout + +*timeout()* + +Amount of time without any communication after which the connection +would be closed. The default value is *300* seconds. +