diff --git a/assets/img/footer_logo_e.png b/assets/img/footer_logo_e.png new file mode 100644 index 00000000..0496faf3 Binary files /dev/null and b/assets/img/footer_logo_e.png differ diff --git a/assets/img/footer_logo_e@2x.png b/assets/img/footer_logo_e@2x.png new file mode 100644 index 00000000..bacb62b8 Binary files /dev/null and b/assets/img/footer_logo_e@2x.png differ diff --git a/ejabberd-docs-24.02.pdf b/ejabberd-docs-24.02.pdf index 357a187d..64f09b2d 100644 Binary files a/ejabberd-docs-24.02.pdf and b/ejabberd-docs-24.02.pdf differ diff --git a/ejabberd-docs-24.02.zip b/ejabberd-docs-24.02.zip index 0c7231af..bca2c46c 100644 Binary files a/ejabberd-docs-24.02.zip and b/ejabberd-docs-24.02.zip differ diff --git a/livebooks/ejabberd-developer-livebook/index.html b/livebooks/ejabberd-developer-livebook/index.html index 97d0fd52..1801c426 100644 --- a/livebooks/ejabberd-developer-livebook/index.html +++ b/livebooks/ejabberd-developer-livebook/index.html @@ -5978,7 +5978,7 @@

The ejabberd Developer Livebook -

Run in Livebook

+

Run in Livebook

filename = "ejabberd.yml"
 
diff --git a/roadmap/index.html b/roadmap/index.html
index 873d7715..f9122547 100644
--- a/roadmap/index.html
+++ b/roadmap/index.html
@@ -6348,6 +6348,7 @@ 
2015&par
 
  • Added support for WebSocket
    • 
 
  • Customizable session backends
    • 
 
  • SCRAM support for SQL authentication backend
    • 
+
  • Documentation was converted from LaTeX to Markdown and published in docs.ejabberd.im/
    • 
 
 
 
  • 
@@ -6355,7 +6356,6 @@ 
    2015&par
 
 
    • 
diff --git a/search/search_index.json b/search/search_index.json
index 1c03f111..950f1bc6 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"CHANGELOG/","title":"ChangeLog","text":""},{"location":"CHANGELOG/#version-2402","title":"Version 24.02","text":""},{"location":"CHANGELOG/#core","title":"Core:","text":"
       
    • Added Matrix gateway in mod_matrix_gw
      •  
    • Support SASL2 and Bind2
      •  
    • Support tls-server-end-point channel binding and sasl2 codec
      •  
    • Support tls-exporter channel binding
      •  
    • Support XEP-0474: SASL SCRAM Downgrade Protection
      •  
    • Fix presenting features and returning results of inline bind2 elements
      •  
    • disable_sasl_scram_downgrade_protection: New option to disable XEP-0474
      •  
    • negotiation_timeout: Increase default value from 30s to 2m
      •  
    • mod_carboncopy: Teach how to interact with bind2 inline requests
      •  
    "},{"location":"CHANGELOG/#other","title":"Other:","text":"
       
    • ejabberdctl: Fix startup problem when having set EJABBERD_OPTS and logger options
      •  
    • ejabberdctl: Set EJABBERD_OPTS back to \"\", and use previous flags as example
      •  
    • eldap: Change logic for eldap tls_verify=soft and false
      •  
    • eldap: Don't set fail_if_no_peer_cert for eldap ssl client connections
      •  
    • Ignore hints when checking for chat states
      •  
    • mod_mam: Support XEP-0424 Message Retraction
      •  
    • mod_mam: Fix XEP-0425: Message Moderation with SQL storage
      •  
    • mod_ping: Support XEP-0198 pings when stream management is enabled
      •  
    • mod_pubsub: Normalize pubsub max_items node options on read
      •  
    • mod_pubsub: PEP nodetree: Fix reversed logic in node fixup function
      •  
    • mod_pubsub: Only care about PEP bookmarks options when creating node from scratch
      •  
    "},{"location":"CHANGELOG/#sql","title":"SQL:","text":"
       
    • MySQL: Support sha256_password auth plugin
      •  
    • ejabberd_sql_schema: Use the first unique index as a primary key
      •  
    • Update SQL schema files for MAM's XEP-0424
      •  
    • New option sql_flags: right now only useful to enable mysql_alternative_upsert
      •  
    "},{"location":"CHANGELOG/#installers-and-container","title":"Installers and Container:","text":"
       
    • Container: Add ability to ignore failures in execution of CTL_ON_* commands
      •  
    • Container: Update to Erlang/OTP 26.2, Elixir 1.16.1 and Alpine 3.19
      •  
    • Container: Update this custom ejabberdctl to match the main one
      •  
    • make-binaries: Bump OpenSSL 3.2.1, Erlang/OTP 26.2.2, Elixir 1.16.1
      •  
    • make-binaries: Bump many dependency versions
      •  
    "},{"location":"CHANGELOG/#commands-api","title":"Commands API:","text":"
       
    • print_sql_schema: New command available in ejabberdctl command-line script
      •  
    • ejabberdctl: Rework temporary node name generation
      •  
    • ejabberdctl: Print argument description, examples and note in help
      •  
    • ejabberdctl: Document exclusive ejabberdctl commands like all the others
      •  
    • Commands: Add a new muc_sub tag to all the relevant commands
      •  
    • Commands: Improve syntax of many commands documentation
      •  
    • Commands: Use list arguments in many commands that used separators
      •  
    • Commands: set_presence: switch priority argument from string to integer
      •  
    • ejabberd_commands: Add the command API version as a tag vX
      •  
    • ejabberd_ctl: Add support for list and tuple arguments
      •  
    • ejabberd_xmlrpc: Fix support for restuple error response
      •  
    • mod_http_api: When no specific API version is requested, use the latest
      •  
    "},{"location":"CHANGELOG/#compilation-with-rebar3elixirmix","title":"Compilation with Rebar3/Elixir/Mix:","text":"
       
    • Fix compilation with Erlang/OTP 27: don't use the reserved word 'maybe'
      •  
    • configure: Fix explanation of --enable-group option (#4135)
      •  
    • Add observer and runtime_tools in releases when --enable-tools
      •  
    • Update \"make translations\" to reduce build requirements
      •  
    • Use Luerl 1.0 for Erlang 20, 1.1.1 for 21-26, and temporary fork for 27
      •  
    • Makefile: Add install-rel and uninstall-rel
      •  
    • Makefile: Rename make rel to make prod
      •  
    • Makefile: Update make edoc to use ExDoc, requires mix
      •  
    • Makefile: No need to use escript to run rebar|rebar3|mix
      •  
    • configure: If --with-rebar=rebar3 but rebar3 not system-installed, use local one
      •  
    • configure: Use Mix or Rebar3 by default instead of Rebar2 to compile ejabberd
      •  
    • ejabberdctl: Detect problem running iex or etop and show explanation
      •  
    • Rebar3: Include Elixir files when making a release
      •  
    • Rebar3: Workaround to fix protocol consolidation
      •  
    • Rebar3: Add support to compile Elixir dependencies
      •  
    • Rebar3: Compile explicitly our Elixir files when --enable-elixir
      •  
    • Rebar3: Provide proper path to iex
      •  
    • Rebar/Rebar3: Update binaries to work with Erlang/OTP 24-27
      •  
    • Rebar/Rebar3: Remove Elixir as a rebar dependency
      •  
    • Rebar3/Mix: If dev profile/environment, enable tools automatically
      •  
    • Elixir: Fix compiling ejabberd as a dependency (#4128)
      •  
    • Elixir: Fix ejabberdctl start/live when installed
      •  
    • Elixir: Fix: FORMATTER ERROR: bad return value (#4087)
      •  
    • Elixir: Fix: Couldn't find file Elixir Hex API
      •  
    • Mix: Enable stun by default when vars.config not found
      •  
    • Mix: New option vars_config_path to set path to vars.config (#4128)
      •  
    • Mix: Fix ejabberdctl iexlive problem locating iex in an OTP release
      •  
    "},{"location":"CHANGELOG/#version-2310","title":"Version 23.10","text":""},{"location":"CHANGELOG/#compilation","title":"Compilation:","text":"
       
    • Erlang/OTP: Raise the requirement to Erlang/OTP 20.0 as a minimum
      •  
    • CI: Update tests to Erlang/OTP 26 and recent Elixir
      •  
    • Move Xref and Dialyzer options from workflows to rebar.config
      •  
    • Add sections to rebar.config to organize its content
      •  
    • Dialyzer dirty workarounds because re:mp() is not an exported type
      •  
    • When installing module already configured, keep config as example
      •  
    • Elixir 1.15 removed support for --app
      •  
    • Elixir: Improve support to stop external modules written in Elixir
      •  
    • Elixir: Update syntax of function calls as recommended by Elixir compiler
      •  
    • Elixir: When building OTP release with mix, keep ERLANG_NODE=ejabberd@localhost
      •  
    • ejabberdctl: Pass ERLANG_OPTS when calling erl to parse the INET_DIST_INTERFACE (#4066
      •  
    "},{"location":"CHANGELOG/#commands","title":"Commands:","text":"
       
    • create_room_with_opts: Fix typo and move examples to args_example (#4080)
      •  
    • etop: Let ejabberdctl etop work in a release (if observer application is available)
      •  
    • get_roster: Command now returns groups in a list instead of newlines (#4088)
      •  
    • halt: New command to halt ejabberd abruptly with an error status code
      •  
    • ejabberdctl: Fix calling ejabberdctl command with wrong number of arguments with Erlang 26
      •  
    • ejabberdctl: Improve printing lists in results
      •  
    • ejabberdctl: Support policy=user in the help and return proper arguments
      •  
    • ejabberdctl: Document how to stop a debug shell: control+g
      •  
    "},{"location":"CHANGELOG/#container","title":"Container:","text":"
       
    • Dockerfile: Add missing dependency for mssql databases
      •  
    • Dockerfile: Reorder stages and steps for consistency
      •  
    • Dockerfile: Use Alpine as base for METHOD=package
      •  
    • Dockerfile: Rename packages to improve compatibility
      •  
    • Dockerfile: Provide specific OTP and elixir vsn for direct compilation
      •  
    • Halt ejabberd if a command in CTL_ON_ fails during ejabberd startup
      •  
    "},{"location":"CHANGELOG/#core_1","title":"Core:","text":"
       
    • auth_external_user_exists_check: New option (#3377)
      •  
    • gen_mod: Extend gen_mod API to simplify hooks and IQ handlers registration
      •  
    • gen_mod: Add shorter forms for gen_mod hook/iq_handler API
      •  
    • gen_mod: Update modules to the new gen_mod API
      •  
    • install_contrib_modules: New option to define contrib modules to install automatically
      •  
    • unix_socket: New listener option, useful when setting unix socket files (#4059)
      •  
    • ejabberd_systemd: Add a few debug messages
      •  
    • ejabberd_systemd: Avoid using gen_server timeout (#4054)(#4058)
      •  
    • ejabberd_listener: Increase default listen queue backlog value to 128, which is the default value on both Linux and FreeBSD (#4025)
      •  
    • OAuth: Handle badpass error message
      •  
    • When sending message on behalf of user, trigger user_send_packet (#3990)
      •  
    • Web Admin: In roster page move the AddJID textbox to top (#4067)
      •  
    • Web Admin: Show a warning when visiting webadmin with non-privileged account (#4089)
      •  
    "},{"location":"CHANGELOG/#docs","title":"Docs:","text":"
       
    • Example configuration: clarify 5223 tls options; specify s2s shaper
      •  
    • Make sure that policy=user commands have host instead of server arg in docs
      •  
    • Improve syntax of many command descriptions for the Docs site
      •  
    • Move example Perl extauth script from ejabberd git to Docs site
      •  
    • Remove obsolete example files, and add link in Docs to the archived copies
      •  
    "},{"location":"CHANGELOG/#installers-make-binaries","title":"Installers (make-binaries):","text":"
       
    • Bump Erlang/OTP version to 26.1.1, and other dependencies
      •  
    • Remove outdated workaround
      •  
    • Don't build Linux-PAM examples
      •  
    • Fix check for current Expat version
      •  
    • Apply minor simplifications
      •  
    • Don't duplicate config entries
      •  
    • Don't hard-code musl version
      •  
    • Omit unnecessary glibc setting
      •  
    • Set kernel version for all builds
      •  
    • Let curl fail on HTTP errors
      •  
    "},{"location":"CHANGELOG/#modules","title":"Modules:","text":"
       
    • mod_muc_log: Add trailing backslash to URLs shown in disco info
      •  
    • mod_muc_occupantid: New module with support for XEP-0421 Occupant Id (#3397)
      •  
    • mod_muc_rtbl: Better error handling in (#4050)
      •  
    • mod_private: Add support for XEP-0402 PEP Native Bookmarks
      •  
    • mod_privilege: Don't fail to edit roster (#3942)
      •  
    • mod_pubsub: Fix usage of plugins option, which produced default_node_config ignore (#4070)
      •  
    • mod_pubsub: Add pubsub_delete_item hook
      •  
    • mod_pubsub: Report support of config-node-max in pep
      •  
    • mod_pubsub: Relay pubsub iq queries to muc members without using bare jid (#4093)
      •  
    • mod_pubsub: Allow pubsub node owner to overwrite items published by other persons
      •  
    • mod_push_keepalive: Delay wake_on_start
      •  
    • mod_push_keepalive: Don't let hook crash
      •  
    • mod_push: Add notify_on option
      •  
    • mod_push: Set last-message-sender to bare JID
      •  
    • mod_register_web: Make redirect to page that end with / (#3177)
      •  
    • mod_shared_roster_ldap: Don't crash in get_member_jid on empty output (#3614)
      •  
    "},{"location":"CHANGELOG/#muc","title":"MUC:","text":"
       
    • Add support to register nick in a room (#3455)
      •  
    • Convert allow_private_message MUC room option to allowpm (#3736)
      •  
    • Update xmpp version to send roomconfig_changesubject in disco#info (#4085)
      •  
    • Fix crash when loading room from DB older than ffa07c6, 23.04
      •  
    • Fix support to retract a MUC room message
      •  
    • Don't always store messages passed through muc_filter_message (#4083)
      •  
    • Pass also MUC room retract messages over the muc_filter_message (#3397)
      •  
    • Pass MUC room private messages over the muc_filter_message too (#3397)
      •  
    • Store the subject author JID, and run muc_filter_message when sending subject (#3397)
      •  
    • Remove existing role information for users that are kicked from room (#4035)
      •  
    • Expand rule \"mucsub subscribers are members in members only rooms\" to more places
      •  
    "},{"location":"CHANGELOG/#sql_1","title":"SQL:","text":"
       
    • Add ability to force alternative upsert implementation in mysql
      •  
    • Properly parse mysql version even if it doesn't have type tag
      •  
    • Use prepared statement with mysql
      •  
    • Add alternate version of mysql upsert
      •  
    • ejabberd_auth_sql: Reset scram fields when setting plain password
      •  
    • mod_privacy_sql: Fix return values from calculate_diff
      •  
    • mod_privacy_sql: Optimize set_list
      •  
    • mod_privacy_sql: Use more efficient way to calculate changes in set_privacy_list
      •  
    "},{"location":"CHANGELOG/#version-2304","title":"Version 23.04","text":""},{"location":"CHANGELOG/#general","title":"General:","text":"
       
    • New s2s_out_bounce_packet hook
      •  
    • Re-allow anonymous connection for connection without client certificates (#3985)
      •  
    • Stop ejabberd_system_monitor before stopping node
      •  
    • captcha_url option now accepts auto value, and it's the default
      •  
    • mod_mam: Add support for XEP-0425: Message Moderation
      •  
    • mod_mam_sql: Fix problem with results of mam queries using rsm with max and before
      •  
    • mod_muc_rtbl: New module for Real-Time Block List for MUC rooms (#4017)
      •  
    • mod_roster: Set roster name from XEP-0172, or the stored one (#1611)
      •  
    • mod_roster: Preliminary support to store extra elements in subscription request (#840)
      •  
    • mod_pubsub: Pubsub xdata fields max_item/item_expira/children_max use max not infinity
      •  
    • mod_vcard_xupdate: Invalidate vcard_xupdate cache on all nodes when vcard is updated
      •  
    "},{"location":"CHANGELOG/#admin","title":"Admin:","text":"
       
    • ext_mod: Improve support for loading *.so files from ext_mod dependencies
      •  
    • Improve output in gen_html_doc_for_commands command
      •  
    • Fix ejabberdctl output formatting (#3979)
      •  
    • Log HTTP handler exceptions
      •  
    "},{"location":"CHANGELOG/#muc_1","title":"MUC:","text":"
       
    • New command get_room_history
      •  
    • Persist none role for outcasts
      •  
    • Try to populate room history from mam when unhibernating
      •  
    • Make mod_muc_room:set_opts process persistent flag first
      •  
    • Allow passing affiliations and subscribers to create_room_with_opts command
      •  
    • Store state in db in mod_muc:create_room()
      •  
    • Make subscribers members by default
      •  
    "},{"location":"CHANGELOG/#sql-schemas","title":"SQL schemas:","text":"
       
    • Fix a long standing bug in new schema migration
      •  
    • update_sql command: Many improvements in new schema migration
      •  
    • update_sql command: Add support to migrate MySQL too
      •  
    • Change PostgreSQL SERIAL to BIGSERIAL columns
      •  
    • Fix minor SQL schema inconsistencies
      •  
    • Remove unnecessary indexes
      •  
    • New SQL schema migrate fix
      •  
    "},{"location":"CHANGELOG/#ms-sql","title":"MS SQL:","text":"
       
    • MS SQL schema fixes
      •  
    • Add new schema for MS SQL
      •  
    • Add MS SQL support for new schema migration
      •  
    • Minor MS SQL improvements
      •  
    • Fix MS SQL error caused by ORDER BY in subquery
      •  
    "},{"location":"CHANGELOG/#sql-tests","title":"SQL Tests:","text":"
       
    • Add support for running tests on MS SQL
      •  
    • Add ability to run tests on upgraded DB
      •  
    • Un-deprecate ejabberd_config:set_option/2
      •  
    • Use python3 to run extauth.py for tests
      •  
    • Correct README for creating test docker MS SQL DB
      •  
    • Fix TSQLlint warnings in MSSQL test script
      •  
    "},{"location":"CHANGELOG/#testing","title":"Testing:","text":"
       
    • Fix Shellcheck warnings in shell scripts
      •  
    • Fix Remark-lint warnings
      •  
    • Fix Prospector and Pylint warnings in test extauth.py
      •  
    • Stop testing ejabberd with Erlang/OTP 19.3, as Github Actions no longer supports ubuntu-18.04
      •  
    • Test only with oldest OTP supported (20.0), newest stable (25.3) and bleeding edge (26.0-rc2)
      •  
    • Upload Common Test logs as artifact in case of failure
      •  
    "},{"location":"CHANGELOG/#ecs-container-image","title":"ecs container image:","text":"
       
    • Update Alpine to 3.17 to get Erlang/OTP 25 and Elixir 1.14
      •  
    • Add tini as runtime init
      •  
    • Set ERLANG_NODE fixed to ejabberd@localhost
      •  
    • Upload images as artifacts to Github Actions
      •  
    • Publish tag images automatically to ghcr.io
      •  
    "},{"location":"CHANGELOG/#ejabberd-container-image","title":"ejabberd container image:","text":"
       
    • Update Alpine to 3.17 to get Erlang/OTP 25 and Elixir 1.14
      •  
    • Add METHOD to build container using packages (#3983)
      •  
    • Add tini as runtime init
      •  
    • Detect runtime dependencies automatically
      •  
    • Remove unused Mix stuff: ejabberd script and static COOKIE
      •  
    • Copy captcha scripts to /opt/ejabberd-*/lib like the installers
      •  
    • Expose only HOME volume, it contains all the required subdirs
      •  
    • ejabberdctl: Don't use .../releases/COOKIE, it's no longer included
      •  
    "},{"location":"CHANGELOG/#installers","title":"Installers:","text":"
       
    • make-binaries: Bump versions, e.g. erlang/otp to 25.3
      •  
    • make-binaries: Fix building with erlang/otp v25.x
      •  
    • make-packages: Fix for installers workflow, which didn't find lynx
      •  
    "},{"location":"CHANGELOG/#version-2301","title":"Version 23.01","text":""},{"location":"CHANGELOG/#general_1","title":"General:","text":"
       
    • Add misc:uri_parse/2 to allow declaring default ports for protocols
      •  
    • CAPTCHA: Add support to define module instead of path to script
      •  
    • Clustering: Handle mnesia_system_event mnesia_up when other node joins this (#3842)
      •  
    • ConverseJS: Don't set i18n option because Converse enforces it instead of browser lang (#3951)
      •  
    • ConverseJS: Try to redirect access to files mod_conversejs to CDN when there is no local copies
      •  
    • ext_mod: compile C files and install them in ejabberd's priv
      •  
    • ext_mod: Support to get module status from Elixir modules
      •  
    • make-binaries: reduce log output
      •  
    • make-binaries: Bump zlib version to 1.2.13
      •  
    • MUC: Don't store mucsub presence events in offline storage
      •  
    • MUC: hibernation_time is not an option worth storing in room state (#3946)
      •  
    • Multicast: Jid format when multicastc was cached (#3950)
      •  
    • mysql: Pass ssl options to mysql driver
      •  
    • pgsql: Do not set standard_conforming_strings to off (#3944)
      •  
    • OAuth: Accept jid as a HTTP URL query argument
      •  
    • OAuth: Handle when client is not identified
      •  
    • PubSub: Expose the pubsub#type field in disco#info query to the node (#3914)
      •  
    • Translations: Update German translation
      •  
    "},{"location":"CHANGELOG/#admin_1","title":"Admin:","text":"
       
    • api_permissions: Fix option crash when doesn't have who: section
      •  
    • log_modules_fully: New option to list modules that will log everything
      •  
    • outgoing_s2s_families: Changed option's default to IPv6, and fall back to IPv4
      •  
    • Fix bash completion when using Relive or other install methods
      •  
    • Fix portability issue with some shells (#3970)
      •  
    • Allow admin command to subscribe new users to members_only rooms
      •  
    • Use alternative split/2 function that works with Erlang/OTP as old as 19.3
      •  
    • Silent warning in OTP24 about not specified cacerts in SQL connections
      •  
    • Fix compilation warnings with Elixir 1.14
      •  
    "},{"location":"CHANGELOG/#doap","title":"DOAP:","text":"
       
    • Support extended -protocol erlang attribute
      •  
    • Add extended RFCs and XEP details to some protocol attributes
      •  
    • tools/generate-doap.sh: New script to generate DOAP file, add make doap (#3915)
      •  
    • ejabberd.doap: New DOAP file describing ejabberd supported protocols
      •  
    "},{"location":"CHANGELOG/#mqtt","title":"MQTT:","text":"
       
    • Add MQTT bridge module
      •  
    • Add support for certificate authentication in MQTT bridge
      •  
    • Implement reload in MQTT bridge
      •  
    • Add support for websockets to MQTT bridge
      •  
    • Recognize ws5/wss5 urls in MQTT bridge
      •  
    • mqtt_publish: New hook for MQTT publish event
      •  
    • mqtt_(un)subscribe: New hooks for MQTT subscribe & unsubscribe events
      •  
    "},{"location":"CHANGELOG/#vscode","title":"VSCode:","text":"
       
    • Improve .devcontainer to use use devcontainer image and .vscode
      •  
    • Add .vscode files to instruct VSCode how to run ejabberd
      •  
    • Add Erlang LS default configuration
      •  
    • Add Elvis default configuration
      •  
    "},{"location":"CHANGELOG/#version-2210","title":"Version 22.10","text":""},{"location":"CHANGELOG/#core_2","title":"Core:","text":"
       
    • Add log_burst_limit_* options (#3865)
      •  
    • Support ERL_DIST_PORT option to work without epmd
      •  
    • Auth JWT: Catch all errors from jose_jwt:verify and log debugging details (#3890)
      •  
    • CAPTCHA: Support @VERSION@ and @SEMVER@ in captcha_cmd option (#3835)
      •  
    • HTTP: Fix unix socket support (#3894)
      •  
    • HTTP: Handle invalid values in X-Forwarded-For header more gracefuly
      •  
    • Listeners: Let module take over socket
      •  
    • Listeners: Don't register listeners that failed to start in config reload
      •  
    • mod_admin_extra: Handle empty roster group names
      •  
    • mod_conversejs: Fix crash when mod_register not enabled (#3824)
      •  
    • mod_host_meta: Complain at start if listener is not encrypted
      •  
    • mod_ping: Fix regression on stop_ping in clustering context (#3817)
      •  
    • mod_pubsub: Don't crash on command failures
      •  
    • mod_shared_roster: Fix cache invalidation
      •  
    • mod_shared_roster_ldap: Update roster_get hook to use #roster_item{}
      •  
    • prosody2ejabberd: Fix parsing of scram password from prosody
      •  
    "},{"location":"CHANGELOG/#mix","title":"MIX:","text":"
       
    • Fix MIX's filter_nodes
      •  
    • Return user jid on join
      •  
    • mod_mix_pam: Add new MIX namespaces to disco features
      •  
    • mod_mix_pam: Add handling of IQs with newer MIX namespaces
      •  
    • mod_mix_pam: Do roster pushes on join/leave
      •  
    • mod_mix_pam: Parse sub elements of the mix join remote result
      •  
    • mod_mix_pam: Provide MIX channels as roster entries via hook
      •  
    • mod_mix_pam: Display joined channels on webadmin page
      •  
    • mod_mix_pam: Adapt to renaming of participant-id from mix_roster_channel record
      •  
    • mod_roster: Change hook type from #roster{} to #roster_item{}
      •  
    • mod_roster: Respect MIX <annotate/> setting
      •  
    • mod_roster: Adapt to change of mix_annotate type to boolean in roster_query
      •  
    • mod_shared_roster: Fix wrong hook type #roster{} (now #roster_item{})
      •  
    "},{"location":"CHANGELOG/#muc_2","title":"MUC:","text":"
       
    • Store role, and use it when joining a moderated room (#3330)
      •  
    • Don't persist none role (#3330)
      •  
    • Allow MUC service admins to bypass max_user_conferences limitation
      •  
    • Show allow_query_users room option in disco info (#3830)
      •  
    • mod_muc_room: Don't set affiliation to none if it's already none in process_item_change/3
      •  
    • Fix mucsub unsubscribe notification payload to have muc_unsubcribe in it
      •  
    • Allow muc_{un}subscribe hooks to modify sent packets
      •  
    • Pass room state to muc_{un}subscribed hook
      •  
    • The archive_msg export fun requires MUC Service for room archives
      •  
    • Export mod_muc_admin:get_room_pid/2
      •  
    • Export function for getting room diagnostics
      •  
    "},{"location":"CHANGELOG/#sql_2","title":"SQL:","text":"
       
    • Handle errors reported from begin/commit inside transaction
      •  
    • Make connection close errors bubble up from inside sql transaction
      •  
    • Make first sql reconnect wait shorter time
      •  
    • React to sql driver process exit earlier
      •  
    • Skip connection exit message when we triggered reconnection
      •  
    • Add syntax_tools to applications, required when using ejabberd_sql_pt (#3869)
      •  
    • Fix mam delete_old_messages_batch for sql backend
      •  
    • Use INSERT ... ON DUPLICATE KEY UPDATE for upsert on mysql
      •  
    • Update mysql library
      •  
    • Catch mysql connection being close earlier
      •  
    "},{"location":"CHANGELOG/#build","title":"Build:","text":"
       
    • make all: Generate start scripts here, not in make install (#3821)
      •  
    • make clean: Improve this and \"distclean\"
      •  
    • make deps: Ensure deps configuration is ran when getting deps (#3823)
      •  
    • make help: Update with recent changes
      •  
    • make install: Don't leak DESTDIR in files copied by 'make install'
      •  
    • make options: Fix error reporting on OTP24+
      •  
    • make update: configure also in this case, similarly to make deps
      •  
    • Add definition to detect OTP older than 25, used by ejabberd_auth_http
      •  
    • Configure eimp with mix to detect image convert properly (#3823)
      •  
    • Remove unused macro definitions detected by rebar3_hank
      •  
    • Remove unused header files which content is already in xmpp library
      •  
    "},{"location":"CHANGELOG/#container_1","title":"Container:","text":"
       
    • Get ejabberd-contrib sources to include them
      •  
    • Copy .ejabberd-modules directory if available
      •  
    • Do not clone repo inside container build
      •  
    • Use make deps, which performs additional steps (#3823)
      •  
    • Support ERL_DIST_PORT option to work without epmd
      •  
    • Copy ejabberd-docker-install.bat from docker-ejabberd git and rename it
      •  
    • Set a less frequent healthcheck to reduce CPU usage (#3826)
      •  
    • Fix build instructions, add more podman examples
      •  
    "},{"location":"CHANGELOG/#installers_1","title":"Installers:","text":"
       
    • make-binaries: Include CAPTCHA script with release
      •  
    • make-binaries: Edit rebar.config more carefully
      •  
    • make-binaries: Fix linking of EIMP dependencies
      •  
    • make-binaries: Fix GitHub release version checks
      •  
    • make-binaries: Adjust Mnesia spool directory path
      •  
    • make-binaries: Bump Erlang/OTP version to 24.3.4.5
      •  
    • make-binaries: Bump Expat and libpng versions
      •  
    • make-packages: Include systemd unit with RPM
      •  
    • make-packages: Fix permissions on RPM systems
      •  
    • make-installers: Support non-root installation
      •  
    • make-installers: Override code on upgrade
      •  
    • make-installers: Apply cosmetic changes
      •  
    "},{"location":"CHANGELOG/#external-modules","title":"External modules:","text":"
       
    • ext_mod: Support managing remote nodes in the cluster
      •  
    • ext_mod: Handle correctly when COMMIT.json not found
      •  
    • Don't bother with COMMIT.json user-friendly feature in automated user case
      •  
    • Handle not found COMMIT.json, for example in GH Actions
      •  
    • Add WebAdmin page for managing external modules
      •  
    "},{"location":"CHANGELOG/#workflows-actions","title":"Workflows Actions:","text":"
       
    • Update workflows to Erlang 25
      •  
    • Update workflows: Ubuntu 18 is deprecated and 22 is added
      •  
    • CI: Remove syntax_tools from applications, as fast_xml fails Dialyzer
      •  
    • Runtime: Add Xref options to be as strict as CI
      •  
    "},{"location":"CHANGELOG/#version-2205","title":"Version 22.05","text":""},{"location":"CHANGELOG/#core_3","title":"Core","text":"
       
    • C2S: Don't expect that socket will be available in c2s_terminated hook
      •  
    • Event handling process hook tracing
      •  
    • Guard against erlang:system_info(logical_processors) not always returning a number
      •  
    • domain_balancing: Allow for specifying type only, without specifying component_number
      •  
    "},{"location":"CHANGELOG/#mqtt_1","title":"MQTT","text":"
       
    • Add TLS certificate authentication for MQTT connections
      •  
    • Fix login when generating client id, keep connection record (#3593)
      •  
    • Pass property name as expected in mqtt_codec (fixes login using MQTT 5)
      •  
    • Support MQTT subscriptions spread over the cluster (#3750)
      •  
    "},{"location":"CHANGELOG/#muc_3","title":"MUC","text":"
       
    • Attach meta field with real jid to mucsub subscription events
      •  
    • Handle user removal
      •  
    • Stop empty MUC rooms 30 seconds after creation
      •  
    • default_room_options: Update options configurable
      •  
    • subscribe_room_many_max_users: New option in mod_muc_admin
      •  
    "},{"location":"CHANGELOG/#mod_conversejs","title":"mod_conversejs","text":"
       
    • Improved options to support @HOST@ and auto values
      •  
    • Set auth and register options based on ejabberd configuration
      •  
    • conversejs_options: New option
      •  
    • conversejs_resources: New option
      •  
    "},{"location":"CHANGELOG/#pubsub","title":"PubSub","text":"
       
    • mod_pubsub: Allow for limiting item_expire value
      •  
    • mod_pubsub: Unsubscribe JID on whitelist removal
      •  
    • node_pep: Add config-node and multi-items features (#3714)
      •  
    "},{"location":"CHANGELOG/#sql_3","title":"SQL","text":"
       
    • Improve compatibility with various db engine versions
      •  
    • Sync old-to-new schema script with reality (#3790)
      •  
    • Slight improvement in MSSQL testing support, but not yet complete
      •  
    "},{"location":"CHANGELOG/#other-modules","title":"Other Modules","text":"
       
    • auth_jwt: Checking if an user is active in SM for a JWT authenticated user (#3795)
      •  
    • mod_configure: Implement Get List of Registered/Online Users from XEP-0133
      •  
    • mod_host_meta: New module to serve host-meta files, see XEP-0156
      •  
    • mod_mam: Store all mucsub notifications not only message notifications
      •  
    • mod_ping: Delete ping timer if resource is gone after the ping has been sent
      •  
    • mod_ping: Don't send ping if resource is gone
      •  
    • mod_push: Fix notifications for pending sessions (XEP-0198)
      •  
    • mod_push: Keep push session ID on session resume
      •  
    • mod_shared_roster: Adjust special group cache size
      •  
    • mod_shared_roster: Normalize JID on unset_presence (#3752)
      •  
    • mod_stun_disco: Fix parsing of IPv6 listeners
      •  
    "},{"location":"CHANGELOG/#dependencies","title":"Dependencies","text":"
       
    • autoconf: Supported from 2.59 to the new 2.71
      •  
    • fast_tls: Update to 1.1.14 to support OpenSSL 3
      •  
    • jiffy: Update to 1.1.1 to support Erlang/OTP 25.0-rc1
      •  
    • luerl: Update to 1.0.0, now available in hex.pm
      •  
    • lager: This dependency is used only when Erlang is older than 22
      •  
    • rebar2: Updated binary to work from Erlang/OTP 22 to 25
      •  
    • rebar3: Updated binary to work from Erlang/OTP 22 to 25
      •  
    • make update: Fix when used with rebar 3.18
      •  
    "},{"location":"CHANGELOG/#compile","title":"Compile","text":"
       
    • mix release: Copy include/ files for ejabberd, deps and otp, in mix.exs
      •  
    • rebar3 release: Fix ERTS path in ejabberdctl
      •  
    • configure.ac: Set default ejabberd version number when not using git
      •  
    • mix.exs: Move some dependencies as optional
      •  
    • mix.exs: No need to use Distillery, Elixir has built-in support for OTP releases (#3788)
      •  
    • tools/make-binaries: New script for building Linux binaries
      •  
    • tools/make-installers: New script for building command line installers
      •  
    "},{"location":"CHANGELOG/#start","title":"Start","text":"
       
    • New make relive similar to ejabberdctl live without installing
      •  
    • ejabberdctl: Fix some warnings detected by ShellCheck
      •  
    • ejabberdctl: Mention in the help: etop, ping and started/stopped
      •  
    • make rel: Switch to paths: conf/, database/, logs/
      •  
    • mix.exs: Add -boot and -boot_var in ejabberdctl instead of adding vm.args
      •  
    • tools/captcha.sh: Fix some warnings detected by ShellCheck
      •  
    "},{"location":"CHANGELOG/#commands_1","title":"Commands","text":"
       
    • Accept more types of ejabberdctl commands arguments as JSON-encoded
      •  
    • delete_old_mam_messages_batch: New command with rate limit
      •  
    • delete_old_messages_batch: New command with rate limit
      •  
    • get_room_occupants_number: Don't request the whole MUC room state (#3684, #1964)
      •  
    • get_vcard: Add support for MUC room vCard
      •  
    • oauth_revoke_token: Add support to work with all backends
      •  
    • room_unused_*: Optimize commands in SQL by reusing created_at
      •  
    • rooms_unused_...: Let get_all_rooms handle global argument (#3726)
      •  
    • stop|restart: Terminate ejabberd_sm before everything else to ensure sessions closing (#3641)
      •  
    • subscribe_room_many: New command
      •  
    "},{"location":"CHANGELOG/#translations","title":"Translations","text":"
       
    • Updated Catalan
      •  
    • Updated French
      •  
    • Updated German
      •  
    • Updated Portuguese
      •  
    • Updated Portuguese (Brazil)
      •  
    • Updated Spanish
      •  
    "},{"location":"CHANGELOG/#workflows","title":"Workflows","text":"
       
    • CI: Publish CT logs and Cover on failure to an external GH Pages repo
      •  
    • CI: Test shell scripts using ShellCheck (#3738)
      •  
    • Container: New workflow to build and publish containers
      •  
    • Installers: Add job to create draft release
      •  
    • Installers: New workflow to build binary packages
      •  
    • Runtime: New workflow to test compilation, rel, starting and ejabberdctl
      •  
    "},{"location":"CHANGELOG/#version-2112","title":"Version 21.12","text":""},{"location":"CHANGELOG/#commands_2","title":"Commands","text":"
       
    • create_room_with_opts: Fixed when using SQL storage
      •  
    • change_room_option: Add missing fields from config inside mod_muc_admin:change_options
      •  
    • piefxis: Fixed arguments of all commands
      •  
    "},{"location":"CHANGELOG/#modules_1","title":"Modules","text":"
       
    • mod_caps: Don't forget caps on XEP-0198 resumption
      •  
    • mod_conversejs: New module to serve a simple page for Converse.js
      •  
    • mod_http_upload_quota: Avoid max_days race
      •  
    • mod_muc: Support MUC hats (XEP-0317, conversejs/prosody compatible)
      •  
    • mod_muc: Optimize MucSub processing
      •  
    • mod_muc: Fix exception in mucsub {un}subscription events multicast handler
      •  
    • mod_multicast: Improve and optimize multicast routing code
      •  
    • mod_offline: Allow storing non-composing x:events in offline
      •  
    • mod_ping: Send ping from server, not bare user JID
      •  
    • mod_push: Fix handling of MUC/Sub messages
      •  
    • mod_register: New allow_modules option to restrict registration modules
      •  
    • mod_register_web: Handle unknown host gracefully
      •  
    • mod_register_web: Use mod_register configured restrictions
      •  
    "},{"location":"CHANGELOG/#pubsub_1","title":"PubSub","text":"
       
    • Add delete_expired_pubsub_items command
      •  
    • Add delete_old_pubsub_items command
      •  
    • Optimize publishing on large nodes (SQL)
      •  
    • Support unlimited number of items
      •  
    • Support max_items=max node configuration
      •  
    • Bump default value for max_items limit from 10 to 1000
      •  
    • Use configured max_items by default
      •  
    • node_flat: Avoid catch-all clauses for RSM
      •  
    • node_flat_sql: Avoid catch-all clauses for RSM
      •  
    "},{"location":"CHANGELOG/#sql_4","title":"SQL","text":"
       
    • Use INSERT ... ON CONFLICT in SQL_UPSERT for PostgreSQL >= 9.5
      •  
    • mod_mam export: assign MUC entries to the MUC service
      •  
    • MySQL: Fix typo when creating index
      •  
    • PgSQL: Add SASL auth support, PostgreSQL 14
      •  
    • PgSQL: Add missing SQL migration for table push_session
      •  
    • PgSQL: Fix vcard_search definition in pgsql new schema
      •  
    "},{"location":"CHANGELOG/#other_1","title":"Other","text":"
       
    • captcha-ng.sh: \"sort -R\" command not POSIX, added \"shuf\" and \"cat\" as fallback
      •  
    • Make s2s connection table cleanup more robust
      •  
    • Update export/import of scram password to XEP-0227 1.1
      •  
    • Update Jose to 1.11.1 (the last in hex.pm correctly versioned)
      •  
    "},{"location":"CHANGELOG/#version-2107","title":"Version 21.07","text":""},{"location":"CHANGELOG/#compilation_1","title":"Compilation","text":"
       
    • Add rebar3 3.15.2 binary
      •  
    • Add support for mix to: ./configure --enable-rebar=mix
      •  
    • Improved make rel to work with rebar3 and mix
      •  
    • Add make dev to build a development release with rebar3 or mix
      •  
    • Hex: Add sql/ and vars.config to Hex package files
      •  
    • Hex: Update mix applications list to fix error p1_utils is listed as both...
      •  
    • There are so many targets in Makefile... add make help
      •  
    • Fix extauth.py failure in test suite with Python 3
      •  
    • Added experimental support for GitHub Codespaces
      •  
    • Switch test service from TravisCI to GitHub Actions
      •  
    "},{"location":"CHANGELOG/#commands_3","title":"Commands:","text":"
       
    • Display extended error message in ejabberdctl
      •  
    • Remove SMP option from ejabberdctl.cfg, -smp was removed in OTP 21
      •  
    • create_room: After creating room, store in DB if it's persistent
      •  
    • help: Major changes in its usage and output
      •  
    • srg_create: Update to use label parameter instead of name
      •  
    "},{"location":"CHANGELOG/#modules_2","title":"Modules:","text":"
       
    • ejabberd_listener: New send_timeout option
      •  
    • mod_mix: Improvements to update to 0.14.1
      •  
    • mod_muc_room: Don't leak owner JIDs
      •  
    • mod_multicast: Routing for more MUC packets
      •  
    • mod_multicast: Correctly strip only other bcc addresses
      •  
    • mod_mqtt: Allow shared roster group placeholder in mqtt topic
      •  
    • mod_pubsub: Several fixes when using PubSub with RSM
      •  
    • mod_push: Handle MUC/Sub events correctly
      •  
    • mod_shared_roster: Delete cache after performing change to be sure that in cache will be up to date data
      •  
    • mod_shared_roster: Improve database and caching
      •  
    • mod_shared_roster: Reconfigure cache when options change
      •  
    • mod_vcard: Fix invalid_encoding error when using extended plane characters in vcard
      •  
    • mod_vcard: Update econf:vcard() to generate correct vcard_temp record
      •  
    • WebAdmin: New simple pages to view mnesia tables information and content
      •  
    • WebSocket: Fix typos
      •  
    "},{"location":"CHANGELOG/#sql_5","title":"SQL:","text":"
       
    • MySQL Backend Patch for scram-sha512
      •  
    • SQLite: When exporting for SQLite, use its specific escape options
      •  
    • SQLite: Minor fixes for new_sql_schema support
      •  
    • mod_privacy: Cast as boolean when exporting privacy_list_data to PostgreSQL
      •  
    • mod_mqtt: Add mqtt_pub table definition for MSSQL
      •  
    • mod_shared_roster: Add missing indexes to sr_group tables in all SQL databases
      •  
    "},{"location":"CHANGELOG/#version-2104","title":"Version 21.04","text":""},{"location":"CHANGELOG/#api-commands","title":"API Commands:","text":"
       
    • add_rosteritem/...: Add argument guards to roster commands
      •  
    • get_user_subscriptions: New command for MUC/Sub
      •  
    • remove_mam_for_user_with_peer: Fix when removing room archive
      •  
    • send_message: Fix bug introduced in ejabberd 21.01
      •  
    • set_vcard: Return modules errors
      •  
    "},{"location":"CHANGELOG/#build-and-setup","title":"Build and setup:","text":"
       
    • Allow ejabberd to be compatible as a dependency for an Erlang project using rebar3
      •  
    • CAPTCHA: New question/answer-based CAPTCHA script
      •  
    • --enable-lua: new configure option for luerl instead of --enable-tools
      •  
    • Remove support for HiPE, it was experimental and Erlang/OTP 24 removes it
      •  
    • Update sql_query record to handle the Erlang/OTP 24 compiler reports
      •  
    • Updated dependencies to fix Dialyzer warnings
      •  
    "},{"location":"CHANGELOG/#miscellaneous","title":"Miscellaneous:","text":"
       
    • CAPTCHA: Update FORM_TYPE from captcha to register
      •  
    • LDAP: fix eldap certificate verification
      •  
    • MySQL: Fix for \"specified key was too long\"
      •  
    • Translations: updated the Esperanto, Greek, and Japanese translations
      •  
    • Websocket: Fix PONG responses
      •  
    "},{"location":"CHANGELOG/#modules_3","title":"Modules:","text":"
       
    • mod_block_strangers: If stanza is type error, allow it passing
      •  
    • mod_caps: Don't request roster when not needed
      •  
    • mod_caps: Skip reading roster in one more case
      •  
    • mod_mam: Remove queryid from MAM fin element
      •  
    • mod_mqtt: When deregistering XMPP account, close its MQTT sessions
      •  
    • mod_muc: Take in account subscriber's affiliation when checking access to moderated room
      •  
    • mod_muc: Use monitors to track online and hard-killed rooms
      •  
    • mod_muc: When occupant is banned, remove his subscriptions too
      •  
    • mod_privacy: Make fetching roster lazy
      •  
    • mod_pubsub: Don't fail on PEP unsubscribe
      •  
    • mod_pubsub: Fix gen_pubsub_node:get_state return value
      •  
    • mod_vcard: Obtain and provide photo type in vCard LDAP
      •  
    "},{"location":"CHANGELOG/#version-2101","title":"Version 21.01","text":""},{"location":"CHANGELOG/#miscellaneous-changes","title":"Miscellaneous changes:","text":"
       
    • log_rotate_size option: Fix handling of \u2018infinity\u2019 value
      •  
    • mod_time: Fix invalid timezone
      •  
    • Auth JWT: New check_decoded_jwt hook runs the default JWT verifier
      •  
    • MUC: Allow non-occupant non-subscribed service admin send private MUC message
      •  
    • MUC: New max_password and max_captcha_whitelist options
      •  
    • OAuth: New oauth_cache_rest_failure_life_time option
      •  
    • PEP: Skip reading pep nodes that we know won\u2019t be requested due to caps
      •  
    • SQL: Add sql script to migrate mysql from old schema to new
      •  
    • SQL: Don\u2019t use REPLACE for upsert when there are \u201c-\u201d fields.
      •  
    • Shared Rosters LDAP: Add multi-domain support (and flexibility)
      •  
    • Sqlite3: Fix dependency version
      •  
    • Stun: Block loopback addresses by default
      •  
    • Several documentation fixes and clarifications
      •  
    "},{"location":"CHANGELOG/#commands_4","title":"Commands:","text":"
       
    • decide_room: Use better fallback value for room activity time when skipping room
      •  
    • delete_old_message: Fix when using sqlite spool table
      •  
    • module_install: Make ext_mod compile module with debug_info flags
      •  
    • room_unused_*: Don\u2019t fetch subscribers list
      •  
    • send_message: Don\u2019t include empty in messages
      •  
    • set_room_affiliation: Validate affiliations
      •  
    "},{"location":"CHANGELOG/#running","title":"Running:","text":"
       
    • Docker: New Dockerfile and devcontainer.json
      •  
    • New ejabberdctl foreground-quiet
      •  
    • Systemd: Allow for listening on privileged ports
      •  
    • Systemd: Integrate nicely with systemd
      •  
    "},{"location":"CHANGELOG/#translations_1","title":"Translations:","text":"
       
    • Moved gettext PO files to a new ejabberd-po repository
      •  
    • Improved several translations: Catalan, Chinese, German, Greek, Indonesian, Norwegian, Portuguese (Brazil), Spanish.
      •  
    "},{"location":"CHANGELOG/#version-2012","title":"Version 20.12","text":"
       
    • Add support for SCRAM-SHA-{256,512}-{PLUS} authentication
      •  
    • Don't use same value in cache for user don't exist and wrong password
      •  
    • outgoing_s2s_ipv*_address: New options to set ipv4/ipv6 outbound s2s out interface
      •  
    • s2s_send_packet: this hook now filters outgoing s2s stanzas
      •  
    • start_room: new hook runs when a room process is started
      •  
    • check_decoded_jwt: new hook to check decoded JWT after success authentication
      •  
    "},{"location":"CHANGELOG/#admin_2","title":"Admin","text":"
       
    • Docker: Fix DB initialization
      •  
    • New sql_odbc_driver option: choose the mssql ODBC driver
      •  
    • Rebar3: Fully supported. Enable with ./configure --with-rebar=/path/to/rebar3
      •  
    • systemd: start ejabberd in foreground
      •  
    "},{"location":"CHANGELOG/#modules_4","title":"Modules:","text":"
       
    • MAM: Make sure that jid used as base in mam xml_compress is bare
      •  
    • MAM: Support for MAM Flipped Pages
      •  
    • MUC: Always show MucSub subscribers nicks
      •  
    • MUC: Don't forget not-persistent rooms in load_permanent_rooms
      •  
    • MUC Admin: Better error reporting
      •  
    • MUC Admin: Fix commands with hibernated rooms
      •  
    • MUC Admin: Many improvements in rooms_unused_list/destroy
      •  
    • MUC Admin: create_room_with_opts Store options only if room starts
      •  
    • Pubsub: Remove 'dag' node plugin documentation
      •  
    • Push: Fix API call return type on error
      •  
    • Push: Support cache config changes on reload
      •  
    • Register: Allow for account-removal-only setup again
      •  
    • Roster: Make roster subscriptions work better with invalid roster state in db
      •  
    • Vcard: Fix vCard search by User when using Mnesia
      •  
    • WebAdmin: Allow vhost admins to view WebAdmin menus
      •  
    • WebAdmin: Don't do double utf-8 conversion on translated strings
      •  
    • WebAdmin: Mark dangerous buttons with CSS
      •  
    • WebSocket: Make websocket send put back pressure on c2s process
      •  
    "},{"location":"CHANGELOG/#version-2007","title":"Version 20.07","text":""},{"location":"CHANGELOG/#changes-in-this-version","title":"Changes in this version","text":"
       
    • Add support for using unix sockets in listeners.
      •  
    • Make this version compatible with erlang R23
      •  
    • Make room permissions checks more strict for subscribers
      •  
    • Fix problem with muc rooms crashing when using muc logger   with some locales
      •  
    • Limit stat calls that logger module issues
      •  
    • Don't throw errors when using user_regexp acl rule and   having non-matching host
      •  
    • Fix problem with leaving old data when updating shared rosters
      •  
    • Fix edge case that caused failure of resuming old sessions with   stream management.
      •  
    • Fix crash when room that was started with logging enabled was later   changed to logging disabled
      •  
    • Increase default shaper limits (this should help with delays for   clients that are using jingle)
      •  
    • Fix couple compatibility problems which prevented working on   erlang R19
      •  
    • Fix sending presence unavailable when session terminates for   clients that only send directed presences (helps with sometimes   not leaving muc rooms on disconnect).
      •  
    • Prevent supervisor errors for sockets that were closed before   they were passed to handler modules
      •  
    • Make stun module work better with ipv6 addresses
      •  
    "},{"location":"CHANGELOG/#version-2003","title":"Version 20.03","text":""},{"location":"CHANGELOG/#changes-in-this-version_1","title":"Changes in this version","text":"
       
    • Add support of ssl connection when connection to mysql   database (configured with sql_ssl: true option)
      •  
    • Experimental support for cockroachdb when configured   with postgres connector
      •  
    • Add cache and optimize queries issued by mod_shared_roster,   this should greatly improve performance of this module when   used with sql backend
      •  
    • Fix problem with accessing webadmin
      •  
    • Make webadmin work even when url is missing trailing slash
      •  
    • When compiling external modules with ext_mod, use flags   that were detected during compilation of ejabberd
      •  
    • Make config changed to ldap options be updated when issued   reload_config command
      •  
    • Fix room_empty_destory command
      •  
    • Fix reporting errors in send_stanza command when xml   passed to it couldn't be passed correctly
      •  
    "},{"location":"CHANGELOG/#version-2002","title":"Version 20.02","text":""},{"location":"CHANGELOG/#changes-in-this-version_2","title":"Changes in this version","text":"
       
    • Fix problems when trying to use string format with unicode   values directly in xmpp nodes
      •  
    • Add missing oauth_client table declaration in lite.new.sql
      •  
    • Improve compatibility with CocroachDB
      •  
    • Fix importing of piefxis files that did use scram passwords
      •  
    • Fix importing of piefxis files that had multiple includes   in them
      •  
    • Update jiffy dependency
      •  
    • Allow storage of emojis when using mssql database (Thanks   to Christoph Scholz)
      •  
    • Make ejabberd_auth_http be able to use auth_opts
      •  
    • Make custom_headers options in http modules correctly   override built-in values
      •  
    • Fix return value of reload_config and dump_config commands
      •  
    "},{"location":"CHANGELOG/#version-2001","title":"Version 20.01","text":""},{"location":"CHANGELOG/#new-features","title":"New features","text":"
       
    • Implement OAUTH authentication in mqtt
      •  
    • Make logging infrastructure use new logger introduced   in Erlang (requires OTP22)
      •  
    • New configuration parser/validator
      •  
    • Initial work on being able to use CockroachDB as database backend
      •  
    • Add gc command
      •  
    • Add option to disable using prepared statements on Postgresql
      •  
    • Implement routine for converting password to SCRAM format   for all backends not only SQL
      •  
    • Add infrastructure for having module documentation directly   in individual module source code
      •  
    • Generate man page automatically
      •  
    • Implement copy feature in mod_carboncopy
      •  
    "},{"location":"CHANGELOG/#fixes","title":"Fixes","text":"
       
    • Make webadmin work with configurable paths
      •  
    • Fix handling of result in xmlrpc module
      •  
    • Make webadmin work even when accessed through not declared domain
      •  
    • Better error reporting in xmlrpc
      •  
    • Limit amount of results returned by disco queries to pubsub nodes
      •  
    • Improve validation of configured JWT keys
      •  
    • Fix race condition in Redis/SQL startup
      •  
    • Fix loading order of third party modules
      •  
    • Fix reloading of ACL rules
      •  
    • Make account removal requests properly route response
      •  
    • Improve handling of malformed inputs in send_message command
      •  
    • Omit push notification if storing message in offline storage   failed
      •  
    • Fix crash in stream management when timeout was not set
      •  
    "},{"location":"CHANGELOG/#version-1909","title":"Version 19.09","text":""},{"location":"CHANGELOG/#admin_3","title":"Admin","text":"
       
    • The minimum required Erlang/OTP version is now 19.3
      •  
    • Fix API call using OAuth (#2982)
      •  
    • Rename MUC command arguments from Host to Service (#2976)
      •  
    "},{"location":"CHANGELOG/#webadmin","title":"Webadmin","text":"
       
    • Don't treat 'Host' header as a virtual XMPP host (#2989)
      •  
    • Fix some links to Guide in WebAdmin and add new ones (#3003)
      •  
    • Use select fields to input host in WebAdmin Backup (#3000)
      •  
    • Check account auth provided in WebAdmin is a local host (#3000)
      •  
    "},{"location":"CHANGELOG/#acme","title":"ACME","text":"
       
    • Improve ACME implementation
      •  
    • Fix IDA support in ACME requests
      •  
    • Fix unicode formatting in ACME module
      •  
    • Log an error message on IDNA failure
      •  
    • Support IDN hostnames in ACME requests
      •  
    • Don't attempt to create ACME directory on ejabberd startup
      •  
    • Don't allow requesting certificates for localhost or IP-like domains
      •  
    • Don't auto request certificate for localhost and IP-like domains
      •  
    • Add listener for ACME challenge in example config
      •  
    "},{"location":"CHANGELOG/#authentication","title":"Authentication","text":"
       
    • JWT-only authentication for some users (#3012)
      •  
    "},{"location":"CHANGELOG/#muc_4","title":"MUC","text":"
       
    • Apply default role after revoking admin affiliation (#3023)
      •  
    • Custom exit message is not broadcast (#3004)
      •  
    • Revert \"Affiliations other than admin and owner cannot invite to members_only rooms\" (#2987)
      •  
    • When join new room with password, set pass and password_protected (#2668)
      •  
    • Improve rooms_* commands to accept 'global' as MUC service argument (#2976)
      •  
    • Rename MUC command arguments from Host to Service (#2976)
      •  
    "},{"location":"CHANGELOG/#sql_6","title":"SQL","text":"
       
    • Fix transactions for Microsoft SQL Server (#2978)
      •  
    • Spawn SQL connections on demand only
      •  
    "},{"location":"CHANGELOG/#misc","title":"Misc","text":"
       
    • Add support for XEP-0328: JID Prep
      •  
    • Added gsfonts for captcha
      •  
    • Log Mnesia table type on creation
      •  
    • Replicate Mnesia 'bosh' table when nodes are joined
      •  
    • Fix certificate selection for s2s (#3015)
      •  
    • Provide meaningful error when adding non-local users to shared roster (#3000)
      •  
    • Websocket: don't treat 'Host' header as a virtual XMPP host (#2989)
      •  
    • Fix sm ack related c2s error (#2984)
      •  
    • Don't hide the reason why c2s connection has failed
      •  
    • Unicode support
      •  
    • Correctly handle unicode in log messages
      •  
    • Fix unicode processing in ejabberd.yml
      •  
    "},{"location":"CHANGELOG/#version-1908","title":"Version 19.08","text":""},{"location":"CHANGELOG/#administration","title":"Administration","text":"
       
    • Improve ejabberd halting procedure
      •  
    • Process unexpected erlang messages uniformly: logging a warning
      •  
    • mod_configure: Remove modules management
      •  
    "},{"location":"CHANGELOG/#configuration","title":"Configuration","text":"
       
    • Use new configuration validator
      •  
    • ejabberd_http: Use correct virtual host when consulting trusted_proxies
      •  
    • Fix Elixir modules detection in the configuration file
      •  
    • Make option 'validate_stream' global
      •  
    • Allow multiple definitions of host_config and append_host_config
      •  
    • Introduce option 'captcha_url'
      •  
    • mod_stream_mgmt: Allow flexible timeout format
      •  
    • mod_mqtt: Allow flexible timeout format in session_expiry option
      •  
    "},{"location":"CHANGELOG/#misc_1","title":"Misc","text":"
       
    • Fix SQL connections leakage
      •  
    • New authentication method using JWT tokens
      •  
    • extauth: Add 'certauth' command
      •  
    • Improve SQL pool logic
      •  
    • Add and improve type specs
      •  
    • Improve extraction of translated strings
      •  
    • Improve error handling/reporting when loading language translations
      •  
    • Improve hooks validator and fix bugs related to hooks registration
      •  
    • Gracefully close inbound s2s connections
      •  
    • mod_mqtt: Fix usage of TLS
      •  
    • mod_offline: Make count_offline_messages cache work when using mam for storage
      •  
    • mod_privacy: Don't attempt to query 'undefined' active list
      •  
    • mod_privacy: Fix race condition
      •  
    "},{"location":"CHANGELOG/#muc_5","title":"MUC","text":"
       
    • Add code for hibernating inactive muc_room processes
      •  
    • Improve handling of unexpected iq in mod_muc_room
      •  
    • Attach mod_muc_room processes to a supervisor
      •  
    • Restore room when receiving message or generic iq for not started room
      •  
    • Distribute routing of MUC messages across all CPU cores
      •  
    "},{"location":"CHANGELOG/#pubsub_2","title":"PubSub","text":"
       
    • Fix pending nodes retrieval for SQL backend
      •  
    • Check access_model when publishing PEP
      •  
    • Remove deprecated pubsub plugins
      •  
    • Expose access_model and publish_model in pubsub#metadata
      •  
    "},{"location":"CHANGELOG/#version-1905","title":"Version 19.05","text":""},{"location":"CHANGELOG/#admin_4","title":"Admin","text":"
       
    • The minimum required Erlang/OTP version is now 19.1
      •  
    • Provide a suggestion when unknown command, module, option or request handler is detected
      •  
    • Deprecate some listening options: captcha, register, web_admin, http_bind and xmlrpc
      •  
    • Add commands to get Mnesia info: mnesia_info and mnesia_table_info
      •  
    • Fix Register command to respect mod_register's Access option
      •  
    • Fixes in Prosody import: privacy and rooms
      •  
    • Remove TLS options from the example config
      •  
    • Improve request_handlers validator
      •  
    • Fix syntax in example Elixir config file
      •  
    "},{"location":"CHANGELOG/#auth","title":"Auth","text":"
       
    • Correctly support cache tags in ejabberd_auth
      •  
    • Don't process failed EXTERNAL authentication by mod_fail2ban
      •  
    • Don't call to mod_register when it's not loaded
      •  
    • Make anonymous auth don't {de}register user when there are other resources
      •  
    "},{"location":"CHANGELOG/#developer","title":"Developer","text":"
       
    • Rename listening callback from start/2 to start/3
      •  
    • New hook called when room gets destroyed: room_destroyed
      •  
    • New hooks for tracking mucsub subscriptions changes: muc_subscribed, muc_unsubscribed
      •  
    • Make static hooks analyzer working again
      •  
    "},{"location":"CHANGELOG/#muc_6","title":"MUC","text":"
       
    • Service admins are allowed to recreate room even if archive is nonempty
      •  
    • New option user_mucsub_from_muc_archive
      •  
    • Avoid late arrival of get_disco_item response
      •  
    • Handle get_subscribed_rooms call from mod_muc_room pid
      •  
    • Fix room state cleanup from db on change of persistent option change
      •  
    • Make get_subscribed_rooms work even for non-persistant rooms
      •  
    • Allow non-moderator subscribers to get list of room subscribers
      •  
    "},{"location":"CHANGELOG/#offline","title":"Offline","text":"
       
    • New option bounce_groupchat: make it not bounce mucsub/groupchat messages
      •  
    • New option use_mam_for_storage: fetch data from mam instead of spool table
      •  
    • When applying limit of max msgs in spool check only spool size
      •  
    • Do not store mucsub wrapped messages with no-store hint in offline storage
      •  
    • Always store ActivityMarker messages
      •  
    • Don't issue count/message fetch queries for offline from mam when not needed
      •  
    • Properly handle infinity as max number of message in mam offline storage
      •  
    • Sort messages by stanza_id when using mam storage in mod_offline
      •  
    • Return correct value from count_offline_messages with mam storage option
      •  
    • Make mod_offline put msg ignored by mam in spool when mam storage is on
      •  
    "},{"location":"CHANGELOG/#sql_7","title":"SQL:","text":"
       
    • Add SQL schemas for MQTT tables
      •  
    • Report better errors on SQL terms decode failure
      •  
    • Fix PostgreSQL compatibility in mod_offline_sql:remove_old_messages
      •  
    • Fix handling of list arguments on pgsql
      •  
    • Preliminary support for SQL in process_rosteritems command
      •  
    "},{"location":"CHANGELOG/#tests","title":"Tests","text":"
       
    • Add tests for user mucsub mam from muc mam
      •  
    • Add tests for offline with mam storage
      •  
    • Add tests for offline use_mam_for_storage
      •  
    • Initial Docker environment to run ejabberd test suite
      •  
    • Test offline:use_mam_for_storage, mam:user_mucsub_from_muc_archive used together
      •  
    "},{"location":"CHANGELOG/#websocket","title":"Websocket","text":"
       
    • Add WebSockets support to mod_mqtt
      •  
    • Return \"Bad request\" error when origin in websocket connection doesn't match
      •  
    • Fix RFC6454 violation on websocket connection when validating Origin header
      •  
    • Origin header validation on websocket connection
      •  
    "},{"location":"CHANGELOG/#other-modules_1","title":"Other modules","text":"
       
    • mod_adhoc: Use xml:lang from stanza when it's missing in  element
      •  
    • mod_announce: Add 'sessionid' attribute when required
      •  
    • mod_bosh: Don't put duplicate polling attribute in bosh payload
      •  
    • mod_http_api: Improve argument error messages and log messages
      •  
    • mod_http_upload: Feed whole image to eimp:identify/1
      •  
    • mod_http_upload: Log nicer warning on unknown host
      •  
    • mod_http_upload: Case-insensitive host comparison
      •  
    • mod_mqtt: Support other socket modules
      •  
    • mod_push: Check for payload in encrypted messages
      •  
    "},{"location":"CHANGELOG/#version-1902","title":"Version 19.02","text":""},{"location":"CHANGELOG/#admin_5","title":"Admin","text":"
       
    • Fix in configure.ac the Erlang/OTP version: from 17.5 to 19.0
      •  
    • reload_config command: Fix crash when sql_pool_size option is used
      •  
    • reload_config command: Fix crash when SQL is not configured
      •  
    • rooms_empty_destroy command: Several fixes to behave more conservative
      •  
    • Fix serverhost->host parameter name for muc_(un)register_nick API
      •  
    "},{"location":"CHANGELOG/#configuration_1","title":"Configuration","text":"
       
    • Allow specifying tag for listener for api_permission purposes
      •  
    • Change default ciphers to intermediate
      •  
    • Define default ciphers/protocol_option in example config
      •  
    • Don't crash on malformed 'modules' section
      •  
    • mod_mam: New option clear_archive_on_room_destroy to prevent archive removal on room destroy
      •  
    • mod_mam: New option access_preferences to restrict who can modify the MAM preferences
      •  
    • mod_muc: New option access_mam to restrict who can modify that room option
      •  
    • mod_offline: New option store_groupchat to allow storing group chat messages
      •  
    "},{"location":"CHANGELOG/#core_4","title":"Core","text":"
       
    • Add MQTT protocol support
      •  
    • Fix (un)setting of priority
      •  
    • Use OTP application startup infrastructure for starting dependencies
      •  
    • Improve starting order of several dependencies
      •  
    "},{"location":"CHANGELOG/#mam","title":"MAM","text":"
       
    • mod_mam_mnesia/sql: Improve check for empty archive
      •  
    • disallow room creation if archive not empty and clear_archive_on_room_destroy is false
      •  
    • allow check if archive is empty for or user or room
      •  
    • Additional checks for database failures
      •  
    "},{"location":"CHANGELOG/#muc_7","title":"MUC","text":"
       
    • Make sure that room_destroyed is called even when some code throws in terminate
      •  
    • Update muc room state after adding extra access field to it
      •  
    • MUC/Sub: Send mucsub subscriber notification events with from set to room jid
      •  
    "},{"location":"CHANGELOG/#shared-roster","title":"Shared Roster","text":"
       
    • Don't perform roster push for non-local contacts
      •  
    • Handle versioning result when shared roster group has remote account
      •  
    • Fix SQL queries
      •  
    "},{"location":"CHANGELOG/#miscelanea","title":"Miscelanea","text":"
       
    • CAPTCHA: Add no-store hint to CAPTCHA challenge stanzas
      •  
    • HTTP: Reject http_api request with malformed Authentication header
      •  
    • mod_carboncopy: Don't lose carbons on presence change or session resumption
      •  
    • mod_mix: Fix submission-id and channel resource
      •  
    • mod_ping: Fix ping IQ reply/timeout processing (17.x regression)
      •  
    • mod_private: Hardcode item ID for PEP bookmarks
      •  
    • mod_push: Improve notification error handling
      •  
    • PIEFXIS: Fix user export when password is scrammed
      •  
    • Prosody: Improve import of roster items, rooms and attributes
      •  
    • Translations: fixed \"make translations\"
      •  
    • WebAdmin: Fix support to restart module with new options
      •  
    "},{"location":"CHANGELOG/#version-1812","title":"Version 18.12","text":"
       
    • MAM data store compression
      •  
    • Proxy protocol support
      •  
    • MUC Self-Ping optimization (XEP-0410)
      •  
    • Bookmarks conversion (XEP-0411)
      •  
    "},{"location":"CONTAINER/","title":"ejabberd Container","text":""},{"location":"CONTAINER/#ejabberd-container-image","title":"ejabberd Container Image","text":"
    ejabberd is an open-source, robust, scalable and extensible realtime platform built using Erlang/OTP, that includes XMPP Server, MQTT Broker and SIP Service.
     
    This document explains how to use the ejabberd container image available in ghcr.io/processone/ejabberd, built using the files in .github/container/. This image is based in Alpine 3.19, includes Erlang/OTP 26.2 and Elixir 1.16.1.
     
    Alternatively, there is also the ecs container image available in docker.io/ejabberd/ecs, built using the docker-ejabberd/ecs repository. Check the differences between ejabberd and ecs images.
     
    If you are using a Windows operating system, check the tutorials mentioned in ejabberd Docs > Docker Image.
    "},{"location":"CONTAINER/#start-ejabberd","title":"Start ejabberd","text":""},{"location":"CONTAINER/#with-default-configuration","title":"With default configuration","text":"
    Start ejabberd in a new container:
     
    docker run --name ejabberd -d -p 5222:5222 ghcr.io/processone/ejabberd\n
     
    That runs the container as a daemon, using ejabberd default configuration file and XMPP domain \"localhost\".
     
    Stop the running container:
     
    docker stop ejabberd\n
     
    Restart the stopped ejabberd container:
     
    docker restart ejabberd\n
    "},{"location":"CONTAINER/#start-with-erlang-console-attached","title":"Start with Erlang console attached","text":"
    Start ejabberd with an Erlang console attached using the live command:
     
    docker run --name ejabberd -it -p 5222:5222 ghcr.io/processone/ejabberd live\n
     
    That uses the default configuration file and XMPP domain \"localhost\".
    "},{"location":"CONTAINER/#start-with-your-configuration-and-database","title":"Start with your configuration and database","text":"
    Pass a configuration file as a volume and share the local directory to store database:
     
    mkdir database\nchown ejabberd database\n\ncp ejabberd.yml.example ejabberd.yml\n\ndocker run --name ejabberd -it \\\n  -v $(pwd)/ejabberd.yml:/opt/ejabberd/conf/ejabberd.yml \\\n  -v $(pwd)/database:/opt/ejabberd/database \\\n  -p 5222:5222 ghcr.io/processone/ejabberd live\n
     
    Notice that ejabberd runs in the container with an account named ejabberd, and the volumes you mount must grant proper rights to that account.
    "},{"location":"CONTAINER/#next-steps","title":"Next steps","text":""},{"location":"CONTAINER/#register-the-administrator-account","title":"Register the administrator account","text":"
    The default ejabberd configuration does not grant admin privileges to any account, you may want to register a new account in ejabberd and grant it admin rights.
     
    Register an account using the ejabberdctl script:
     
    docker exec -it ejabberd ejabberdctl register admin localhost passw0rd\n
     
    Then edit conf/ejabberd.yml and add the ACL as explained in ejabberd Docs: Administration Account
    "},{"location":"CONTAINER/#check-ejabberd-log-files","title":"Check ejabberd log files","text":"
    Check the content of the log files inside the container, even if you do not put it on a shared persistent drive:
     
    docker exec -it ejabberd tail -f logs/ejabberd.log\n
    "},{"location":"CONTAINER/#inspect-the-container-files","title":"Inspect the container files","text":"
    The container uses Alpine Linux. Start a shell inside the container:
     
    docker exec -it ejabberd sh\n
    "},{"location":"CONTAINER/#open-ejabberd-debug-console","title":"Open ejabberd debug console","text":"
    Open an interactive debug Erlang console attached to a running ejabberd in a running container:
     
    docker exec -it ejabberd ejabberdctl debug\n
    "},{"location":"CONTAINER/#captcha","title":"CAPTCHA","text":"
    ejabberd includes two example CAPTCHA scripts. If you want to use any of them, first install some additional required libraries:
     
    docker exec --user root ejabberd apk add imagemagick ghostscript-fonts bash\n
     
    Now update your ejabberd configuration file, for example: 
    docker exec -it ejabberd vi conf/ejabberd.yml\n
     
    and add this option: 
    captcha_cmd: /opt/ejabberd-22.04/lib/captcha.sh\n
     
    Finally, reload the configuration file or restart the container: 
    docker exec ejabberd ejabberdctl reload_config\n
     
    If the CAPTCHA image is not visible, there may be a problem generating it (the ejabberd log file may show some error message); or the image URL may not be correctly detected by ejabberd, in that case you can set the correct URL manually, for example: 
    captcha_url: https://localhost:5443/captcha\n
     
    For more details about CAPTCHA options, please check the CAPTCHA documentation section.
    "},{"location":"CONTAINER/#advanced-container-configuration","title":"Advanced Container Configuration","text":""},{"location":"CONTAINER/#ports","title":"Ports","text":"
    This container image exposes the ports:
     
       
    • 5222: The default port for XMPP clients.
      •  
    • 5269: For XMPP federation. Only needed if you want to communicate with users on other servers.
      •  
    • 5280: For admin interface.
      •  
    • 5443: With encryption, used for admin interface, API, CAPTCHA, OAuth, Websockets and XMPP BOSH.
      •  
    • 1883: Used for MQTT
      •  
    • 4369-4399: EPMD and Erlang connectivity, used for ejabberdctl and clustering
      •  
    • 5210: Erlang connectivity when ERL_DIST_PORT is set, alternative to EPMD
      •  
    "},{"location":"CONTAINER/#volumes","title":"Volumes","text":"
    ejabberd produces two types of data: log files and database spool files (Mnesia). This is the kind of data you probably want to store on a persistent or local drive (at least the database).
     
    The volumes you may want to map:
     
       
    • /opt/ejabberd/conf/: Directory containing configuration and certificates
      •  
    • /opt/ejabberd/database/: Directory containing Mnesia database. You should back up or export the content of the directory to persistent storage (host storage, local storage, any storage plugin)
      •  
    • /opt/ejabberd/logs/: Directory containing log files
      •  
    • /opt/ejabberd/upload/: Directory containing uploaded files. This should also be backed up.
      •  
     
    All these files are owned by ejabberd user inside the container.
     
    It's possible to install additional ejabberd modules using volumes, this comment explains how to install an additional module using docker-compose.
    "},{"location":"CONTAINER/#commands-on-start","title":"Commands on start","text":"
    The ejabberdctl script reads the CTL_ON_CREATE environment variable the first time the container is started, and reads CTL_ON_START every time the container is started. Those variables can contain one ejabberdctl command, or several commands separated with the blankspace and ; characters.
     
    By default failure of any of commands executed that way would abort start, this can be disabled by prefixing commands with !
     
    Example usage (or check the full example): 
        environment:\n      - CTL_ON_CREATE=! register admin localhost asd\n      - CTL_ON_START=stats registeredusers ;\n                     check_password admin localhost asd ;\n                     status\n
    "},{"location":"CONTAINER/#clustering","title":"Clustering","text":"
    When setting several containers to form a cluster of ejabberd nodes, each one must have a different Erlang Node Name and the same Erlang Cookie.
     
    For this you can either: - edit conf/ejabberdctl.cfg and set variables ERLANG_NODE and ERLANG_COOKIE - set the environment variables ERLANG_NODE_ARG and ERLANG_COOKIE
     
    Example to connect a local ejabberdctl to a containerized ejabberd: 1. When creating the container, export port 5210, and set ERLANG_COOKIE: 
    docker run --name ejabberd -it \\\n  -e ERLANG_COOKIE=`cat $HOME/.erlang.cookie` \\\n  -p 5210:5210 -p 5222:5222 \\\n  ghcr.io/processone/ejabberd\n
     2. Set ERL_DIST_PORT=5210 in ejabberdctl.cfg of container and local ejabberd 3. Restart the container 4. Now use ejabberdctl in your local ejabberd deployment
     
    To connect using a local ejabberd script: 
    ERL_DIST_PORT=5210 _build/dev/rel/ejabberd/bin/ejabberd ping\n
     
    Example using environment variables (see full example docker-compose.yml): 
        environment:\n      - ERLANG_NODE_ARG=ejabberd@node7\n      - ERLANG_COOKIE=dummycookie123\n
    "},{"location":"CONTAINER/#build-a-container-image","title":"Build a Container Image","text":"
    This container image includes ejabberd as a standalone OTP release built using Elixir. That OTP release is configured with:
     
       
    • mix.exs: Customize ejabberd release
      •  
    • vars.config: ejabberd compilation configuration options
      •  
    • config/runtime.exs: Customize ejabberd paths
      •  
    • ejabberd.yml.template: ejabberd default config file
      •  
    "},{"location":"CONTAINER/#direct-build","title":"Direct build","text":"
    Build ejabberd Community Server container image from ejabberd master git repository:
     
    docker buildx build \\\n    -t personal/ejabberd \\\n    -f .github/container/Dockerfile \\\n    .\n
    "},{"location":"CONTAINER/#podman-build","title":"Podman build","text":"
    It's also possible to use podman instead of docker, just notice: - EXPOSE 4369-4399 port range is not supported, remove that in Dockerfile - It mentions that healthcheck is not supported by the Open Container Initiative image format - to start with command live, you may want to add environment variable EJABBERD_BYPASS_WARNINGS=true 
    podman build \\\n    -t ejabberd \\\n    -f .github/container/Dockerfile \\\n    .\n\npodman run --name eja1 -d -p 5222:5222 localhost/ejabberd\n\npodman exec eja1 ejabberdctl status\n\npodman exec -it eja1 sh\n\npodman stop eja1\n\npodman run --name eja1 -it -e EJABBERD_BYPASS_WARNINGS=true -p 5222:5222 localhost/ejabberd live\n
    "},{"location":"CONTAINER/#package-build-for-arm64","title":"Package build for arm64","text":"
    By default, .github/container/Dockerfile builds this container by directly compiling ejabberd, it is a fast and direct method. However, a problem with QEMU prevents building the container in QEMU using Erlang/OTP 25 for the arm64 architecture.
     
    Providing --build-arg METHOD=package is an alternate method to build the container used by the Github Actions workflow that provides amd64 and arm64 container images. It first builds an ejabberd binary package, and later installs it in the image. That method avoids using QEMU, so it can build arm64 container images, but is extremely slow the first time it's used, and consequently not recommended for general use.
     
    In this case, to build the ejabberd container image for arm64 architecture:
     
    docker buildx build \\\n    --build-arg METHOD=package \\\n    --platform linux/arm64 \\\n    -t personal/ejabberd:$VERSION \\\n    -f .github/container/Dockerfile \\\n    .\n
    "},{"location":"CONTAINER/#composer-examples","title":"Composer Examples","text":""},{"location":"CONTAINER/#minimal-example","title":"Minimal Example","text":"
    This is the barely minimal file to get a usable ejabberd. Store it as docker-compose.yml:
     
    services:\n  main:\n    image: ghcr.io/processone/ejabberd\n    container_name: ejabberd\n    ports:\n      - \"5222:5222\"\n      - \"5269:5269\"\n      - \"5280:5280\"\n      - \"5443:5443\"\n
     
    Create and start the container with the command: 
    docker-compose up\n
    "},{"location":"CONTAINER/#customized-example","title":"Customized Example","text":"
    This example shows the usage of several customizations: it uses a local configuration file, stores the mnesia database in a local path, registers an account when it's created, and checks the number of registered accounts every time it's started.
     
    Download or copy the ejabberd configuration file: 
    wget https://raw.githubusercontent.com/processone/ejabberd/master/ejabberd.yml.example\nmv ejabberd.yml.example ejabberd.yml\n
     
    Create the database directory and allow the container access to it: 
    mkdir database\nsudo chown 9000:9000 database\n
     
    Now write this docker-compose.yml file: 
    version: '3.7'\n\nservices:\n\n  main:\n    image: ghcr.io/processone/ejabberd\n    container_name: ejabberd\n    environment:\n      - CTL_ON_CREATE=register admin localhost asd\n      - CTL_ON_START=registered_users localhost ;\n                     status\n    ports:\n      - \"5222:5222\"\n      - \"5269:5269\"\n      - \"5280:5280\"\n      - \"5443:5443\"\n    volumes:\n      - ./ejabberd.yml:/opt/ejabberd/conf/ejabberd.yml:ro\n      - ./database:/opt/ejabberd/database\n
    "},{"location":"CONTAINER/#clustering-example","title":"Clustering Example","text":"
    In this example, the main container is created first. Once it is fully started and healthy, a second container is created, and once ejabberd is started in it, it joins the first one.
     
    An account is registered in the first node when created (and we ignore errors that can happen when doing that - for example whenn account already exists), and it should exist in the second node after join.
     
    Notice that in this example the main container does not have access to the exterior; the replica exports the ports and can be accessed.
     
    version: '3.7'\n\nservices:\n\n  main:\n    image: ghcr.io/processone/ejabberd\n    container_name: ejabberd\n    environment:\n      - ERLANG_NODE_ARG=ejabberd@main\n      - ERLANG_COOKIE=dummycookie123\n      - CTL_ON_CREATE=! register admin localhost asd\n\n  replica:\n    image: ghcr.io/processone/ejabberd\n    container_name: replica\n    depends_on:\n      main:\n        condition: service_healthy\n    ports:\n      - \"5222:5222\"\n      - \"5269:5269\"\n      - \"5280:5280\"\n      - \"5443:5443\"\n    environment:\n      - ERLANG_NODE_ARG=ejabberd@replica\n      - ERLANG_COOKIE=dummycookie123\n      - CTL_ON_CREATE=join_cluster ejabberd@main\n      - CTL_ON_START=registered_users localhost ;\n                     status\n
    "},{"location":"COPYING/","title":"License","text":"
    As a special exception, the authors give permission to link this program with the OpenSSL library and distribute the resulting binary.
    "},{"location":"COPYING/#gnu-general-public-license","title":"GNU GENERAL PUBLIC LICENSE","text":"
    Version 2, June 1991
     
    Copyright (C) 1989, 1991 Free Software Foundation, Inc.  \n51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA\n\nEveryone is permitted to copy and distribute verbatim copies\nof this license document, but changing it is not allowed.\n
    "},{"location":"COPYING/#preamble","title":"Preamble","text":"
    The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too.
     
    When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
     
    To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
     
    For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
     
    We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
     
    Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
     
    Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
     
    The precise terms and conditions for copying, distribution and modification follow.
    "},{"location":"COPYING/#terms-and-conditions-for-copying-distribution-and-modification","title":"TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION","text":"
    0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The \"Program\", below, refers to any such program or work, and a \"work based on the Program\" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term \"modification\".) Each licensee is addressed as \"you\".
     
    Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
     
    1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.
     
    You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
     
    2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
     
    a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
     
    b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
     
    c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)
     
    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
     
    Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.
     
    In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
     
    3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
     
    a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
     
    b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
     
    c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
     
    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
     
    If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
     
    4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
     
    5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
     
    6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
     
    7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.
     
    If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.
     
    It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
     
    This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
     
    8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
     
    9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
     
    Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and \"any later version\", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
     
    10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
     
    NO WARRANTY
     
    11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM \"AS IS\" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
     
    12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
     
    END OF TERMS AND CONDITIONS
    "},{"location":"COPYING/#how-to-apply-these-terms-to-your-new-programs","title":"How to Apply These Terms to Your New Programs","text":"
    If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
     
    To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the \"copyright\" line and a pointer to where the full notice is found.
     
    one line to give the program's name and an idea of what it does.\nCopyright (C) yyyy  name of author\n\nThis program is free software; you can redistribute it and/or\nmodify it under the terms of the GNU General Public License\nas published by the Free Software Foundation; either version 2\nof the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program; if not, write to the Free Software\nFoundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.\n
     
    Also add information on how to contact you by electronic and paper mail.
     
    If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
     
    Gnomovision version 69, Copyright (C) year name of author\nGnomovision comes with ABSOLUTELY NO WARRANTY; for details\ntype `show w'.  This is free software, and you are welcome\nto redistribute it under certain conditions; type `show c' \nfor details.\n
     
    The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.
     
    You should also get your employer (if you work as a programmer) or your school, if any, to sign a \"copyright disclaimer\" for the program, if necessary. Here is a sample; alter the names:
     
    Yoyodyne, Inc., hereby disclaims all copyright\ninterest in the program `Gnomovision'\n(which makes passes at compilers) written \nby James Hacker.\n\nsignature of Ty Coon, 1 April 1989\nTy Coon, President of Vice\n
     
    This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License.
    "},{"location":"README-DOCS/","title":"ejabberd Docs Source Code","text":"
    The ejabberd Community Server has its source code available in the ejabberd git repository. Its documentation is published in the ejabberd Docs website, and its source code is available in the docs git repository.
     
    This is a community effort and you are welcome to submit issues or pull requests in order to improve the docs and benefit the ejabberd community.
     
    This documentation site is built using MkDocs and Material for MkDocs.
    "},{"location":"README-DOCS/#installation","title":"Installation","text":"
    To build the site you need Python 3.6 or later, then install the dependencies:
    "},{"location":"README-DOCS/#pip","title":"pip","text":"
    mkdir -p .venv\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n
     
    Info
     
    From now on, remember to run source .venv/bin/activate before running any mkdocs [...] command.
     
    Tip
     
    You can freeze the dependencies to a file using pip freeze > requirements.txt.
    "},{"location":"README-DOCS/#debian","title":"Debian","text":"
    You could install most dependencies using APT:
     
    apt-get install mkdocs \\\n                mkdocs-material \\\n                mkdocs-material-extensions \\\n                mkdocs-redirects \\\n                python3-bs4\n
     
    Warning
     
    Unfortunately Debian doesn't package mkdocs-with-pdf, so you should remove with-pdf plugin from mkdocs.yml.
    "},{"location":"README-DOCS/#building","title":"Building","text":"
    Now you can start a small webserver that builds the site dynamically:
     
    mkdocs serve\n
     
    or build the site into static html files in the site/ directory:
     
    mkdocs build\n
    "},{"location":"README-DOCS/#testing","title":"Testing","text":"
    To verify the internal URLs in the site:
     
    TEST=true mkdocs serve\n
     
    To verify the internal URLs and also the external links:
     
    TEST=true TEST_EXTERNAL=true mkdocs serve\n
    "},{"location":"README-DOCS/#updating-content","title":"Updating content","text":"
    Some pages in this documentation are extracted from a running ejabberd node:
     
       
    • admin/configuration/toplevel.md
      •  
    • admin/configuration/modules.md
      •  
    • developer/ejabberd-api/admin-api.md
      •  
    • developer/ejabberd-api/admin-tags.md
      •  
     
    To update those pages, install ejabberd, start it and run make all in this repository. This gets documentation from ejabberd, processes it to obtain markdown content and moves the files to this repository.
     
    Additionally, there are several other pages that are markdown files copied from ejabberd git repository and docker-ejabberd git repository. Those repositories must be available next to docs.ejabberd.im before running make all.
    "},{"location":"README-DOCS/#markdown-shorthands","title":"Markdown Shorthands","text":"
    When editing ejabberd source code to document top-level options, modules or API commands, there is some additional syntax supported to generate HTML URLs:
     
    For example, this text in the ejabberd source code:
     
    _`mod_muc_admin`_\n_`bookmarks_to_pep`_ API\n_`default_db`_\n_`basic.md#captcha|CAPTCHA`_\nhttps://xmpp.org/extensions/xep-0045.html[XEP-0045]\n
     
    gets converted into this markdown:
     
    [mod_muc_admin](../../admin/configuration/modules.md#mod_muc_admin)\n[bookmarks_to_pep](../../developer/ejabberd-api/admin-api.md#bookmarks_to_pep) API\n[default_db](toplevel.md#default_db)\n[CAPTCHA](basic.md#captcha)\n[XEP-0045](https://xmpp.org/extensions/xep-0045.html)\n
     
    There are example usage of those shorthands in ejabberd, for example in mod_muc.erl.
    "},{"location":"README-ECS/","title":"ecs Container","text":""},{"location":"README-ECS/#ecs-container-image","title":"ecs Container Image","text":"
    ejabberd is an open-source XMPP server, robust, scalable and modular, built using Erlang/OTP, and also includes MQTT Broker and SIP Service.
     
    This container image allows you to run a single node ejabberd instance in a container.
     
    There is an Alternative Image in GitHub Packages, built using a different method and some improvements.
     
    If you are using a Windows operating system, check the tutorials mentioned in ejabberd Docs > Docker Image.
    "},{"location":"README-ECS/#start-ejabberd","title":"Start ejabberd","text":""},{"location":"README-ECS/#with-default-configuration","title":"With default configuration","text":"
    You can start ejabberd in a new container with the following command:
     
    docker run --name ejabberd -d -p 5222:5222 ejabberd/ecs\n
     
    This command will run the container image as a daemon, using ejabberd default configuration file and XMPP domain \"localhost\".
     
    To stop the running container, you can run:
     
    docker stop ejabberd\n
     
    If needed, you can restart the stopped ejabberd container with:
     
    docker restart ejabberd\n
    "},{"location":"README-ECS/#start-with-erlang-console-attached","title":"Start with Erlang console attached","text":"
    If you would like to start ejabberd with an Erlang console attached you can use the live command:
     
    docker run -it -p 5222:5222 ejabberd/ecs live\n
     
    This command will use default configuration file and XMPP domain \"localhost\".
    "},{"location":"README-ECS/#start-with-your-configuration-and-database","title":"Start with your configuration and database","text":"
    This command passes the configuration file using the volume feature and shares the local directory to store database:
     
    mkdir database\ndocker run -d --name ejabberd -v $(pwd)/ejabberd.yml:/home/ejabberd/conf/ejabberd.yml -v $(pwd)/database:/home/ejabberd/database -p 5222:5222 ejabberd/ecs\n
    "},{"location":"README-ECS/#next-steps","title":"Next steps","text":""},{"location":"README-ECS/#register-the-administrator-account","title":"Register the administrator account","text":"
    The default ejabberd configuration has already granted admin privilege to an account that would be called admin@localhost, so you just need to register such an account to start using it for administrative purposes. You can register this account using the ejabberdctl script, for example:
     
    docker exec -it ejabberd bin/ejabberdctl register admin localhost passw0rd\n
    "},{"location":"README-ECS/#check-ejabberd-log-files","title":"Check ejabberd log files","text":"
    Check the ejabberd log file in the container:
     
    docker exec -it ejabberd tail -f logs/ejabberd.log\n
    "},{"location":"README-ECS/#inspect-the-container-files","title":"Inspect the container files","text":"
    The container uses Alpine Linux. You can start a shell there with:
     
    docker exec -it ejabberd sh\n
    "},{"location":"README-ECS/#open-ejabberd-debug-console","title":"Open ejabberd debug console","text":"
    You can open a live debug Erlang console attached to a running container:
     
    docker exec -it ejabberd bin/ejabberdctl debug\n
    "},{"location":"README-ECS/#captcha","title":"CAPTCHA","text":"
    ejabberd includes two example CAPTCHA scripts. If you want to use any of them, first install some additional required libraries:
     
    docker exec --user root ejabberd apk add imagemagick ghostscript-fonts bash\n
     
    Now update your ejabberd configuration file, for example: 
    docker exec -it ejabberd vi conf/ejabberd.yml\n
     
    and add this option: 
    captcha_cmd: /home/ejabberd/lib/ejabberd-21.1.0/priv/bin/captcha.sh\n
     
    Finally, reload the configuration file or restart the container: 
    docker exec ejabberd bin/ejabberdctl reload_config\n
     
    If the CAPTCHA image is not visible, there may be a problem generating it (the ejabberd log file may show some error message); or the image URL may not be correctly detected by ejabberd, in that case you can set the correct URL manually, for example: 
    captcha_url: https://localhost:5443/captcha\n
     
    For more details about CAPTCHA options, please check the CAPTCHA documentation section.
    "},{"location":"README-ECS/#use-ejabberdapi","title":"Use ejabberdapi","text":"
    When the container is running (and thus ejabberd), you can exec commands inside the container using ejabberdctl or any other of the available interfaces, see Understanding ejabberd \"commands\"
     
    Additionally, this container image includes the ejabberdapi executable. Please check the ejabberd-api homepage for configuration and usage details.
     
    For example, if you configure ejabberd like this: 
    listen:\n  -\n    port: 5282\n    module: ejabberd_http\n    request_handlers:\n      \"/api\": mod_http_api\n\nacl:\n  loopback:\n    ip:\n      - 127.0.0.0/8\n      - ::1/128\n      - ::FFFF:127.0.0.1/128\n\napi_permissions:\n  \"admin access\":\n    who:\n      access:\n        allow:\n          acl: loopback\n    what:\n      - \"register\"\n
     
    Then you could register new accounts with this query:
     
    docker exec -it ejabberd bin/ejabberdapi register --endpoint=http://127.0.0.1:5282/ --jid=admin@localhost --password=passw0rd\n
    "},{"location":"README-ECS/#advanced-container-configuration","title":"Advanced container configuration","text":""},{"location":"README-ECS/#ports","title":"Ports","text":"
    This container image exposes the ports:
     
       
    • 5222: The default port for XMPP clients.
      •  
    • 5269: For XMPP federation. Only needed if you want to communicate with users on other servers.
      •  
    • 5280: For admin interface.
      •  
    • 5443: With encryption, used for admin interface, API, CAPTCHA, OAuth, Websockets and XMPP BOSH.
      •  
    • 1883: Used for MQTT
      •  
    • 4369-4399: EPMD and Erlang connectivity, used for ejabberdctl and clustering
      •  
    "},{"location":"README-ECS/#volumes","title":"Volumes","text":"
    ejabberd produces two types of data: log files and database (Mnesia). This is the kind of data you probably want to store on a persistent or local drive (at least the database).
     
    Here are the volume you may want to map:
     
       
    • /home/ejabberd/conf/: Directory containing configuration and certificates
      •  
    • /home/ejabberd/database/: Directory containing Mnesia database. You should back up or export the content of the directory to persistent storage (host storage, local storage, any storage plugin)
      •  
    • /home/ejabberd/logs/: Directory containing log files
      •  
    • /home/ejabberd/upload/: Directory containing uploaded files. This should also be backed up.
      •  
     
    All these files are owned by ejabberd user inside the container. Corresponding UID:GID is 9000:9000. If you prefer bind mounts instead of volumes, then you need to map this to valid UID:GID on your host to get read/write access on mounted directories.
    "},{"location":"README-ECS/#commands-on-start","title":"Commands on start","text":"
    The ejabberdctl script reads the CTL_ON_CREATE environment variable the first time the container is started, and reads CTL_ON_START every time the container is started. Those variables can contain one ejabberdctl command, or several commands separated with the blankspace and ; characters.
     
    By default failure of any of commands executed that way would abort start, this can be disabled by prefixing commands with !
     
    Example usage (or check the full example): 
        environment:\n      - CTL_ON_CREATE=\\! register admin localhost asd\n      - CTL_ON_START=stats registeredusers ;\n                     check_password admin localhost asd ;\n                     status\n
    "},{"location":"README-ECS/#clustering","title":"Clustering","text":"
    When setting several containers to form a cluster of ejabberd nodes, each one must have a different Erlang Node Name and the same Erlang Cookie. For this you can either: - edit conf/ejabberdctl.cfg and set variables ERLANG_NODE and ERLANG_COOKIE - set the environment variables ERLANG_NODE_ARG and ERLANG_COOKIE
     
    Once you have the ejabberd nodes properly set and running, you can tell the secondary nodes to join the master node using the join_cluster API call.
     
    Example using environment variables (see the full docker-compose.yml clustering example): 
    environment:\n  - ERLANG_NODE_ARG=ejabberd@replica\n  - ERLANG_COOKIE=dummycookie123\n  - CTL_ON_CREATE=join_cluster ejabberd@main\n
    "},{"location":"README-ECS/#change-mnesia-node-name","title":"Change Mnesia Node Name","text":"
    To use the same Mnesia database in a container with a different hostname, it is necessary to change the old hostname stored in Mnesia.
     
    This section is equivalent to the ejabberd Documentation Change Computer Hostname, but particularized to containers that use this ecs container image from ejabberd 23.01 or older.
    "},{"location":"README-ECS/#setup-old-container","title":"Setup Old Container","text":"
    Let's assume a container running ejabberd 23.01 (or older) from this ecs container image, with the database directory binded and one registered account. This can be produced with: 
    OLDCONTAINER=ejaold\nNEWCONTAINER=ejanew\n\nmkdir database\nsudo chown 9000:9000 database\ndocker run -d --name $OLDCONTAINER -p 5222:5222 \\\n       -v $(pwd)/database:/home/ejabberd/database \\\n       ejabberd/ecs:23.01\ndocker exec -it $OLDCONTAINER bin/ejabberdctl started\ndocker exec -it $OLDCONTAINER bin/ejabberdctl register user1 localhost somepass\ndocker exec -it $OLDCONTAINER bin/ejabberdctl registered_users localhost\n
     
    Methods to know the Erlang node name: 
    ls database/ | grep ejabberd@\ndocker exec -it $OLDCONTAINER bin/ejabberdctl status\ndocker exec -it $OLDCONTAINER grep \"started in the node\" logs/ejabberd.log\n
    "},{"location":"README-ECS/#change-mnesia-node","title":"Change Mnesia Node","text":"
    First of all let's store the Erlang node names and paths in variables. In this example they would be: 
    OLDCONTAINER=ejaold\nNEWCONTAINER=ejanew\nOLDNODE=ejabberd@95145ddee27c\nNEWNODE=ejabberd@localhost\nOLDFILE=/home/ejabberd/database/old.backup\nNEWFILE=/home/ejabberd/database/new.backup\n
     
       
    1.  
      Start your old container that can still read the Mnesia database correctly. If you have the Mnesia spool files, but don't have access to the old container anymore, go to Create Temporary Container and later come back here.
       
      2.  
    2.  
      Generate a backup file and check it was created: 
      docker exec -it $OLDCONTAINER bin/ejabberdctl backup $OLDFILE\nls -l database/*.backup\n
       
      3.  
    3.  
      Stop ejabberd: 
      docker stop $OLDCONTAINER\n
       
      4.  
    4.  
      Create the new container. For example: 
      docker run \\\n       --name $NEWCONTAINER \\\n       -d \\\n       -p 5222:5222 \\\n       -v $(pwd)/database:/home/ejabberd/database \\\n       ejabberd/ecs:latest\n
       
      5.  
    5.  
      Convert the backup file to new node name: 
      docker exec -it $NEWCONTAINER bin/ejabberdctl mnesia_change_nodename $OLDNODE $NEWNODE $OLDFILE $NEWFILE\n
       
      6.  
    6.  
      Install the backup file as a fallback: 
      docker exec -it $NEWCONTAINER bin/ejabberdctl install_fallback $NEWFILE\n
       
      7.  
    7.  
      Restart the container: 
      docker restart $NEWCONTAINER\n
       
      8.  
    8.  
      Check that the information of the old database is available. In this example, it should show that the account user1 is registered: 
      docker exec -it $NEWCONTAINER bin/ejabberdctl registered_users localhost\n
       
      9.  
    9.  
      When the new container is working perfectly with the converted Mnesia database, you may want to remove the unneeded files: the old container, the old Mnesia spool files, and the backup files.
       
      10.  
    "},{"location":"README-ECS/#create-temporary-container","title":"Create Temporary Container","text":"
    In case the old container that used the Mnesia database is not available anymore, a temporary container can be created just to read the Mnesia database and make a backup of it, as explained in the previous section.
     
    This method uses --hostname command line argument for docker, and ERLANG_NODE_ARG environment variable for ejabberd. Their values must be the hostname of your old container and the Erlang node name of your old ejabberd node. To know the Erlang node name please check Setup Old Container.
     
    Command line example: 
    OLDHOST=${OLDNODE#*@}\ndocker run \\\n       -d \\\n       --name $OLDCONTAINER \\\n       --hostname $OLDHOST \\\n       -p 5222:5222 \\\n       -v $(pwd)/database:/home/ejabberd/database \\\n       -e ERLANG_NODE_ARG=$OLDNODE \\\n       ejabberd/ecs:latest\n
     
    Check the old database content is available: 
    docker exec -it $OLDCONTAINER bin/ejabberdctl registered_users localhost\n
     
    Now that you have ejabberd running with access to the Mnesia database, you can continue with step 2 of previous section Change Mnesia Node.
    "},{"location":"README-ECS/#generating-ejabberd-release","title":"Generating ejabberd release","text":""},{"location":"README-ECS/#configuration","title":"Configuration","text":"
    Image is built by embedding an ejabberd Erlang/OTP standalone release in the image.
     
    The configuration of ejabberd Erlang/OTP release is customized with:
     
       
    • rel/config.exs: Customize ejabberd release
      •  
    • rel/dev.exs: ejabberd environment configuration for development release
      •  
    • rel/prod.exs: ejabberd environment configuration for production release
      •  
    • vars.config: ejabberd compilation configuration options
      •  
    • conf/ejabberd.yml: ejabberd default config file
      •  
     
    Build ejabberd Community Server base image from ejabberd master on Github:
     
    docker build -t ejabberd/ecs .\n
     
    Build ejabberd Community Server base image for a given ejabberd version:
     
    ./build.sh 18.03\n
    "},{"location":"README-ECS/#composer-examples","title":"Composer Examples","text":""},{"location":"README-ECS/#minimal-example","title":"Minimal Example","text":"
    This is the barely minimal file to get a usable ejabberd. Store it as docker-compose.yml:
     
    services:\n  main:\n    image: ejabberd/ecs\n    container_name: ejabberd\n    ports:\n      - \"5222:5222\"\n      - \"5269:5269\"\n      - \"5280:5280\"\n      - \"5443:5443\"\n
     
    Create and start the container with the command: 
    docker-compose up\n
    "},{"location":"README-ECS/#customized-example","title":"Customized Example","text":"
    This example shows the usage of several customizations: it uses a local configuration file, stores the mnesia database in a local path, registers an account when it's created, and checks the number of registered accounts every time it's started.
     
    Download or copy the ejabberd configuration file: 
    wget https://raw.githubusercontent.com/processone/ejabberd/master/ejabberd.yml.example\nmv ejabberd.yml.example ejabberd.yml\n
     
    Create the database directory and allow the container access to it: 
    mkdir database\nsudo chown 9000:9000 database\n
     
    Now write this docker-compose.yml file: 
    version: '3.7'\n\nservices:\n\n  main:\n    image: ejabberd/ecs\n    container_name: ejabberd\n    environment:\n      - CTL_ON_CREATE=register admin localhost asd\n      - CTL_ON_START=registered_users localhost ;\n                     status\n    ports:\n      - \"5222:5222\"\n      - \"5269:5269\"\n      - \"5280:5280\"\n      - \"5443:5443\"\n    volumes:\n      - ./ejabberd.yml:/home/ejabberd/conf/ejabberd.yml:ro\n      - ./database:/home/ejabberd/database\n
    "},{"location":"README-ECS/#clustering-example","title":"Clustering Example","text":"
    In this example, the main container is created first. Once it is fully started and healthy, a second container is created, and once ejabberd is started in it, it joins the first one.
     
    An account is registered in the first node when created (and we ignore errors that can happen when doing that - for example when account already exists), and it should exist in the second node after join.
     
    Notice that in this example the main container does not have access to the exterior; the replica exports the ports and can be accessed.
     
    version: '3.7'\n\nservices:\n\n  main:\n    image: ejabberd/ecs\n    container_name: main\n    environment:\n      - ERLANG_NODE_ARG=ejabberd@main\n      - ERLANG_COOKIE=dummycookie123\n      - CTL_ON_CREATE=\\! register admin localhost asd\n    healthcheck:\n      test: netstat -nl | grep -q 5222\n      start_period: 5s\n      interval: 5s\n      timeout: 5s\n      retries: 120\n\n  replica:\n    image: ejabberd/ecs\n    container_name: replica\n    depends_on:\n      main:\n        condition: service_healthy\n    ports:\n      - \"5222:5222\"\n      - \"5269:5269\"\n      - \"5280:5280\"\n      - \"5443:5443\"\n    environment:\n      - ERLANG_NODE_ARG=ejabberd@replica\n      - ERLANG_COOKIE=dummycookie123\n      - CTL_ON_CREATE=join_cluster ejabberd@main\n      - CTL_ON_START=registered_users localhost ;\n                     status\n
    "},{"location":"README-GIT/","title":"Readme","text":"
    ejabberd is an open-source, robust, scalable and extensible realtime platform built using Erlang/OTP, that includes XMPP Server, MQTT Broker and SIP Service.
     
    Check the features in ejabberd.im, ejabberd Docs, ejabberd at ProcessOne, and the list of supported protocols in ProcessOne and XMPP.org.
    "},{"location":"README-GIT/#installation","title":"Installation","text":"
    There are several ways to install ejabberd:
     
       
    • Source code: compile yourself, see COMPILE
      •  
    • Installers: ProcessOne Download and GitHub Releases for releases, GitHub Actions for master branch (run/deb/rpm for x64 and arm64)
      •  
    • ecs container image: Docker Hub and Github Packages, see ecs README (for x64)
      •  
    • ejabberd container image: Github Packages for releases and master branch, see CONTAINER (for x64 and arm64)
      •  
    • Using your Operating System package
      •  
    • Using the Homebrew package manager
      •  
    "},{"location":"README-GIT/#documentation","title":"Documentation","text":"
    Please check the ejabberd Docs website.
     
    When compiling from source code, you can get some help with:
     
    ./configure --help\nmake help\n
     
    Once ejabberd is installed, try:
     
    ejabberdctl help\nman ejabberd.yml\n
    "},{"location":"README-GIT/#development","title":"Development","text":"
    Bug reports and features are tracked using GitHub Issues, please check CONTRIBUTING for details.
     
    Translations can be improved online using Weblate or in your local machine as explained in Localization.
     
    Documentation for developers is available in ejabberd docs: Developers.
     
    There are nightly builds of ejabberd, both for master branch and for Pull Requests: - Installers: go to GitHub Actions: Installers, open the most recent commit, on the bottom of that commit page, download the ejabberd-packages.zip artifact. - ejabberd container image: go to ejabberd Github Packages
     
    Security reports or concerns should preferably be reported privately, please send an email to the address: contact at process-one dot net or some other method from ProcessOne Contact.
     
    For commercial offering and support, including ejabberd Business Edition and Fluux (ejabberd in the Cloud), please check ProcessOne ejabberd page.
    "},{"location":"README-GIT/#community","title":"Community","text":"
    There are several places to get in touch with other ejabberd developers and administrators:
     
       
    • ejabberd XMPP chatroom: ejabberd@conference.process-one.net
      •  
    • GitHub Discussions
      •  
    • Stack Overflow
      •  
    "},{"location":"README-GIT/#license","title":"License","text":"
    ejabberd is released under the GNU General Public License v2 (see COPYING), and ejabberd translations under MIT License.
    "},{"location":"README-HUB/","title":"ejabberd Community Server Docker Image","text":""},{"location":"README-HUB/#what-is-ejabberd","title":"What is ejabberd","text":"
    ejabberd is an open-source, robust, scalable and extensible realtime platform built using Erlang/OTP, that includes XMPP Server, MQTT Broker and SIP Service.
     
    Check the features in ejabberd.im, ejabberd Docs, ejabberd at ProcessOne, and a list of supported protocols and XEPs.
    "},{"location":"README-HUB/#what-is-ejabberdecs","title":"What is ejabberd/ecs","text":"
    This ejabberd/ecs Docker image is built for stable ejabberd releases using docker-ejabberd/ecs. It's based in Alpine Linux, and is aimed at providing a simple image to setup and configure.
     
    Please report problems related to this ejabberd/ecs image packaging in docker-ejabberd Issues, and general ejabberd problems in ejabberd Issues.
    "},{"location":"README-HUB/#how-to-use-the-ejabberdecs-image","title":"How to use the ejabberd/ecs image","text":"
    Please check ejabberd/ecs README
    "},{"location":"README-HUB/#supported-architectures","title":"Supported Architectures","text":"
    This ejabberd/ecs docker image is built for the linux/amd64 architecture.
    "},{"location":"README-HUB/#alternative-image-in-github","title":"Alternative Image in GitHub","text":"
    There is another container image published in ejabberd GitHub Packages, that you can download from the GitHub Container Registry.
     
    Its usage is similar to this ejabberd/ecs image, with some benefits and changes worth noting:
     
       
    • it's available for linux/amd64 and linux/arm64 architectures
      •  
    • it's built also for master branch, in addition to the stable ejabberd releases
      •  
    • it includes less customizations to the base ejabberd compared to ejabberd/ecs
      •  
    • it stores data in /opt/ejabberd/ instead of /home/ejabberd/
      •  
     
    See its documentation in CONTAINER.
    "},{"location":"admin/","title":"ejabberd for Administrators","text":"
    This area contains information on administering your ejabberd system.
     
    Additionally, you can refer to those extra topics:
     
       
    •  
      Advanced ejabberd Administration provides guidance on how to     handle advanced ejabberd topics.
       
      •  
    •  
      Administration API Reference provides documentation   for commands available in ejabberdctl and ReST API.
       
      •  
    •  
      ejabberdctl Reference provides documentation   for ejabberd server administration command-line tool.
       
      •  
    •  
      Admin FAQ provides tips and information on Frequently   Asked Questions for ejabberd Administrators.
       
      •  
    "},{"location":"admin/introduction/","title":"Features","text":"
    ejabberd is a free and open source instant messaging server written in Erlang/OTP.
     
    ejabberd is cross-platform, distributed, fault-tolerant, and based on open standards to achieve real-time communication.
     
    ejabberd is designed to be a rock-solid and feature rich XMPP server.
     
    ejabberd is suitable for small deployments, whether they need to be scalable or not, as well as extremely large deployments.
     
    Check also the features in ejabberd.im, ejabberd at ProcessOne, and the list of supported protocols in ProcessOne and XMPP.org.
    "},{"location":"admin/introduction/#key-features","title":"Key Features","text":"
    ejabberd is:
     
       
    •  
      Cross-platform: ejabberd runs under Microsoft Windows and Unix-derived systems such as Linux, FreeBSD and NetBSD.
       
      •  
    •  
      Distributed: You can run ejabberd on a cluster of machines all serving the same Jabber domain(s). When you need more capacity you can simply add a new cheap node to your cluster. Accordingly, you do not need to buy an expensive high-end machine to support tens of thousands concurrent users.
       
      •  
    •  
      Fault-tolerant: You can deploy an ejabberd cluster so that all the information required for a properly working service will be replicated permanently on all nodes. This means that if one of the nodes crashes, the others will continue working without disruption. In addition, nodes can be added or replaced on the fly.
       
      •  
    •  
      Administrator Friendly: ejabberd is built on top of the Erlang programming language. As a result, if you wish, you can perform self-contained deployments. You are not required to install an external database, an external web server, amongst others because everything is already included, and ready to run out of the box. Other administrator benefits include:
       
         
      • Comprehensive documentation.
        •  
      • Straightforward installers for Linux, Mac OS X, and Windows.
        •  
      • Web Administration.
        •  
      • Shared Roster Groups.
        •  
      • Command line administration tool.
        •  
      • Can integrate with existing authentication mechanisms.
        •  
      • Capability to send announce messages.
        •  
       
      •  
    •  
      Internationalized: ejabberd leads in internationalization and is well suited to build services available across the world. Related features are:
       
         
      • Translated to 25 languages.
        •  
      • Support for IDNA.
        •  
       
      •  
    •  
      Open Standards: ejabberd is the first Open Source Jabber server staking a claiming to full complyiance to the XMPP standard.
       
         
      • Fully XMPP compliant.
        •  
      • XML-based protocol.
        •  
      • Many protocols supported.
        •  
       
      •  
    "},{"location":"admin/introduction/#additional-features","title":"Additional Features","text":"
    ejabberd also comes with a wide range of other state-of-the-art features:
     
       
    •  
      Modular
       
         
      • Load only the modules you want.
        •  
      • Extend ejabberd with your own custom modules.
        •  
       
      •  
    •  
      Security
       
         
      • SASL and STARTTLS for c2s and s2s connections.
        •  
      • STARTTLS and Dialback s2s connections.
        •  
      • Web Admin accessible via HTTPS secure access.
        •  
       
      •  
    •  
      Databases
       
         
      • Internal database for fast deployment (Mnesia).
        •  
      • Native MySQL support.
        •  
      • Native PostgreSQL support.
        •  
      • ODBC data storage support.
        •  
      • Microsoft SQL Server support.
        •  
      • SQLite support.
        •  
       
      •  
    •  
      Authentication
       
         
      • Internal Authentication.
        •  
      • PAM, LDAP and SQL.
        •  
      • External Authentication script.
        •  
       
      •  
    •  
      Others
       
         
      • Support for virtual hosting.
        •  
      • Compressing XML streams with Stream Compression   (XEP-0138).
        •  
      • Statistics via Statistics Gathering   (XEP-0039).
        •  
      • IPv6 support both for c2s and s2s connections.
        •  
      • Multi-User Chat module with support for clustering and HTML logging.
        •  
      • Users Directory based on users vCards.
        •  
      • Publish-Subscribe component with support for   Personal Eventing via Pubsub.
        •  
      • Support for web clients: Support for XMPP subprotocol for WebSocket and HTTP Binding (BOSH) services.
        •  
      • IRC transport.
        •  
      • SIP support.
        •  
      • Component support: interface with networks such as AIM, ICQ and MSN installing special transports.
        •  
       
      •  
    "},{"location":"admin/configuration/","title":"Configuring ejabberd","text":"
    Here are the main entry points to learn more about ejabberd configuration. ejabberd is extremely powerful and can be configured in many ways with many options.
     
    Do not let this complexity scare you. Most of you will be fine with default config file (or light changes).
     
    Tutorials for first-time users:
     
       
    • How to move to ejabberd XMPP server
      •  
    • How to set up ejabberd video & voice calling (STUN/TURN)
      •  
    • How to configure ejabberd to get 100% in XMPP compliance test
      •  
     
    Detailed documentation in sections:
     
       
    • File Format
      •  
    • Basic Configuration: hosts, acl, logging...
      •  
    • Authentication: auth_method
      •  
    • Databases
      •  
    • LDAP
      •  
    • Listen Modules: c2s, s2s, http, sip, stun...
      •  
    • Listen Options
      •  
    • Top-Level Options
      •  
    • Modules Options
      •  
     
    There's also a copy of the old configuration document which was used up to ejabberd 20.03.
    "},{"location":"admin/configuration/authentication/","title":"Authentication","text":""},{"location":"admin/configuration/authentication/#supported-methods","title":"Supported Methods","text":"
    The authentication methods supported by ejabberd are:
     
       
    •  
      internal \u2014 See section\u00a0Internal.
       
      •  
    •  
      external \u2014 See section\u00a0External Script.
       
      •  
    •  
      ldap \u2014 See section\u00a0 LDAP.
       
      •  
    •  
      sql \u2014 See section Relational Databases.
       
      •  
    •  
      anonymous \u2014 See section\u00a0Anonymous Login and SASL Anonymous.
       
      •  
    •  
      pam \u2014 See section\u00a0Pam Authentication.
       
      •  
    •  
      jwt \u2014 See section\u00a0JWT Authentication.
       
      •  
     
    The top-level option auth_method defines the authentication methods that are used for user authentication. The option syntax is:
     
    auth_method: [Method1, Method2, ...]\n
     
    When the auth_method option is omitted, ejabberd relies on the default database which is configured in default_db option. If this option is not set neither, then the default authentication method will be internal.
     
    Account creation is only supported by internal, external and sql auth methods.
    "},{"location":"admin/configuration/authentication/#general-options","title":"General Options","text":"
    The top-level option auth_password_format allows to store the passwords in SCRAM format, see the SCRAM section.
     
    Other top-level options that are relevant to the authentication configuration: disable_sasl_mechanisms, fqdn.
     
    Authentication caching is enabled by default, and can be disabled in a specific vhost with the option auth_use_cache. The global authentication cache can be configured for all the authentication methods with the global top-level options: auth_cache_missed, auth_cache_size, auth_cache_life_time. For example:
     
    auth_cache_size: 1500\nauth_cache_life_time: 10 minutes\n\nhost_config:\n  example.org:\n    auth_method: [internal]\n  example.net:\n    auth_method: [ldap]\n    auth_use_cache: false\n
    "},{"location":"admin/configuration/authentication/#internal","title":"Internal","text":"
    ejabberd uses its internal Mnesia database as the default authentication method. The value internal will enable the internal authentication method.
     
    To store the passwords in SCRAM format instead of plaintext, see the SCRAM section.
     
    Examples:
     
       
    •  
      To use internal authentication on example.org and LDAP  authentication on example.net:
       
      host_config:\n  example.org:\n    auth_method: [internal]\n  example.net:\n    auth_method: [ldap]\n
       
      •  
    •  
      To use internal authentication with hashed passwords on all virtual  hosts:
       
      auth_method: internal\nauth_password_format: scram\n
       
      •  
    "},{"location":"admin/configuration/authentication/#external-script","title":"External Script","text":"
    In the external authentication method, ejabberd uses a custom script to perform authentication tasks. The server administrator can write that external authentication script in any programming language.
     
    Please check some example scripts, and the details on the interface between ejabberd and the script in the Developers > Internals > External Authentication section.
     
    Options:
     
       
    • extauth_pool_name
      •  
    • extauth_pool_size
      •  
    • extauth_program
      •  
     
    Please note that caching interferes with the ability to maintain multiple passwords per account. So if your authentication mechanism supports application-specific passwords, caching must be disabled in the host that uses this authentication method with the option auth_use_cache.
     
    This example sets external authentication, specifies the extauth script, disables caching, and starts three instances of the script for each virtual host defined in ejabberd:
     
    auth_method: [external]\nextauth_program: /etc/ejabberd/JabberAuth.class.php\nextauth_pool_size: 3\nauth_use_cache: false\n
    "},{"location":"admin/configuration/authentication/#anonymous-login-and-sasl-anonymous","title":"Anonymous Login and SASL Anonymous","text":"
    The anonymous authentication method enables two modes for anonymous authentication:
     
    Anonymous login:   This is a standard login, that use the classical login and password  mechanisms, but where password is accepted or preconfigured for all  anonymous users. This login is compliant with SASL authentication,  password and digest non-SASL authentication, so this option will  work with almost all XMPP clients
     
    SASL Anonymous:   This is a special SASL authentication mechanism that allows to login  without providing username or password (see  XEP-0175). The main  advantage of SASL Anonymous is that the protocol was designed to  give the user a login. This is useful to avoid in some case, where  the server has many users already logged or registered and when it  is hard to find a free username. The main disavantage is that you  need a client that specifically supports the SASL Anonymous  protocol.
     
    The anonymous authentication method can be configured with the following options. Remember that you can use the host_config option to set virtual host specific options (see section\u00a0Virtual Hosting):
     
       
    • allow_multiple_connections
      •  
    • anonymous_protocol
      •  
     
    Examples:
     
       
    •  
      To enable anonymous login on all virtual hosts:
       
      auth_method: [anonymous]\nanonymous_protocol: login_anon\n
       
      •  
    •  
      Similar as previous example, but limited to public.example.org:
       
      host_config:\n  public.example.org:\n    auth_method: [anonymous]\n    anonymous_protoco: login_anon\n
       
      •  
    •  
      To enable anonymous login and internal authentication on a virtual  host:
       
      host_config:\n  public.example.org:\n    auth_method:\n      - internal\n      - anonymous\n    anonymous_protocol: login_anon\n
       
      •  
    •  
      To enable SASL Anonymous on a virtual host:
       
      host_config:\n  public.example.org:\n    auth_method: [anonymous]\n    anonymous_protocol: sasl_anon\n
       
      •  
    •  
      To enable SASL Anonymous and anonymous login on a virtual host:
       
      host_config:\n  public.example.org:\n    auth_method: [anonymous]\n    anonymous_protocol: both\n
       
      •  
    •  
      To enable SASL Anonymous, anonymous login, and internal  authentication on a virtual host:
       
      host_config:\n  public.example.org:\n    auth_method:\n      - internal\n      - anonymous\n    anonymous_protocol: both\n
       
      •  
     
    There are more configuration examples and XMPP client example stanzas in Anonymous users support.
    "},{"location":"admin/configuration/authentication/#pam-authentication","title":"PAM Authentication","text":"
    ejabberd supports authentication via Pluggable Authentication Modules (PAM). PAM is currently supported in AIX, FreeBSD, HP-UX, Linux, Mac OS X, NetBSD and Solaris. PAM authentication is disabled by default, so you have to configure and compile ejabberd with PAM support enabled:
     
    ./configure --enable-pam && make install\n
     
    Options:
     
       
    • pam_service
      •  
    • pam_userinfotype
      •  
     
    Example:
     
    auth_method: [pam]\npam_service: ejabberd\n
     
    Though it is quite easy to set up PAM support in ejabberd, PAM itself introduces some security issues:
     
       
    •  
      To perform PAM authentication ejabberd uses external C-program  called epam. By default, it is located in  /var/lib/ejabberd/priv/bin/ directory. You have to set it root on  execution in the case when your PAM module requires root privileges  (pam_unix.so for example). Also you have to grant access for  ejabberd to this file and remove all other permissions from it.  Execute with root privileges:
       
      chown root:ejabberd /var/lib/ejabberd/priv/bin/epam\nchmod 4750 /var/lib/ejabberd/priv/bin/epam\n
       
      •  
    •  
      Make sure you have the latest version of PAM installed on your  system. Some old versions of PAM modules cause memory leaks. If you  are not able to use the latest version, you can kill(1) epam  process periodically to reduce its memory consumption: ejabberd  will restart this process immediately.
       
      •  
    •  
      epam program tries to turn off delays on authentication failures.  However, some PAM modules ignore this behavior and rely on their own  configuration options. You can create a configuration file  ejabberd.pam. This example shows how to turn off delays in  pam_unix.so module:
       
      #%PAM-1.0\nauth        sufficient  pam_unix.so likeauth nullok nodelay\naccount     sufficient  pam_unix.so\n
       
      •  
     
    That is not a ready to use configuration file: you must use it as a  hint when building your own PAM configuration instead. Note that if  you want to disable delays on authentication failures in the PAM  configuration file, you have to restrict access to this file, so a  malicious user can\u2019t use your configuration to perform brute-force  attacks.
     
       
    •  
      You may want to allow login access only for certain users.  pam_listfile.so module provides such functionality.
       
      •  
    •  
      If you use pam_winbind to authorise against a Windows Active  Directory, then /etc/nsswitch.conf must be configured to use  winbind as well.
       
      •  
    "},{"location":"admin/configuration/authentication/#jwt-authentication","title":"JWT Authentication","text":"
    ejabberd supports authentication using JSON Web Token (JWT).  When enabled, clients send signed tokens instead of passwords, which are checked using a private key specified in the jwt_key option. JWT payload must look like this:
     
    {\n  \"jid\": \"test@example.org\",\n  \"exp\": 1564436511\n}\n
     
    Options:
     
       
    • jwt_key
      •  
    • jwt_auth_only_rule
      •  
    • jwt_jid_field
      •  
     
    Example:
     
    auth_method: jwt\njwt_key: /path/to/jwt/key\n
     
    In this example, admins can use both JWT and plain passwords, while the rest of users can use only JWT.
     
    # the order is important here, don't use [sql, jwt]\nauth_method: [jwt, sql]\n\naccess_rules:\n  jwt_only:\n    deny: admin\n    allow: all\n\njwt_auth_only_rule: jwt_only\n
     
    Please notice that, when using JWT authentication, mod_offline will not work. With JWT authentication the accounts do not exist in the database, and there is no way to know if a given account exists or not.
     
    For more information about JWT authentication, you can check a brief tutorial in the ejabberd 19.08 release notes.
    "},{"location":"admin/configuration/authentication/#scram","title":"SCRAM","text":"
    The top-level option auth_password_format defines in what format the users passwords are stored: SCRAM format or plaintext format.
     
    The top-level option auth_scram_hash defines the hash algorithm that will be used to scram the password.
     
    ejabberd supports channel binding to the external channel, allowing the clients to use -PLUS authentication mechanisms.
     
    In summary, depending on the configured options, ejabberd supports:
     
       
    • SCRAM_SHA-1(-PLUS)
      •  
    • SCRAM_SHA-256(-PLUS)
      •  
    • SCRAM_SHA-512(-PLUS)
      •  
     
    For details about the client-server communication when using SCRAM, refer to SASL Authentication and SCRAM.
    "},{"location":"admin/configuration/authentication/#internal-storage","title":"Internal storage","text":"
    When ejabberd starts with internal auth method and SCRAM password format configured:
     
    auth_method: internal\nauth_password_format: scram\n
     
    and detects that there are plaintext passwords stored, they are automatically converted to SCRAM format:
     
    [info] Passwords in Mnesia table 'passwd' will be SCRAM'ed\n[info] Transforming table 'passwd', this may take a while\n
    "},{"location":"admin/configuration/authentication/#sql-database","title":"SQL Database","text":"
    Please note that if you use SQL auth method and SCRAM password format, the plaintext passwords already stored in the database are not automatically converted to SCRAM format.
     
    To convert plaintext passwords to SCRAM format in your database, use the convert_to_scram command:
     
    ejabberdctl convert_to_scram example.org\n
    "},{"location":"admin/configuration/authentication/#foreign-authentication","title":"Foreign authentication","text":"
    Note on SCRAM using and foreign authentication limitations: when using the SCRAM password format, it is not possible to use foreign authentication method in ejabberd, as the real password is not known.
     
    Foreign authentication are use to authenticate through various bridges ejabberd provide. Foreign authentication includes at the moment SIP and TURN auth support and they will not be working with SCRAM.
    "},{"location":"admin/configuration/basic/","title":"Basic Configuration","text":""},{"location":"admin/configuration/basic/#xmpp-domains","title":"XMPP Domains","text":""},{"location":"admin/configuration/basic/#host-names","title":"Host Names","text":"
    ejabberd supports managing several independent XMPP domains on a single ejabberd instance, using a feature called virtual hosting.
     
    The option hosts  defines a list containing one or more domains that ejabberd will serve.
     
    Of course, the hosts list can contain just one domain if you do not want to host multiple XMPP domains on the same instance.
     
    Examples:
     
       
    •  
      Serving one domain:
       
      hosts: [example.org]\n
       
      •  
    •  
      Serving three domains:
       
      hosts:\n  - example.net\n  - example.com\n  - jabber.somesite.org\n
       
      •  
    "},{"location":"admin/configuration/basic/#virtual-hosting","title":"Virtual Hosting","text":"
    When managing several XMPP domains in a single instance, those domains are truly independent. It means they can even have different configuration parameters.
     
    Options can be defined separately for every virtual host using the host_config option.
     
    Examples:
     
       
    •  
      Domain example.net is using the internal authentication method  while domain example.com is using the LDAP server running on the  domain localhost to perform authentication:
       
      host_config:\n  example.net:\n    auth_method: internal\n  example.com:\n    auth_method: ldap\n    ldap_servers:\n      - localhost\n    ldap_uids:\n      - uid\n    ldap_rootdn: \"dc=localdomain\"\n    ldap_password: \"\"\n
       
      •  
    •  
      Domain example.net is using SQL to perform authentication while  domain example.com is using the LDAP servers running on the  domains localhost and otherhost:
       
      host_config:\n  example.net:\n    auth_method: sql\n    sql_type: odbc\n    sql_server: \"DSN=ejabberd;UID=ejabberd;PWD=ejabberd\"\n  example.com:\n    auth_method: ldap\n    ldap_servers:\n      - localhost\n      - otherhost\n    ldap_uids:\n      - uid\n    ldap_rootdn: \"dc=example,dc=com\"\n    ldap_password: \"\"\n
       
      •  
     
    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, instead of defining each option in host_config use append_host_config with the same syntax.
     
    In this example three virtual hosts have some similar modules, but there are also other different modules for some specific virtual hosts:
     
    ## This ejabberd server has three vhosts:\nhosts:\n  - one.example.org\n  - two.example.org\n  - three.example.org\n\n## Configuration of modules that are common to all vhosts\nmodules:\n  mod_roster:    {}\n  mod_configure: {}\n  mod_disco:     {}\n  mod_private:   {}\n  mod_time:      {}\n  mod_last:      {}\n  mod_version:   {}\n\nappend_host_config:\n  ## Add some modules to vhost one:\n  one.example.org:\n    modules:\n      mod_muc:\n        host: conference.one.example.org\n      mod_ping: {}\n  ## Add a module just to vhost two:\n  two.example.org:\n    modules:\n      mod_muc:\n        host: conference.two.example.org\n
    "},{"location":"admin/configuration/basic/#logging","title":"Logging","text":"
    ejabberd configuration can help a lot by having the right amount of logging set up.
     
    There are several toplevel options to configure logging:
     
       
    • loglevel: Verbosity of log files generated by ejabberd.
      •  
    • hide_sensitive_log_data:     Privacy option to disable logging of IP address or sensitive data.
      •  
    • log_modules_fully:     Modules that will log everything independently from the general loglevel option.
      •  
    • log_rotate_size
      •  
    • log_rotate_count:     Setting count to N keeps N rotated logs. Setting count to 0     does not disable rotation, it instead rotates the file and keeps no previous     versions around. Setting size to X rotate log when it reaches X bytes.
      •  
    • log_burst_limit_count
      •  
    • log_burst_limit_window_time
      •  
     
    The values in default configuration file are:
     
    log_rotate_size: 10485760\nlog_rotate_count: 1\n
     
    For example, log warning and higher messages, but all c2s messages, and hide sensitive data:
     
    loglevel: warning\nhide_sensitive_log_data: true\nlog_modules_fully: [ejabberd_c2s]\n
    "},{"location":"admin/configuration/basic/#default-language","title":"Default Language","text":"
    The language option defines the default language of server strings that can be seen by XMPP clients. If a XMPP client does not support xml:lang, ejabberd uses the language specified in this option.
     
    The option syntax is:
     
    language: Language: The default value is en. In order to take effect there must be a translation file Language.msg in ejabberd\u2019s msgs directory.
     
    For example, to set Russian as default language:
     
    language: ru\n
     
    The page Internationalization and Localization provides more details.
    "},{"location":"admin/configuration/basic/#captcha","title":"CAPTCHA","text":"
    Some ejabberd modules can be configured to require a CAPTCHA challenge on certain actions, for instance mod_block_strangers, mod_muc, mod_register, and mod_register_web. If the client does not support CAPTCHA Forms (XEP-0158), a web link is provided so the user can fill the challenge in a web browser.
     
    Example scripts are provided that generate the image using ImageMagick\u2019s Convert program and Ghostscript fonts. Remember to install those dependencies: in Debian install the imagemagick and gsfonts packages; in container images check their documentation for details.
     
    The relevant top-level options are:
     
       
    •  
      captcha_cmd: Path | Module:   Full path to a script that generates the image,   or name of a module that supports generating CAPTCHA images   (mod_ecaptcha,   mod_captcha_rust).   The default value disables the feature: undefined
       
      •  
    •  
      captcha_url: URL | auto:   An URL where CAPTCHA requests should be sent,   or auto to determine the URL automatically.   The default value is auto.
       
      •  
     
    And finally, configure request_handlers for the ejabberd_http listener with a path handled by ejabberd_captcha, where the CAPTCHA images will be served.
     
    Example configuration:
     
    hosts: [example.org]\n\ncaptcha_cmd: /lib/ejabberd/priv/bin/captcha.sh\n# captcha_cmd: /opt/ejabberd-23.01/lib/captcha.sh\n# captcha_cmd: mod_ecaptcha\n\ncaptcha_url: auto\n## captcha_url: http://example.org:5280/captcha\n## captcha_url: https://example.org:443/captcha\n## captcha_url: http://example.com/captcha\n\nlisten:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /captcha: ejabberd_captcha\n
    "},{"location":"admin/configuration/basic/#acme","title":"ACME","text":"
    ACME is used 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.
    "},{"location":"admin/configuration/basic/#setting-up-acme","title":"Setting up ACME","text":"
    In ejabberd, ACME is configured using the acme top-level option, check there the available options and example configuration.
     
    The automated mode is enabled by default. However, some configuration of ejabberd is still required, because ACME requires HTTP challenges: an ACME remote server will connect to your ejabberd server on HTTP port 80 during certificate issuance.
     
    For that reason you must have an ejabberd_http listener with TLS disabled handling an \"ACME well known\" path. For example:
     
    listen:\n  -\n    module: ejabberd_http\n    port: 5280\n    tls: false\n    request_handlers:\n      /.well-known/acme-challenge: ejabberd_acme\n
     
    Note that the ACME protocol requires challenges to be sent on port 80. Since this is a privileged port, ejabberd cannot listen on it directly without root privileges. Thus you need some mechanism to forward port 80 to the port defined by the listener (port 5280 in the example above). There are several ways to do this: using NAT, setcap (Linux only), or HTTP front-ends (e.g. sslh, nginx, haproxy and so on). Pick one that fits your installation the best, but DON'T run ejabberd as root.
     
    If you see errors in the logs with ACME server problem reports, it's highly recommended to change ca_url option in the acme top-level option to the URL pointing to some staging ACME environment, fix the problems until you obtain a certificate, and then change the URL back and retry using request-certificate ejabberdctl command (see below). This is needed because ACME servers typically have rate limits, preventing you from requesting certificates too rapidly and you can get stuck for several hours or even days. By default, ejabberd uses Let's Encrypt authority. Thus, the default value of ca_url option is https://acme-v02.api.letsencrypt.org/directory and the staging URL will be https://acme-staging-v02.api.letsencrypt.org/directory:
     
    acme:\n  ## Staging environment\n  ca_url: https://acme-staging-v02.api.letsencrypt.org/directory\n  ## Production environment (the default):\n  # ca_url: https://acme-v02.api.letsencrypt.org/directory\n
     
    The automated mode can be disabled by setting auto option to false in the acme top-level option:
     
    acme:\n  auto: false\n
     
    In this case automated renewals are still enabled, however, in order to request a new certificate, you need to run request_certificate  API command:
     
    ejabberdctl request-certificate all\n
     
    If you only want to request certificates for a subset of the domains, run:
     
    ejabberdctl request-certificate domain.tld,pubsub.domain.tld,server.com,conference.server.com,...\n
     
    You can view the certificates obtained using ACME and list_certificates:
     
    $ ejabberdctl list-certificates\ndomain.tld /path/to/cert/file1 true\nserver.com /path/to/cert/file2 false\n
     
    The output is mostly self-explained: every line contains the domain, the corresponding certificate file, and whether this certificate file is used or not. A certificate might not be used for several reasons: mostly because ejabberd detects a better certificate (i.e. not expired, or having a longer lifetime). It's recommended to revoke unused certificates if they are not yet expired (see below).
     
    At any point you can revoke a certificate using revoke_certificate: pick the certificate file from the listing above and run:
     
    ejabberdctl revoke-certificate /path/to/cert/file\n
     
    If the commands return errors, consult the log files for details.
    "},{"location":"admin/configuration/basic/#acme-implementation-details","title":"ACME implementation details","text":"
    In nutshell, certification requests are performed in two phases. Firstly, ejabberd creates an account at the ACME server. That is an EC private key. Secondly, a certificate is requested. In the case of a revocation, no account is used - only a certificate in question is needed. All information is stored under acme directory inside spool directory of ejabberd (typically /var/lib/ejabberd). An example content of the directory is the following:
     
    $ tree /var/lib/ejabberd\n/var/lib/ejabberd\n\u251c\u2500\u2500 acme\n\u2502   \u251c\u2500\u2500 account.key\n\u2502   \u2514\u2500\u2500 live\n\u2502       \u251c\u2500\u2500 251ce180d964e98a2f18b65504df2ab7c55943e2\n\u2502       \u2514\u2500\u2500 93816a8429ebbaa75574eb3f59d4a806b67d6917\n...\n
     
    Here, account.key is the EC private key used to identify the ACME account. You can inspect its content using openssl command:
     
    openssl ec -text -noout -in /var/lib/ejabberd/acme/account.key\n
     
    Obtained certificates are stored under acme/live directory. You can inspect any of the certificates using openssl command as well:
     
    openssl x509 -text -noout -in /var/lib/ejabberd/acme/live/251ce180d964e98a2f18b65504df2ab7c55943e2\n
     
    In the case of errors, you can delete the whole acme directory - ejabberd will recreate its content on next certification request. However, don't delete it too frequently - usually there is a rate limit on the number of accounts and certificates an ACME server creates. In particular, for Let's Encrypt the limits are described here.
    "},{"location":"admin/configuration/basic/#access-rights","title":"Access Rights","text":"
    This section describes new ACL syntax introduced in ejabberd 16.06. For old access rule and ACL syntax documentation, please refer to configuration document archive
    "},{"location":"admin/configuration/basic/#acl","title":"ACL","text":"
    Access control in ejabberd is performed via Access Control Lists (ACLs), using the acl option. The declarations of ACLs in the configuration file have the following syntax:
     
    acl:\n  ACLName:\n    ACLType: ACLValue\n
     
    ACLType: ACLValue can be one of the following:
     
       
    •  
      all:   Matches all JIDs. Example:
       
      acl:\n  world: all\n
       
      •  
    •  
      user: Username:   Matches the user with the name Username on any of the local virtual host.  Example:
       
      acl:\n  admin:\n    user: yozhik\n
       
      •  
    •  
      user: {Username: Server} | Jid:   Matches the user with the JID Username@Server and any resource.  Example:
       
      acl:\n  admin:\n    - user:\n        yozhik@example.org\n    - user: peter@example.org\n
       
      •  
    •  
      server: Server:   Matches any JID from server Server. Example:
       
      acl:\n  exampleorg:\n    server: example.org\n
       
      •  
    •  
      resource: Resource:   Matches any JID with a resource Resource. Example:
       
      acl:\n  mucklres:\n    resource: muckl\n
       
      •  
    •  
      shared_group: Groupname:   Matches any member of a Shared Roster Group with name Groupname in  the virtual host. Example:
       
      acl:\n  techgroupmembers:\n    shared_group: techteam\n
       
      •  
    •  
      shared_group: {Groupname: Server}:   Matches any member of a Shared Roster Group with name Groupname in  the virtual host Server. Example:
       
      acl:\n  techgroupmembers:\n    shared_group:\n      techteam: example.org\n
       
      •  
    •  
      ip: Network:   Matches any IP address from the Network. Example:
       
      acl:\n  loopback:\n    ip:\n      - 127.0.0.0/8\n      - \"::1\"\n
       
      •  
    •  
      user_regexp: Regexp:   Matches any local user with a name that matches Regexp on local  virtual hosts. Example:
       
      acl:\n  tests:\n    user_regexp: \"^test[0-9]*$\"\n
       
      •  
    •  
      user_regexp: {Regexp: Server} | JidRegexp:   Matches any user with a name that matches Regexp at server  Server. Example:
       
      acl:\n  tests:\n    user_regexp:\n      - \"^test1\": example.org\n      - \"^test2@example.org\"\n
       
      •  
    •  
      server_regexp: Regexp:   Matches any JID from the server that matches Regexp. Example:
       
      acl:\n  icq:\n    server_regexp: \"^icq\\\\.\"\n
       
      •  
    •  
      resource_regexp: Regexp:   Matches any JID with a resource that matches Regexp. Example:
       
      acl:\n  icq:\n    resource_regexp: \"^laptop\\\\.\"\n
       
      •  
    •  
      node_regexp: {UserRegexp: ServerRegexp}:   Matches any user with a name that matches UserRegexp at any server  that matches ServerRegexp. Example:
       
      acl:\n  yozhik:\n    node_regexp:\n      \"^yozhik$\": \"^example.(com|org)$\"\n
       
      •  
     
       
    •  
      user_glob: Glob:
       
      •  
    •  
      user_glob: {Glob: Server}:
       
      •  
    •  
      server_glob: Glob:
       
      •  
    •  
      resource_glob: Glob:
       
      •  
    •  
      node_glob: {UserGlob: ServerGlob}:   This is the same as above. However, it uses shell glob patterns instead of regexp. These patterns can have the following special characters:
       
         
      •  
        *:   matches any string including the null string.
         
        •  
      •  
        ?:   matches any single character.
         
        •  
      •  
        [...]:   matches any of the enclosed characters. Character ranges are  specified by a pair of characters separated by a -. If the  first character after [ is a !, any character not enclosed  is matched.
         
        •  
       
      •  
     
    The following ACLName are pre-defined:
     
       
    •  
      all:   Matches any JID.
       
      •  
    •  
      none:   Matches no JID.
       
      •  
    "},{"location":"admin/configuration/basic/#access-rules","title":"Access Rules","text":"
    The access_rules option is used to allow or deny access to different services. The syntax is:
     
    access_rules:\n  AccessName:\n    - allow|deny: ACLRule|ACLDefinition\n
     
    Each definition may contain arbitrary number of - allow or - deny sections, and each section can contain any number of acl rules (as defined in previous section, it recognizes one additional rule acl: RuleName that matches when acl rule named RuleName matches). If no rule or definition is defined, the rule all is applied.
     
    Definition's - allow and - deny sections are processed in top to bottom order, and first one for which all listed acl rules matches is returned as result of access rule. If no rule matches deny is returned.
     
    To simplify configuration two shortcut version are available: - allow: acl and - allow, example below shows equivalent definitions where short or long version are used:
     
    access_rules:\n  a_short: admin\n  a_long:\n    - acl: admin\n  b_short:\n    - deny: banned\n    - allow\n  b_long:\n    - deny:\n      - acl: banned\n    - allow:\n      - all\n
     
    If you define specific Access rights in a virtual host, remember that the globally defined Access rights have precedence over those. This means that, in case of conflict, the Access granted or denied in the global server is used and the Access of a virtual host doesn't have effect.
     
    Example:
     
    access_rules:\n  configure:\n    - allow: admin\n  something:\n    - deny: someone\n    - allow\n  s2s_banned:\n    - deny: problematic_hosts\n    - deny:\n      - acl: banned_forever\n    - deny:\n      - ip: 222.111.222.111/32\n    - deny:\n      - ip: 111.222.111.222/32\n    - allow\n  xmlrpc_access:\n    - allow:\n      - user: peter@example.com\n    - allow:\n      - user: ivone@example.com\n    - allow:\n      - user: bot@example.com\n      - ip: 10.0.0.0/24\n
     
    The following AccessName are pre-defined:
     
       
    •  
      all:   Always returns the value \u2018allow\u2019.
       
      •  
    •  
      none:   Always returns the value \u2018deny\u2019.
       
      •  
    "},{"location":"admin/configuration/basic/#shaper-rules","title":"Shaper Rules","text":"
    The shaper_rules top-level option declares shapers to use for matching user/hosts. The syntax is:
     
    shaper_rules:\n  ShaperRuleName:\n    - Number|ShaperName: ACLRule|ACLDefinition\n
     
    Semantic is similar to that described in Access Rights section, only difference is that instead using - allow or - deny, name of shaper or number should be used.
     
    Examples:
     
    shaper_rules:\n  connections_limit:\n    - 10:\n      - user: peter@example.com\n    - 100: admin\n    - 5\n  download_speed:\n    - fast: admin\n    - slow: anonymous_users\n    - normal\n  log_days: 30\n
    "},{"location":"admin/configuration/basic/#limiting-opened-sessions","title":"Limiting Opened Sessions","text":"
    The special access max_user_sessions specifies the maximum number of sessions (authenticated connections) per user. If a user tries to open more sessions by using different resources, the first opened session will be disconnected. The error session replaced will be sent to the disconnected session. The value for this option can be either a number, or infinity. The default value is infinity.
     
    The syntax is:
     
    shaper_rules:\n  max_user_sessions:\n    - Number: ACLRule|ACLDefinition\n
     
    This example limits the number of sessions per user to 5 for all users, and to 10 for admins:
     
    shaper_rules:\n  max_user_sessions:\n    - 10: admin\n    - 5\n
    "},{"location":"admin/configuration/basic/#connections-to-remote-server","title":"Connections to Remote Server","text":"
    The special access max_s2s_connections specifies how many simultaneous S2S connections can be established to a specific remote XMPP server. The default value is 1. There\u2019s also available the access max_s2s_connections_per_node.
     
    The syntax is:
     
    shaper_rules:\n  max_s2s_connections: MaxNumber\n
     
    For example, let's allow up to 3 connections with each remote server:
     
    shaper_rules:\n  max_s2s_connections: 3\n
    "},{"location":"admin/configuration/basic/#shapers","title":"Shapers","text":"
    The shaper top-level option defines limitations in the connection traffic. The basic syntax is:
     
    shaper:\n  ShaperName: Rate\n
     
    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.
     
    This example defines a shaper with name normal that limits traffic speed to 1,000bytes/second, and another shaper with name fast that limits traffic speed to 50,000bytes/second:
     
    shaper:\n  normal: 1000\n  fast: 50000\n
     
    You can use the full syntax to set the BurstSize too:
     
    shaper:\n  ShaperName:\n    rate: Rate\n    burst_size: BurstSize\n
     
    With BurstSize you can allow client to send more data, but its amount can be clamped reasonably. Each connection is allowed to send BurstSize of data before processing is delayed, and that amount is replenished by Rate each second, but never more than what BurstSize allows. This allows the client to send quite a bit of data at once, but still have limited amount of data to send on constant basis.
     
    In this example, the normal shaper has Rate set to 1000 and the BurstSize takes that same value. The not_normal shaper has the same Rate that before, and sets a higher BurstSize:
     
    shaper:\n  normal: 1000\n  not_normal:\n    rate: 1000\n    burst_size: 20000\n
    "},{"location":"admin/configuration/database/","title":"Database Configuration","text":""},{"location":"admin/configuration/database/#supported-storages","title":"Supported storages","text":"
    ejabberd uses its internal Mnesia database by default. However, it is possible to use a relational database, key-value storage or an LDAP server to store persistent, long-living data. ejabberd is very flexible: you can configure different authentication methods for different virtual hosts, you can configure different authentication mechanisms for the same virtual host (fallback), you can set different storage systems for modules, and so forth.
     
    The following databases are supported by ejabberd:
     
       
    •  
      Mnesia
       
      •  
    •  
      MySQL. Check the tutorial Using ejabberd with MySQL
       
      •  
    •  
      Any ODBC compatible database
       
      •  
    •  
      PostgreSQL
       
      •  
    •  
      MS SQL Server/SQL Azure
       
      •  
    •  
      SQLite
       
      •  
    •  
      Redis(only for transient data)
       
      •  
     
    Please check LDAP Configuration section for documentation about using LDAP.
    "},{"location":"admin/configuration/database/#database-schema","title":"Database Schema","text":"
    When using external database backend, ejabberd does not create schema and tables by itself. If you plan to use MySQL, PostgreSQL, MS SQL or SQLite, you must create the schema before you run ejabberd.
     
       
    •  
      If installing ejabberd from sources, you will find sql script for your backend   in the installation directory. By default: /usr/local/lib/ejabberd/priv/sql
       
      •  
    •  
      If installing ejabberd from Process-One installer, the init scripts are located   in the ejabberd's installation path under <base>/lib/ejabberd*/priv/sql
       
      •  
     
    If using MySQL or PostgreSQL, you can choose between the default or the new schemas.
     
    See ejabberd SQL Database Schema for details on database schemas.
    "},{"location":"admin/configuration/database/#virtual-hosting","title":"Virtual Hosting","text":"
    Important note about virtual hosting: if you define several domains in ejabberd.yml (see section Host Names), you probably want that each virtual host uses a different configuration of database, authentication and storage, so that usernames do not conflict and mix between different virtual hosts. For that purpose, the options described in the next sections must be set inside a host_config for each vhost (see section Virtual Hosting). For example:
     
    host_config:\n  public.example.org:\n    sql_type: pgsql\n    sql_server: localhost\n    sql_database: database-public-example-org\n    sql_username: ejabberd\n    sql_password: password\n    auth_method: [sql]\n
    "},{"location":"admin/configuration/database/#default-database","title":"Default database","text":"
    You can simplify the configuration by setting the default database. This can be done with the default_db top-level option:
     
    default_db: mnesia|sql:  This will define the default database for a module lacking db_type option or if auth_method option is not set.
    "},{"location":"admin/configuration/database/#relational-databases","title":"Relational Databases","text":""},{"location":"admin/configuration/database/#default-and-new-schemas","title":"Default and New Schemas","text":"
    There are two database schemas available in ejabberd: the default schema is preferable when serving one massive domain, the new schema is preferable when serving many small domains.
     
    The default schema stores only one XMPP domain in the database. The XMPP domain is not stored as this is the same for all the accounts, and this saves space in massive deployments. However, to handle several domains, you have to setup one database per domain and configure each one independently using host_config, so in that case you may prefer the new schema.
     
    The new schema stores the XMPP domain in a new column server_host in the database entries, so it allows to handle several XMPP domains in a single ejabberd database. Using this schema is preferable when serving several XMPP domains and changing domains from time to time. However, if you have only one massive domain, you may prefer to use the default schema.
     
    To use the new schema, edit the ejabberd configuration file and enable new_sql_schema top-level option:
     
    new_sql_schema: true\n
     
    Now, when creating the new database, remember to use the proper SQL schema! For example, if you are using MySQL and choose the default schema, use mysql.sql. If you are using PostgreSQL and need the new schema, use pg.new.sql.
     
    If you already have a MySQL or PostgreSQL database with the default schema and contents, you can upgrade it to the new schema:
     
       
    •  
      MySQL: Edit the file sql/mysql.old-to.new.sql which is included with ejabberd, fill DEFAULT_HOST in the first line, and import that SQL file in your database. Then enable the new_sql_schema option in the ejabberd configuration, and restart ejabberd.
       
      •  
    •  
      PostgreSQL: First enable new_sql_schema and mod_admin_update_sql in your ejabberd configuration:     
      new_sql_schema: true\nmodules:\n  mod_admin_update_sql: {}\n
       then restart ejabberd, and finally execute the update_sql command:     
      ejabberdctl update_sql\n
       
      •  
    "},{"location":"admin/configuration/database/#sql-options","title":"SQL Options","text":"
    The actual database access is defined in the options with sql_ prefix. The values are used to define if we want to use ODBC, or one of the two native interface available, PostgreSQL or MySQL.
     
    To configure SQL there are several top-level options:
     
       
    • sql_type
      •  
    • sql_server
      •  
    • sql_port
      •  
    • sql_database
      •  
    • sql_username
      •  
    • sql_password
      •  
    • sql_ssl
      •  
    • sql_ssl_verify
      •  
    • sql_ssl_cafile
      •  
    • sql_ssl_certfile
      •  
    • sql_pool_size
      •  
    • sql_keepalive_interval
      •  
    • sql_odbc_driver
      •  
    • sql_start_interval
      •  
    • sql_prepared_statements
      •  
    • update_sql_schema
      •  
     
    Example of plain ODBC connection:
     
    sql_server: \"DSN=database;UID=ejabberd;PWD=password\"\n
     
    Example of MySQL connection:
     
    sql_type: mysql\nsql_server: server.company.com\nsql_port: 3306 # the default\nsql_database: mydb\nsql_username: user1\nsql_password: \"**********\"\nsql_pool_size: 5\n
    "},{"location":"admin/configuration/database/#sql-authentication","title":"SQL Authentication","text":"
    You can authenticate users against an SQL database, see the option auth_method in the Authentication section.
     
    To store the passwords in SCRAM format instead of plaintext, see the SCRAM section.
    "},{"location":"admin/configuration/database/#sql-with-ssl-connection","title":"SQL with SSL Connection","text":"
    It's possible to setup SSL encrypted connections to PostgreSQL, MySQL and MsSQL by enabling the sql_ssl option in ejabberd's configuration file: sql_ssl: true
     
    Please notice that ejabberd verifies the certificate presented by the SQL server against the CA certificate list. For that reason, if your SQL server uses a self-signed certificate, you need to setup sql_ssl_verify and sql_ssl_cafile, for example:
     
    sql_ssl: true\nsql_ssl_verify: false\nsql_ssl_cafile: \"/path/to/sql_server_cacert.pem\"\n
     
    This tells ejabberd to ignore problems from not matching any CA certificate from default list, and instead try to verify using the specified CA certificate.
    "},{"location":"admin/configuration/database/#sql-storage","title":"SQL Storage","text":"
    Several ejabberd modules have options called db_type, and can store their tables in an SQL database instead of internal.
     
    In this sense, if you defined your database access using the SQL Options, you can configure a module to use your database by adding the option db_type: sql to that module.
     
    Alternatively, if you want all modules to use your SQL database when possible, you may prefer to set SQL as your default database.
    "},{"location":"admin/configuration/database/#redis","title":"Redis","text":"
    Redis is an advanced key-value cache and store. You can use it to store transient data, such as records for C2S (client) sessions. There are several options available:
     
       
    •  
      redis_server: String:   A hostname of the Redis server. The default is localhost.
       
      •  
    •  
      redis_port: Port:   The port where the Redis server is accepting connections. The default     is 6379.
       
      •  
    •  
      redis_password: String:   The password to the Redis server. The default is an empty string,     i.e. no password.
       
      •  
    •  
      redis_db: N:   Redis database number. The default is 0.
       
      •  
    •  
      redis_connect_timeout: N:   A number of seconds to wait for the connection to be established to the Redis     server. The default is 1 second.
       
      •  
     
    Example configuration:
     
    redis_server: redis.server.com\nredis_db: 1\n
    "},{"location":"admin/configuration/database/#microsoft-sql-server","title":"Microsoft SQL Server","text":"
    For now, MS SQL is only supported in Unix-like OS'es. You need to have unixODBC installed on your machine, and your Erlang/OTP must be compiled with ODBC support. Also, in some cases you need to add machine name to sql_username, especially when you have sql_server defined as an IP address, e.g.:
     
    sql_type: mssql\nsql_server: 1.2.3.4\nsql_username: user1@host\n
     
    By default, ejabberd will use the FreeTDS driver. You need to have the driver file libtdsodbc.so installed in your library PATH on your system.
     
    If the FreeTDS driver is not installed in a standard location, or if you want to use another ODBC driver, you can specify the path to the driver using the sql_odbc_driver option, available in ejabberd 20.12 or later. For example, if you want to use Microsoft ODBC Driver 17 for SQL Server:
     
    sql_odbc_driver: \"/opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.3.so.1.1\"\n
     
    Note that if you use a Microsoft driver, you may have to use an IP address instead of a host name for the sql_server option.
     
    If hostname (or IP address) is specified in sql_server option, ejabberd will connect using a an ODBC DSN connection string constructed with:
     
       
    • SERVER=sql_server
      •  
    • DATABASE=sql_database
      •  
    • UID=sql_username
      •  
    • PWD=sql_password
      •  
    • PORT=sql_port
      •  
    • ENCRYPTION=required (only if sql_ssl is true)
      •  
    • CLIENT_CHARSET=UTF-8
      •  
     
    Since ejabberd 23.04, t is possible to use different connection options by putting a full ODBC connection string in sql_server (e.g. DSN=database;UID=ejabberd;PWD=password). The DSN must be configured in existing system or user odbc.ini file, where it can be configured as desired, using a driver from system odbcinst.ini. The sql_odbc_driver option will have no effect in this case.
     
    If specifying an ODBC connection string, an ODBC connection string must also be specified for any other hosts using MS SQL DB, otherwise the auto-generated ODBC configuration will interfere.
    "},{"location":"admin/configuration/file-format/","title":"File format","text":""},{"location":"admin/configuration/file-format/#yaml-file-format","title":"Yaml File Format","text":"
    ejabberd loads its configuration file during startup. This configuration file is written in YAML format, and its file name MUST have \u201c.yml\u201d or \u201c.yaml\u201d extension. This helps ejabberd to differentiate between this new format and the legacy configuration file format.
     
    Please, consult ejabberd.log for configuration errors. ejabberd will report syntax related errors, as well as complains about unknown options and invalid values. Make sure you respect indentation (YAML is sensitive to this) or you will get pretty cryptic errors.
     
    Note that ejabberd never edits the configuration file. If you are changing parameters at runtime from web admin interface, you will need to apply them to configuration file manually. This is to prevent messing up with your config file comments, syntax, etc.
    "},{"location":"admin/configuration/file-format/#reload-at-runtime","title":"Reload at Runtime","text":"
    You can modify the ejabberd configuration file and reload it at runtime: the changes you made are applied immediately, no need to restart ejabberd. This applies to adding, changing or removing vhosts, listened ports, modules, ACLs or any other options.
     
    How to do this?
     
       
    1. Let's assume your ejabberd server is already running
      2.  
    2. Modify the configuration file
      3.  
    3. Run the reload_config command
      4.  
    4. ejabberd will read that file, check its YAML syntax is valid,    check the options are valid and known...
      5.  
    5. If there's any problem in the configuration file,    the reload is aborted and an error message is logged with details,    so you can fix the problem.
      6.  
    6. If the file is right, it detects the changed options,    and applies them immediately (add/remove hosts, add/remove modules, ...)
      7.  
    "},{"location":"admin/configuration/file-format/#legacy-configuration-file","title":"Legacy Configuration File","text":"
    In previous ejabberd version the configuration file should be written in Erlang terms. The format is still supported, but it is highly recommended to convert it to the new YAML format with the convert_to_yaml API command using ejabberdctl.
     
    If you want to specify some options using the old Erlang format, you can set them in an additional cfg file, and include it using the include_config_file option, see Include Additional Files for the option description and a related example in Restrict Execution with AccessCommands.
    "},{"location":"admin/configuration/file-format/#include-additional-files","title":"Include Additional Files","text":"
    The option include_config_file  in a configuration file instructs ejabberd to include other configuration files immediately.
     
    This is a basic example:
     
    include_config_file: /etc/ejabberd/additional.yml\n
     
    In this example, the included file is not allowed to contain a listen option. If such an option is present, the option will not be accepted. The file is in a subdirectory from where the main configuration file is.
     
    include_config_file:\n  ./example.org/additional_not_listen.yml:\n    disallow: [listen]\n
     
    Please notice that options already defined in the main configuration file cannot be redefined in the included configuration files. But you can use host_config and append_host_config as usual (see Virtual Hosting).
     
    In this example, ejabberd.yml defines some ACL for the whole ejabberd server, and later includes another file:
     
    acl:\n  admin:\n    user:\n      - admin@localhost\ninclude_config_file:\n  /etc/ejabberd/acl.yml\n
     
    The file acl.yml can add additional administrators to one of the virtual hosts:
     
    append_host_config:\n  localhost:\n    acl:\n      admin:\n        user:\n          - bob@localhost\n          - jan@localhost\n
    "},{"location":"admin/configuration/file-format/#macros-in-configuration-file","title":"Macros in Configuration File","text":"
    In the ejabberd configuration file, it is possible to define a macro for a value and later use this macro when defining an option.
     
    A macro is defined using the define_macro option.
     
    This example shows the basic usage of a macro:
     
    define_macro:\n  LOG_LEVEL_NUMBER: 5\nloglevel: LOG_LEVEL_NUMBER\n
     
    The resulting option interpreted by ejabberd is: loglevel: 5.
     
    This example shows that values can be any arbitrary YAML value:
     
    define_macro:\n  USERBOB:\n    user:\n      - bob@localhost\nacl:\n  admin: USERBOB\n
     
    The resulting option interpreted by ejabberd is:
     
    acl:\n  admin:\n    user:\n      - bob@localhost\n
     
    This complex example:
     
    define_macro:\n  NUMBER_PORT_C2S: 5222\n  NUMBER_PORT_HTTP: 5280\nlisten:\n  -\n    port: NUMBER_PORT_C2S\n    module: ejabberd_c2s\n  -\n    port: NUMBER_PORT_HTTP\n    module: ejabberd_http\n
     
    produces this result after being interpreted:
     
    listen:\n  -\n    port: 5222\n    module: ejabberd_c2s\n  -\n    port: 5280\n    module: ejabberd_http\n
    "},{"location":"admin/configuration/ldap/","title":"LDAP Configuration","text":""},{"location":"admin/configuration/ldap/#supported-storages","title":"Supported storages","text":"
    The following LDAP servers are tested with ejabberd:
     
       
    •  
      Active Directory (see section\u00a0Active Directory)
       
      •  
    •  
      OpenLDAP
       
      •  
    •  
      CommuniGate Pro
       
      •  
    •  
      Normally any LDAP compatible server should work; inform us about  your success with a not-listed server so that we can list it here.
       
      •  
    "},{"location":"admin/configuration/ldap/#ldap","title":"LDAP","text":"
    ejabberd has built-in LDAP support. You can authenticate users against LDAP server and use LDAP directory as vCard storage.
     
    Usually ejabberd treats LDAP as a read-only storage: it is possible to consult data, but not possible to create accounts or edit vCard that is stored in LDAP. However, it is possible to change passwords if mod_register module is enabled and LDAP server supports RFC 3062.
    "},{"location":"admin/configuration/ldap/#ldap-connection","title":"LDAP Connection","text":"
    Two connections are established to the LDAP server per vhost, one for authentication and other for regular calls.
     
    To configure the LDAP connection there are these top-level options:
     
       
    • ldap_servers
      •  
    • ldap_encrypt
      •  
    • ldap_tls_verify
      •  
    • ldap_tls_cacertfile
      •  
    • ldap_tls_depth
      •  
    • ldap_port
      •  
    • ldap_rootdn
      •  
    • ldap_password
      •  
    • ldap_deref_aliases
      •  
     
    Example:
     
    auth_method: [ldap]\nldap_servers:\n  - ldap1.example.org\nldap_port: 389\nldap_rootdn: \"cn=Manager,dc=domain,dc=org\"\nldap_password: \"**********\"\n
    "},{"location":"admin/configuration/ldap/#ldap-authentication","title":"LDAP Authentication","text":"
    You can authenticate users against an LDAP directory. Note that current LDAP implementation does not support SASL authentication.
     
    To configure LDAP authentication there are these top-level options:
     
       
    • ldap_base
      •  
    • ldap_uids
      •  
    • ldap_filter
      •  
    • ldap_dn_filter
      •  
    "},{"location":"admin/configuration/ldap/#ldap-examples","title":"LDAP Examples","text":""},{"location":"admin/configuration/ldap/#common-example","title":"Common example","text":"
    Let\u2019s say ldap.example.org is the name of our LDAP server. We have users with their passwords in ou=Users,dc=example,dc=org directory. Also we have addressbook, which contains users emails and their additional infos in ou=AddressBook,dc=example,dc=org directory. The connection to the LDAP server is encrypted using TLS, and using the custom port 6123. Corresponding authentication section should looks like this:
     
    ## Authentication method\nauth_method: [ldap]\n## DNS name of our LDAP server\nldap_servers: [ldap.example.org]\n## Bind to LDAP server as \"cn=Manager,dc=example,dc=org\" with password \"secret\"\nldap_rootdn: \"cn=Manager,dc=example,dc=org\"\nldap_password: secret\nldap_encrypt: tls\nldap_port: 6123\n## Define the user's base\nldap_base: \"ou=Users,dc=example,dc=org\"\n## We want to authorize users from 'shadowAccount' object class only\nldap_filter: \"(objectClass=shadowAccount)\"\n
     
    Now we want to use users LDAP-info as their vCards. We have four attributes defined in our LDAP schema: mail \u2014 email address, givenName \u2014 first name, sn \u2014 second name, birthDay \u2014 birthday. Also we want users to search each other. Let\u2019s see how we can set it up:
     
    modules:\n  mod_vcard:\n    db_type: ldap\n    ## We use the same server and port, but want to bind anonymously because\n    ## our LDAP server accepts anonymous requests to\n    ## \"ou=AddressBook,dc=example,dc=org\" subtree.\n    ldap_rootdn: \"\"\n    ldap_password: \"\"\n    ## define the addressbook's base\n    ldap_base: \"ou=AddressBook,dc=example,dc=org\"\n    ## uidattr: user's part of JID is located in the \"mail\" attribute\n    ## uidattr_format: common format for our emails\n    ldap_uids:\n      mail: \"%u@mail.example.org\"\n    ## We have to define empty filter here, because entries in addressbook does not\n    ## belong to shadowAccount object class\n    ldap_filter: \"\"\n    ## Now we want to define vCard pattern\n    ldap_vcard_map:\n     NICKNAME: {\"%u\": []} # just use user's part of JID as their nickname\n     GIVEN: {\"%s\": [givenName]}\n     FAMILY: {\"%s\": [sn]}\n     FN: {\"%s, %s\": [sn, givenName]} # example: \"Smith, John\"\n     EMAIL: {\"%s\": [mail]}\n     BDAY: {\"%s\": [birthDay]}\n    ## Search form\n    ldap_search_fields:\n      User: \"%u\"\n      Name: givenName\n      \"Family Name\": sn\n      Email: mail\n      Birthday: birthDay\n    ## vCard fields to be reported\n    ## Note that JID is always returned with search results\n    ldap_search_reported:\n      \"Full Name\": FN\n      Nickname: NICKNAME\n      Birthday: BDAY\n
     
    Note that mod_vcard with LDAP backend checks for the existence of the user before searching their information in LDAP.
    "},{"location":"admin/configuration/ldap/#active-directory","title":"Active Directory","text":"
    Active Directory is just an LDAP-server with predefined attributes. A sample configuration is shown below:
     
    auth_method: [ldap]\nldap_servers: [office.org]  # List of LDAP servers\nldap_base: \"DC=office,DC=org\" # Search base of LDAP directory\nldap_rootdn: \"CN=Administrator,CN=Users,DC=office,DC=org\" # LDAP manager\nldap_password: \"*******\" # Password to LDAP manager\nldap_uids: [sAMAccountName]\nldap_filter: \"(memberOf=*)\"\n\nmodules:\n  mod_vcard:\n    db_type: ldap\n    ldap_vcard_map:\n      NICKNAME: {\"%u\": []}\n      GIVEN: {\"%s\": [givenName]}\n      MIDDLE: {\"%s\": [initials]}\n      FAMILY: {\"%s\": [sn]}\n      FN: {\"%s\": [displayName]}\n      EMAIL: {\"%s\": [mail]}\n      ORGNAME: {\"%s\": [company]}\n      ORGUNIT: {\"%s\": [department]}\n      CTRY: {\"%s\": [c]}\n      LOCALITY: {\"%s\": [l]}\n      STREET: {\"%s\": [streetAddress]}\n      REGION: {\"%s\": [st]}\n      PCODE: {\"%s\": [postalCode]}\n      TITLE: {\"%s\": [title]}\n      URL: {\"%s\": [wWWHomePage]}\n      DESC: {\"%s\": [description]}\n      TEL: {\"%s\": [telephoneNumber]}\n    ldap_search_fields:\n      User: \"%u\"\n      Name: givenName\n      \"Family Name\": sn\n      Email: mail\n      Company: company\n      Department: department\n      Role: title\n      Description: description\n      Phone: telephoneNumber\n    ldap_search_reported:\n      \"Full Name\": FN\n      Nickname: NICKNAME\n      Email: EMAIL\n
    "},{"location":"admin/configuration/ldap/#shared-roster-in-ldap","title":"Shared Roster in LDAP","text":"
    Since mod_shared_roster_ldap has a few complex options, some of them are documented with more detail here:
    "},{"location":"admin/configuration/ldap/#filters","title":"Filters","text":"
    ldap_ufilter:   \u201cUser Filter\u201d \u2013 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. If  unspecified, defaults to the top-level parameter of the same name.  If that one also is unspecified, then the filter is assembled from  values of other parameters as follows ([ldap_SOMETHING] is used to  mean \u201cthe value of the configuration parameter  ldap_SOMETHING\u201d):
     
    (&(&([ldap_memberattr]=[ldap_memberattr_format])([ldap_groupattr]=%g))[ldap_filter])\n
     
    Subsequently %u and %g are replaced with a *. This means that given the defaults, the filter sent to the LDAP server would be (&(memberUid=*)(cn=*)). If however the ldap_memberattr_format is something like uid=%u,ou=People,o=org, then the filter will be (&(memberUid=uid=*,ou=People,o=org)(cn=*)).
     
    ldap_filter:   Additional filter which is AND-ed together with User  Filter and Group Filter. If unspecified,  defaults to the top-level parameter of the same name. If that one is  also unspecified, then no additional filter is merged with the other  filters.
     
    Note that you will probably need to manually define the User and Group Filter (since the auto-assembled ones will not work) if:
     
       
    •  
      your ldap_memberattr_format is anything other than a  simple %u,
       
      •  
    •  
      and the attribute specified with ldap_memberattr does not support substring matches.
       
      •  
     
    An example where it is the case is OpenLDAP and (unique)MemberName attribute from the groupOf(Unique)Names objectClass. A symptom of this problem is that you will see messages such as the following in your slapd.log:
     
    get_filter: unknown filter type=130\nfilter=\"(&(?=undefined)(?=undefined)(something=else))\"\n
    "},{"location":"admin/configuration/ldap/#control-parameters","title":"Control parameters","text":"
    These parameters control the behaviour of the module.
     
    ldap_memberattr_format_re:   A regex for extracting user ID from the value of the attribute named  by ldap_memberattr.
     
    An example value \u201cCN=(\\\\w*),(OU=.*,)*DC=company,DC=com\u201d works for user IDs such as the following:
     
       
    • CN=Romeo,OU=Montague,DC=company,DC=com
      •  
    • CN=Abram,OU=Servants,OU=Montague,DC=company,DC=com
      •  
    • CN=Juliet,OU=Capulet,DC=company,DC=com
      •  
    • CN=Peter,OU=Servants,OU=Capulet,DC=company,DC=com
      •  
     
    In case:
     
       
    • the option is unset,
      •  
    • or the re module in unavailable in the current Erlang environment,
      •  
    • or the regular expression does not compile,
      •  
     
    then instead of a regular expression, a simple format specified by ldap_memberattr_format is used. Also, in the last two cases an error message is logged during the module initialization.
     
    Also, note that in all cases ldap_memberattr_format (and *not* the regex version) is used for constructing the default \u201cUser/Group Filter\u201d \u2014 see section\u00a0Filters.
    "},{"location":"admin/configuration/ldap/#retrieving-the-roster","title":"Retrieving the roster","text":"
    When the module is called to retrieve the shared roster for a user, the following algorithm is used:
     
       
    1.  
      [step:rfilter] A list of names of groups to display is created: the Roster Filter is run against the base DN, retrieving the values of the attribute named by ldap_groupattr.
       
      2.  
    2.  
      Unless the group cache is fresh (see the ldap_group_cache_validity option), it is refreshed:
       
         
      1.  
        Information for all groups is retrieved using a single query: the Group Filter is run against the Base DN, retrieving the values of attributes named by ldap_groupattr (group ID), ldap_groupdesc (group \u201cDisplay Name\u201d) and ldap_memberattr (IDs of group members).
         
        2.  
      2.  
        group \u201cDisplay Name\u201d, read from the attribute named by ldap_groupdesc, is stored in the cache for the   given group
         
        3.  
      3.  
        the following processing takes place for each retrieved value of attribute named by ldap_memberattr:
         
           
        1.  
          the user ID part of it is extracted using ldap_memberattr_format(_re),
           
          2.  
        2.  
          then (unless ldap_auth_check is set to off) for each found user ID, the module checks (using the ejabberd authentication subsystem) whether such user exists in the given virtual host. It is skipped if the check is enabled and fails.    This step is here for historical reasons. If you have a tidy DIT and properly defined \u201cRoster Filter\u201d and \u201cGroup Filter\u201d, it is safe to disable it by setting ldap_auth_check to off \u2014 it will speed up the roster retrieval.
           
          3.  
        3.  
          the user ID is stored in the list of members in the cache for the given group.
           
          4.  
         
        4.  
       
      3.  
    3.  
      For each item (group name) in the list of groups retrieved in step\u00a0[step:rfilter]:
       
         
      1.  
        the display name of a shared roster group is retrieved from the group cache
         
        2.  
      2.  
        for each IDs of users which belong to the group, retrieved from the group cache:
         
           
        1.  
          the ID is skipped if it\u2019s the same as the one for which we are retrieving the roster. This is so that the user does not have himself in the roster.
           
          2.  
        2.  
          the display name of a shared roster user is retrieved:
           
             
          1.  
            first, unless the user name cache is fresh (see the ldap_user_cache_validity option), it is refreshed by running the User Filter, against the Base DN, retrieving the values of attributes named by ldap_useruid and ldap_userdesc.
             
            2.  
          2.  
            then, the display name for the given user ID is retrieved from the user name cache.
             
            3.  
           
          3.  
         
        3.  
       
      4.  
    "},{"location":"admin/configuration/ldap/#multi-domain","title":"Multi-Domain","text":"
    By default, the module option ldap_userjidattr is set to the empty string, in that case the JID of the user's contact is formed by compounding UID of the contact @ Host of the user owning the roster.
     
    When the option ldap_userjidattr is set to something like \"mail\", then it uses that field to determine the JID of the contact. This is useful if the ldap mail attribute contains the JID of the accounts.
     
    Basically, it allows us to define a groupOfNames (e.g. xmppRosterGroup) and list any users, anywhere in the ldap directory by specifying the attribute defining the JID of the members.
     
    This allows hosts/domains other than that of the roster owner. It is also more flexible, since the LDAP manager can specify the JID of the users without any assumptions being made. The only down side is that there must be an LDAP attribute (field) filled in for all Jabber/XMPP users.
     
    Below is a sample, a relevant LDAP entry, and ejabberd's module configuration:
     
    cn=Example Org Roster,ou=groups,o=Example Organisation,dc=acme,dc=com\nobjectClass: groupOfNames\nobjectClass: xmppRosterGroup\nobjectClass: top\nxmppRosterStatus: active\nmember:\ndescription: Roster group for Example Org\ncn: Example Org Roster\nuniqueMember: uid=john,ou=people,o=Example Organisation,dc=acme,dc=com\nuniqueMember: uid=pierre,ou=people,o=Example Organisation,dc=acme,dc=com\nuniqueMember: uid=jane,ou=people,o=Example Organisation,dc=acme,dc=com\n\nuid=john,ou=people,o=Example Organisation,dc=acme,dc=com\nobjectClass: top\nobjectClass: person\nobjectClass: organizationalPerson\nobjectClass: inetOrgPerson\nobjectClass: mailUser\nobjectClass: sipRoutingObject\nuid: john\ngivenName: John\nsn: Doe\ncn: John Doe\ndisplayName: John Doe\naccountStatus: active\nuserPassword: secretpass\nIMAPURL: imap://imap.example.net:143\nmailHost: smtp.example.net\nmail: john@example.net\nsipLocalAddress: john@example.net\n
     
    Below is the sample ejabberd.yml module configuration to match:
     
    mod_shared_roster_ldap:\n  ldap_servers:\n    - \"ldap.acme.com\"\n  ldap_encrypt: tls\n  ldap_port: 636\n  ldap_rootdn: \"cn=Manager,dc=acme,dc=com\"\n  ldap_password: \"supersecretpass\"\n  ldap_base: \"dc=acme,dc=com\"\n  ldap_filter: \"(objectClass=*)\"\n  ldap_rfilter: \"(&(objectClass=xmppRosterGroup)(xmppRosterStatus=active))\"\n  ldap_gfilter: \"(&(objectClass=xmppRosterGroup)(xmppRosterStatus=active)(cn=%g))\"\n  ldap_groupattr: \"cn\"\n  ldap_groupdesc: \"cn\"\n  ldap_memberattr: \"uniqueMember\"\n  ldap_memberattr_format_re: \"uid=([a-z.]*),(ou=.*,)*(o=.*,)*dc=acme,dc=com\"\n  ldap_useruid: \"uid\"\n  ldap_userdesc: \"cn\"\n   ldap_userjidattr: \"mail\"\n   ldap_auth_check: false\n   ldap_user_cache_validity: 86400\n   ldap_group_cache_validity: 86400\n
    "},{"location":"admin/configuration/ldap/#configuration-examples","title":"Configuration examples","text":"
    Since there are many possible DIT layouts, it will probably be easiest to understand how to configure the module by looking at an example for a given DIT (or one resembling it).
    "},{"location":"admin/configuration/ldap/#flat-dit","title":"Flat DIT","text":"
    This seems to be the kind of DIT for which this module was initially designed. Basically there are just user objects, and group membership is stored in an attribute individually for each user. For example in a layout like this, it's stored in the ou attribute:
     
     
    Such layout has a few downsides, including:
     
       
    •  
      information duplication \u2013 the group name is repeated in every member  object
       
      •  
    •  
      difficult group management \u2013 information about group members is not  centralized, but distributed between member objects
       
      •  
    •  
      inefficiency \u2013 the list of unique group names has to be computed by  iterating over all users
       
      •  
     
    This however seems to be a common DIT layout, so the module keeps supporting it. You can use the following configuration\u2026
     
    modules:\n  mod_shared_roster_ldap:\n    ldap_base: \"ou=flat,dc=nodomain\"\n    ldap_rfilter: \"(objectClass=inetOrgPerson)\"\n    ldap_groupattr: ou\n    ldap_memberattr: cn\n    ldap_filter: \"(objectClass=inetOrgPerson)\"\n    ldap_userdesc: displayName\n
     
    \u2026to be provided with a roster upon connecting as user czesio, as shown in this figure:
     
    "},{"location":"admin/configuration/ldap/#deep-dit","title":"Deep DIT","text":"
    This type of DIT contains distinctly typed objects for users and groups \u2013 see the next figure. They are shown separated into different subtrees, but it\u2019s not a requirement.
     
     
    If you use the following example module configuration with it:
     
    modules:\n  mod_shared_roster_ldap:\n    ldap_base: \"ou=deep,dc=nodomain\"\n    ldap_rfilter: \"(objectClass=groupOfUniqueNames)\"\n    ldap_filter: \"\"\n    ldap_gfilter: \"(&(objectClass=groupOfUniqueNames)(cn=%g))\"\n    ldap_groupdesc: description\n    ldap_memberattr: uniqueMember\n    ldap_memberattr_format: \"cn=%u,ou=people,ou=deep,dc=nodomain\"\n    ldap_ufilter: \"(&(objectClass=inetOrgPerson)(cn=%u))\"\n    ldap_userdesc: displayName\n
     
    \u2026and connect as user czesio, then ejabberd will provide you with the roster shown in this figure:
     
    "},{"location":"admin/configuration/ldap/#vcard-in-ldap","title":"vCard in LDAP","text":"
    Since LDAP may be complex to configure in mod_vcard, this section provides more details.
     
    ejabberd can map LDAP attributes to vCard fields. This feature is enabled when the mod_vcard module is configured with db_type: ldap. Notice that it does not depend on the authentication method (see LDAP Authentication).
     
    Usually ejabberd treats LDAP as a read-only storage: it is possible to consult data, but not possible to create accounts or edit vCard that is stored in LDAP. However, it is possible to change passwords if mod_register module is enabled and LDAP server supports RFC 3062.
     
    This feature has its own optional parameters. The first group of parameters has the same meaning as the top-level LDAP parameters to set the authentication method: ldap_servers, ldap_port, ldap_rootdn, ldap_password, ldap_base, ldap_uids, ldap_deref_aliases and ldap_filter. See section LDAP Authentication for detailed information about these options. If one of these options is not set, ejabberd will look for the top-level option with the same name.
     
    Examples:
     
       
    •  
      Let\u2019s say ldap.example.org is the name of our LDAP server. We have  users with their passwords in ou=Users,dc=example,dc=org  directory. Also we have addressbook, which contains users emails and  their additional infos in ou=AddressBook,dc=example,dc=org  directory. Corresponding authentication section should looks like  this:
       
      ## authentication method\nauth_method: ldap\n## DNS name of our LDAP server\nldap_servers:\n  - ldap.example.org\n## We want to authorize users from 'shadowAccount' object class only\nldap_filter: \"(objectClass=shadowAccount)\"\n
       
      •  
    •  
      Now we want to use users LDAP-info as their vCards. We have four attributes defined in our LDAP schema: mail \u2014 email address, givenName \u2014 first name, sn \u2014 second name, birthDay \u2014 birthday. Also we want users to search each other. Let\u2019s see how we can set it up:
       
      modules:\n  mod_vcard:\n    db_type: ldap\n    ## We use the same server and port, but want to bind anonymously because\n    ## our LDAP server accepts anonymous requests to\n    ## \"ou=AddressBook,dc=example,dc=org\" subtree.\n    ldap_rootdn: \"\"\n    ldap_password: \"\"\n    ## define the addressbook's base\n    ldap_base: \"ou=AddressBook,dc=example,dc=org\"\n    ## uidattr: user's part of JID is located in the \"mail\" attribute\n    ## uidattr_format: common format for our emails\n    ldap_uids: {\"mail\": \"%u@mail.example.org\"}\n    ## Now we want to define vCard pattern\n    ldap_vcard_map:\n      NICKNAME: {\"%u\": []} # just use user's part of JID as their nickname\n      FIRST: {\"%s\": [givenName]}\n      LAST: {\"%s\": [sn]}\n      FN: {\"%s, %s\": [sn, givenName]} # example: \"Smith, John\"\n      EMAIL: {\"%s\": [mail]}\n      BDAY: {\"%s\": [birthDay]}\n    ## Search form\n    ldap_search_fields:\n      User: \"%u\"\n      Name: givenName\n      \"Family Name\": sn\n      Email: mail\n      Birthday: birthDay\n    ## vCard fields to be reported\n    ## Note that JID is always returned with search results\n    ldap_search_reported:\n      \"Full Name\": FN\n      Nickname: NICKNAME\n      Birthday: BDAY\n
       
      Note that mod_vcard with LDAP backend checks an existence of the user before searching their info in LDAP.
       
      •  
    •  
      ldap_vcard_map example:
       
      ldap_vcard_map:\n  NICKNAME: {\"%u\": []} # just use user's part of JID as their nickname\n  FN: {\"%s\": [displayName]}\n  CTRY: {Russia: []}\n  EMAIL: {\"%u@%d\": []}\n  DESC: {\"%s\\n%s\": [title, description]}\n
       
      •  
    •  
      ldap_search_fields example:
       
      ldap_search_fields:\n  User: uid\n  \"Full Name\": displayName\n  Email: mail\n
       
      •  
    •  
      ldap_search_reported example:
       
      ldap_search_reported:\n  \"Full Name\": FN\n  Email: EMAIL\n  Birthday: BDAY\n  Nickname: NICKNAME\n
       
      •  
    "},{"location":"admin/configuration/listen-options/","title":"Listen Options","text":"
    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.
     
    This is a detailed description of each option allowed by the listening modules:
    "},{"location":"admin/configuration/listen-options/#access","title":"access","text":"
    AccessName
     
    This option defines access to the port. The default value is all.
    "},{"location":"admin/configuration/listen-options/#backlog","title":"backlog","text":"
    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.
    "},{"location":"admin/configuration/listen-options/#cafile","title":"cafile","text":"
    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 top-level option. To set a file for all server connections, you can use the s2s_cafile top-level option or the ca_file top-level option.
     
    Please note: if this option is set in ejabberd_c2s or ejabberd_s2s_in and the corresponding top-level option is also set (c2s_cafile, s2s_cafile), then the top-level option is used, not this one.
    "},{"location":"admin/configuration/listen-options/#certfile","title":"certfile","text":"
    Path
     
    Path to the certificate file. Only makes sense when the tls options is set. If this option is not set, you should set the certfiles top-level option or configure ACME.
    "},{"location":"admin/configuration/listen-options/#check_from","title":"check_from","text":"
    true | false
     
    This option can be used with ejabberd_service only.  XEP-0114 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 \u2019from\u2019 attribute. Only use  this option if you are completely sure about it. The default value  is true, to be compliant with  XEP-0114.
    "},{"location":"admin/configuration/listen-options/#ciphers","title":"ciphers","text":"
    Ciphers
     
    OpenSSL ciphers list in the same format accepted by  \u2018openssl ciphers\u2019 command.
     
    Please note: if this option is set in ejabberd_c2s or ejabberd_s2s_in and the corresponding top-level option is also set (c2s_ciphers, s2s_ciphers), then the top-level option is used, not this one.
    "},{"location":"admin/configuration/listen-options/#custom_headers","title":"custom_headers","text":"
    {Name: Value}
     
    Specify additional HTTP headers to be included in all HTTP responses. Default value is: []
    "},{"location":"admin/configuration/listen-options/#default_host","title":"default_host","text":"
    undefined | HostName
     
    If the HTTP request received by ejabberd contains the HTTP header  Host with an ambiguous virtual host that doesn\u2019t match any one  defined in ejabberd (see         Host Names),         then this configured HostName  is set as the request Host. The default value of this option is:  undefined.
    "},{"location":"admin/configuration/listen-options/#dhfile","title":"dhfile","text":"
    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 or ejabberd_s2s_in and the corresponding top-level option is also set (c2s_dhfile, s2s_dhfile), then the top-level option is used, not this one.
    "},{"location":"admin/configuration/listen-options/#global_routes","title":"global_routes","text":"
    true | false
     
    This option emulates legacy behaviour which registers all routes defined in 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.
    "},{"location":"admin/configuration/listen-options/#hosts","title":"hosts","text":"
    {Hostname: [HostOption, ...]}
     
    The external Jabber component that connects to this 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).
    "},{"location":"admin/configuration/listen-options/#max_fsm_queue","title":"max_fsm_queue","text":"
    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         and ejabberd_c2s         listeners, or also globally for         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  \u2019undefined\u2019. Default value: \u201910000\u2019.
    "},{"location":"admin/configuration/listen-options/#max_payload_size","title":"max_payload_size","text":"
    Size
     
    Specify the maximum payload size in bytes. It can be either an integer or the word infinity. The default value is infinity.
    "},{"location":"admin/configuration/listen-options/#max_stanza_size","title":"max_stanza_size","text":"
    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.
    "},{"location":"admin/configuration/listen-options/#password","title":"password","text":"
    Secret
     
    Specify the password to verify an external component that connects to the port.
    "},{"location":"admin/configuration/listen-options/#port","title":"port","text":"
    Port number, or unix domain socket path
     
     improved in 20.07
     
    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.
    "},{"location":"admin/configuration/listen-options/#protocol_options","title":"protocol_options","text":"
    ProtocolOpts
     
    List of general options relating to SSL/TLS. These map to  OpenSSL\u2019s set_options().  The default entry is: \"no_sslv3|cipher_server_preference|no_compression\"
     
    Please note: if this option is set in ejabberd_c2s or ejabberd_s2s_in and the corresponding top-level option is also set (c2s_protocol_options, s2s_protocol_options), then the top-level option is used, not this one.
    "},{"location":"admin/configuration/listen-options/#request_handlers","title":"request_handlers","text":"
    {Path: Module}
     
    To define one or several handlers that will serve HTTP requests in 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:
     
    request_handlers:\n  /a/b: mod_foo\n  /bosh: mod_bosh\n  /mqtt: mod_mqtt\n
    "},{"location":"admin/configuration/listen-options/#send_timeout","title":"send_timeout","text":"
    Integer | infinity
     
     new in 21.07
     
    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
    "},{"location":"admin/configuration/listen-options/#shaper","title":"shaper","text":"
    none | ShaperName
     
    This option defines a shaper for the port (see section Shapers).  The default value is none.
    "},{"location":"admin/configuration/listen-options/#shaper_rule","title":"shaper_rule","text":"
    none | ShaperRule
     
    This option defines a shaper rule for ejabberd_service (see section Shapers). The recommended value is fast.
    "},{"location":"admin/configuration/listen-options/#starttls","title":"starttls","text":"
    true | false
     
    This option specifies that STARTTLS encryption is available on connections to the port. You should also set the certfiles top-level option or configure ACME.
     
    This option gets implicitly enabled when enabling starttls_required or tls_verify.
    "},{"location":"admin/configuration/listen-options/#starttls_required","title":"starttls_required","text":"
    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 top-level option or configure ACME.
     
    Enabling this option implicitly enables also the starttls option.
    "},{"location":"admin/configuration/listen-options/#tag","title":"tag","text":"
    String
     
    Allow specifying a tag in a listen section and later use it to have a special api_permissions just for it.
     
    For example:
     
    listen:\n  -\n    port: 4000\n    module: ejabberd_http\n    tag: \"magic_listener\"\n\napi_permissions:\n  \"magic_access\":\n    from:\n      - tag: \"magic_listener\"\n    who: all\n    what: \"*\"\n
     
    The default value is the empty string: \"\".
    "},{"location":"admin/configuration/listen-options/#timeout","title":"timeout","text":"
    Integer
     
    Timeout of the connections, expressed in milliseconds. Default: 5000
    "},{"location":"admin/configuration/listen-options/#tls","title":"tls","text":"
    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,  which can be enabled in ejabberd with the option         starttls.
     
    If this option is set, you should also set the         certfiles top-level         option or configure ACME.
     
    The option tls can also be used in         ejabberd_http         to support HTTPS.
     
    Enabling this option implicitly disables the starttls option.
    "},{"location":"admin/configuration/listen-options/#tls_compression","title":"tls_compression","text":"
    true | false
     
    Whether to enable or disable TLS compression. The default value is  false.
     
    Please note: if this option is set in ejabberd_c2s or ejabberd_s2s_in and the corresponding top-level option is also set (c2s_tls_compression, s2s_tls_compression), then the top-level option is used, not this one.
    "},{"location":"admin/configuration/listen-options/#tls_verify","title":"tls_verify","text":"
    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. 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 option.
    "},{"location":"admin/configuration/listen-options/#use_proxy_protocol","title":"use_proxy_protocol","text":"
    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.     The default value of this option isfalse.
    "},{"location":"admin/configuration/listen-options/#zlib","title":"zlib","text":"
    true | false
     
    This option specifies that Zlib stream compression (as defined in  XEP-0138) is available  on connections to the port.
    "},{"location":"admin/configuration/listen/","title":"Listen Modules","text":"
    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.
    "},{"location":"admin/configuration/listen/#listen-options","title":"Listen Options","text":"
    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:
     
    listen:\n  -\n    port: 5222\n    ip: 127.0.0.1\n    module: ejabberd_c2s\n    starttls: true\n  -\n    port: 5269\n    transport: tcp\n    module: ejabberd_s2s_in\n
    "},{"location":"admin/configuration/listen/#ejabberd_c2s","title":"ejabberd_c2s","text":"
    Handles c2s connections.
     
    General listen options supported: access, cafile, ciphers, dhfile, max_fsm_queue, max_stanza_size, protocol_options, send_timeout, shaper, starttls, starttls_required, tls, tls_compression, tls_verify, zlib.
    "},{"location":"admin/configuration/listen/#ejabberd_s2s_in","title":"ejabberd_s2s_in","text":"
    Handles incoming s2s connections.
     
    General listen options supported: cafile, ciphers, dhfile, max_fsm_queue, max_stanza_size, protocol_options, send_timeout, shaper, tls, tls_compression.
    "},{"location":"admin/configuration/listen/#ejabberd_service","title":"ejabberd_service","text":"
    Interacts with an external component as defined in XEP-0114: Jabber Component Protocol.
     
    General listen options supported: access, cafile, certfile, check_from, ciphers, dhfile, global_routes, hosts, max_fsm_queue, max_stanza_size, password, protocol_options, send_timeout, shaper, shaper_rule, tls, tls_compression.
    "},{"location":"admin/configuration/listen/#mod_mqtt","title":"mod_mqtt","text":"
    Support for MQTT requires configuring mod_mqtt both in the listen and the modules sections. Check the mod_mqtt module options, and the MQTT Support section.
     
    General listen options supported: backlog, max_fsm_queue, max_payload_size, send_timeout, tls, tls_verify.
    "},{"location":"admin/configuration/listen/#ejabberd_stun","title":"ejabberd_stun","text":"
    ejabberd can act as a stand-alone STUN/TURN server, and this module handles STUN/TURN requests as defined in (RFC 5389/RFC 5766. In that role ejabberd helps clients with ICE (RFC 5245 or Jingle ICE (XEP-0176 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, send_timeout, shaper, 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
       
      8b12c67 (Major reorganization of the Listen page)
       
      The IPv4 address advertised by your TURN server. The address should not be NAT\u2019ed 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\u2019ed 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):
     
    listen:\n  -\n    port: 3478\n    transport: udp\n    module: ejabberd_stun\n  -\n    port: 3478\n    module: ejabberd_stun\n  -\n    port: 5349\n    module: ejabberd_stun\n    certfile: /etc/ejabberd/server.pem\n
     
    Example configuration with TURN functionality. Note that STUN is always enabled if TURN is enabled. Here, only UDP section is shown:
     
    listen:\n  -\n    port: 3478\n    transport: udp\n    use_turn: true\n    turn_ipv4_address: 10.20.30.1\n    module: ejabberd_stun\n
     
    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 of RFC 5389 and section Creating an Allocation of RFC 5766 for details.
     
    Example DNS SRV configuration for STUN only:
     
    _stun._udp   IN SRV  0 0 3478 stun.example.com.\n_stun._tcp   IN SRV  0 0 3478 stun.example.com.\n_stuns._tcp  IN SRV  0 0 5349 stun.example.com.\n
     
    And you should also add these in the case if TURN is enabled:
     
    _turn._udp   IN SRV  0 0 3478 turn.example.com.\n_turn._tcp   IN SRV  0 0 3478 turn.example.com.\n_turns._tcp  IN SRV  0 0 5349 turn.example.com.\n
    "},{"location":"admin/configuration/listen/#ejabberd_sip","title":"ejabberd_sip","text":"
    ejabberd has built-in support to handle SIP requests as defined in RFC 3261.
     
    To activate this feature, add the ejabberd_sip listen module, enable 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 section. If option tls is specified, option certfile must be specified as well, otherwise incoming TLS connections would fail.
     
    General listen options supported: certfile, send_timeout, tls.
     
    Example configuration with standard ports (as per RFC 3261):
     
    listen:\n  -\n    port: 5060\n    transport: udp\n    module: ejabberd_sip\n  -\n    port: 5060\n    module: ejabberd_sip\n  -\n    port: 5061\n    module: ejabberd_sip\n    tls: true\n    certfile: /etc/ejabberd/server.pem\n
     
    Note that there is no StartTLS support in SIP and SNI 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 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\u2019s not fatal, however, highly recommended.
     
    Example configuration of NAPTR records:
     
    example.com IN NAPTR 10  0 \"s\" \"SIPS+D2T\" \"\" _sips._tcp.example.com.\nexample.com IN NAPTR 20  0 \"s\" \"SIP+D2T\" \"\" _sip._tcp.example.com.\nexample.com IN NAPTR 30  0 \"s\" \"SIP+D2U\" \"\" _sip._udp.example.com.\n
     
    Example configuration of SRV records with standard ports (as per RFC 3261:
     
    _sip._udp   IN SRV  0 0 5060 sip.example.com.\n_sip._tcp   IN SRV  0 0 5060 sip.example.com.\n_sips._tcp  IN SRV  0 0 5061 sip.example.com.\n
     
    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.
    "},{"location":"admin/configuration/listen/#ejabberd_http","title":"ejabberd_http","text":"
    Handles incoming HTTP connections.
     
    With the proper request handlers configured, this serves HTTP services like ACME, API, BOSH, CAPTCHA, Fileserver, OAuth, RegisterWeb, Upload, WebAdmin, WebSocket, XML-RPC.
     
    Options: cafile, ciphers, custom_headers, default_host, dhfile, protocol_options, request_handlers, send_timeout, tag, tls, tls_compression, and the trusted_proxies top-level option.
    "},{"location":"admin/configuration/listen/#ejabberd_http_ws","title":"ejabberd_http_ws","text":"
    This module enables XMPP communication over WebSocket connection as described in RFC 7395.
    "},{"location":"admin/configuration/listen/#websocket-config","title":"WebSocket Config","text":"
    To enable WebSocket, simply add a handler to the request_handlers section of an ejabberd_http listener:
     
    listen:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /xmpp: ejabberd_http_ws\n
     
    This module can be configured using those top-level options:
     
       
    • websocket_origin
      •  
    • websocket_ping_interval
      •  
    • websocket_timeout
      •  
    "},{"location":"admin/configuration/listen/#websocket-discovery","title":"WebSocket Discovery","text":"
    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). One easy way to provide that file is using mod_host_meta.
    "},{"location":"admin/configuration/listen/#testing-websocket","title":"Testing WebSocket","text":"
    A test client can be found on Github: WebSocket test client
     
    There is an example configuration for WebSocket and Converse.js in the ejabberd 21.12 release notes.
    "},{"location":"admin/configuration/listen/#ejabberd_xmlrpc","title":"ejabberd_xmlrpc","text":"
    Handles XML-RPC requests to execute ejabberd commands. It is configured as a request handler in ejabberd_http.
     
    This is the minimum configuration required to enable the feature:
     
    listen:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /xmlrpc: ejabberd_xmlrpc\n\napi_permissions:\n  \"public commands\":\n    who:\n      ip: 127.0.0.1/8\n    what:\n      - connected_users_number\n
     
    Example Python3 script:
     
    import xmlrpc.client\nserver = xmlrpc.client.ServerProxy(\"http://127.0.0.1:5280/xmlrpc/\");\nprint(server.connected_users_number())\n
     
    By default there is no restriction to who can execute what commands, so it is strongly recommended that you configure restrictions using API Permissions.
     
    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):
     
    listen:\n  -\n    port: 5280\n    ip: \"::\"\n    module: ejabberd_http\n    request_handlers:\n      /xmlrpc: ejabberd_xmlrpc\n\napi_permissions:\n  \"some XMLRPC commands\":\n    from: ejabberd_xmlrpc\n    who:\n      - ip: 127.0.0.1\n      - user: user1@localhost\n    what:\n      - registered_users\n      - connected_users_number\n
     
    Example Python3 script for that restricted configuration:
     
    import xmlrpc.client\nserver = xmlrpc.client.ServerProxy(\"http://127.0.0.1:5280/xmlrpc/\");\n\nparams = {}\nparams['host'] = 'localhost'\n\nauth = {'user': 'user1',\n        'server': 'localhost',\n        'password': 'mypass11',\n        'admin': True}\n\ndef calling(command, data):\n    fn = getattr(server, command)\n    return fn(auth, data)\n\nprint(calling('registered_users', params))\n
     
    Please notice, when using the old Python2, replace the two first lines with:
     
    import xmlrpclib\nserver = xmlrpclib.Server(\"http://127.0.0.1:5280/xmlrpc/\");\n
     
    It's possible to use OAuth for authentication instead of plain password, see OAuth Support.
     
    In ejabberd 20.03 and older, it was possible to configure ejabberd_xmlrpc as a listener, see the old document for reference and example configuration: Listening Module.
     
    Just for reference, there's also the old ejabberd_xmlrpc documentation with example clients in other languages.
    "},{"location":"admin/configuration/listen/#examples","title":"Examples","text":"
    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. The socket only listens connections to the IP address 127.0.0.1.
       
      •  
     
    hosts:\n  - example.com\n  - example.org\n  - example.net\n\ncertfiles:\n  - /etc/ejabberd/server.pem\n  - /etc/ejabberd/example_com.pem\n\nlisten:\n  -\n    port: 5222\n    module: ejabberd_c2s\n    access: c2s\n    shaper: c2s_shaper\n    starttls: true\n    max_stanza_size: 65536\n  -\n    port: 5223\n    module: ejabberd_c2s\n    access: c2s\n    shaper: c2s_shaper\n    tls: true\n    max_stanza_size: 65536\n  -\n    port: 5269\n    ip: \"::\"\n    module: ejabberd_s2s_in\n    shaper: s2s_shaper\n    max_stanza_size: 131072\n  -\n    port: 3478\n    transport: udp\n    module: ejabberd_stun\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /bosh: mod_bosh\n  -\n    port: 5281\n    ip: 127.0.0.1\n    module: ejabberd_http\n    tls: true\n    request_handlers:\n      /admin: ejabberd_web_admin\n      /bosh: mod_bosh\n\ns2s_use_starttls: optional\noutgoing_s2s_families:\n  - ipv4\n  - ipv6\noutgoing_s2s_timeout: 10000\ntrusted_proxies: [127.0.0.1, 192.168.1.11]\n
     
    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 \u2018bad\u2019.
       
      •  
    •  
      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:  \u201cjabber.example.org\u201d and \u201cexample.com\u201d.
       
      •  
    •  
      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\u00a0Managing: 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 aim.example.org is connected to port 5233 on localhost IP  addresses (127.0.0.1 and ::1) with password \u2018aimsecret\u2019.
       
      •  
    •  
      The ICQ transport JIT (icq.example.org and sms.example.org) is  connected to port 5234 with password \u2018jitsecret\u2019.
       
      •  
    •  
      The MSN transport msn.example.org is connected to port 5235 with password  \u2018msnsecret\u2019.
       
      •  
    •  
      The Yahoo! transport yahoo.example.org is connected to port 5236 with password  \u2018yahoosecret\u2019.
       
      •  
    •  
      The  Gadu-Gadu transport gg.example.org is connected to port 5237 with password  \u2018ggsecret\u2019.
       
      •  
    •  
      The Jabber Mail Component jmc.example.org is connected to port 5238 with password  \u2018jmcsecret\u2019.
       
      •  
    •  
      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.
       
      •  
     
    acl:\n  blocked:\n    user: bad\n  trusted_servers:\n    server:\n      - example.com\n      - jabber.example.org\n  xmlrpc_bot:\n    user:\n      - xmlrpc-robot@example.org\nshaper:\n  normal: 1000\nshaper_rules:\n  c2s_shaper:\n    - none: admin\n    - normal\naccess_rules:\n  c2s:\n    - deny: blocked\n    - allow\n  xmlrpc_access:\n    - allow: xmlrpc_bot\n  s2s:\n    - allow: trusted_servers\ncertfiles:\n  - /path/to/ssl.pem\ns2s_access: s2s\ns2s_use_starttls: required_trusted\nlisten:\n  -\n    port: 5222\n    module: ejabberd_c2s\n    shaper: c2s_shaper\n    access: c2s\n  -\n    ip: 192.168.0.1\n    port: 5223\n    module: ejabberd_c2s\n    tls: true\n    access: c2s\n  -\n    ip: \"FDCA:8AB6:A243:75EF::1\"\n    port: 5223\n    module: ejabberd_c2s\n    tls: true\n    access: c2s\n  -\n    port: 5269\n    module: ejabberd_s2s_in\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /admin: ejabberd_web_admin\n      /bosh: mod_bosh\n      /mqtt: mod_mqtt\n  -\n    port: 4560\n    module: ejabberd_xmlrpc\n    access_commands: {}\n  -\n    ip: 127.0.0.1\n    port: 5233\n    module: ejabberd_service\n    hosts:\n      aim.example.org:\n        password: aimsecret\n  -\n    ip: \"::1\"\n    port: 5233\n    module: ejabberd_service\n    hosts:\n      aim.example.org:\n        password: aimsecret\n  -\n    port: 5234\n    module: ejabberd_service\n    hosts:\n      icq.example.org:\n        password: jitsecret\n      sms.example.org:\n        password: jitsecret\n  -\n    port: 5235\n    module: ejabberd_service\n    hosts:\n      msn.example.org:\n        password: msnsecret\n  -\n    port: 5236\n    module: ejabberd_service\n    password: yahoosecret\n  -\n    port: 5237\n    module: ejabberd_service\n    hosts:\n      gg.example.org:\n        password: ggsecret\n  -\n    port: 5238\n    module: ejabberd_service\n    hosts:\n      jmc.example.org:\n        password: jmcsecret\n  -\n    port: 5239\n    module: ejabberd_service\n    check_from: false\n    hosts:\n      custom.example.org:\n        password: customsecret\n
     
    Note, that for services based in jabberd14 or WPJabber you have to make the transports log and do XDB by themselves:
     
    <!--\n   You have to add elogger and rlogger entries here when using ejabberd.\n   In this case the transport will do the logging.\n-->\n\n<log id='logger'>\n  <host/>\n  <logtype/>\n  <format>%d: [%t] (%h): %s</format>\n  <file>/var/log/jabber/service.log</file>\n</log>\n\n<!--\n   Some XMPP server implementations do not provide\n   XDB services (for example, jabberd2 and ejabberd).\n   xdb_file.so is loaded in to handle all XDB requests.\n-->\n\n<xdb id=\"xdb\">\n  <host/>\n  <load>\n    <!-- this is a lib of wpjabber or jabberd14 -->\n    <xdb_file>/usr/lib/jabber/xdb_file.so</xdb_file>\n    </load>\n  <xdb_file xmlns=\"jabber:config:xdb_file\">\n    <spool><jabberd:cmdline flag='s'>/var/spool/jabber</jabberd:cmdline></spool>\n  </xdb_file>\n</xdb>\n
    "},{"location":"admin/configuration/modules/","title":"Modules Options","text":"
    This section describes modules options of ejabberd 24.02.  If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the Archive. The modules that changed in this version are marked with \ud83d\udfe4.
    "},{"location":"admin/configuration/modules/#mod_adhoc","title":"mod_adhoc","text":"
    This module implements XEP-0050: Ad-Hoc Commands. It\u2019s 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.
      •  
    "},{"location":"admin/configuration/modules/#mod_admin_extra","title":"mod_admin_extra","text":"
    This module provides additional administrative commands.
     
    Details for some commands:
     
       
    •  
      ban-acount: 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\u2019t 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 blankspaces, 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:
     
    acl:\n  adminextraresource:\n    - resource: \"modadminextraf8x,31ad\"\naccess_rules:\n  vcard_set:\n    - allow: adminextraresource\nmodules:\n  mod_admin_extra: {}\n  mod_vcard:\n    access_set: vcard_set\n
     
    Content of roster file for pushroster command:
     
    [{<<\"bob\">>, <<\"example.org\">>, <<\"workers\">>, <<\"Bob\">>},\n{<<\"mart\">>, <<\"example.org\">>, <<\"workers\">>, <<\"Mart\">>},\n{<<\"Rich\">>, <<\"example.org\">>, <<\"bosses\">>, <<\"Rich\">>}].\n
     
    With this call, the sessions of the local account which JID is boby@example.org will be kicked, and its password will be set to something like BANNED_ACCOUNT\u201420080425T21:45:07\u20142176635\u2014Spammed_rooms
     
    ejabberdctl vhost example.org ban-account boby \"Spammed rooms\"\n
     
    Call to srg-create using double-quotes and single-quotes:
     
    ejabberdctl srg-create g1 example.org \"'Group number 1'\" this_is_g1 g1\n
    "},{"location":"admin/configuration/modules/#mod_admin_update_sql","title":"mod_admin_update_sql","text":"
    This module can be used to update existing SQL database from the default to the new schema. Check the section 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 API.
     
    The module has no options.
    "},{"location":"admin/configuration/modules/#mod_announce","title":"mod_announce","text":"
    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 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) 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level default_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_avatar","title":"mod_avatar","text":"
    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.
     
    Also, the module supports conversion between avatar image formats on the fly.
     
    The module depends on mod_vcard, mod_vcard_xupdate and 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:
       
      convert:\n  webp: jpg\n  default: png\n
       
      •  
    •  
      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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_block_strangers","title":"mod_block_strangers","text":"
    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\u2019ll 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\u2019s 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\u2019s JID is in user\u2019s 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 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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_blocking","title":"mod_blocking","text":"
    The module implements XEP-0191: Blocking Command.
     
    This module depends on mod_privacy where all the configuration is performed.
     
    The module has no options.
    "},{"location":"admin/configuration/modules/#mod_bosh","title":"mod_bosh","text":"
    This module implements XMPP over BOSH as defined in XEP-0124 and XEP-0206. 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level 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 option, but applied to this module only.
       
      •  
    •  
      ram_db_type: mnesia | sql | redis Same as top-level default_ram_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
     
    Example:
     
    listen:\n  -\n    port: 5222\n    module: ejabberd_c2s\n  -\n    port: 5443\n    module: ejabberd_http\n    request_handlers:\n      /bosh: mod_bosh\n\nmodules:\n  mod_bosh: {}\n
    "},{"location":"admin/configuration/modules/#mod_caps","title":"mod_caps","text":"
    This module implements XEP-0115: Entity Capabilities. The main purpose of the module is to provide PEP functionality (see mod_pubsub).
     
    Available options:
     
       
    •  
      cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level default_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_carboncopy","title":"mod_carboncopy","text":"
    The module implements XEP-0280: Message Carbons. The module broadcasts messages on all connected user resources (devices).
     
    The module has no options.
    "},{"location":"admin/configuration/modules/#mod_client_state","title":"mod_client_state","text":"
    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). This can save bandwidth and resources.
     
    A stanza is dropped from the queue if it\u2019s 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\u2019t 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) 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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_configure","title":"mod_configure","text":"
    The module provides server configuration functionality via XEP-0050: Ad-Hoc Commands. Implements many commands as defined in XEP-0133: Service Administration. This module requires mod_adhoc to be loaded.
     
    The module has no options.
    "},{"location":"admin/configuration/modules/#mod_conversejs","title":"mod_conversejs","text":"
     added in 21.12 and improved in 22.05
     
    This module serves a simple page for the Converse XMPP web browser client.
     
    To use this module, in addition to adding it to the modules section, you must also enable it in listen \u2192 ejabberd_http \u2192 request_handlers.
     
    Make sure either mod_bosh or ejabberd_http_ws 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} added in 22.05  Specify additional options to be passed to Converse. See Converse configuration. Only boolean, integer and string values are supported; lists are not supported.
       
      •  
    •  
      conversejs_resources: Path added in 22.05  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:
     
    listen:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /bosh: mod_bosh\n      /websocket: ejabberd_http_ws\n      /conversejs: mod_conversejs\n\nmodules:\n  mod_bosh: {}\n  mod_conversejs:\n    websocket_url: \"ws://@HOST@:5280/websocket\"\n
     
    Host Converse locally and let auto detection of WebSocket and Converse URLs:
     
    listen:\n  -\n    port: 443\n    module: ejabberd_http\n    tls: true\n    request_handlers:\n      /websocket: ejabberd_http_ws\n      /conversejs: mod_conversejs\n\nmodules:\n  mod_conversejs:\n    conversejs_resources: \"/home/ejabberd/conversejs-9.0.0/package/dist\"\n
     
    Configure some additional options for Converse
     
    modules:\n  mod_conversejs:\n    websocket_url: auto\n    conversejs_options:\n      auto_away: 30\n      clear_cache_on_logout: true\n      i18n: \"pt\"\n      locked_domain: \"@HOST@\"\n      message_archiving: always\n      theme: dracula\n
    "},{"location":"admin/configuration/modules/#mod_delegation","title":"mod_delegation","text":"
    This module is an implementation of XEP-0355: Namespace Delegation. 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 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.
     
    access_rules:\n  external_pubsub:\n    allow: external_component\n  external_mam:\n    allow: external_component\n\nacl:\n  external_component:\n    server: sat-pubsub.example.org\n\nmodules:\n  mod_delegation:\n    namespaces:\n      urn:xmpp:mam:1:\n        access: external_mam\n      http://jabber.org/protocol/pubsub:\n        access: external_pubsub\n
    "},{"location":"admin/configuration/modules/#mod_disco","title":"mod_disco","text":"
    This module adds support for XEP-0030: Service Discovery. 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. 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:
       
      server_info:\n  -\n    modules: all\n    name: abuse-addresses\n    urls: [\"mailto:abuse@shakespeare.lit\"]\n  -\n    modules: [mod_muc]\n    name: \"Web chatroom logs\"\n    urls: [\"http://www.example.org/muc-logs\"]\n  -\n    modules: [mod_disco]\n    name: feedback-addresses\n    urls:\n      - http://shakespeare.lit/feedback.php\n      - mailto:feedback@shakespeare.lit\n      - xmpp:feedback@shakespeare.lit\n  -\n    modules:\n      - mod_disco\n      - mod_vcard\n    name: admin-addresses\n    urls:\n      - mailto:xmpp@shakespeare.lit\n      - xmpp:admins@shakespeare.lit\n
       
      •  
    "},{"location":"admin/configuration/modules/#mod_fail2ban","title":"mod_fail2ban","text":"
    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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_host_meta","title":"mod_host_meta","text":"
     added in 22.05
     
    This module serves small host-meta files as described in XEP-0156: Discovering Alternative XMPP Connection Methods.
     
    To use this module, in addition to adding it to the modules section, you must also enable it in listen \u2192 ejabberd_http \u2192 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:
     
    listen:\n  -\n    port: 443\n    module: ejabberd_http\n    tls: true\n    request_handlers:\n      /bosh: mod_bosh\n      /ws: ejabberd_http_ws\n      /.well-known/host-meta: mod_host_meta\n      /.well-known/host-meta.json: mod_host_meta\n\nmodules:\n  mod_bosh: {}\n  mod_host_meta:\n    bosh_service_url: \"https://@HOST@:5443/bosh\"\n    websocket_url: \"wss://@HOST@:5443/ws\"\n
    "},{"location":"admin/configuration/modules/#mod_http_api","title":"mod_http_api","text":"
    This module provides a ReST interface to call ejabberd API commands using JSON data.
     
    To use this module, in addition to adding it to the modules section, you must also enable it in listen \u2192 ejabberd_http \u2192 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:
     
    listen:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /api: mod_http_api\n\nmodules:\n  mod_http_api: {}\n
    "},{"location":"admin/configuration/modules/#mod_http_fileserver","title":"mod_http_fileserver","text":"
    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:
       
      content_types:\n  .css: text/css\n  .gif: image/gif\n  .html: text/html\n  .jar: application/java-archive\n  .jpeg: image/jpeg\n  .jpg: image/jpeg\n  .js: text/javascript\n  .png: image/png\n  .svg: image/svg+xml\n  .txt: text/plain\n  .xml: application/xml\n  .xpi: application/x-xpinstall\n  .xul: application/vnd.mozilla.xul+xml\n
       
      •  
    •  
      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\u2019s 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:
     
    listen:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /pub/content: mod_http_fileserver\n\nmodules:\n  mod_http_fileserver:\n    docroot: /var/www\n    accesslog: /var/log/ejabberd/access.log\n    directory_indices:\n      - index.html\n      - main.htm\n    custom_headers:\n      X-Powered-By: Erlang/OTP\n      X-Fry: \"It's a widely-believed fact!\"\n    content_types:\n      .ogg: audio/ogg\n      .png: image/png\n    default_content_type: text/html\n
    "},{"location":"admin/configuration/modules/#mod_http_upload","title":"mod_http_upload","text":"
    This module allows for requesting permissions to upload a file via HTTP as described in XEP-0363: HTTP File Upload. 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 \u2192 ejabberd_http \u2192 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\u2019s mod_http_upload_external 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 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\u2019s 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\u2019s 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:
       
      # This XML representation of vCard:\n#   <vCard xmlns='vcard-temp'>\n#     <FN>Conferences</FN>\n#     <ADR>\n#       <WORK/>\n#       <STREET>Elm Street</STREET>\n#     </ADR>\n#   </vCard>\n#\n# is translated to:\nvcard:\n  fn: Conferences\n  adr:\n    -\n      work: true\n      street: Elm Street\n
       
      •  
     
    Example:
     
    listen:\n  -\n    port: 5443\n    module: ejabberd_http\n    tls: true\n    request_handlers:\n      /upload: mod_http_upload\n\nmodules:\n  mod_http_upload:\n    docroot: /ejabberd/upload\n    put_url: \"https://@HOST@:5443/upload\"\n
    "},{"location":"admin/configuration/modules/#mod_http_upload_quota","title":"mod_http_upload_quota","text":"
    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\u2019s 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:
     
    shaper_rules:\n  soft_upload_quota:\n    1000: all # MiB\n  hard_upload_quota:\n    1100: all # MiB\n\nmodules:\n  mod_http_upload: {}\n  mod_http_upload_quota:\n    max_days: 100\n
    "},{"location":"admin/configuration/modules/#mod_jidprep","title":"mod_jidprep","text":"
    This module allows XMPP clients to ask the server to normalize a JID as per the rules specified in RFC 6122: XMPP Address Format. 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.
      •  
    "},{"location":"admin/configuration/modules/#mod_last","title":"mod_last","text":"
    This module adds support for XEP-0012: Last Activity. 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level default_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_legacy_auth","title":"mod_legacy_auth","text":"
    The module implements XEP-0078: Non-SASL Authentication.
     
    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.
    "},{"location":"admin/configuration/modules/#mod_mam","title":"mod_mam","text":"
    This module implements XEP-0313: Message Archive Management and XEP-0441: Message Archive Management Preferences. 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\u2019s stream management code (see 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\u2019s 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level 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) 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 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\u2019s 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\u2019s messages are archived as usual. The default value is false.
       
      •  
    •  
      use_cache: true | false Same as top-level 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 separa 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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_matrix_gw","title":"mod_matrix_gw \ud83d\udfe4","text":"
     added in 24.02
     
    Matrix 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%matrixdomain.tld@matrix.myxmppdomain.tld, where matrix.myxmppdomain.tld is the JID of the gateway service as set by the host option. The default is false.
       
      •  
     
    Example:
     
    listen:\n  -\n    port: 8448\n    module: ejabberd_http\n    tls: true\n    request_handlers:\n      \"/_matrix\": mod_matrix_gw\n\nmodules:\n  mod_matrix_gw:\n    key_name: \"key1\"\n    key: \"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n    matrix_id_as_jid: true\n
    "},{"location":"admin/configuration/modules/#mod_metrics","title":"mod_metrics","text":"
    This module sends events to external backend (by now only 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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_mix","title":"mod_mix","text":"
     added in 16.03 and improved in 19.02
     
    This module is an experimental implementation of XEP-0369: Mediated Information eXchange (MIX). It\u2019s asserted that the MIX protocol is going to replace the MUC protocol in the future (see mod_muc).
     
    To learn more about how to use that feature, you can refer to our tutorial: Getting started with MIX
     
    The module depends on 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 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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_mix_pam","title":"mod_mix_pam","text":"
    This module implements XEP-0405: Mediated Information eXchange (MIX): Participant Server Requirements. 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level default_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_mqtt","title":"mod_mqtt","text":"
    This module adds support for the MQTT 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level 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 option, but applied to this module only.
       
      •  
    •  
      ram_db_type: mnesia Same as top-level 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 option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_mqtt_bridge","title":"mod_mqtt_bridge","text":"
    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.
     
    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:
     
    modules:\n  mod_mqtt_bridge:\n    servers:\n      \"mqtt://server.com\":\n        publish:\n          \"localA\": \"remoteA\" # local changes to 'localA' will be replicated on remote server as 'remoteA'\n          \"topicB\": \"topicB\"\n        subscribe:\n          \"remoteB\": \"localB\" # changes to 'remoteB' on remote server will be stored as 'localB' on local server\n        authentication:\n          certfile: \"/etc/ejabberd/mqtt_server.pem\"\n    replication_user: \"mqtt@xmpp.server.com\"\n
    "},{"location":"admin/configuration/modules/#mod_muc","title":"mod_muc","text":"
    This module provides support for XEP-0045: Multi-User Chat. 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 improved in 23.10  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 added in 22.05  Remove affiliations for non-existing local users on startup. The default value is false.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level 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. 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\u2019t 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 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. 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:
         
        presence_broadcast:\n  - moderator\n  - participant\n  - visitor\n
         
        •  
      •  
        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\u2019re 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 added in 21.01  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 added in 21.01  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 overcrowed, 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. 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 option, but applied to this module only.
       
      •  
    •  
      ram_db_type: mnesia | sql Same as top-level 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:
       
      # This XML representation of vCard:\n#   <vCard xmlns='vcard-temp'>\n#     <FN>Conferences</FN>\n#     <ADR>\n#       <WORK/>\n#       <STREET>Elm Street</STREET>\n#     </ADR>\n#   </vCard>\n#\n# is translated to:\nvcard:\n  fn: Conferences\n  adr:\n    -\n      work: true\n      street: Elm Street\n
       
      •  
    "},{"location":"admin/configuration/modules/#mod_muc_admin","title":"mod_muc_admin","text":"
    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.
     
    Available options:
     
       
    • subscribe_room_many_max_users: Number added in 22.05  How many users can be subscribed to a room at once using the subscribe_room_many command. The default value is 50.
      •  
    "},{"location":"admin/configuration/modules/#mod_muc_log","title":"mod_muc_log","text":"
    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.
     
    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:
       
      file_permissions:\n  mode: 644\n  group: 33\n
       
      •  
    •  
      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:
       
      top_link:\n  /: Home\n
       
      •  
    •  
      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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_muc_occupantid","title":"mod_muc_occupantid","text":"
     added in 23.10
     
    This module implements XEP-0421: Anonymous unique occupant identifiers for MUCs.
     
    When the module is enabled, the feature is enabled in all semi-anonymous rooms.
     
    The module has no options.
    "},{"location":"admin/configuration/modules/#mod_muc_rtbl","title":"mod_muc_rtbl","text":"
     added in 23.04
     
    This module implement Real-time blocklists for MUC rooms.
     
    It works by observing remote pubsub node conforming with specification described in https://xmppbl.org/.
     
    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
       
      •  
    "},{"location":"admin/configuration/modules/#mod_multicast","title":"mod_multicast","text":"
    This module implements a service for XEP-0033: Extended Stanza Addressing.
     
    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:
         
        # Default values:\nlocal:\n  message: 100\n  presence: 100\nremote:\n  message: 20\n  presence: 20\n
         
        •  
       
      •  
    •  
      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:
     
    # Only admins can send packets to multicast service\naccess_rules:\n  multicast:\n    - allow: admin\n\n# If you want to allow all your users:\naccess_rules:\n  multicast:\n    - allow\n\n# This allows both admins and remote users to send packets,\n# but does not allow local users\nacl:\n  allservers:\n    server_glob: \"*\"\naccess_rules:\n  multicast:\n    - allow: admin\n    - deny: local\n    - allow: allservers\n\nmodules:\n  mod_multicast:\n     host: multicast.example.org\n     access: multicast\n     limits:\n       local:\n         message: 40\n         presence: infinite\n       remote:\n         message: 150\n
    "},{"location":"admin/configuration/modules/#mod_offline","title":"mod_offline","text":"
    This module implements XEP-0160: Best Practices for Handling Offline Messages and XEP-0013: Flexible Offline Message Retrieval. 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 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 optimisation 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 optimisation is enabled.
       
      •  
    •  
      cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level 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.
       
      •  
    •  
      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 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\u2019t 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:
     
    acl:\n  admin:\n    user:\n      - admin1@localhost\n      - admin2@example.org\n  poweruser:\n    user:\n      - bob@example.org\n      - jane@example.org\n\nshaper_rules:\n  max_user_offline_messages:\n    - 5000: poweruser\n    - 2000: admin\n    - 100\n\nmodules:\n  ...\n  mod_offline:\n    access_max_user_messages: max_user_offline_messages\n  ...\n
    "},{"location":"admin/configuration/modules/#mod_ping","title":"mod_ping","text":"
    This module implements support for XEP-0199: XMPP Ping 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 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 is loaded and stream management is enabled by a client, killing the client connection doesn\u2019t 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:
     
    modules:\n  mod_ping:\n    send_pings: true\n    ping_interval: 4 min\n    timeout_action: kill\n
    "},{"location":"admin/configuration/modules/#mod_pres_counter","title":"mod_pres_counter","text":"
    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:
     
    modules:\n  mod_pres_counter:\n    count: 5\n    interval: 30 secs\n
    "},{"location":"admin/configuration/modules/#mod_privacy","title":"mod_privacy","text":"
    This module implements XEP-0016: Privacy Lists.
     
    Note
     
    Nowadays modern XMPP clients rely on XEP-0191: Blocking Command which is implemented by mod_blocking module. However, you still need mod_privacy loaded in order for mod_blocking to work.
     
    Available options:
     
       
    •  
      cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level default_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_private","title":"mod_private","text":"
    This module adds support for XEP-0049: Private XML Storage.
     
    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\u2019s conferences (XEP-0048: Bookmarks).
     
    It also implements the bookmark conversion described in XEP-0402: PEP Native Bookmarks, see the command bookmarks_to_pep API.
     
    Available options:
     
       
    •  
      cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level default_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_privilege","title":"mod_privilege","text":"
    This module is an implementation of XEP-0356: Privileged Entity. 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 or MAM 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, 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\u2019s roster. The default value is none.
         
        •  
      •  
        get: AccessName    Sets read access to a user\u2019s roster. The default value is none.
         
        •  
      •  
        set: AccessName    Sets write access to a user\u2019s roster. The default value is none.
         
        •  
       
      •  
     
    Example:
     
    modules:\n  mod_privilege:\n    roster:\n      get: all\n    presence:\n      managed_entity: all\n    message:\n      outgoing: all\n
    "},{"location":"admin/configuration/modules/#mod_proxy65","title":"mod_proxy65","text":"
    This module implements XEP-0065: SOCKS5 Bytestreams. 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\u2019s 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. 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 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:
     
    acl:\n  admin:\n    user: admin@example.org\n  proxy_users:\n    server: example.org\n\naccess_rules:\n  proxy65_access:\n    allow: proxy_users\n\nshaper_rules:\n  proxy65_shaper:\n    none: admin\n  proxyrate: proxy_users\n\nshaper:\n  proxyrate: 10240\n\nmodules:\n  mod_proxy65:\n    host: proxy1.example.org\n    name: \"File Transfer Proxy\"\n    ip: 200.150.100.1\n    port: 7778\n    max_connections: 5\n    access: proxy65_access\n    shaper: proxy65_shaper\n    recbuf: 10240\n    sndbuf: 10240\n
    "},{"location":"admin/configuration/modules/#mod_pubsub","title":"mod_pubsub","text":"
    This module offers a service for XEP-0060: Publish-Subscribe. The functionality in mod_pubsub can be extended using plugins. The plugin that implements PEP (XEP-0163: Personal Eventing via Pubsub) is enabled in the default ejabberd configuration file, and it requires 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 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:
       
      force_node_config:\n  ## Avoid buggy clients to make their bookmarks public\n  storage:bookmarks:\n    access_model: whitelist\n
       
      •  
    •  
      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 added in 21.12  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. 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:
       
      modules:\n  ...\n  mod_pubsub:\n    pep_mapping:\n      http://jabber.org/protocol/tune: tune\n  ...\n
       
      •  
    •  
      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:
       
      # This XML representation of vCard:\n#   <vCard xmlns='vcard-temp'>\n#     <FN>Conferences</FN>\n#     <ADR>\n#       <WORK/>\n#       <STREET>Elm Street</STREET>\n#     </ADR>\n#   </vCard>\n#\n# is translated to:\nvcard:\n  fn: Conferences\n  adr:\n    -\n      work: true\n      street: Elm Street\n
       
      •  
     
    Examples:
     
    Example of configuration that uses flat nodes as default, and allows use of flat, hometree and pep nodes:
     
    modules:\n  mod_pubsub:\n    access_createnode: pubsub_createnode\n    max_subscriptions_node: 100\n    default_node_config:\n      notification_type: normal\n      notify_retract: false\n      max_items: 4\n    plugins:\n      - flat\n      - pep\n
     
    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:
     
    modules:\n  mod_pubsub:\n    db_type: sql\n    access_createnode: pubsub_createnode\n    ignore_pep_from_offline: true\n    last_item_cache: false\n    plugins:\n      - flat\n      - pep\n
    "},{"location":"admin/configuration/modules/#mod_push","title":"mod_push","text":"
    This module implements the XMPP server\u2019s part of the push notification solution specified in XEP-0357: Push Notifications. It does not generate, for example, APNS or FCM notifications directly. Instead, it\u2019s 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\u2019s mobile device using platform-dependant backend services such as FCM or APNS.
     
    Available options:
     
       
    •  
      cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level 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\u2019s JID is included with push notifications generated for incoming messages with a body. The default value is false.
       
      •  
    •  
      notify_on: messages | all added in 23.10  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\u2019s set to all, any kind of XMPP stanza will trigger a notification. If unsure, it\u2019s strongly recommended to stick to all, which is the default value.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_push_keepalive","title":"mod_push_keepalive","text":"
    This module tries to keep the stream management session (see 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\u2019t respond to push notifications.
     
    The module depends on 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 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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_register","title":"mod_register","text":"
    This module adds support for XEP-0077: In-Band Registration. 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 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\u2019t 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, ...] added in 21.12  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. 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 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.
       
      •  
    •  
      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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_register_web","title":"mod_register_web","text":"
    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 to register a new account. To enable this feature, configure the top-level captcha_cmd and top-level 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 \u2192 ejabberd_http \u2192 request_handlers, no need to enable in modules. The module depends on mod_register where all the configuration is performed.
     
    The module has no options.
     
    Example:
     
    listen:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /register: mod_register_web\n\nmodules:\n  mod_register: {}\n
    "},{"location":"admin/configuration/modules/#mod_roster","title":"mod_roster","text":"
    This module implements roster management as defined in RFC6121 Section 2. The module also adds support for XEP-0237: Roster Versioning.
     
    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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level 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 or mod_shared_roster_ldap, you must set the value of the option to false.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    •  
      versioning: true | false Enables/disables Roster Versioning. The default value is false.
       
      •  
     
    Example:
     
    modules:\n  mod_roster:\n    versioning: true\n    store_current_id: false\n
    "},{"location":"admin/configuration/modules/#mod_s2s_dialback","title":"mod_s2s_dialback","text":"
    The module adds support for XEP-0220: Server Dialback to provide server identity verification based on DNS.
     
    Warning
     
    DNS-based verification is vulnerable to DNS cache poisoning, 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\u2019s compromised).
     
    Available options:
     
       
    • access: AccessName An access rule that can be used to restrict dialback for some servers. The default value is all.
      •  
     
    Example:
     
    modules:\n  mod_s2s_dialback:\n    access:\n      allow:\n        server: legacy.domain.tld\n        server: invalid-cert.example.org\n      deny: all\n
    "},{"location":"admin/configuration/modules/#mod_service_log","title":"mod_service_log","text":"
    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.
     
    Available options:
     
       
    • loggers: [Domain, ...] A list of servers or connected components to which stanzas will be forwarded.
      •  
     
    Example:
     
    modules:\n  mod_service_log:\n    loggers:\n      - xmpp-server.tld\n      - component.domain.tld\n
    "},{"location":"admin/configuration/modules/#mod_shared_roster","title":"mod_shared_roster","text":"
    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\u2019s members. A group of other vhost can be identified with     groupid@vhost.
       
      •  
     
    This module depends on mod_roster. If not enabled, roster queries will return 503 errors.
     
    Available options:
     
       
    •  
      cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level default_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level 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:
     
    Name: club_members\nLabel: Club Members\nDescription: Members from the computer club\nMembers: member1@example.org, member2@example.org, member3@example.org\nDisplayed Groups: club_members\n
     
    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:
     
    First list:\nName: management\nLabel: Management\nDescription: Management\nMembers: manager1@example.org, manager2@example.org\nDisplayed: management, marketing, sales\n\nSecond list:\nName: marketing\nLabel: Marketing\nDescription: Marketing\nMembers: marketeer1@example.org, marketeer2@example.org, marketeer3@example.org\nDisplayed: management, marketing\n\nThird list:\nName: sales\nLabel: Sales\nDescription: Sales\nMembers: salesman1@example.org, salesman2@example.org, salesman3@example.org\nDisplayed: management, sales\n
    "},{"location":"admin/configuration/modules/#mod_shared_roster_ldap","title":"mod_shared_roster_ldap","text":"
    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 section for more     information about them.
       
      •  
     
    Check also the Configuration 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size Same as top-level 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 option, but applied to this module only.
       
      •  
    •  
      ldap_base Same as top-level ldap_base option, but applied to this module only.
       
      •  
    •  
      ldap_deref_aliases Same as top-level ldap_deref_aliases option, but applied to this module only.
       
      •  
    •  
      ldap_encrypt Same as top-level 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 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 \u2192 memberUid; groupOfNames \u2192 member; groupOfUniqueNames \u2192 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 section.
       
      •  
    •  
      ldap_password Same as top-level ldap_password option, but applied to this module only.
       
      •  
    •  
      ldap_port Same as top-level 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 option, but applied to this module only.
       
      •  
    •  
      ldap_servers Same as top-level ldap_servers option, but applied to this module only.
       
      •  
    •  
      ldap_tls_cacertfile Same as top-level ldap_tls_cacertfile option, but applied to this module only.
       
      •  
    •  
      ldap_tls_certfile Same as top-level ldap_tls_certfile option, but applied to this module only.
       
      •  
    •  
      ldap_tls_depth Same as top-level ldap_tls_depth option, but applied to this module only.
       
      •  
    •  
      ldap_tls_verify Same as top-level 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 section.
       
      •  
    •  
      ldap_uids Same as top-level 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 option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_sic","title":"mod_sic","text":"
    This module adds support for XEP-0279: Server IP Check. 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.
    "},{"location":"admin/configuration/modules/#mod_sip","title":"mod_sip","text":"
    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 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 TCP connections. The default value is 2 minutes.
       
      •  
    •  
      flow_timeout_udp: timeout() The options sets a keep-alive timer for SIP outbound 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 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\u2019re 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:
     
    modules:\n  mod_sip:\n    always_record_route: false\n    record_route: \"sip:example.com;lr\"\n    routes:\n      - \"sip:example.com;lr\"\n      - \"sip:sip.example.com;lr\"\n    flow_timeout_udp: 30 sec\n    flow_timeout_tcp: 1 min\n    via:\n      - tls://sip-tls.example.com:5061\n      - tcp://sip-tcp.example.com:5060\n      - udp://sip-udp.example.com:5060\n
    "},{"location":"admin/configuration/modules/#mod_stats","title":"mod_stats","text":"
    This module adds support for XEP-0039: Statistics Gathering. 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.
    "},{"location":"admin/configuration/modules/#mod_stream_mgmt","title":"mod_stream_mgmt","text":"
    This module adds support for XEP-0198: Stream Management. This protocol allows active management of an XML stream between two XMPP entities, including features for stanza acknowledgements and stream resumption.
     
    Available options:
     
       
    •  
      ack_timeout: timeout() A time to wait for stanza acknowledgements. 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 option, but applied to this module only. The default value is 48 hours.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level 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 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\u2019t 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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_stun_disco","title":"mod_stun_disco","text":"
     added in 20.04
     
    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.
     
    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\u2019s 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\u2019t 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\u2019s 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\u2019s built-in STUN/TURN server and with external servers that support the same REST API For Access To TURN Services. 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\u2019s 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:
       
      services:\n  -\n    host: 203.0.113.3\n    port: 3478\n    type: stun\n    transport: udp\n    restricted: false\n  -\n    host: 203.0.113.3\n    port: 3478\n    type: turn\n    transport: udp\n    restricted: true\n  -\n    host: 2001:db8::3\n    port: 3478\n    type: stun\n    transport: udp\n    restricted: false\n  -\n    host: 2001:db8::3\n    port: 3478\n    type: turn\n    transport: udp\n    restricted: true\n  -\n    host: server.example.com\n    port: 5349\n    type: turns\n    transport: tcp\n    restricted: true\n
       
      •  
    "},{"location":"admin/configuration/modules/#mod_time","title":"mod_time","text":"
    This module adds support for XEP-0202: Entity Time. In other words, the module reports server\u2019s system time.
     
    The module has no options.
    "},{"location":"admin/configuration/modules/#mod_vcard","title":"mod_vcard","text":"
    This module allows end users to store and retrieve their vCard, and to retrieve other users vCards, as defined in XEP-0054: vcard-temp. 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql | ldap Same as top-level 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\u2019s 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. 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 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:
       
      # This XML representation of vCard:\n#\n#   <vCard xmlns='vcard-temp'>\n#     <FN>Conferences</FN>\n#     <ADR>\n#       <WORK/>\n#       <STREET>Elm Street</STREET>\n#     </ADR>\n#   </vCard>\n#\n# is translated to:\n#\nvcard:\n  fn: Conferences\n  adr:\n    -\n      work: true\n      street: Elm Street\n
       
      •  
     
    Available options for ldap backend:
     
       
    •  
      ldap_backups Same as top-level ldap_backups option, but applied to this module only.
       
      •  
    •  
      ldap_base Same as top-level ldap_base option, but applied to this module only.
       
      •  
    •  
      ldap_deref_aliases Same as top-level ldap_deref_aliases option, but applied to this module only.
       
      •  
    •  
      ldap_encrypt Same as top-level ldap_encrypt option, but applied to this module only.
       
      •  
    •  
      ldap_filter Same as top-level ldap_filter option, but applied to this module only.
       
      •  
    •  
      ldap_password Same as top-level ldap_password option, but applied to this module only.
       
      •  
    •  
      ldap_port Same as top-level ldap_port option, but applied to this module only.
       
      •  
    •  
      ldap_rootdn Same as top-level 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:
       
      User: \"%u\"\n\"Full Name\": displayName\n\"Given Name\": givenName\n\"Middle Name\": initials\n\"Family Name\": sn\nNickname: \"%u\"\nBirthday: birthDay\nCountry: c\nCity: l\nEmail: mail\n\"Organization Name\": o\n\"Organization Unit\": ou\n
       
      •  
    •  
      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:
       
      \"Full Name\": FN\n\"Given Name\": FIRST\n\"Middle Name\": MIDDLE\n\"Family Name\": LAST\n\"Nickname\": NICKNAME\n\"Birthday\": BDAY\n\"Country\": CTRY\n\"City\": LOCALITY\n\"Email\": EMAIL\n\"Organization Name\": ORGNAME\n\"Organization Unit\": ORGUNIT\n
       
      •  
    •  
      ldap_servers Same as top-level ldap_servers option, but applied to this module only.
       
      •  
    •  
      ldap_tls_cacertfile Same as top-level ldap_tls_cacertfile option, but applied to this module only.
       
      •  
    •  
      ldap_tls_certfile Same as top-level ldap_tls_certfile option, but applied to this module only.
       
      •  
    •  
      ldap_tls_depth Same as top-level ldap_tls_depth option, but applied to this module only.
       
      •  
    •  
      ldap_tls_verify Same as top-level ldap_tls_verify option, but applied to this module only.
       
      •  
    •  
      ldap_uids Same as top-level 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. 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:
       
      NICKNAME: {\"%u\": []}\nFN: {\"%s\": [displayName]}\nLAST: {\"%s\": [sn]}\nFIRST: {\"%s\": [givenName]}\nMIDDLE: {\"%s\": [initials]}\nORGNAME: {\"%s\": [o]}\nORGUNIT: {\"%s\": [ou]}\nCTRY: {\"%s\": [c]}\nLOCALITY: {\"%s\": [l]}\nSTREET: {\"%s\": [street]}\nREGION: {\"%s\": [st]}\nPCODE: {\"%s\": [postalCode]}\nTITLE: {\"%s\": [title]}\nURL: {\"%s\": [labeleduri]}\nDESC: {\"%s\": [description]}\nTEL: {\"%s\": [telephoneNumber]}\nEMAIL: {\"%s\": [mail]}\nBDAY: {\"%s\": [birthDay]}\nROLE: {\"%s\": [employeeType]}\nPHOTO: {\"%s\": [jpegPhoto]}\n
       
      •  
     
    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.
      •  
    "},{"location":"admin/configuration/modules/#mod_vcard_xupdate","title":"mod_vcard_xupdate","text":"
    The user\u2019s client can store an avatar in the user vCard. The vCard-Based Avatars protocol (XEP-0153) 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 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\u2019t want to set use_cache to false.
     
    The module depends on mod_vcard.
     
    Note
     
    Nowadays XEP-0153 is used mostly as \"read-only\", i.e. modern clients don\u2019t publish their avatars inside vCards. Thus in the majority of cases the module is only used along with mod_avatar for providing backward compatibility.
     
    Available options:
     
       
    •  
      cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_version","title":"mod_version","text":"
    This module implements XEP-0092: Software Version. Consequently, it answers ejabberd\u2019s version when queried.
     
    Available options:
     
       
    • show_os: true | false Should the operating system be revealed or not. The default value is true.
      •  
    "},{"location":"admin/configuration/toplevel/","title":"Top-Level Options","text":"
    This section describes top level options of ejabberd 24.02.  If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the Archive. The options that changed in this version are marked with \ud83d\udfe4.
    "},{"location":"admin/configuration/toplevel/#access_rules","title":"access_rules","text":"
    {AccessName: {allow|deny: ACLRules|ACLName}} 
     
    This option defines 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 option). There are no access rules defined by default.
     
    Example:
     
    access_rules:\n  configure:\n    allow: admin\n  something:\n    deny: someone\n    allow: all\n  s2s_banned:\n    deny: problematic_hosts\n    deny: banned_forever\n    deny:\n      ip: 222.111.222.111/32\n    deny:\n      ip: 111.222.111.222/32\n    allow: all\n  xmlrpc_access:\n    allow:\n      user: peter@example.com\n    allow:\n      user: ivone@example.com\n    allow:\n      user: bot@example.com\n      ip: 10.0.0.0/24\n
    "},{"location":"admin/configuration/toplevel/#acl","title":"acl","text":"
    {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 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.
       
      •  
    "},{"location":"admin/configuration/toplevel/#acme","title":"acme","text":"
    Options 
     
    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     https://acme-v02.api.letsencrypt.org/directory - the directory URL     of Let\u2019s 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\u2019s 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:
     
    acme:\n  ca_url: https://acme-v02.api.letsencrypt.org/directory\n  contact:\n    - mailto:admin@domain.tld\n    - mailto:bot@domain.tld\n  auto: true\n  cert_type: rsa\n
    "},{"location":"admin/configuration/toplevel/#allow_contrib_modules","title":"allow_contrib_modules","text":"
    true | false 
     
    Whether to allow installation of third-party modules or not. See ejabberd-contrib documentation section. The default value is true.
    "},{"location":"admin/configuration/toplevel/#allow_multiple_connections","title":"allow_multiple_connections","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#anonymous_protocol","title":"anonymous_protocol","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#api_permissions","title":"api_permissions","text":"
    [Permission, ...] 
     
    Define the permissions for API access. Please consult the ejabberd Docs web \u2192 For Developers \u2192 ejabberd ReST API \u2192 API Permissions.
    "},{"location":"admin/configuration/toplevel/#append_host_config","title":"append_host_config","text":"
    {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.
    "},{"location":"admin/configuration/toplevel/#auth_cache_life_time","title":"auth_cache_life_time","text":"
    timeout() 
     
    Same as cache_life_time, but applied to authentication cache only. If not set, the value from cache_life_time will be used.
    "},{"location":"admin/configuration/toplevel/#auth_cache_missed","title":"auth_cache_missed","text":"
    true | false 
     
    Same as cache_missed, but applied to authentication cache only. If not set, the value from cache_missed will be used.
    "},{"location":"admin/configuration/toplevel/#auth_cache_size","title":"auth_cache_size","text":"
    pos_integer() | infinity 
     
    Same as cache_size, but applied to authentication cache only. If not set, the value from cache_size will be used.
    "},{"location":"admin/configuration/toplevel/#auth_external_user_exists_check","title":"auth_external_user_exists_check","text":"
    true | false 
     
     added in 23.10
     
    Supplement check for user existence based on mod_last data, for authentication methods that don\u2019t 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.
    "},{"location":"admin/configuration/toplevel/#auth_method","title":"auth_method","text":"
    [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].
    "},{"location":"admin/configuration/toplevel/#auth_opts","title":"auth_opts","text":"
    [Option, ...] 
     
    This is used by the contributed module ejabberd_auth_http that can be installed from the ejabberd-contrib Git repository. Please refer to that module\u2019s README file for details.
    "},{"location":"admin/configuration/toplevel/#auth_password_format","title":"auth_password_format","text":"
    plain | scram 
     
     improved in 20.01
     
    The option defines in what format the users passwords are stored, plain text or in 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 option.
       
      •  
     
    The default value is plain.
    "},{"location":"admin/configuration/toplevel/#auth_scram_hash","title":"auth_scram_hash","text":"
    sha | sha256 | sha512 
     
    Hash algorithm that should be used to store password in SCRAM format. You shouldn\u2019t 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.
    "},{"location":"admin/configuration/toplevel/#auth_use_cache","title":"auth_use_cache","text":"
    true | false 
     
    Same as use_cache, but applied to authentication cache only. If not set, the value from use_cache will be used.
    "},{"location":"admin/configuration/toplevel/#c2s_cafile","title":"c2s_cafile","text":"
    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 to specify this option per-vhost.
     
    To set a specific file per listener, use the listener\u2019s cafile option. Please notice that c2s_cafile overrides the listener\u2019s cafile option.
    "},{"location":"admin/configuration/toplevel/#c2s_ciphers","title":"c2s_ciphers","text":"
    [Cipher, ...] 
     
    A list of OpenSSL ciphers to use for c2s connections. The default value is shown in the example below:
     
    Example:
     
    c2s_ciphers:\n  - HIGH\n  - \"!aNULL\"\n  - \"!eNULL\"\n  - \"!3DES\"\n  - \"@STRENGTH\"\n
    "},{"location":"admin/configuration/toplevel/#c2s_dhfile","title":"c2s_dhfile","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#c2s_protocol_options","title":"c2s_protocol_options","text":"
    [Option, ...] 
     
    List of general SSL options to use for c2s connections. These map to OpenSSL\u2019s set_options(). The default value is shown in the example below:
     
    Example:
     
    c2s_protocol_options:\n  - no_sslv3\n  - cipher_server_preference\n  - no_compression\n
    "},{"location":"admin/configuration/toplevel/#c2s_tls_compression","title":"c2s_tls_compression","text":"
    true | false 
     
    Whether to enable or disable TLS compression for c2s connections. The default value is false.
    "},{"location":"admin/configuration/toplevel/#ca_file","title":"ca_file","text":"
    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 option.
    "},{"location":"admin/configuration/toplevel/#cache_life_time","title":"cache_life_time","text":"
    timeout() 
     
    The time of a cached item to keep in cache. Once it\u2019s 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, oauth_cache_life_time, router_cache_life_time, and sm_cache_life_time.
    "},{"location":"admin/configuration/toplevel/#cache_missed","title":"cache_missed","text":"
    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). Usually you don\u2019t 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, oauth_cache_missed, router_cache_missed, and sm_cache_missed.
    "},{"location":"admin/configuration/toplevel/#cache_size","title":"cache_size","text":"
    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\u2019s 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, oauth_cache_size, router_cache_size, and sm_cache_size.
    "},{"location":"admin/configuration/toplevel/#captcha_cmd","title":"captcha_cmd","text":"
    Path | ModuleName 
     
     improved in 23.01
     
    Full path to a script that generates 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\u2019s 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:
     
    captcha_cmd: /opt/ejabberd-@VERSION@/lib/ejabberd-@SEMVER@/priv/bin/captcha.sh\n
    "},{"location":"admin/configuration/toplevel/#captcha_host","title":"captcha_host","text":"
    String 
     
    Deprecated. Use captcha_url instead.
    "},{"location":"admin/configuration/toplevel/#captcha_limit","title":"captcha_limit","text":"
    pos_integer() | infinity 
     
    Maximum number of 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.
    "},{"location":"admin/configuration/toplevel/#captcha_url","title":"captcha_url","text":"
    URL | auto | undefined 
     
     improved in 23.04
     
    An URL where 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. The default value is auto.
    "},{"location":"admin/configuration/toplevel/#certfiles","title":"certfiles","text":"
    [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\u2019s Encrypt certificates for your domain \"domain.tld\", the configuration will look like this:
     
    certfiles:\n  - /etc/letsencrypt/live/domain.tld/fullchain.pem\n  - /etc/letsencrypt/live/domain.tld/privkey.pem\n
    "},{"location":"admin/configuration/toplevel/#cluster_backend","title":"cluster_backend","text":"
    Backend 
     
    A database backend to use for storing information about cluster. The only available value so far is mnesia.
    "},{"location":"admin/configuration/toplevel/#cluster_nodes","title":"cluster_nodes","text":"
    [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.
    "},{"location":"admin/configuration/toplevel/#default_db","title":"default_db","text":"
    mnesia | sql 
     
    Default persistent storage for ejabberd. Modules and other components (e.g. authentication) may have its own value. The default value is mnesia.
    "},{"location":"admin/configuration/toplevel/#default_ram_db","title":"default_ram_db","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#define_macro","title":"define_macro","text":"
    {MacroName: MacroValue} 
     
    Defines a macro. The value can be any valid arbitrary YAML value. For convenience, it\u2019s 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:
     
    define_macro:\n  DEBUG: debug\n  LOG_LEVEL: DEBUG\n  USERBOB:\n    user: bob@localhost\n\nloglevel: LOG_LEVEL\n\nacl:\n  admin: USERBOB\n
    "},{"location":"admin/configuration/toplevel/#disable_sasl_mechanisms","title":"disable_sasl_mechanisms","text":"
    [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.
    "},{"location":"admin/configuration/toplevel/#disable_sasl_scram_downgrade_protection","title":"disable_sasl_scram_downgrade_protection","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#domain_balancing","title":"domain_balancing","text":"
    {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\u2019s to attribute;     source - by the full JID of the packet\u2019s from attribute;     bare_destination - by the bare JID (without resource) of the     packet\u2019s to attribute; bare_source - by the bare JID (without     resource) of the packet\u2019s from attribute is used. The default     value is random.
       
      •  
     
    Example:
     
    domain_balancing:\n  component.domain.tld:\n    type: destination\n    component_number: 5\n  transport.example.org:\n    type: bare_source\n
    "},{"location":"admin/configuration/toplevel/#ext_api_headers","title":"ext_api_headers","text":"
    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: \"\".
    "},{"location":"admin/configuration/toplevel/#ext_api_http_pool_size","title":"ext_api_http_pool_size","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#ext_api_path_oauth","title":"ext_api_path_oauth","text":"
    Path 
     
    Define the base URI path when performing OAUTH ReST requests. The default value is: \"/oauth\".
    "},{"location":"admin/configuration/toplevel/#ext_api_url","title":"ext_api_url","text":"
    URL 
     
    Define the base URI when performing ReST requests. The default value is: \"http://localhost/api\".
    "},{"location":"admin/configuration/toplevel/#extauth_pool_name","title":"extauth_pool_name","text":"
    Name 
     
    Define the pool name appendix, so the full pool name will be extauth_pool_Name. The default value is the hostname.
    "},{"location":"admin/configuration/toplevel/#extauth_pool_size","title":"extauth_pool_size","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#extauth_program","title":"extauth_program","text":"
    Path 
     
    Indicate in this option the full path to the external authentication script. The script must be executable by ejabberd.
    "},{"location":"admin/configuration/toplevel/#fqdn","title":"fqdn","text":"
    Domain 
     
    A fully qualified domain name that will be used in SASL DIGEST-MD5 authentication. The default is detected automatically.
    "},{"location":"admin/configuration/toplevel/#hide_sensitive_log_data","title":"hide_sensitive_log_data","text":"
    true | false 
     
    A privacy option to not log sensitive data (mostly IP addresses). The default value is false for backward compatibility.
    "},{"location":"admin/configuration/toplevel/#host_config","title":"host_config","text":"
    {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:
     
    hosts:\n  - domain.tld\n  - example.org\n\nauth_method:\n  - sql\n\nhost_config:\n  domain.tld:\n    auth_method:\n      - ldap\n
    "},{"location":"admin/configuration/toplevel/#hosts","title":"hosts","text":"
    [Domain1, Domain2, ...] 
     
    The option defines a list containing one or more domains that ejabberd will serve. This is a mandatory option.
    "},{"location":"admin/configuration/toplevel/#include_config_file","title":"include_config_file","text":"
    [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.
       
      •  
    "},{"location":"admin/configuration/toplevel/#install_contrib_modules","title":"install_contrib_modules","text":"
    [Module, ...] 
     
     added in 23.10
     
    Modules to install from ejabberd-contrib at start time. The default value is an empty list of modules: [].
    "},{"location":"admin/configuration/toplevel/#jwt_auth_only_rule","title":"jwt_auth_only_rule","text":"
    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, \u2026), users that match this rule can only use JWT. The default value is none.
    "},{"location":"admin/configuration/toplevel/#jwt_jid_field","title":"jwt_jid_field","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#jwt_key","title":"jwt_key","text":"
    FilePath 
     
    Path to the file that contains the JWK Key. The default value is undefined.
    "},{"location":"admin/configuration/toplevel/#language","title":"language","text":"
    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\".
    "},{"location":"admin/configuration/toplevel/#ldap_backups","title":"ldap_backups","text":"
    [Host, ...] 
     
    A list of IP addresses or DNS names of LDAP backup servers. When no servers listed in 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\u2019t 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.
    "},{"location":"admin/configuration/toplevel/#ldap_base","title":"ldap_base","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#ldap_deref_aliases","title":"ldap_deref_aliases","text":"
    never | always | finding | searching 
     
    Whether to dereference aliases or not. The default value is never.
    "},{"location":"admin/configuration/toplevel/#ldap_dn_filter","title":"ldap_dn_filter","text":"
    {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\u2019s 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 option if possible.
     
    Example:
     
    ldap_dn_filter:\n  \"(&(name=%s)(owner=%D)(user=%u@%d))\": [sn]\n
    "},{"location":"admin/configuration/toplevel/#ldap_encrypt","title":"ldap_encrypt","text":"
    tls | none 
     
    Whether to encrypt LDAP connection using TLS or not. The default value is none. NOTE: STARTTLS encryption is not supported.
    "},{"location":"admin/configuration/toplevel/#ldap_filter","title":"ldap_filter","text":"
    Filter 
     
    An LDAP filter as defined in RFC4515. There is no default value. Example: \"(&(objectClass=shadowAccount)(memberOf=XMPP Users))\". NOTE: don\u2019t forget to close brackets and don\u2019t use superfluous whitespaces. Also you must not use \"uid\" attribute in the filter because this attribute will be appended to the filter automatically.
    "},{"location":"admin/configuration/toplevel/#ldap_password","title":"ldap_password","text":"
    Password 
     
    Bind password. The default value is an empty string.
    "},{"location":"admin/configuration/toplevel/#ldap_port","title":"ldap_port","text":"
    1..65535 
     
    Port to connect to your LDAP server. The default port is 389 if encryption is disabled and 636 if encryption is enabled.
    "},{"location":"admin/configuration/toplevel/#ldap_rootdn","title":"ldap_rootdn","text":"
    RootDN 
     
    Bind Distinguished Name. The default value is an empty string, which means \"anonymous connection\".
    "},{"location":"admin/configuration/toplevel/#ldap_servers","title":"ldap_servers","text":"
    [Host, ...] 
     
    A list of IP addresses or DNS names of your LDAP servers. The default value is [localhost].
    "},{"location":"admin/configuration/toplevel/#ldap_tls_cacertfile","title":"ldap_tls_cacertfile","text":"
    Path 
     
    A path to a file containing PEM encoded CA certificates. This option is required when TLS verification is enabled.
    "},{"location":"admin/configuration/toplevel/#ldap_tls_certfile","title":"ldap_tls_certfile","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#ldap_tls_depth","title":"ldap_tls_depth","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#ldap_tls_verify","title":"ldap_tls_verify","text":"
    false | soft | hard 
     
    This option specifies whether to verify LDAP server certificate or not when TLS is enabled. When hard is set, ejabberd doesn\u2019t 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.
    "},{"location":"admin/configuration/toplevel/#ldap_uids","title":"ldap_uids","text":"
    [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\u2019s part of the JID and AttrFormat must contain one and only one pattern variable \"%u\" which will be replaced by the user\u2019s part of the JID. For example, \"%u@example.org\". If the value is in the form of [Attr] then AttrFormat is assumed to be \"%u\".
    "},{"location":"admin/configuration/toplevel/#listen","title":"listen","text":"
    [Options, ...] 
     
    The option for listeners configuration. See the Listen Modules section for details.
    "},{"location":"admin/configuration/toplevel/#log_burst_limit_count","title":"log_burst_limit_count","text":"
    Number 
     
     added in 22.10
     
    The number of messages to accept in log_burst_limit_window_time period before starting to drop them. Default 500
    "},{"location":"admin/configuration/toplevel/#log_burst_limit_window_time","title":"log_burst_limit_window_time","text":"
    Number 
     
     added in 22.10
     
    The time period to rate-limit log messages by. Defaults to 1 second.
    "},{"location":"admin/configuration/toplevel/#log_modules_fully","title":"log_modules_fully","text":"
    [Module, ...] 
     
     added in 23.01
     
    List of modules that will log everything independently from the general loglevel option.
    "},{"location":"admin/configuration/toplevel/#log_rotate_count","title":"log_rotate_count","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#log_rotate_size","title":"log_rotate_size","text":"
    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).
    "},{"location":"admin/configuration/toplevel/#loglevel","title":"loglevel","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#max_fsm_queue","title":"max_fsm_queue","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#modules","title":"modules","text":"
    {Module: Options} 
     
    The option for modules configuration. See Modules section for details.
    "},{"location":"admin/configuration/toplevel/#negotiation_timeout","title":"negotiation_timeout","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#net_ticktime","title":"net_ticktime","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#new_sql_schema","title":"new_sql_schema","text":"
    true | false 
     
    Whether to use new SQL schema. All schemas are located at https://github.com/processone/ejabberd/tree/24.02/sql. 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.
    "},{"location":"admin/configuration/toplevel/#oauth_access","title":"oauth_access","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#oauth_cache_life_time","title":"oauth_cache_life_time","text":"
    timeout() 
     
    Same as cache_life_time, but applied to OAuth cache only. If not set, the value from cache_life_time will be used.
    "},{"location":"admin/configuration/toplevel/#oauth_cache_missed","title":"oauth_cache_missed","text":"
    true | false 
     
    Same as cache_missed, but applied to OAuth cache only. If not set, the value from cache_missed will be used.
    "},{"location":"admin/configuration/toplevel/#oauth_cache_rest_failure_life_time","title":"oauth_cache_rest_failure_life_time","text":"
    timeout() 
     
     added in 21.01
     
    The time that a failure in OAuth ReST is cached. The default value is infinity.
    "},{"location":"admin/configuration/toplevel/#oauth_cache_size","title":"oauth_cache_size","text":"
    pos_integer() | infinity 
     
    Same as cache_size, but applied to OAuth cache only. If not set, the value from cache_size will be used.
    "},{"location":"admin/configuration/toplevel/#oauth_client_id_check","title":"oauth_client_id_check","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#oauth_db_type","title":"oauth_db_type","text":"
    mnesia | sql 
     
    Database backend to use for OAuth authentication. The default value is picked from default_db option, or if it\u2019s not set, mnesia will be used.
    "},{"location":"admin/configuration/toplevel/#oauth_expire","title":"oauth_expire","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#oauth_use_cache","title":"oauth_use_cache","text":"
    true | false 
     
    Same as use_cache, but applied to OAuth cache only. If not set, the value from use_cache will be used.
    "},{"location":"admin/configuration/toplevel/#oom_killer","title":"oom_killer","text":"
    true | false 
     
    Enable or disable OOM (out-of-memory) killer. When system memory raises above the limit defined in 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.
    "},{"location":"admin/configuration/toplevel/#oom_queue","title":"oom_queue","text":"
    Size 
     
    Trigger OOM killer when some of the running Erlang processes have messages queue above this Size. Note that such processes won\u2019t be killed if oom_killer option is set to false or if oom_watermark is not reached yet.
    "},{"location":"admin/configuration/toplevel/#oom_watermark","title":"oom_watermark","text":"
    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 option). Later, when memory drops below this Percent, OOM killer is deactivated. The default value is 80 percents.
    "},{"location":"admin/configuration/toplevel/#outgoing_s2s_families","title":"outgoing_s2s_families","text":"
    [ipv6 | ipv4, ...] 
     
     changed in 23.01
     
    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 and Erlang/OTP 22, or newer versions of them.
    "},{"location":"admin/configuration/toplevel/#outgoing_s2s_ipv4_address","title":"outgoing_s2s_ipv4_address","text":"
    Address 
     
     added in 20.12
     
    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.
    "},{"location":"admin/configuration/toplevel/#outgoing_s2s_ipv6_address","title":"outgoing_s2s_ipv6_address","text":"
    Address 
     
     added in 20.12
     
    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.
    "},{"location":"admin/configuration/toplevel/#outgoing_s2s_port","title":"outgoing_s2s_port","text":"
    1..65535 
     
    A port number to use for outgoing s2s connections when the target server doesn\u2019t have an SRV record. The default value is 5269.
    "},{"location":"admin/configuration/toplevel/#outgoing_s2s_timeout","title":"outgoing_s2s_timeout","text":"
    timeout() 
     
    The timeout in seconds for outgoing S2S connection attempts. The default value is 10 seconds.
    "},{"location":"admin/configuration/toplevel/#pam_service","title":"pam_service","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#pam_userinfotype","title":"pam_userinfotype","text":"
    username | jid 
     
    This option defines what type of information about the user ejabberd provides to the PAM service: only the username, or the user\u2019s JID. Default is username.
    "},{"location":"admin/configuration/toplevel/#pgsql_users_number_estimate","title":"pgsql_users_number_estimate","text":"
    true | false 
     
    Whether to use PostgreSQL estimation when counting registered users. The default value is false.
    "},{"location":"admin/configuration/toplevel/#queue_dir","title":"queue_dir","text":"
    Directory 
     
    If queue_type option is set to file, use this Directory to store file queues. The default is to keep queues inside Mnesia directory.
    "},{"location":"admin/configuration/toplevel/#queue_type","title":"queue_type","text":"
    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 option where file queues will be placed. The default value is ram.
    "},{"location":"admin/configuration/toplevel/#redis_connect_timeout","title":"redis_connect_timeout","text":"
    timeout() 
     
    A timeout to wait for the connection to be re-established to the Redis server. The default is 1 second.
    "},{"location":"admin/configuration/toplevel/#redis_db","title":"redis_db","text":"
    Number 
     
    Redis database number. The default is 0.
    "},{"location":"admin/configuration/toplevel/#redis_password","title":"redis_password","text":"
    Password 
     
    The password to the Redis server. The default is an empty string, i.e. no password.
    "},{"location":"admin/configuration/toplevel/#redis_pool_size","title":"redis_pool_size","text":"
    Number 
     
    The number of simultaneous connections to the Redis server. The default value is 10.
    "},{"location":"admin/configuration/toplevel/#redis_port","title":"redis_port","text":"
    1..65535 
     
    The port where the Redis server is accepting connections. The default is 6379.
    "},{"location":"admin/configuration/toplevel/#redis_queue_type","title":"redis_queue_type","text":"
    ram | file 
     
    The type of request queue for the Redis server. See description of queue_type option for the explanation. The default value is the value defined in queue_type or ram if the latter is not set.
    "},{"location":"admin/configuration/toplevel/#redis_server","title":"redis_server","text":"
    Hostname 
     
    A hostname or an IP address of the Redis server. The default is localhost.
    "},{"location":"admin/configuration/toplevel/#registration_timeout","title":"registration_timeout","text":"
    timeout() 
     
    This is a global option for module 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.
    "},{"location":"admin/configuration/toplevel/#resource_conflict","title":"resource_conflict","text":"
    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. 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.
    "},{"location":"admin/configuration/toplevel/#router_cache_life_time","title":"router_cache_life_time","text":"
    timeout() 
     
    Same as cache_life_time, but applied to routing table cache only. If not set, the value from cache_life_time will be used.
    "},{"location":"admin/configuration/toplevel/#router_cache_missed","title":"router_cache_missed","text":"
    true | false 
     
    Same as cache_missed, but applied to routing table cache only. If not set, the value from cache_missed will be used.
    "},{"location":"admin/configuration/toplevel/#router_cache_size","title":"router_cache_size","text":"
    pos_integer() | infinity 
     
    Same as cache_size, but applied to routing table cache only. If not set, the value from cache_size will be used.
    "},{"location":"admin/configuration/toplevel/#router_db_type","title":"router_db_type","text":"
    mnesia | redis | sql 
     
    Database backend to use for routing information. The default value is picked from default_ram_db option, or if it\u2019s not set, mnesia will be used.
    "},{"location":"admin/configuration/toplevel/#router_use_cache","title":"router_use_cache","text":"
    true | false 
     
    Same as use_cache, but applied to routing table cache only. If not set, the value from use_cache will be used.
    "},{"location":"admin/configuration/toplevel/#rpc_timeout","title":"rpc_timeout","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#s2s_access","title":"s2s_access","text":"
    Access 
     
    This Access Rule 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.
    "},{"location":"admin/configuration/toplevel/#s2s_cafile","title":"s2s_cafile","text":"
    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 will be used.
     
    You can use host_config to specify this option per-vhost.
    "},{"location":"admin/configuration/toplevel/#s2s_ciphers","title":"s2s_ciphers","text":"
    [Cipher, ...] 
     
    A list of OpenSSL ciphers to use for s2s connections. The default value is shown in the example below:
     
    Example:
     
    s2s_ciphers:\n  - HIGH\n  - \"!aNULL\"\n  - \"!eNULL\"\n  - \"!3DES\"\n  - \"@STRENGTH\"\n
    "},{"location":"admin/configuration/toplevel/#s2s_dhfile","title":"s2s_dhfile","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#s2s_dns_retries","title":"s2s_dns_retries","text":"
    Number 
     
    DNS resolving retries. The default value is 2.
    "},{"location":"admin/configuration/toplevel/#s2s_dns_timeout","title":"s2s_dns_timeout","text":"
    timeout() 
     
    The timeout for DNS resolving. The default value is 10 seconds.
    "},{"location":"admin/configuration/toplevel/#s2s_max_retry_delay","title":"s2s_max_retry_delay","text":"
    timeout() 
     
    The maximum allowed delay for s2s connection retry to connect after a failed connection attempt. The default value is 300 seconds (5 minutes).
    "},{"location":"admin/configuration/toplevel/#s2s_protocol_options","title":"s2s_protocol_options","text":"
    [Option, ...] 
     
    List of general SSL options to use for s2s connections. These map to OpenSSL\u2019s set_options(). The default value is shown in the example below:
     
    Example:
     
    s2s_protocol_options:\n  - no_sslv3\n  - cipher_server_preference\n  - no_compression\n
    "},{"location":"admin/configuration/toplevel/#s2s_queue_type","title":"s2s_queue_type","text":"
    ram | file 
     
    The type of a queue for s2s packets. See description of queue_type option for the explanation. The default value is the value defined in queue_type or ram if the latter is not set.
    "},{"location":"admin/configuration/toplevel/#s2s_timeout","title":"s2s_timeout","text":"
    timeout() 
     
    A time to wait before closing an idle s2s connection. The default value is 1 hour.
    "},{"location":"admin/configuration/toplevel/#s2s_tls_compression","title":"s2s_tls_compression","text":"
    true | false 
     
    Whether to enable or disable TLS compression for s2s connections. The default value is false.
    "},{"location":"admin/configuration/toplevel/#s2s_use_starttls","title":"s2s_use_starttls","text":"
    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).
    "},{"location":"admin/configuration/toplevel/#s2s_zlib","title":"s2s_zlib","text":"
    true | false 
     
    Whether to use zlib compression (as defined in XEP-0138) or not. The default value is false. WARNING: this type of compression is nowadays considered insecure.
    "},{"location":"admin/configuration/toplevel/#shaper","title":"shaper","text":"
    {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 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:
     
    shaper:\n  normal: 1000\n  fast: 50000\n
    "},{"location":"admin/configuration/toplevel/#shaper_rules","title":"shaper_rules","text":"
    {ShaperRuleName: {Number|ShaperName: ACLRule|ACLName}} 
     
    An entry allowing to declaring shaper to use for matching user/hosts. Semantics is similar to access_rules option, the only difference is that instead using allow or deny, a name of a shaper (defined in shaper option) or a positive number should be used.
     
    Example:
     
    shaper_rules:\n  connections_limit:\n    10:\n      user: peter@example.com\n    100: admin\n    5: all\n  download_speed:\n    fast: admin\n    slow: anonymous_users\n    normal: all\n  log_days: 30\n
    "},{"location":"admin/configuration/toplevel/#sm_cache_life_time","title":"sm_cache_life_time","text":"
    timeout() 
     
    Same as cache_life_time, but applied to client sessions table cache only. If not set, the value from cache_life_time will be used.
    "},{"location":"admin/configuration/toplevel/#sm_cache_missed","title":"sm_cache_missed","text":"
    true | false 
     
    Same as cache_missed, but applied to client sessions table cache only. If not set, the value from cache_missed will be used.
    "},{"location":"admin/configuration/toplevel/#sm_cache_size","title":"sm_cache_size","text":"
    pos_integer() | infinity 
     
    Same as cache_size, but applied to client sessions table cache only. If not set, the value from cache_size will be used.
    "},{"location":"admin/configuration/toplevel/#sm_db_type","title":"sm_db_type","text":"
    mnesia | redis | sql 
     
    Database backend to use for client sessions information. The default value is picked from default_ram_db option, or if it\u2019s not set, mnesia will be used.
    "},{"location":"admin/configuration/toplevel/#sm_use_cache","title":"sm_use_cache","text":"
    true | false 
     
    Same as use_cache, but applied to client sessions table cache only. If not set, the value from use_cache will be used.
    "},{"location":"admin/configuration/toplevel/#sql_connect_timeout","title":"sql_connect_timeout","text":"
    timeout() 
     
    A time to wait for connection to an SQL server to be established. The default value is 5 seconds.
    "},{"location":"admin/configuration/toplevel/#sql_database","title":"sql_database","text":"
    Database 
     
    An SQL database name. For SQLite this must be a full path to a database file. The default value is ejabberd.
    "},{"location":"admin/configuration/toplevel/#sql_flags","title":"sql_flags \ud83d\udfe4","text":"
    [mysql_alternative_upsert] 
     
     added in 24.02
     
    This option accepts a list of SQL flags, and is empty by default. mysql_alternative_upsert forces the alternative upsert implementation in MySQL.
    "},{"location":"admin/configuration/toplevel/#sql_keepalive_interval","title":"sql_keepalive_interval","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#sql_odbc_driver","title":"sql_odbc_driver","text":"
    Path 
     
     added in 20.12
     
    Path to the ODBC driver to use to connect to a Microsoft SQL Server database. This option only applies if the sql_type option is set to mssql and sql_server is not an ODBC connection string. The default value is: libtdsodbc.so
    "},{"location":"admin/configuration/toplevel/#sql_password","title":"sql_password","text":"
    Password 
     
    The password for SQL authentication. The default is empty string.
    "},{"location":"admin/configuration/toplevel/#sql_pool_size","title":"sql_pool_size","text":"
    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\u2019s not recommended to change it due to potential race conditions.
    "},{"location":"admin/configuration/toplevel/#sql_port","title":"sql_port","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#sql_prepared_statements","title":"sql_prepared_statements","text":"
    true | false 
     
     added in 20.01
     
    This option is true by default, and is useful to disable prepared statements. The option is valid for PostgreSQL and MySQL.
    "},{"location":"admin/configuration/toplevel/#sql_query_timeout","title":"sql_query_timeout","text":"
    timeout() 
     
    A time to wait for an SQL query response. The default value is 60 seconds.
    "},{"location":"admin/configuration/toplevel/#sql_queue_type","title":"sql_queue_type","text":"
    ram | file 
     
    The type of a request queue for the SQL server. See description of queue_type option for the explanation. The default value is the value defined in queue_type or ram if the latter is not set.
    "},{"location":"admin/configuration/toplevel/#sql_server","title":"sql_server","text":"
    Host 
     
     improved in 23.04
     
    The hostname or IP address of the SQL server. For sql_type mssql or odbc this can also be an ODBC connection string. The default value is localhost.
    "},{"location":"admin/configuration/toplevel/#sql_ssl","title":"sql_ssl","text":"
    true | false 
     
     improved in 20.03
     
    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.
    "},{"location":"admin/configuration/toplevel/#sql_ssl_cafile","title":"sql_ssl_cafile","text":"
    Path 
     
    A path to a file with CA root certificates that will be used to verify SQL connections. Implies sql_ssl and 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.
    "},{"location":"admin/configuration/toplevel/#sql_ssl_certfile","title":"sql_ssl_certfile","text":"
    Path 
     
    A path to a certificate file that will be used for SSL connections to the SQL server. Implies sql_ssl option is set to true. There is no default which means ejabberd won\u2019t provide a client certificate to the SQL server. This option has no effect for MS SQL.
    "},{"location":"admin/configuration/toplevel/#sql_ssl_verify","title":"sql_ssl_verify","text":"
    true | false 
     
    Whether to verify SSL connection to the SQL server against CA root certificates defined in sql_ssl_cafile option. Implies sql_ssl option is set to true. This option has no effect for MS SQL. The default value is false.
    "},{"location":"admin/configuration/toplevel/#sql_start_interval","title":"sql_start_interval","text":"
    timeout() 
     
    A time to wait before retrying to restore failed SQL connection. The default value is 30 seconds.
    "},{"location":"admin/configuration/toplevel/#sql_type","title":"sql_type","text":"
    mssql | mysql | odbc | pgsql | sqlite 
     
    The type of an SQL connection. The default is odbc.
    "},{"location":"admin/configuration/toplevel/#sql_username","title":"sql_username","text":"
    Username 
     
    A user name for SQL authentication. The default value is ejabberd.
    "},{"location":"admin/configuration/toplevel/#trusted_proxies","title":"trusted_proxies","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#update_sql_schema","title":"update_sql_schema","text":"
    true | false 
     
     added in 23.10
     
    Allow ejabberd to update SQL schema. The default value is false.
    "},{"location":"admin/configuration/toplevel/#use_cache","title":"use_cache","text":"
    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, oauth_use_cache, router_use_cache, and sm_use_cache.
    "},{"location":"admin/configuration/toplevel/#validate_stream","title":"validate_stream","text":"
    true | false 
     
    Whether to validate any incoming XML packet according to the schemas of supported XMPP extensions. WARNING: the validation is only intended for the use by client developers - don\u2019t enable it in production environment. The default value is false.
    "},{"location":"admin/configuration/toplevel/#version","title":"version","text":"
    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 module. The default value is obtained at compile time from the underlying version control system.
    "},{"location":"admin/configuration/toplevel/#websocket_origin","title":"websocket_origin","text":"
    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\".
    "},{"location":"admin/configuration/toplevel/#websocket_ping_interval","title":"websocket_ping_interval","text":"
    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\u2019t 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.
    "},{"location":"admin/configuration/toplevel/#websocket_timeout","title":"websocket_timeout","text":"
    timeout() 
     
    Amount of time without any communication after which the connection would be closed. The default value is 300 seconds.
    "},{"location":"admin/contrib/","title":"External authentication","text":"
    There are examples of external authentication scripts in many different languages in the page: https://ejabberd.im/extauth
    "},{"location":"admin/contrib/#main-contribution-repository","title":"Main contribution repository","text":"
    Check also the contributions hosted in the ejabberd-contrib Github repository.
    "},{"location":"admin/contrib/#ejabberd-api-libraries","title":"ejabberd API libraries","text":"
    Here is a ejabberd API implementations allowing to ease ejabberd integration with your own backends:
     
       
    • Pyejabberd:   Client library for ejabberd XMLRPC API, in Python, by Dirkmoors, MIT license.     See https://pypi.python.org/pypi/pyejabberd     and https://github.com/dirkmoors/pyejabberd
      •  
    "},{"location":"admin/contrib/#old-obsolete-contributions","title":"Old / obsolete contributions","text":"
    Finally, there is an old list of contributions that were developed for ejabberd 2.x in: https://ejabberd.im/contributions
    "},{"location":"admin/ejabberdctl/","title":"ejabberctl Reference","text":"
    Here are main features covered by ejabberdctl command-line tool:
     
       
    • ejabberdctl overview
      •  
    • Administration Commands API
      •  
    • Multi User Chat Administration Commands
      •  
    "},{"location":"admin/ejabberdctl/muc-admin/","title":"Multi User Chat Administration Commands","text":""},{"location":"admin/ejabberdctl/muc-admin/#prerequisite","title":"Prerequisite","text":"
    Most of the command to manage MUC service depends on the activation of mod_muc_admin module in ejabberd.
     
    mod_muc_admin is included in ejabberd main code base since ejabberd 15.04.
     
    To enable mod_muc_admin-dependant ejabberdctl commands, you just need to add mod_muc_admin in modules section of ejabberd config file.
     
    For example, in ejabberd.yml format:
     
    modules:\n  mod_muc_admin: {}\n
    "},{"location":"admin/ejabberdctl/muc-admin/#commands","title":"Commands","text":"
    The most updated and detailed list of commands for managing a MUC service and MUC rooms is available in the muc API tag and the muc_room API tag.
    "},{"location":"admin/ejabberdctl/muc-admin/#online-rooms","title":"Online Rooms","text":"
    List existing rooms ('global' to get all vhosts).
     
    ejabberdctl muc_online_rooms [global]\n
    "},{"location":"admin/ejabberdctl/muc-admin/#unregister-nickname","title":"Unregister nickname","text":"
    Unregister the nick in the MUC service.
     
    ejabberdctl muc_unregister_nick nickname\n
    "},{"location":"admin/ejabberdctl/muc-admin/#create-muc-room","title":"Create MUC room","text":"
    Create a MUC room name@service in host.
     
    ejabberdctl create_room room_name muc_service xmpp_domain\n
    "},{"location":"admin/ejabberdctl/muc-admin/#destroy-muc-room","title":"Destroy MUC room","text":"
    Destroy a MUC chat room.
     
    ejabberdctl destroy_room room_name muc_service\n
    "},{"location":"admin/ejabberdctl/muc-admin/#create-multiple-rooms-from-file","title":"Create multiple rooms from file","text":"
    Create the rooms listed in a local file.
     
    ejabberdctl create_rooms_file filename\n
     
    TODO: Describe the file format.
    "},{"location":"admin/ejabberdctl/muc-admin/#destroy-multiple-rooms-from-file","title":"Destroy multiple rooms from file","text":"
    Destroy the rooms indicated in a local file.
     
    ejabberdctl destroy_rooms_file filename\n
    "},{"location":"admin/ejabberdctl/muc-admin/#list-unused-muc-rooms","title":"List unused MUC rooms","text":"
    List rooms that have not been used in several days on an XMPP domain.
     
    ejabberdctl rooms_unused_list xmpp_domain number_of_days\n
    "},{"location":"admin/ejabberdctl/muc-admin/#destroy-unused-muc-rooms","title":"Destroy unused MUC rooms","text":"
    Destroy rooms that have not been used in several days on an XMPP domain.
     
    ejabberdctl rooms_unused_destroy xmpp_domain number_of_days\n
    "},{"location":"admin/ejabberdctl/muc-admin/#list-rooms-joined-by-a-given-user","title":"List rooms joined by a given user","text":"
    Get the list of rooms where a user is occupant.
     
    ejabberdctl get_user_rooms user_real_jid xmpp_domain\n
    "},{"location":"admin/ejabberdctl/muc-admin/#list-the-occupants-of-a-muc-room","title":"List the occupants of a MUC room","text":"
    Get the list of occupants of a MUC room.
     
    ejabberdctl get_room_occupants room_name muc_service\n
    "},{"location":"admin/ejabberdctl/muc-admin/#retrieve-number-of-occupants-in-a-muc-room","title":"Retrieve number of occupants in a MUC room","text":"
    Get the number of occupants of a MUC room.
     
    ejabberdctl get_room_occupants_number room_name muc_service\n
    "},{"location":"admin/ejabberdctl/muc-admin/#invite-several-users-to-a-muc-room","title":"Invite several users to a MUC room","text":"
    Send a direct invitation to several JIDs. Password and Message can also be: none. Users JIDs are separated with ':'.
     
    ejabberdctl send_direct_invitation room_name muc_service password reason jid1[:jid2]\n
    "},{"location":"admin/ejabberdctl/muc-admin/#change-option-for-a-muc-room","title":"Change option for a MUC room","text":"
    Change an option in a MUC room.
     
    ejabberdctl change_room_option room_name muc_service option value\n
    "},{"location":"admin/ejabberdctl/muc-admin/#get-options-from-a-muc-room","title":"Get options from a MUC room","text":"
    Get options from a MUC room.
     
    ejabberdctl get_room_options room_name muc_service\n
    "},{"location":"admin/ejabberdctl/muc-admin/#change-affiliation-for-a-user-in-a-muc-room","title":"Change affiliation for a user in a MUC room","text":"
    Change an affiliation in a MUC room. Affiliation can be one of: owner, admin, member, outcast, none.
     
    ejabberdctl set_room_affiliation room_name muc_service user_jid affiliation\n
    "},{"location":"admin/ejabberdctl/muc-admin/#get-affiliations-for-a-muc-room","title":"Get affiliations for a MUC room","text":"
    Get the list of affiliations of a MUC room.
     
    ejabberdctl get_room_affiliations room_name muc_service\n
    "},{"location":"admin/guide/","title":"Advanced ejabberd Administration","text":"
       
    • Clustering ejabberd
      •  
    • Managing an ejabberd server
      •  
    • MQTT Support
      •  
    • Securing ejabberd
      •  
    • Troubleshooting ejabberd
      •  
    • Unattended installation
      •  
    • XMPP Extensions, and how to support them
      •  
    "},{"location":"admin/guide/clustering/","title":"Clustering","text":""},{"location":"admin/guide/clustering/#purpose","title":"Purpose","text":"
    The purpose of ejabberd clustering is to be able to use several servers for a single or small group of large domains, for fault-tolerance and scalability.
     
    Note that you do not necessarily need clustering if you want to run two large domains independently. You may simply want to run two different independent servers.
     
    However, to build reliable service and support large user base, clustering is a must have feature.
    "},{"location":"admin/guide/clustering/#how-it-works","title":"How it Works","text":"
    A XMPP domain is served by one or more ejabberd nodes. These nodes can be run on different machines that are connected via a network. They all must have the ability to connect to port 4369 of all another nodes, and must have the same magic cookie (see Erlang/OTP documentation, in other words the file ~ejabberd/.erlang.cookie must be the same on all nodes). This is needed because all nodes exchange information about connected users, s2s connections, registered services, etc\u2026
     
    Each ejabberd node has the following modules:
     
       
    • router
      •  
    • local router
      •  
    • session manager
      •  
    • s2s manager
      •  
    "},{"location":"admin/guide/clustering/#router","title":"Router","text":"
    This module is the main router of XMPP packets on each node. It routes them based on their destination\u2019s domains. It uses a global routing table. The domain of the packet\u2019s destination is searched in the routing table, and if it is found, the packet is routed to the appropriate process. If not, it is sent to the s2s manager.
    "},{"location":"admin/guide/clustering/#local-router","title":"Local Router","text":"
    This module routes packets which have a destination domain equal to one of this server\u2019s host names. If the destination JID has a non-empty user part, it is routed to the session manager, otherwise it is processed depending on its content.
    "},{"location":"admin/guide/clustering/#session-manager","title":"Session Manager","text":"
    This module routes packets to local users. It looks up to which user resource a packet must be sent via a presence table. Then the packet is either routed to the appropriate c2s process, or stored in offline storage, or bounced back.
    "},{"location":"admin/guide/clustering/#s2s-manager","title":"s2s Manager","text":"
    This module routes packets to other XMPP servers. First, it checks if an opened s2s connection from the domain of the packet\u2019s source to the domain of the packet\u2019s destination exists. If that is the case, the s2s manager routes the packet to the process serving this connection, otherwise a new connection is opened.
    "},{"location":"admin/guide/clustering/#before-you-get-started","title":"Before you get started","text":"
    Before you start implementing clustering, there are a few things you need to take into account:
     
       
    • Cluster should be set up in a single data center: The clustering in   ejabberd Community Edition relies on low latency networking. While it may   work across regions, it is recommended that you run an ejabberd   cluster in a single Amazon region.
      •  
    • Clustering relies on Erlang features and Mnesia shared schemas. Before   getting started, it is best to get familiar with the Erlang environment   as this guide will heavily reference Erlang terms.
      •  
    "},{"location":"admin/guide/clustering/#clustering-setup","title":"Clustering Setup","text":""},{"location":"admin/guide/clustering/#adding-a-node-to-a-cluster","title":"Adding a node to a cluster","text":"
    Suppose you have already configured ejabberd on one node named ejabberd01. Let's create an additional node (ejabberd02) and connect them together.
     
       
    1. Copy the /home/ejabberd/.erlang.cookie file from ejabberd01 to    ejabberd02.
      2.  
     
    Alternatively you could pass the -setcookie <value>    option to all erl commands below.
     
       
    1.  
      Make sure your new ejabberd node is properly configured. Usually,    you want to have the same ejabberd.yml config file on the new node that on the    other cluster nodes.
       
      2.  
    2.  
      Adding a node to the cluster is done by starting a new ejabberd node within the same network, and running join_cluster from a cluster node. On the ejabberd02 node for example, as ejabberd is already started, run the following command as the ejabberd daemon user, using the ejabberdctl script:
       
      3.  
     
    ejabberdctl --no-timeout join_cluster 'ejabberd@ejabberd01'\n
     
    This enables ejabberd's internal replications to be launched across all nodes so new nodes can start receiving messages from other nodes and be registered in the routing tables.
    "},{"location":"admin/guide/clustering/#removing-a-node-from-the-cluster","title":"Removing a node from the cluster","text":"
    To remove a node from the cluster, it just needs to be shut down. There is no specific delay for the cluster to figure out that the node is gone, the node is immediately removed from other router entries. All clients directly connected to the stopped node are disconnected, and should reconnect to other nodes.
     
    If the cluster is used behind a load balancer and the node has been removed from the load balancer, no new clients should be connecting to that node but established connections should be kept, thus allowing to remove a node smoothly, by stopping it after most clients disconnected by themselves. If the node is started again, it's immediately attached back to the cluster until it has been explicitly removed permanently from the cluster.
     
    To permanently remove a running node from the cluster, the leave_cluster command must be run as the ejabberd daemon user, from one node of the cluster:
     
    ejabberdctl leave_cluster 'ejabberd@ejabberd02'\n
     
    The removed node must be running while calling leave_cluster to make it permanently removed. It's then immediately stopped.
    "},{"location":"admin/guide/clustering/#restarting-cluster-nodes","title":"Restarting cluster nodes","text":"
    Ejabberd Community Server uses mnesia internal database to manage cluster and internode synchronisation. As a result, you may restart ejabberd nodes as long as there is at least one running node. If you stop the last running node of a cluster, you MUST restart that node first in order to get a running service back.
    "},{"location":"admin/guide/clustering/#service-load-balancing","title":"Service Load-Balancing","text":""},{"location":"admin/guide/clustering/#domain-load-balancing-algorithm","title":"Domain Load-Balancing Algorithm","text":"
    ejabberd includes 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 cluster and that the traffic will be automatically distributed.
     
    The default distribution algorithm attempts to deliver to a local instance of a component. If several local instances are available, one instance is chosen at random. If no instance is available locally, one instance is randomly chosen among the remote component instances.
     
    If you need a different behaviour, you can change the load balancing behaviour with the domain_balancing option.
    "},{"location":"admin/guide/clustering/#load-balancing-buckets","title":"Load-Balancing Buckets","text":"
    When there is a risk of failure for a given component, domain balancing can cause service trouble. If one component is failing the service will not work correctly unless the sessions are rebalanced.
     
    In this case, it is best to limit the problem to the sessions handled by the failing component. This is what the component_number option does, making the load balancing algorithm not dynamic, but sticky on a fix number of component instances. Check domain_balancing top-level option documentation for details.
    "},{"location":"admin/guide/managing/","title":"Managing an ejabberd server","text":""},{"location":"admin/guide/managing/#ejabberdctl","title":"ejabberdctl","text":"
    With the ejabberdctl command line administration script you can execute ejabberdctl commands (described in the next section, ejabberdctl Commands) and also many general ejabberd commands (described in section ejabberd Commands). This means you can start, stop and perform many other administrative tasks in a local or remote ejabberd server (by providing the argument \u2013node NODENAME).
     
    The ejabberdctl script can be configured in the file ejabberdctl.cfg. This file includes detailed information about each configurable option. See section Erlang Runtime System.
     
    The ejabberdctl script returns a numerical status code. Success is represented by 0, error is represented by 1, and other codes may be used for specific results. This can be used by other scripts to determine automatically if a command succeeded or failed, for example using: echo $?
     
    To restrict what commands can be executed; see API Permissions.
    "},{"location":"admin/guide/managing/#bash-completion","title":"Bash Completion","text":"
    If you use Bash, you can get Bash completion for ejabberdctl commands names.
     
    Some methods to enable that feature:
     
       
    •  
      Copy the file tools/ejabberdctl.bc to the directory /etc/bash_completion.d/ (in Debian, Ubuntu, Fedora and maybe others)
       
      •  
    •  
      Or add to your $HOME/.bashrc a line similar to:
       
      source /path/to/ejabberd/tools/ejabberdctl.bc\n
       
      •  
     
    When ejabberd is running in the machine, type ejabberdctl in a console and press the TAB key.
     
    The first time this is used, the list of commands is extracted from ejabberd and stored in a file in /tmp/. The next time, that file is reused for faster responses.
    "},{"location":"admin/guide/managing/#ejabberdctl-commands","title":"ejabberdctl Commands","text":"
    When ejabberdctl is executed without any parameter, it displays the available options. If there isn't an ejabberd server running, the available parameters are:
     
       
    •  
      start:   Start ejabberd in background mode. This is the default method.
       
      •  
    •  
      debug:   Attach an Erlang shell to an already existing ejabberd server.  This allows to execute commands interactively in the ejabberd  server.
       
      •  
    •  
      live:   Start ejabberd in live mode: the shell keeps attached to the  started server, showing log messages and allowing to execute  interactive commands.
       
      •  
     
    If there is an ejabberd server running in the system, ejabberdctl shows the ejabberdctl commands described below and all the ejabberd commands available in that server (see List of ejabberd Commands).
     
    The ejabberdctl commands are:
     
       
    •  
      help:   Get help about ejabberdctl or any available command. Try  ejabberdctl help help.
       
      •  
    •  
      status:   Check the status of the ejabberd server.
       
      •  
    •  
      stop:   Stop the ejabberd server.
       
      •  
    •  
      restart:   Restart the ejabberd server.
       
      •  
    •  
      mnesia:   Get information about the Mnesia database.
       
      •  
    "},{"location":"admin/guide/managing/#ejabberd-commands","title":"ejabberd Commands","text":"
    Please go to the API section.
    "},{"location":"admin/guide/managing/#erlang-runtime-system","title":"Erlang Runtime System","text":"
    ejabberd is an Erlang/OTP application that runs inside an Erlang runtime system. This system is configured using environment variables and command line parameters. The ejabberdctl administration script uses many of those possibilities. You can configure some of them with the file ejabberdctl.cfg, which includes detailed description about them. This section describes for reference purposes all the environment variables and command line parameters.
     
    The environment variables:
     
    EJABBERD_CONFIG_PATH:   Path to the ejabberd configuration file.
     
    EJABBERD_MSGS_PATH:   Path to the directory with translated strings.
     
    EJABBERD_LOG_PATH:   Path to the ejabberd service log file.
     
    EJABBERD_SO_PATH:   Path to the directory with binary system libraries.
     
    EJABBERD_DOC_PATH:   Path to the directory with ejabberd documentation.
     
    EJABBERD_PID_PATH:   Path to the PID file that ejabberd can create when started.
     
    HOME:   Path to the directory that is considered ejabberd\u2019s home. This  path is used to read the file .erlang.cookie.
     
    ERL_CRASH_DUMP:   Path to the file where crash reports will be dumped.
     
    ERL_EPMD_ADDRESS:   IP address where epmd listens for connections (see epmd).
     
    ERL_INETRC:   Indicates which IP name resolution to use. If using -sname,  specify either this option or -kernel inetrc filepath.
     
    ERL_MAX_PORTS:   Maximum number of simultaneously open Erlang ports.
     
    ERL_MAX_ETS_TABLES:   Maximum number of ETS and Mnesia tables.
     
    The command line parameters:
     
    -sname ejabberd:   The Erlang node will be identified using only the first part of the  host name, i.e. other Erlang nodes outside this domain cannot  contact this node. This is the preferable option in most cases.
     
    -name ejabberd:   The Erlang node will be fully identified. This is only useful if you  plan to setup an ejabberd cluster with nodes in different  networks.
     
    -kernel inetrc \u2019/etc/ejabberd/inetrc\u2019:   Indicates which IP name resolution to use. If using -sname,  specify either this option or ERL_INETRC.
     
    -kernel inet_dist_listen_min 4200 inet_dist_listen_min 4210:   Define the first and last ports that epmd can listen to  (see epmd).
     
    -kernel inet_dist_use_interface { 127,0,0,1 }:   Define the IP address where this Erlang node listens for other nodes  connections (see epmd).
     
    -detached:   Starts the Erlang system detached from the system console. Useful  for running daemons and background processes.
     
    -noinput:   Ensures that the Erlang system never tries to read any input. Useful  for running daemons and background processes.
     
    -pa /var/lib/ejabberd/ebin:   Specify the directory where Erlang binary files (*.beam) are  located.
     
    -s ejabberd:   Tell Erlang runtime system to start the ejabberd application.
     
    -mnesia dir \u2019/var/lib/ejabberd/\u2019:   Specify the Mnesia database directory.
     
    -sasl sasl_error_logger {file, /var/log/ejabberd/erlang.log}:   Path to the Erlang/OTP system log file. SASL here means \u201cSystem  Architecture Support Libraries\u201d not \u201cSimple Authentication and  Security Layer\u201d.
     
    +K [true|false]:   Kernel polling.
     
    -smp [auto|enable|disable]:   SMP support.
     
    +P 250000:   Maximum number of Erlang processes.
     
    -remsh ejabberd@localhost:   Open an Erlang shell in a remote Erlang node.
     
    -hidden:   The connections to other nodes are hidden (not published). The  result is that this node is not considered part of the cluster. This  is important when starting a temporary ctl or debug node.
     
    Note that some characters need to be escaped when used in shell scripts, for instance \" and {}. You can find other options in the Erlang manual page (erl -man erl).
    "},{"location":"admin/guide/managing/#web-admin","title":"Web Admin","text":"
    The ejabberd Web Admin allows to administer some parts of ejabberd using a web browser: accounts, Shared Roster Groups, manage the Mnesia database, create and restore backups, view server statistics, \u2026
    "},{"location":"admin/guide/managing/#basic-setup","title":"Basic Setup","text":"
       
    1.  
      If not done already, register an account and grant administration rights to it    (see Administration Account):
       
      acl:\n  admin:\n    user: admin1@example.org\naccess_rules:\n  configure:\n    allow: admin\n
       
      2.  
    2.  
      Make sure ejabberd_web_admin is available in    request_handlers    of a ejabberd_http listener.    If you want to use HTTPS, enable tls.    For example:
       
      listen:\n   -\n     port: 5443\n     ip: \"::\"\n     module: ejabberd_http\n     tls: true\n     request_handlers:\n       /admin: ejabberd_web_admin\n
       
      3.  
    3.  
      Open the Web Admin page in your favourite web browser. The exact address depends on your configuration; in this example the address is: https://example.net:5443/admin/
       
      4.  
    4.  
      In the login window provide the full Jabber ID: admin1@example.org and password.    If the web address hostname is the same that the account JID,    you can provide simply the username instead of the full JID: admin1.
       
      5.  
    5.  
      You're good! You can now use the Web Admin.
       
      6.  
    "},{"location":"admin/guide/managing/#advanced-configuration","title":"Advanced Configuration","text":"
    There are two access rules supported:
     
       
    • configure determines what accounts can access the Web Admin and make changes.
      •  
    • webadmin_view grants only view access:    those accounts can browse the Web Admin with read-only access.
      •  
     
    Example configurations:
     
       
    •  
      You can serve the Web Admin on the same port as the HTTP Polling   interface. In this example you should point your web browser to   http://example.org:5280/admin/ to administer all virtual hosts or   to http://example.org:5280/admin/server/example.com/ to administer   only the virtual host example.com. Before you get access to the   Web Admin you need to enter as username, the JID and password from a   registered user that is allowed to configure ejabberd. In this   example you can enter as username admin@example.net to   administer all virtual hosts (first URL). If you log in with   admin@example.com on   http://example.org:5280/admin/server/example.com/ you can only   administer the virtual host example.com. The account   reviewer@example.com can browse that vhost in read-only mode.
       
      acl:\n  admin:\n    user:\n      - admin: example.net\n\nhost_config:\n  example.com:\n    acl:\n      admin:\n        user:\n          - admin: example.com\n      viewers:\n        user:\n          - reviewer: example.com\n\naccess:\n  configure:\n    admin: allow\n  webadmin_view:\n    viewers: allow\n\nhosts:\n  - example.org\n\nlisten:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /admin: ejabberd_web_admin\n
       
      •  
    •  
      For security reasons, you can serve the Web Admin on a secured connection, on a port differing from the HTTP Polling interface, and bind it to the internal LAN IP. The Web Admin will be accessible by pointing your web browser to https://192.168.1.1:5282/admin/:
       
      hosts:\n  - example.org\nlisten:\n  -\n    port: 5280\n    module: ejabberd_http\n  -\n    ip: \"192.168.1.1\"\n    port: 5282\n    module: ejabberd_http\n    certfile: \"/usr/local/etc/server.pem\"\n    tls: true\n    request_handlers:\n      /admin: ejabberd_web_admin\n
       
      •  
     
    Certain pages in the ejabberd Web Admin contain a link to a related section in the ejabberd Installation and Operation Guide. In order to view such links, a copy in HTML format of the Guide must be installed in the system. The file is searched by default in /share/doc/ejabberd/guide.html. The directory of the documentation can be specified in the environment variable EJABBERD_DOC_PATH. See section Erlang Runtime System.
    "},{"location":"admin/guide/managing/#ad-hoc-commands","title":"Ad-hoc Commands","text":"
    If you enable mod_configure and mod_adhoc, you can perform several administrative tasks in ejabberd with an XMPP client. The client must support Ad-Hoc Commands (XEP-0050), and you must login in the XMPP server with an account with proper privileges.
    "},{"location":"admin/guide/managing/#change-computer-hostname","title":"Change Computer Hostname","text":"
    ejabberd uses the distributed Mnesia database. Being distributed, Mnesia enforces consistency of its file, so it stores the name of the Erlang node in it (see section Erlang Node Name). The name of an Erlang node includes the hostname of the computer. So, the name of the Erlang node changes if you change the name of the machine in which ejabberd runs, or when you move ejabberd to a different machine.
     
    You have two ways to use the old Mnesia database in an ejabberd with new node name: put the old node name in ejabberdctl.cfg, or convert the database to the new node name.
     
    Those example steps will backup, convert and load the Mnesia database. You need to have either the old Mnesia spool dir or a backup of Mnesia. If you already have a backup file of the old database, you can go directly to step 5. You also need to know the old node name and the new node name. If you don\u2019t know them, look for them by executing ejabberdctl or in the ejabberd log files.
     
    Before starting, setup some variables:
     
    OLDNODE=ejabberd@oldmachine\nNEWNODE=ejabberd@newmachine\nOLDFILE=/tmp/old.backup\nNEWFILE=/tmp/new.backup\n
     
       
    1.  
      Start ejabberd enforcing the old node name:
       
      ejabberdctl --node $OLDNODE start\n
       
      2.  
    2.  
      Generate a backup file:
       
      ejabberdctl --node $OLDNODE backup $OLDFILE\n
       
      3.  
    3.  
      Stop the old node:
       
      ejabberdctl --node $OLDNODE stop\n
       
      4.  
    4.  
      Make sure there aren't files in the Mnesia spool dir. For example:
       
      mkdir /var/lib/ejabberd/oldfiles\nmv /var/lib/ejabberd/*.* /var/lib/ejabberd/oldfiles/\n
       
      5.  
    5.  
      Start ejabberd. There isn't any need to specify the node name  anymore:
       
      ejabberdctl start\n
       
      6.  
    6.  
      Convert the backup to new node name using     mnesia_change_nodename:
       
      ejabberdctl mnesia_change_nodename $OLDNODE $NEWNODE $OLDFILE $NEWFILE\n
       
      7.  
    7.  
      Install the backup file as a fallback using     install_fallback:
       
      ejabberdctl install_fallback $NEWFILE\n
       
      8.  
    8.  
      Stop ejabberd:
       
      ejabberdctl stop\n
       
      You may see an error message in the log files, it\u2019s normal, so don\u2019t worry:
       
      Mnesia(ejabberd@newmachine):\n** ERROR ** (ignoring core)\n** FATAL ** A fallback is installed and Mnesia must be restarted.\n  Forcing shutdown after mnesia_down from ejabberd@newmachine...\n
       
      9.  
    9.  
      Now you can finally start ejabberd:
       
      ejabberdctl start\n
       
      10.  
    10.  
      Check that the information of the old database is available:  accounts, rosters... After you finish, remember to delete the  temporary backup files from public directories.
       
      11.  
    "},{"location":"admin/guide/security/","title":"Securing ejabberd","text":""},{"location":"admin/guide/security/#firewall-settings","title":"Firewall Settings","text":"
    You need to take the following ports in mind when configuring your firewall. The ports may change depending on your ejabberd configuration. Most of them are TCP ports, except the explicitely mentioned ones:
     Port Description 5222 Jabber/XMPP client connections, plain or STARTTLS 5223 Jabber client connections using the old SSL method 5269 Jabber/XMPP incoming server connections 5280/5443 HTTP/HTTPS for Web Admin and many more (ejabberd_http) 1883/8883 MQTT/MQTTS service (mod_mqtt) 3478/5349 STUN+TURN/STUNS+TURNS service (ejabberd_stun) 3478 UDP ' ' 49152-65535 range UDP STUN+TURN service (ejabberd_stun), configure with turn_min_port and turn_max_port 5060/5061 SIP service (ejabberd_sip) 7777 SOCKS5 file transfer proxy (mod_proxy65) 4369 EPMD (see epmd) listens for Erlang node name requests random port range Used by epmd for connections between Erlang nodes, configure with inet_dist_listen_min and inet_dist_listen_max 5210 Erlang connectivity when ERL_DIST_PORT is set, alternative to EPMD"},{"location":"admin/guide/security/#epmd","title":"epmd","text":"
    epmd (Erlang Port Mapper Daemon) is a small name server included in Erlang/OTP and used by Erlang programs when establishing distributed Erlang communications. ejabberd needs epmd to use ejabberdctl and also when clustering ejabberd nodes. This small program is automatically started by Erlang, and is never stopped. If ejabberd is stopped, and there aren't any other Erlang programs running in the system, you can safely stop epmd if you want.
     
    ejabberd runs inside an Erlang node. To communicate with ejabberd, the script ejabberdctl starts a new Erlang node and connects to the Erlang node that holds ejabberd. In order for this communication to work, epmd must be running and listening for name requests in the port 4369. You should block the port 4369 in the firewall in such a way that only the programs in your machine can access it, or configure the option ERL_EPMD_ADDRESS in the file ejabberdctl.cfg.
     
    If you build a cluster of several ejabberd instances, each ejabberd instance is called an ejabberd node. Those ejabberd nodes use a special Erlang communication method to build the cluster, and EPMD is again needed listening in the port 4369. So, if you plan to build a cluster of ejabberd nodes you must open the port 4369 for the machines involved in the cluster. Remember to block the port so Internet doesn't have access to it.
     
    Once an Erlang node solved the node name of another Erlang node using EPMD and port 4369, the nodes communicate directly. The ports used in this case by default are random, but can be configured in the file ejabberdctl.cfg. The Erlang command-line parameter used internally is, for example:
     
    erl ... -kernel inet_dist_listen_min 4370 inet_dist_listen_max 4375\n
     
    It is also possible to configure in ejabberdctl.cfg the network interface where the Erlang node will listen and accept connections. The Erlang command-line parameter used internally is, for example:
     
    erl ... -kernel inet_dist_use_interface \"{127,0,0,1}\"\n
    "},{"location":"admin/guide/security/#erlang-cookie","title":"Erlang Cookie","text":"
    The Erlang cookie is a string with numbers and letters. An Erlang node reads the cookie at startup from the command-line parameter -setcookie. If not indicated, the cookie is read from the file $HOME/.erlang.cookie.
     
    If this file does not exist, it is created immediately with a random cookie in the user $HOME path. This means the user running ejabberd must have a $HOME, and have write access to that path. So, when you create a new account in your system for running ejabberd, either allow it to have a $HOME, or set as $HOME a path where ejabberd will have write access. Depending on your setup, examples could be:
     
    adduser --home /usr/local/var/lib/ejabberd ejabberd\n
     
    or
     
    adduser --home /var/lib/ejabberd ejabberd\n
     
    Two Erlang nodes communicate only if they have the same cookie. Setting a cookie on the Erlang node allows you to structure your Erlang network and define which nodes are allowed to connect to which.
     
    Thanks to Erlang cookies, you can prevent access to the Erlang node by mistake, for example when there are several Erlang nodes running different programs in the same machine.
     
    Setting a secret cookie is a simple method to difficult unauthorized access to your Erlang node. However, the cookie system is not ultimately effective to prevent unauthorized access or intrusion to an Erlang node. The communication between Erlang nodes are not encrypted, so the cookie could be read sniffing the traffic on the network. The recommended way to secure the Erlang node is to block the port 4369.
    "},{"location":"admin/guide/security/#erlang-node-name","title":"Erlang Node Name","text":"
    An Erlang node may have a node name. The name can be short (if indicated with the command-line parameter -sname) or long (if indicated with the parameter -name). Starting an Erlang node with -sname limits the communication between Erlang nodes to the LAN.
     
    Using the option -sname instead of -name is a simple method to difficult unauthorized access to your Erlang node. However, it is not ultimately effective to prevent access to the Erlang node, because it may be possible to fake the fact that you are on another network using a modified version of Erlang epmd. The recommended way to secure the Erlang node is to block the port 4369.
    "},{"location":"admin/guide/security/#securing-sensitive-files","title":"Securing Sensitive Files","text":"
    ejabberd stores sensitive data in the file system either in plain text or binary files. The file system permissions should be set to only allow the proper user to read, write and execute those files and directories.
     
    ejabberd configuration file: /etc/ejabberd/ejabberd.yml:   Contains the JID of administrators and passwords of external  components. The backup files probably contain also this information,  so it is preferable to secure the whole /etc/ejabberd/ directory.
     
    ejabberd service log: /var/log/ejabberd/ejabberd.log:   Contains IP addresses of clients. If the loglevel is set to 5, it  contains whole conversations and passwords. If a logrotate system is  used, there may be several log files with similar information, so it  is preferable to secure the whole /var/log/ejabberd/ directory.
     
    Mnesia database spool files in /var/lib/ejabberd/:   The files store binary data, but some parts are still readable. The  files are generated by Mnesia and their permissions cannot be set  directly, so it is preferable to secure the whole  /var/lib/ejabberd/ directory.
     
    Erlang cookie file: /var/lib/ejabberd/.erlang.cookie:   See section Erlang Cookie.
    "},{"location":"admin/guide/troubleshooting/","title":"Troubleshooting ejabberd","text":""},{"location":"admin/guide/troubleshooting/#log-files","title":"Log Files","text":"
    An ejabberd node writes three log files:
     
       
    •  
      ejabberd.log:   is the ejabberd service log, with the messages reported by ejabberd code
       
      •  
    •  
      error.log:   is the file accumulating error messages from ejabberd.log
       
      •  
    •  
      crash.log:   is the Erlang/OTP log, with the crash messages reported by Erlang/OTP using SASL (System Architecture Support Libraries)
       
      •  
     
    The option loglevel modifies the verbosity of the file ejabberd.log. The syntax:
     
    loglevel: Level: The standard form to set a global log level.
     
    The possible Level are:
     
       
    •  
      0:   No ejabberd log at all (not recommended)
       
      •  
    •  
      1:   Critical
       
      •  
    •  
      2:   Error
       
      •  
    •  
      3:   Warning
       
      •  
    •  
      4:   Info
       
      •  
    •  
      5:   Debug
       
      •  
     
    For example, the default configuration is:
     
    loglevel: 4
     
    By default ejabberd rotates the log files when they get grown above a certain size. The exact value is controlled by the log_rotate_size top-level option.
     
    However, you can rotate the log files manually. You can either use an external tool for log rotation and the reopen_log API command to reopen the log files, or the rotate_log API command to perform both steps (please refer to section ejabberd Commands).
     
    The log_rotate_count toplevel option defines the number of rotated files to keep by the reopen_log API command. Every such file has a numeric suffix.
    "},{"location":"admin/guide/troubleshooting/#debug-console","title":"Debug Console","text":"
    The Debug Console is an Erlang shell attached to an already running ejabberd server. With this Erlang shell, an experienced administrator can perform complex tasks.
     
    This shell gives complete control over the ejabberd server, so it is important to use it with extremely care. There are some simple and safe examples in the article Interconnecting Erlang Nodes
     
    To exit the shell, close the window or press the keys: control+c control+c.
    "},{"location":"admin/guide/troubleshooting/#too-many-db-tables","title":"Too many db tables","text":"
    When running ejabberd, the log shows this error:
     
    ** Too many db tables **\n
     
    The number of concurrent ETS and Mnesia tables is limited. If this error occurs, it means that you have reached this limit.
     
    For a solution, please read the section about ERL_MAX_ETS_TABLES on the Performance Tuning page.
    "},{"location":"admin/guide/unattended/","title":"Unattended Installation","text":"
    Bitrock framework allow unattended installation. With this mode, the installer will not prompt the user for any information and will instead use the default settings configured for each of the parameters. That way, no input is required from the user during the installation. It's also possible to define the values through command line or using a configuration file
     
    ./sample-installer.bin --mode unattended --param1 value1 --param2 value2 ....\n./sample-installer.bin --mode unattended --optionfile optionfile\n
     
    Where optionfile should contain a list of pairs key=value. For instance:
     
    param1=value1\nparam2=value2\n
    "},{"location":"admin/guide/unattended/#available-parameters-for-ejabberd-installer","title":"Available parameters for ejabberd installer","text":"
    Installer recognizes those options:
     
    --admin <username>:  sets user name used that should have admin access
     
    --adminpw <password>:  password used by admin user
     
    --ejabberddomain <domain>:  domain that should be used XMPP server
     
    --installdir <path>:  installation directory
     
    --cluster <0|1>:  setting this to 1 would setup this installation as a part of    cluster (by default it's value is assumed 0)
     
    --hostname <name>:  node id used by ejabberd to use as part of erlang node id (has    only be set when using clustered environment
    "},{"location":"admin/guide/mqtt/","title":"MQTT Support","text":""},{"location":"admin/guide/mqtt/#benefits","title":"Benefits","text":"
    ejabberd is a multiprotocol server that supports MQTT out of the box since ejabberd Business Edition 4.0 and ejabberd Community Server 19.02
     
    There are major benefits in using MQTT service embedded in ejabberd:
     
       
    1. MQTT service relies on ejabberd infrastructure code, that has been battle tested since 15+ years, like the clustering engine. ejabberd MQTT service has been tested on large scale and can support millions of concurrent connections highly efficiently. ejabberd MQTT is rock-solid and highly scalable.
      2.  
    2. The ejabberd APIs and modules can be reused in MQTT. Authentication, virtual hosting, database backends, ... They both work with XMPP and MQTT. You can also share your security policy, as defined in the configuration file between the two protocols.
      3.  
    3. You can leverage existing skills and plugins you have written for ejabberd, like for example custom authentication.
      4.  
    4. You can deploy services that take advantage of both protocols and have them interoperate with each other, on a single platform, with a single tool.
      5.  
    5. ejabberd supports MQTT 5: it is a state of the art, modern MQTT server. And it also supports MQTT 3.1.1 in case you want to use previous clients.
      6.  
     
    In summary:
     
       
    • You can switch between XMPP and MQTT as you wish, even use both protocols on the same infrastructure.
      •  
    • You will save on infrastructure, given the high-performance of the platform.
      •  
    • You get support on solution design for real-time infrastructure and can get help choosing between XMPP and MQTT, from a vendor that has no interest in selling one protocol more than another.
      •  
     
    ejabberd Business Edition offers a different clustering than eCS. Using MQTT with ejabberd Business Edition means you can leverage:
     
       
    • The clustering engine of eBE will be used for the MQTT service. It means that you have a more scalable cluster, that supports geoclustering. With geoclustering, you can deploy a single MQTT service across different datacenters, spread in different regions. You can deploy a truly global service.
      •  
    • The backend integration that are supported in ejabberd Business Edition will be available in MQTT. You have no need to develop support for new API.
      •  
    "},{"location":"admin/guide/mqtt/#basic-setup","title":"Basic Setup","text":"
    Maybe you already have MQTT enabled in your ejabberd server, as it comes enabled by default in many distributions.
     
    MQTT support in ejabberd is enabled by adding mod_mqtt to the list of listen and the list of modules like this:
     
    listen:\n  -\n    port: 1883\n    module: mod_mqtt\n    backlog: 1000\n\nmodules:\n  mod_mqtt: {}\n
     
    The listener on port 1883 is MQTT over cleartext TCP/IP connection; you can later setup encryption, WebSocket, and encrypted WebSocket.
     
    For available options you can consult the mod_mqtt listener and the mod_mqtt module.
    "},{"location":"admin/guide/mqtt/#test-setup","title":"Test Setup","text":"
    Start ejabberd server and you can connect to ejabberd MQTT service with your preferred MQTT client.
     
    Let's use the clients included with mosquitto, available in Debian, Brew and many others (see mosquitto downloads).
     
    First of all register several accounts and subscribe one to the topic test/1 with:
     
    ejabberdctl register author localhost Pass\nejabberdctl register user1 localhost Pass\n\nmosquitto_sub -u user1@localhost -P Pass -t \"test/1\" -d -v\n\nClient (null) sending CONNECT\nClient (null) received CONNACK (0)\nClient (null) sending SUBSCRIBE (Mid: 1, Topic: test/1, QoS: 0, Options: 0x00)\nClient (null) received SUBACK\nSubscribed (mid: 1): 0\n
     
    Then go to another terminal or window and publish something on that topic:
     
    mosquitto_pub -u author@localhost -P Pass -t \"test/1\" -d -m \"ABC\"\n\nClient (null) sending CONNECT\nClient (null) received CONNACK (0)\nClient (null) sending PUBLISH (d0, q0, r0, m1, 'test/1', ... (3 bytes))\nClient (null) sending DISCONNECT\n
     
    You will see the message received and displayed in the mosquitto_sub window:
     
    Client (null) received PUBLISH (d0, q0, r0, m0, 'test/1', ... (3 bytes))\ntest/1 ABC\n
    "},{"location":"admin/guide/mqtt/#access-control","title":"Access Control","text":"
    The mod_mqtt module provides two options for access control:
     
       
    • access_subscribe to restrict access for subscribers,
      •  
    • and access_publish to restrict access for publishers.
      •  
     
    Both options accept mapping filter: rule where filter is an MQTT topic filter and rule is the standard ejabberd Access Rule.
     
    As an example, let's say only author@localhost is allowed to publish to topic \"/test/1/\" and its subtopics, while only user1@localhost is allowed to subscribe to this topic and its subtopics, and nobody else can publish or subscribe to anything else. The configuration will look something like this:
     
    acl:\n  publisher:\n    user: author@localhost\n  subscriber:\n    user: user1@localhost\n\nmodules:\n  mod_mqtt:\n    access_publish:\n      \"test/1/#\":\n        - allow: publisher\n        - deny\n      \"#\":\n        - deny\n    access_subscribe:\n      \"test/1/#\":\n        - allow: subscriber\n        - deny\n      \"#\":\n        - deny\n
    "},{"location":"admin/guide/mqtt/#encryption","title":"Encryption","text":""},{"location":"admin/guide/mqtt/#self-signed-certificate","title":"Self-Signed Certificate","text":"
    If you have already setup encryption in ejabberd, you can bypass this step.
     
    If you want to use TLS, you may want to create a self-signed certificate (at least to get started). The following page is a nice guide: Mosquitto SSL Configuration -MQTT TLS Security.
     
    Here is a summary of the steps, adapted for ejabberd MQTT:
     
    openssl genrsa -des3 -out ca.key 4096\nopenssl req -new -x509 -days 1826 -key ca.key -out ca.crt\nopenssl genrsa -out server.key 4096\nopenssl req -new -out server.csr -key server.key\nopenssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 360\ncat server.crt server.key > mqtt.pem\n
     
    Now copy mqtt.pem to the path with ejabberd configuration files, and configure accordingly:
     
    certfiles:\n  - \"/etc/ejabberd/mqtt.pem\"\n
    "},{"location":"admin/guide/mqtt/#configure-encryption","title":"Configure Encryption","text":"
    Add a new listener with tls option in the port number 8883 (the standard for encrypted MQTT):
     
    listen:\n  -\n    port: 1883\n    module: mod_mqtt\n    backlog: 1000\n  -\n    port: 8883\n    module: mod_mqtt\n    backlog: 1000\n    tls: true\n
     
    The listener on port 1883 is MQTT over cleartext TCP/IP connection. The listener on port 8883 is MQTT over TLS. You can enable both or only one of them depending on your needs.
    "},{"location":"admin/guide/mqtt/#test-encryption","title":"Test Encryption","text":"
    You can repeat the commands from previous test, appending -p 8883 to use the encrypted port. If you are using a self-signed certificate as explained previously, you will also have to append --cafile server.crt. For example:
     
    mosquitto_sub -u user1@localhost -P Pass -t \"test/1\" -d -v -p 8883 --cafile server.crt\n
    "},{"location":"admin/guide/mqtt/#websocket","title":"WebSocket","text":""},{"location":"admin/guide/mqtt/#setup-ws","title":"Setup WS","text":"
    Add mod_mqtt as a request_handler on the ejabberd_http listener:
     
    listen:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /mqtt: mod_mqtt\n
     
    This configuration maps the path /mqtt to the MQTT WebSocket handler on the main ejabberd HTTP listener.
     
    You can enable listeners independently, for example enable only the WebSocket listener and not the TCP/IP ones.
    "},{"location":"admin/guide/mqtt/#test-ws","title":"Test WS","text":"
    Our beloved mosquitto client does not support MQTT over WebSocket, so you may have to find some capable MQTT client. For example, in MQTTX, setup in the login window:
     
       
    • Host: ws:// localhost
      •  
    • Port: 5280
      •  
    • Path:/mqtt
      •  
     
    If you need an example on how to use MQTTJS library, you can check our small example project: mqttjs-demo
    "},{"location":"admin/guide/mqtt/#encrypted-ws","title":"Encrypted WS","text":"
    To enable encryption on WebSocket, enable tls like this:
     
    listen:\n  -\n    port: 5281\n    ip: \"::\"\n    module: ejabberd_http\n    tls: true\n    request_handlers:\n      /mqtt: mod_mqtt\n
     
    For testing this in the MQTTX client:
     
       
    • Host: wss:// localhost
      •  
    • Port: 5281
      •  
    • Path: /mqtt
      •  
    • SSL/TLS: true
      •  
    • Certificate: CA signed server
      •  
    • If you used a self-signed certificate, you will have to disable SSL Secure
      •  
    "},{"location":"admin/guide/xep/","title":"Supporting and configuring specific XMPP Extensions in ejabberd","text":"
    XMPP extensions support can be implemented in different ways in ejabberd. We have several cases:
     
       
    1. The extension must be implemented as a core feature of ejabberd. In    that case, it may be supported as default and / or have    configuration options in ejabberd config files.
      2.  
    2. The extension can be optional and implemented as a module.
      3.  
    3. The extension may additionally need to be enabled on the client    stream to use it (For example MAM or stream management).
      4.  
     
    This section is here to help you understand how they are implemented XEP by XEP in ejabberd. We intend to explain what you can do in case you want to support a given XEP or if you want to make sure a specific Extension is disabled.
    "},{"location":"admin/guide/xep/#xep-0004-data-forms","title":"XEP-0004: Data Forms","text":""},{"location":"admin/guide/xep/#specification","title":"Specification","text":"
    XEP-0004: Data Forms
    "},{"location":"admin/guide/xep/#implementation","title":"Implementation","text":"
    ejabberd core
    "},{"location":"admin/guide/xep/#comment","title":"Comment","text":"
    This extension is a general design principle for forms in XMPP. The principles are applied by all services, components and modules inside ejabberd.
    "},{"location":"admin/guide/xep/#enabling-disabling","title":"Enabling / Disabling","text":"
    As it is a general specification, it is used as default and cannot be disabled.
    "},{"location":"admin/guide/xep/#xep-0012-last-activity","title":"XEP-0012: Last Activity","text":""},{"location":"admin/guide/xep/#specification_1","title":"Specification","text":"
    XEP-0012: Last Activity
    "},{"location":"admin/guide/xep/#implementation_1","title":"Implementation","text":"
    Main ejabberd module: mod_last.erl
    "},{"location":"admin/guide/xep/#comment_1","title":"Comment","text":"
    This extension is optional. It allows the server to send back information about when the user disconnected their last session.
     
    It also allows to query the uptime of an ejabberd server.
    "},{"location":"admin/guide/xep/#enabling","title":"Enabling","text":"
    Add mod_last configuration in modules section of the configuration file.
     
    It is enabled by default in ejabberd configuration template.
    "},{"location":"admin/guide/xep/#disabling","title":"Disabling","text":"
    Make sure mod_last is not defined or is commented out in ejabberd config modules section.
     
    No side effect.
    "},{"location":"admin/guide/xep/#module-documentation","title":"Module documentation","text":"
       
    • mod_last
      •  
    "},{"location":"admin/guide/xep/#xep-0013-flexible-offline-message-retrieval","title":"XEP-0013: Flexible Offline Message Retrieval","text":""},{"location":"admin/guide/xep/#specification_2","title":"Specification","text":"
    XEP-0013: Flexible Offline Message Retrieval
    "},{"location":"admin/guide/xep/#implementation_2","title":"Implementation","text":"
    Main ejabberd module: mod_offline.erl
    "},{"location":"admin/guide/xep/#comment_2","title":"Comment","text":"
    This extension is active on server if mod_offline module is enabled on ejabberd.
     
    However, it is not used by client automatically. Flexible offline message retrieval is enabled in the following cases:
     
       
    • client send request to retrieve number of messages prior to sending   its initial presence:   Requesting Number of Messages
      •  
    • client send request to retrieve messages headers prior to sending   its initial presence:   Requesting Message Headers
      •  
    • client send all messages retrieval request prior to sending its   initial presence:   Retrieving All Messages
      •  
    "},{"location":"admin/guide/xep/#enabling_1","title":"Enabling","text":"
    Add mod_offline configuration in modules section of the configuration file.
     
    It is enabled and can be used by client if mod_offline is enabled. This is a module enabled by default in default ejabberd configuration file template.
    "},{"location":"admin/guide/xep/#disabling_1","title":"Disabling","text":"
    Make sure mod_offline is not defined or is commented out in    ejabberd config modules section.
     
    Side effect: It will disable all offline messages storage.
    "},{"location":"admin/guide/xep/#module-documentation_1","title":"Module documentation","text":"
       
    • mod_offline
      •  
    "},{"location":"admin/install/","title":"Installation","text":"
    There are several ways to install ejabberd Community Server, depending on your needs and your infrastructure.
    "},{"location":"admin/install/#self-hosted","title":"Self-hosted","text":""},{"location":"admin/install/#container-images","title":"Container Images","text":"
       
    • ejabberd and ecs Container Images \u2013 Ideal for Windows, macOS, Linux, ...
      •  
    "},{"location":"admin/install/#binary-installers","title":"Binary Installers","text":"
       
    • Linux RUN Installer \u2013 Suitable for various Linux distributions
      •  
    • Linux DEB and RPM Installers \u2013 Specifically for DEB and RPM based Linux
      •  
    "},{"location":"admin/install/#linux-and-bsd","title":"Linux and *BSD","text":"
       
    • Operating System Package \u2013 Tailored for System Operators
      •  
    "},{"location":"admin/install/#macos","title":"MacOS","text":"
       
    • Homebrew \u2013 Optimized for MacOS
      •  
    "},{"location":"admin/install/#source-code","title":"Source Code","text":"
       
    • Source Code \u2013 Geared towards developers and advanced administrators
      •  
    "},{"location":"admin/install/#on-premise-ebe","title":"On-Premise (eBE)","text":"
       
    • ejabberd Business Edition \u2013 Explore professional support and managed services on your infrastructure
      •  
    "},{"location":"admin/install/#cloud-hosting-fluux","title":"Cloud Hosting (Fluux)","text":"
       
    • Fluux.io \u2013 Opt for ejabberd hosting with a user-friendly web dashboard
      •  
    "},{"location":"admin/install/binary-installer/","title":"Binary Installers","text":""},{"location":"admin/install/binary-installer/#linux-run-installer","title":"Linux RUN Installer","text":"
    The *.run binary installer will deploy and configure a full featured ejabberd server and does not require any extra dependencies. It includes a stripped down version of Erlang. As such, when using ejabberd installer, you do not need to install Erlang separately.
     
    Those instructions assume installation on localhost for development purposes. In this document, when mentioning ejabberd-YY.MM, we assume YY.MM is the release number, for example 18.01.
     
    Installation using the *.run binary installer:
     
       
    1.  
      Go to ejabberd GitHub Releases.
       
      2.  
    2.  
      Download the run package for your architecture
       
      3.  
    3.  
      Right-click on the downloaded file and select \"Properties\", click on the \"Permissions\" tab and tick the box that says \"Allow executing file as program\".    Alternatively, you can set the installer as executable using the command line:
       
      chmod +x ejabberd-YY.MM-1-linux-x64.run\n
       
      4.  
    4.  
      If the installer runs as superuser (by root or using sudo),    it installs ejabberd binaries in /opt/ejabberd-XX.YY/;    installs your configuration, Mnesia database and logs in /opt/ejabberd/,    and setups an ejabberd service unit in systemd:
       
      sudo ./ejabberd-YY.MM-1-linux-x64.run\n
       
      5.  
    5.  
      If the installer runs as a regular user,    it asks the base path where ejabberd should be installed.    In that case, the ejabberd service unit is not set in systemd,    and systemctl cannot be used to start ejabberd; start it manually.
       
      6.  
    6.  
      After successful installation by root, ejabberd is automatically started.    Check its status with
       
      systemctl status ejabberd\n
       
      7.  
    7.  
      Now that ejabberd is installed and running with the default configuration,    it's time to do some basic setup: edit /opt/ejabberd/conf/ejabberd.yml    and setup in the hosts option the domain that you want ejabberd to serve.    By default it's set to the name of your computer on the local network.
       
      8.  
    8.  
      Restart ejabberd completely using systemctl, or using ejabberdctl,    or simply tell it to reload the configuration file:
       
      sudo systemctl restart ejabberd\nsudo /opt/ejabberd-22.05/bin/ejabberdctl restart\nsudo /opt/ejabberd-22.05/bin/ejabberdctl reload_config\n
       
      9.  
    9.  
      Quite probably you will want to register an account and grant it admin rights,    please check Next Steps: Administration Account.
       
      10.  
    10.  
      Now you can go to the web dashboard at http://localhost:5280/admin/    and fill the username field with the full account JID,    for example admin@domain (or admin@localhost as above).    Then fill the password field with that account's password.    The next step is to get to know how to configure ejabberd.
       
      11.  
    11.  
      If something goes wrong during the installation    and you would like to start from scratch,    you will find the steps to uninstall in the file    /opt/ejabberd-22.05/uninstall.txt.
       
      12.  
    "},{"location":"admin/install/binary-installer/#linux-deb-and-rpm-installers","title":"Linux DEB and RPM Installers","text":"
    ProcessOne provides DEB and RPM all-in-one binary installers with the same content that the *.run binary installer mentioned in the previous section.
     
    Those are self-sufficient packages that contain a minimal Erlang distribution, this ensures that it does not interfere with your existing Erlang version and is also a good way to make sure ejabberd will run with the latest Erlang version.
     
    Those packages install ejabberd in /opt/ejabberd-XX.YY/. Your configuration, Mnesia database and logs are available in /opt/ejabberd/.
     
    You can download directly the DEB and RPM packages from ejabberd GitHub Releases.
     
    If you prefer, you can also get those packages from our official ejabberd packages repository.
    "},{"location":"admin/install/homebrew/","title":"Install ejabberd on macOS","text":""},{"location":"admin/install/homebrew/#homebrew","title":"Homebrew","text":"
    Homebrew is a package manager for macOS that aims to port the many Unix & Linux software that is not easily available or compatible. Homebrew installation is simple and the instruction is available on its website.
     
    Check also the guide for Installing ejabberd development environment on OSX
     
    The ejabberd configuration included in Homebrew's ejabberd has as default domain localhost, and has already granted administrative privileges to the account admin@localhost.
     
       
    1.  
      Once you have Homebrew installed, open Terminal. Run
       
      brew install ejabberd\n
       
      This should install the latest or at most the one-before-latest version of ejabberd. The installation directory should be reported at the end of this process, but usually the main executable is stored at /usr/local/sbin/ejabberdctl.
       
      2.  
    2.  
      Start ejabberd in interactive mode, which prints useful messages in the Terminal.
       
      /usr/local/sbin/ejabberdctl live\n
       
      3.  
    3.  
      Create the account admin@localhost with password set as password:
       
      /usr/local/sbin/ejabberdctl register admin localhost password\n
       
      4.  
    4.  
      Now you can go to the web dashboard at http://localhost:5280/admin/ and fill the username field with the full account JID, for example admin@localhost, then fill the password field with that account's password.
       
      5.  
    5.  
      Without configuration there's not much to see here, therefore the next step is to get to know how to configure ejabberd.
       
      6.  
    "},{"location":"admin/install/next-steps/","title":"Next Steps","text":""},{"location":"admin/install/next-steps/#starting-ejabberd","title":"Starting ejabberd","text":"
    Depending on how you installed ejabberd, it may be started automatically by the operating system at system boot time.
     
    You can use the ejabberdctl command line administration script to start and stop ejabberd, check its status and many other administrative tasks.
     
    If you provided the configure option --enable-user=USER (see compilation options, you can execute ejabberdctl with either that system account or root.
     
    Usage example:
     
    prompt> ejabberdctl start\n\nprompt> ejabberdctl status\nThe node ejabberd@localhost is started with status: started\nejabberd is running in that node\n\nprompt> ejabberdctl stop\n
     
    If ejabberd doesn't start correctly and a crash dump file is generated, there was a severe problem. You can try to start ejabberd in interactive mode with the command bin/ejabberdctl live to see the error messages provided by Erlang and identify the exact the problem.
     
    The ejabberdctl administration script is included in the bin directory in the Linux Installers and Docker image.
     
    Please refer to the section ejabberdctl for details about ejabberdctl, and configurable options to fine tune the Erlang runtime system.
    "},{"location":"admin/install/next-steps/#autostart-on-linux","title":"Autostart on Linux","text":"
    If you compiled ejabberd from source code or some other method that doesn't setup autostarting ejabberd, you can try this method.
     
    On a *nix system, create a system user called 'ejabberd', give it write access to the directories database/ and logs/, and set that as home.
     
    If you want ejabberd to be started as daemon at boot time with that user, copy ejabberd.init from the bin directory to something like /etc/init.d/ejabberd. Then you can call /etc/inid.d/ejabberd start to start the server.
     
    Or if you have a systemd distribution:
     
       
    1. copy ejabberd.service to /etc/systemd/system/
      2.  
    2. run systemctl daemon-reload
      3.  
    3. run systemctl enable ejabberd.service
      4.  
    4. To start the server, you can run systemctl start ejabberd
      5.  
     
    When ejabberd is started, the processes that are started in the system are beam or beam.smp, and also epmd. For more information regarding epmd consult the section relating to epmd.
    "},{"location":"admin/install/next-steps/#administration-account","title":"Administration Account","text":"
    Some ejabberd installation methods ask you details for the first account, and take care to register that account and grant it administrative rights; in that case you can skip this section.
     
    After installing ejabberd from source code or other methods, you may want to register the first XMPP account and grant it administrative rights:
     
       
    1.  
      Register an XMPP account on your ejabberd server.     For example, if example.org is configured in the     hosts     section in your ejabberd configuration file,     then you may want to register an account with JID admin1@example.org.
       
      There are two ways to register an XMPP account in ejabberd:
       
         
      •  
        Using an XMPP client and In-Band Registration.
         
        •  
      •  
        Using ejabberdctl:
         
        ejabberdctl register admin1 example.org password\n
         
        •  
       
      2.  
    2.  
      Edit the ejabberd configuration file to give administration     rights to the XMPP account you registered:
       
      acl:\n  admin:\n    user: admin1@example.org\n\naccess_rules:\n  configure:\n    allow: admin\n
       
      You can grant administrative privileges to many XMPP accounts, and also to accounts in other XMPP servers.
       
      3.  
    3.  
      Restart ejabberd to load the new configuration, or run the     reload_config command.
       
      4.  
    4.  
      Open the Web Admin page in your favourite browser.     The exact address depends on your ejabberd configuration,     and may be     http://localhost:5280/admin/,     https://localhost:5443/admin/,     https://localhost:5280/admin/ ...
       
      5.  
    5.  
      Your web browser shows a login window. Introduce the full JID,     in this example admin1@example.org, and the account password.     If the web address hostname is the same that the account JID,     you can provide simply the username instead of the full JID: admin1.     See Web Admin for details.
       
      6.  
    "},{"location":"admin/install/next-steps/#configuring-ejabberd","title":"Configuring ejabberd","text":"
    Now that you got ejabberd installed and running, it's time to configure it to your needs. You can follow on the Configuration section and take also a look at the Tutorials.
    "},{"location":"admin/install/os-package/","title":"Operating System Packages","text":"
    Many operating systems provide specific ejabberd packages adapted to the system architecture and libraries. They usually also check dependencies and perform basic configuration tasks like creating the initial administrator account.
     
    List of known ejabberd packages:
     
       
    • Alpine Linux
      •  
    • Arch Linux
      •  
    • Debian
      •  
    • Fedora
      •  
    • FreeBSD
      •  
    • Gentoo
      •  
    • OpenSUSE
      •  
    • NetBSD
      •  
    • Ubuntu
      •  
     
    Consult the resources provided by your Operating System for more information.
     
    There's also an ejabberd snap to install ejabberd on several operating systems using Snap package manager.
    "},{"location":"admin/install/source/","title":"Install ejabberd from Source Code","text":"
    The canonical form for distribution of ejabberd stable releases is the source code package. Compiling ejabberd from source code is quite easy in *nix systems, as long as your system have all the dependencies.
    "},{"location":"admin/install/source/#requirements","title":"Requirements","text":"
    To compile ejabberd you need:
     
       
    • GNU Make
      •  
    • GCC
      •  
    • Libexpat \u2265 1.95
      •  
    • Libyaml \u2265 0.1.4
      •  
    • Erlang/OTP \u2265 20.0. We recommend using Erlang OTP 25.3, which is the version used in the binary installers and container images.
      •  
    • OpenSSL \u2265 1.0.0
      •  
     
    Other optional libraries are:
     
       
    • Zlib \u2265 1.2.3, For Zlib Stream Compression
      •  
    • PAM library, for PAM Authentication
      •  
    • ImageMagick\u2019s Convert program and Ghostscript fonts, for CAPTCHA challenges.
      •  
    • Elixir \u2265 1.10.3, for Elixir Development. It is recommended Elixir 1.13.4 or higher and Erlang/OTP 23.0 or higher.
      •  
     
    If your system splits packages in libraries and development headers, install the development packages too.
     
    For example, in Debian:
     
    apt-get install libexpat1-dev libgd-dev libpam0g-dev \\\n                libsqlite3-dev libwebp-dev libyaml-dev \\\n                autoconf automake erlang elixir rebar3\n
    "},{"location":"admin/install/source/#download","title":"Download","text":"
    There are several ways to obtain the ejabberd source code:
     
       
    • Source code archive from ProcessOne Downloads
      •  
    • Source code package from ejabberd GitHub Releases
      •  
    • Latest development code from ejabberd Git repository
      •  
     
    The latest development source code can be retrieved from the Git repository using the commands:
     
    git clone git://github.com/processone/ejabberd.git\ncd ejabberd\n
    "},{"location":"admin/install/source/#compile","title":"Compile","text":"
    The general instructions to compile ejabberd are:
     
    ./autogen.sh\n./configure\nmake\n
     
    In this example, ./configure prepares the installed program to run with a user called ejabberd that should exist in the system (it isn't recommended to run ejabberd with root user):
     
    ./autogen.sh\n./configure --enable-user=ejabberd --enable-mysql\nmake\n
     
    make gets the dependencies and compiles everything.
     
    Note: To build ejabberd, you will need Internet access, as dependencies will be downloaded depending on the selected options.
    "},{"location":"admin/install/source/#configure","title":"./configure","text":"
    The build configuration script supports many options. Get the full list:
     
    ./configure --help\n
     
    Options details:
     
       
    •  
      --bindir=/: Specify the path to the user executables (where epmd and iex are available).
       
      •  
    •  
      --prefix=/: Specify the path prefix where the files will be copied when running the make install command.
       
      •  
    •  
      --with-rebar=/: Specify the path to rebar, rebar3 or   mix
       
       added in 20.12 and improved in 24.02
       
      •  
    •  
      --enable-user[=USER]: Allow this normal system user to execute the ejabberdctl script (see section ejabberdctl), read the configuration files, read and write in the spool directory, read and  write in the log directory. The account user and group must exist in  the machine before running make install. This account needs a HOME directory, because the Erlang cookie file will be created and read there.
       
      •  
    •  
      --enable-group[=GROUP]: Use this option additionally to --enable-user   when that account is in a group that doesn't coincide with its username.
       
      •  
    •  
      --enable-all: Enable many of the database and dependencies     options described here, this is useful for Dialyzer checks:     --enable-debug --enable-elixir --enable-mysql --enable-odbc     --enable-pam --enable-pgsql --enable-redis --enable-sip     --enable-sqlite --enable-stun --enable-tools --enable-zlib
       
      •  
    •  
      --disable-debug: Compile without +debug_info.
       
      •  
    •  
      --enable-elixir: Build ejabberd with Elixir extension support.     Works only with rebar3, not rebar2. Requires to have Elixir installed.     If interested in Elixir development, you may prefer to use --with-rebar=mix
       
       improved in 24.02
       
      •  
    •  
      --disable-erlang-version-check: Don't check Erlang/OTP version.
       
      •  
    •  
      --enable-full-xml: Use XML features in XMPP stream (ex: CDATA). This requires XML compliant clients).
       
      •  
    •  
      --enable-hipe: Compile natively with HiPE. This is an experimental feature, and not recommended.
       
      •  
    •  
      --enable-lager: Use lager Erlang logging tool instead of standard error logger.
       
      •  
    •  
      --enable-latest-deps: Makes rebar use latest versions of   dependencies developed alongside ejabberd instead of version   specified in rebar.config. Should be only used when developing   ejabberd.
       
      •  
    •  
      --enable-lua: Enable Lua support, to import from Prosody.
       
       added in 21.04
       
      •  
    •  
      --enable-mssql: Enable Microsoft SQL Server support, this     option requires --enable-odbc (see [Supported storages][18]).
       
      •  
    •  
      --enable-mysql: Enable MySQL support (see [Supported storages][18]).
       
      •  
    •  
      --enable-new-sql-schema: Use new SQL schema.
       
      •  
    •  
      --enable-odbc: Enable pure ODBC support.
       
      •  
    •  
      --enable-pam: Enable the PAM authentication method (see PAM Authentication section).
       
      •  
    •  
      --enable-pgsql: Enable PostgreSQL support (see [Supported storages][18]).
       
      •  
    •  
      --enable-redis: Enable Redis support to use for external session storage.
       
      •  
    •  
      --enable-roster-gateway-workaround: Turn on workaround for processing gateway subscriptions.
       
      •  
    •  
      --enable-sip: Enable SIP support.
       
      •  
    •  
      --enable-sqlite: Enable SQLite support (see [Supported storages][18]).
       
      •  
    •  
      --disable-stun: Disable STUN/TURN support.
       
      •  
    •  
      --enable-system-deps: Makes rebar use locally installed     dependencies instead of downloading them.
       
      •  
    •  
      --enable-tools: Enable the use of development tools.
       
       changed in 21.04
       
      •  
    •  
      --disable-zlib: Disable Stream Compression (XEP-0138) using zlib.
       
      •  
    "},{"location":"admin/install/source/#make","title":"make","text":"
    This tool is used to compile ejabberd and perform other tasks:
     
       
    • Get, update, compile dependencies; clean files
      •  
    • System install, uninstall
      •  
    • Build OTP production / development releases
      •  
    • Development: edoc, options, translations, tags
      •  
    • Testing: dialyzer, hooks, test, xref
      •  
     
    Get the full list and details:
     
    make help\n
    "},{"location":"admin/install/source/#install","title":"Install","text":"
    There are several ways to install and run the ejabberd compiled from source code: system install, building a production release, or building a development release.
    "},{"location":"admin/install/source/#system-install","title":"System Install","text":"
    To install ejabberd in the destination directories, run the command make install.
     
    Note that you probably need administrative privileges in the system to install ejabberd.
     
    The created files and directories depend on the options provided to ./configure, by default they are:
     
       
    •  
      /etc/ejabberd/:  Configuration directory:
       
         
      • ejabberd.yml:  ejabberd configuration file (see File Format)
        •  
      • ejabberdctl.cfg: Configuration file of the administration script (see Erlang Runtime System)
        •  
      • inetrc: Network DNS configuration file for Erlang
        •  
       
      •  
    •  
      /lib/ejabberd/:
       
         
      • ebin/: Erlang binary files (*.beam)
        •  
      • include/: Erlang header files (*.hrl)
        •  
      • priv/: Additional files required at runtime
        •  
      • bin/: Executable programs
        •  
      • lib/: Binary system libraries (*.so)
        •  
      • msgs/: Translation files (*.msgs) (see Default Language)
        •  
       
      •  
    •  
      /sbin/ejabberdctl: Administration script (see ejabberdctl)
       
      •  
    •  
      /share/doc/ejabberd/: Documentation of ejabberd
       
      •  
    •  
      /var/lib/ejabberd/: Spool directory:
       
         
      • .erlang.cookie: The Erlang cookie file
        •  
      • acl.DCD, ...: Mnesia database spool files (*.DCD, *.DCL, *.DAT)
        •  
       
      •  
    •  
      /var/log/ejabberd/: Log directory (see Logging):
       
         
      • ejabberd.log:   ejabberd service log
        •  
      • erlang.log:   Erlang/OTP system log
        •  
       
      •  
    "},{"location":"admin/install/source/#production-release","title":"Production Release","text":"
     improved in 21.07
     
    You can build an OTP release that includes ejabberd, Erlang/OTP and all the required erlang dependencies in a single tar.gz file. Then you can copy that file to another machine that has the same machine architecture, and run ejabberd without installing anything else.
     
    To build that production release, run:
     
    make prod\n
     
    If you provided to ./configure the option  --with-rebar to use rebar3 or mix, this will directly produce a tar.gz that you can copy.
     
    This example uses rebar3 to manage the compilation, builds an OTP production release, copies the resulting package to a temporary path, and starts ejabberd there:
     
    ./autogen.sh\n./configure --with-rebar=rebar3\nmake\nmake prod\nmkdir $HOME/eja-release\ntar -xzvf _build/prod/ejabberd-*.tar.gz -C $HOME/eja-release\n$HOME/eja-release/bin/ejabberdctl live\n
    "},{"location":"admin/install/source/#development-release","title":"Development Release","text":"
     new in 21.07
     
    If you provided to ./configure the option  --with-rebar to use rebar3 or mix, you can build an OTP development release.
     
    This is designed to run ejabberd in the local machine for development, manual testing... without installing in the system.
     
    This development release has some customizations: uses a dummy certificate file, if you register the account admin@localhost it has admin rights...
     
    This example uses Elixir's mix to manage the compilation, builds an OTP development release, and starts ejabberd there:
     
    ./autogen.sh\n./configure --with-rebar=mix\nmake\nmake dev\n_build/dev/rel/ejabberd/bin/ejabberdctl live\n
    "},{"location":"admin/install/source/#specific-notes","title":"Specific notes","text":""},{"location":"admin/install/source/#asdf","title":"asdf","text":"
    When Erlang/OTP (and/or Elixir) is installed using asdf (multiple runtime version manager), it is available only for your account, in $HOME/.asdf/shims/erl. In that case, you cannot install ejabberd globally in the system, and you cannot use the root account to start it, because that account doesn't have access to erlang.
     
    In that scenario, there are several ways to run/install ejabberd:
     
       
    •  
      Run a development release locally without installing
       
      •  
    •  
      Copy a production release locally
       
      •  
    •  
      Use system install, but install it locally:
       
      •  
     
    ./autogen.sh\n./configure --prefix=$HOME/eja-install --enable-user\nmake\nmake install\n$HOME/eja-install/sbin/ejabberdctl live\n
    "},{"location":"admin/install/source/#bsd","title":"BSD","text":"
    The command to compile ejabberd in BSD systems is gmake.
     
    You may want to check pkgsrc.se for ejabberd.
     
    Up to ejabberd 23.04, some old scripts where included in ejabberd source for NetBSD compilation, and you can take a look to those files for reference in ejabberd 23.04/examples/mtr/ path.
    "},{"location":"admin/install/source/#macos","title":"macOS","text":"
    If compiling from sources on Mac OS X, you must configure ejabberd to use custom OpenSSL, Yaml, iconv. The best approach is to use Homebrew to install your dependencies, then exports your custom path to let configure and make be aware of them.
     
    brew install git erlang elixir openssl expat libyaml libiconv libgd sqlite rebar rebar3 automake autoconf\nexport LDFLAGS=\"-L/usr/local/opt/openssl/lib -L/usr/local/lib -L/usr/local/opt/expat/lib\"\nexport CFLAGS=\"-I/usr/local/opt/openssl/include -I/usr/local/include -I/usr/local/opt/expat/include\"\nexport CPPFLAGS=\"-I/usr/local/opt/openssl/include/ -I/usr/local/include -I/usr/local/opt/expat/include\"\n./configure\nmake\n
     
    Check also the guide for Installing ejabberd development environment on OSX
    "},{"location":"admin/install/source/#start","title":"Start","text":"
    You can use the ejabberdctl command line administration script to start and stop ejabberd. Some examples, depending on your installation method:
     
       
    •  
      When installed in the system: 
      ejabberdctl start\n/sbin/ejabberdctl start\n
       
      •  
    •  
      When built an OTP production release: 
      _build/prod/rel/ejabberd/bin/ejabberdctl start\n_build/prod/rel/ejabberd/bin/ejabberdctl live\n
       
      •  
    •  
      Start interactively without installing or building OTP release: 
      make relive\n
       
      •  
    "},{"location":"admin/install/container/","title":"Install ejabberd using a Container Image","text":"
    There are two official container images of ejabberd that you can install using docker (or podman):
    "},{"location":"admin/install/container/#ejabberd-container-image","title":"ejabberd Container Image","text":"
    The \"ejabberd\" container image is available in the GitHub Container Registry. It is available for x64 and arm64, both for stable ejabberd releases and the master branch. Check the \"ejabberd\" container documentation.
     
    For example, download the latest stable ejabberd release:
     
    docker pull ghcr.io/processone/ejabberd\n
     
    If you use Microsoft Windows 7, 10, or similar operating systems, check those tutorials:
     
       
    • Install ejabberd on Windows 10 using Docker Desktop
      •  
    • Install ejabberd on Windows 7 using Docker Toolbox
      •  
     
    For bug reports and improvement suggestions, if you use the \"ecs\" container image please go to the docker-ejabberd GitHub Issues, if using the \"ejabberd\" container image from github please go to the ejabberd GitHub Issues
    "},{"location":"admin/install/container/#ecs-container-image","title":"ecs Container Image","text":"
    The \"ecs\" container image allows to get ejabberd stable releases in x64 machines. Check the \"ecs\" container documentation.
     
    Download ejabberd with:
     
    docker pull docker.io/ejabberd/ecs\n
    "},{"location":"admin/upgrade/","title":"Upgrade Procedure for ejabberd","text":"
    This document contains administration procedure for each version upgrade. Only upgrade from version N to N+1 is documented and supported. If you upgrade from an older version than previous one, you have to review all upgrade notes and apply each steps one by one for the possible database changes. You also have to stop your old ejabberd server, and start the new one.
     
    Until release note explicitly state you must restart the server for upgrade, you should be able to run soft upgrade using a cluster.  If you don't have cluster, upgrade from older release than previous one, or have explicit note soft upgrade does not work, then you have to fallback to standalone upgrade process.
    "},{"location":"admin/upgrade/#generic-upgrade-process","title":"Generic upgrade process","text":"
    This is the simplest process, and require service restart.
     
       
    • read the corresponding upgrade notes
      •  
    • apply the required changes in database from the upgrade note.
      •  
    • stop old node
      •  
    • archive content of mnesia database directory (database, i.e. /opt/ejabberd-XX.YY/database, /usr/local/var/lib/ejabberd, ...)
      •  
    • install new version
      •  
    • extract database archive in new path
      •  
    •  
      if systemctl is used to manage ejabberd, copy the new service file and reload systemctl: 
      cp ejabberd-21.12/bin/ejabberd.service /etc/systemd/system/\nsystemctl daemon-reload\n
       
      •  
    •  
      start new node
       
      •  
    "},{"location":"admin/upgrade/#soft-upgrade-process","title":"Soft upgrade process","text":"
    This process needs you to run in cluster, with at least two nodes. In this case, we assume you run node A and B with version N, and will upgrade to version N+1.
     
       
    • read the corresponding upgrade notes, make sure it does not explicitly states \"soft upgrade is not supported\".
      •  
    • apply the required changes in database from the upgrade note.
      •  
    • make sure node A is running
      •  
    • run leave_cluster on node B
      •  
    • stop old node B
      •  
    • install new version on B's host
      •  
    • start new node B
      •  
    • run join_cluster on node B, passing node A as parameter
      •  
    • make sure both nodes are running and working as expected
      •  
    • run leave_cluster on node A
      •  
    • stop old node A
      •  
    • install new version on A's host
      •  
    • start new node A
      •  
    • run join_cluster on node A, passing node B as parameter
      •  
    "},{"location":"admin/upgrade/#module-update-process","title":"Module update process","text":"
    Instead of upgrading all ejabberd to a brand new version, maybe you just want to update a few modules with bugfixes... in that case you can update only specific modules.
     
    This process is only recommended for bugfixes that involve functional changes, and do not involve structural or memory changes (those ones are usually detected and applied at server start only).
     
    How to do this?
     
       
    1. Apply the fixes to your source code, compile and reinstall ejabberd,    so the new *.beam files replace the old ones
      2.  
    2. In the ejabberd Web Admin go to Nodes -> your node -> Update
      3.  
    3. This will detect what *.beam files have changed in the installation
      4.  
    4. Select which modules you want to update now, and click Update
      5.  
    5. This will load into memory the corresponding *.beam files
      6.  
     
    If you prefer to use commands, check update_list + update.
     
    Notice this does not restart modules or any other tasks. If the fix you plan to apply requires a module restart, you can use this alternative: restart_module.
    "},{"location":"admin/upgrade/#note-on-database-schema-upgrade","title":"Note on database schema upgrade","text":"
    ejabberd automatically updates the Mnesia table definitions at startup when needed. If you also use an external database (like MySQL, ...) for storage of some modules, check in the corresponding upgrade notes of the new ejabberd version if you need to update those tables yourself manually.
    "},{"location":"admin/upgrade/#specific-version-upgrade-notes","title":"Specific version upgrade notes","text":"
    The corresponsing ugprade notes are available in the release notes of each release, and also available in the Archive section:
     
       
    • Upgrading from ejabberd 23.10 to 24.02
      •  
    • Upgrading from ejabberd 23.04 to 23.10
      •  
    • Upgrading from ejabberd 23.01 to 23.04
      •  
    • Upgrading from ejabberd 22.10 to 23.01
      •  
    • Upgrading from ejabberd 22.05 to 22.10
      •  
    • Upgrading from ejabberd 21.12 to 22.05
      •  
    • Upgrading from ejabberd 21.07 to 21.12
      •  
    • Upgrading from ejabberd 21.04 to 21.07
      •  
    • Upgrading from ejabberd 21.01 to 21.04
      •  
    • Upgrading from ejabberd 19.08 to 20.01
      •  
    • Upgrading from ejabberd 19.05 to 19.08
      •  
    • Upgrading from ejabberd 19.02 to 19.05
      •  
    • Upgrading from ejabberd 18.12 to 19.02
      •  
    • Upgrading from ejabberd 18.09 to 18.12
      •  
    • Upgrading from ejabberd 18.06 to 18.09
      •  
    • Upgrading from ejabberd 18.04 to 18.06
      •  
    • Upgrading from ejabberd 18.03 to 18.04
      •  
    • Upgrading from ejabberd 18.01 to 18.03
      •  
    • Upgrading from ejabberd 17.11 to 18.01
      •  
    • Upgrading from ejabberd 17.09 to 17.11
      •  
    • Upgrading from ejabberd \u226517.06 and \u226417.08 to 17.09
      •  
    • Upgrading from ejabberd 17.03 or 17.04 to 17.06
      •  
    • Upgrading from ejabberd \u226516.08 and \u226417.01 to 17.03
      •  
    • Upgrading from ejabberd 16.06 to 16.08
      •  
    • Upgrading from ejabberd 16.04 to 16.06
      •  
    • Upgrading from ejabberd 16.03 to 16.04
      •  
    • Upgrading from ejabberd 16.02 to 16.03
      •  
    • Upgrading from ejabberd 15.11 to 16.02
      •  
    • Upgrading from ejabberd 2.1.1x to 16.02
      •  
    "},{"location":"archive/","title":"Archived Documentation","text":"
    This section contains archived documentation of previous ejabberd releases. Please notice that it only contains the pages that most probably change between releases.
     
       
    • 24.02
      •  
    • 23.10
      •  
    • 23.04
      •  
    • 23.01
      •  
    • 22.10
      •  
    • 22.05
      •  
    • 21.12
      •  
    • 21.07
      •  
    • 21.04
      •  
    • 21.01
      •  
    • 20.12
      •  
    • 20.07
      •  
    • 20.04
      •  
    • 20.03
      •  
    • 20.02
      •  
    • 20.01
      •  
    "},{"location":"archive/20.01/","title":"Archived Documentation for 20.01","text":"
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • ejabberd 20.01 release announcement
      •  
    • ejabberd Github Compare from 19.09.1
      •  
    "},{"location":"archive/20.01/upgrade/","title":"Upgrade to ejabberd 20.01","text":""},{"location":"archive/20.01/upgrade/#database-changes","title":"Database changes","text":"
    To migrate from 19.08 (or 19.09) to 20.01, you have to use the following commands on your existing database, after you\u2019ve made a backup of it:
    "},{"location":"archive/20.01/upgrade/#mysql","title":"MySQL","text":"
    If you are using the legacy mysql.sql schema:
     
    ALTER TABLE  oauth_client CHANGE `client` `client_id` text PRIMARY KEY;\nALTER TABLE  oauth_client CHANGE `secret` `client_name` text NOT NULL;\n
     
    If you are using the newer mysql.new.sql schema:
     
    CREATE TABLE oauth_client (\n   client_id varchar(191) NOT NULL PRIMARY KEY,\n   client_name text NOT NULL,\n   grant_type text NOT NULL,\n   options text NOT NULL\n) ENGINE=InnoDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n
    "},{"location":"archive/20.01/upgrade/#postgresql","title":"PostgreSQL","text":"
    CREATE TABLE oauth_client (\n    client_id text PRIMARY KEY,\n    client_name text NOT NULL,\n    grant_type text NOT NULL,\n    options text NOT NULL\n);\nALTER TABLE oauth_client RENAME COLUMN client TO client_id;\nALTER TABLE oauth_client RENAME COLUMN secret TO client_name;\n
    "},{"location":"archive/20.02/","title":"Archived Documentation for 20.02","text":"
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • ejabberd 20.02 release announcement
      •  
    • ejabberd Github Compare from 20.01
      •  
    "},{"location":"archive/20.03/","title":"Archived Documentation for 20.03","text":"
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • ejabberd 20.03 release announcement
      •  
    • ejabberd Github Compare from 20.02
      •  
    "},{"location":"archive/20.04/","title":"Archived Documentation for 20.04","text":"
    This section contains some archived sections for ejabberd 20.04.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 20.04 release announcement
      •  
    • Docs Github Compare from 20.03
      •  
    • ejabberd Github Compare from 20.03
      •  
    "},{"location":"archive/20.07/","title":"Archived Documentation for 20.07","text":"
    This section contains some archived sections for ejabberd 20.07.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 20.07 release announcement
      •  
    • Docs Github Compare from 20.04
      •  
    • ejabberd Github Compare from 20.04
      •  
    "},{"location":"archive/20.12/","title":"Archived Documentation for 20.12","text":"
    This section contains some archived sections for ejabberd 20.12.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 20.12 release announcement
      •  
    • Docs Github Compare from 20.07
      •  
    • ejabberd Github Compare from 20.07
      •  
    "},{"location":"archive/21.01/","title":"Archived Documentation for 21.01","text":"
    This section contains some archived sections for ejabberd 21.01.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 21.01 release announcement
      •  
    • Docs Github Compare from 20.12
      •  
    • ejabberd Github Compare from 20.12
      •  
    "},{"location":"archive/21.04/","title":"Archived Documentation for 21.04","text":"
    This section contains some archived sections for ejabberd 21.04.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 21.04 release announcement
      •  
    • Docs Github Compare from 21.01
      •  
    • ejabberd Github Compare from 21.01
      •  
    "},{"location":"archive/21.04/upgrade/","title":"Upgrade to ejabberd 21.04","text":""},{"location":"archive/21.04/upgrade/#database-changes","title":"Database changes","text":""},{"location":"archive/21.04/upgrade/#mysql","title":"MySQL","text":"
    When migrating from any recent version to 21.04, you may want to apply this MySQL database definition improvement.
     
    We updated the database definition to fix the specified key was too long warnings. By default, the new character set and collation (utf8mb4 and utf8mb4_unicode_ci) will only be used with newly created databases. The existing installations don\u2019t need to convert anything.
     
    However, if you feel like it, after you upgrade to ejabberd 21.04, you can apply the following SQL command to convert your existing MySQL database character set to the latest definition:
     
    alter table push_session convert to character set utf8mb4 collate utf8mb4_unicode_ci;\nalter table mqtt_pub convert to character set utf8mb4 collate utf8mb4_unicode_ci;\n
    "},{"location":"archive/21.07/","title":"Archived Documentation for 21.07","text":"
    This section contains some archived sections for ejabberd 21.07.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 21.07 release announcement
      •  
    • Docs Github Compare from 21.04
      •  
    • ejabberd Github Compare from 21.04
      •  
    "},{"location":"archive/21.12/","title":"Archived Documentation for 21.12","text":"
    This section contains some archived sections for ejabberd 21.12.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 21.12 release announcement
      •  
    • Docs Github Compare from 21.07
      •  
    • ejabberd Github Compare from 21.07
      •  
    "},{"location":"archive/21.12/upgrade/","title":"Upgrade to ejabberd 21.12","text":""},{"location":"archive/21.12/upgrade/#postgresql-new-schema","title":"PostgreSQL new schema","text":"
    If you migrated your PostgreSQL database from old to new schema using previous ejabberd versions, your database may be missing the migration steps for the push_session table. You can update it now with: 
    ALTER TABLE push_session ADD COLUMN server_host text NOT NULL DEFAULT '<HOST>';\nDROP INDEX i_push_usn;\nDROP INDEX i_push_ut;\nALTER TABLE push_session ADD PRIMARY KEY (server_host, username, timestamp);\nCREATE UNIQUE INDEX i_push_session_susn ON push_session USING btree (server_host, username, service, node);\n
     
    In the PostgreSQL new schema, the primary key for the vcard_search table was wrong. How to update an existing database:
     
    ALTER TABLE vcard_search DROP CONSTRAINT vcard_search_pkey;\nALTER TABLE vcard_search ADD PRIMARY KEY (server_host, lusername);\n
    "},{"location":"archive/21.12/upgrade/#mod_register_web-restrictions","title":"mod_register_web restrictions","text":"
    mod_register_web is now affected by the restrictions that you configure in mod_register.
    "},{"location":"archive/22.05/","title":"Archived Documentation for 22.05","text":"
    This section contains some archived sections for ejabberd 22.05.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 22.05 release announcement
      •  
    • Docs Github Compare from 21.12
      •  
    • ejabberd Github Compare from 21.12
      •  
    "},{"location":"archive/22.05/upgrade/","title":"Upgrade to ejabberd 22.05","text":""},{"location":"archive/22.05/upgrade/#new-indexes-in-sql-for-muc","title":"New Indexes in SQL for MUC","text":"
    Two new indexes were added to optimize MUC. Those indexes can be added in the database before upgrading to 22.05, that will not affect older versions.
     
    To update an existing database, depending on the schema used to create it:
     
       
    •  
      MySQL (mysql.sql or mysql.new.sql): 
      CREATE INDEX i_muc_room_host_created_at ON muc_room(host(75), created_at);\nCREATE INDEX i_muc_room_subscribers_jid USING BTREE ON muc_room_subscribers(jid);\n
       
      •  
    •  
      PostgreSQL (pg.sql or pg.new.sql): 
      CREATE INDEX i_muc_room_host_created_at ON muc_room USING btree (host, created_at);\nCREATE INDEX i_muc_room_subscribers_jid ON muc_room_subscribers USING btree (jid);\n
       
      •  
    •  
      SQLite (lite.sql or lite.new.sql): 
      CREATE INDEX i_muc_room_host_created_at ON muc_room (host, created_at);\nCREATE INDEX i_muc_room_subscribers_jid ON muc_room_subscribers(jid);\n
       
      •  
    •  
      MS SQL (mssql.sql): 
      CREATE INDEX [muc_room_host_created_at] ON [muc_registered] (host, nick)\n    WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\nCREATE INDEX [muc_room_subscribers_jid] ON [muc_room_subscribers] (jid);\n
       
      •  
    "},{"location":"archive/22.05/upgrade/#fixes-in-postgresql-new-schema","title":"Fixes in PostgreSQL New Schema","text":"
    If you moved your PostgreSQL database from old to new schema using mod_admin_update_sql or the update_sql API command, be aware that those methods forgot to perform some updates.
     
    To fix an existing PostgreSQL database schema, apply those changes manually:
     
    ALTER TABLE archive DROP CONSTRAINT i_archive_sh_peer;\nALTER TABLE archive DROP CONSTRAINT i_archive_sh_bare_peer;\nCREATE INDEX i_archive_sh_username_peer ON archive USING btree (server_host, username, peer);\nCREATE INDEX i_archive_sh_username_bare_peer ON archive USING btree (server_host, username, bare_peer);\n\nDROP TABLE carboncopy;\n\nALTER TABLE push_session DROP CONSTRAINT i_push_session_susn;\nCREATE UNIQUE INDEX i_push_session_susn ON push_session USING btree (server_host, username, service, node);\n\nALTER TABLE mix_pam DROP CONSTRAINT i_mix_pam;\nALTER TABLE mix_pam DROP CONSTRAINT i_mix_pam_us;\nCREATE UNIQUE INDEX i_mix_pam ON mix_pam (username, server_host, channel, service);\nCREATE INDEX i_mix_pam_us ON mix_pam (username, server_host);\n\nALTER TABLE route DROP CONSTRAINT i_route;\nCREATE UNIQUE INDEX i_route ON route USING btree (domain, server_host, node, pid);\n\nALTER TABLE mqtt_pub DROP CONSTRAINT i_mqtt_topic;\nCREATE UNIQUE INDEX i_mqtt_topic_server ON mqtt_pub (topic, server_host);\n
    "},{"location":"archive/22.05/upgrade/#api-changes","title":"API Changes","text":"
    The oauth_revoke_token API command has changed its returned result. Check oauth_revoke_token documentation.
    "},{"location":"archive/22.10/","title":"Archived Documentation for 22.10","text":"
    This section contains some archived sections for ejabberd 22.10.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 22.10 release announcement
      •  
    • Docs Github Compare from 22.05
      •  
    • ejabberd Github Compare from 22.05
      •  
    "},{"location":"archive/22.10/upgrade/","title":"Upgrade to ejabberd 22.10","text":"
    There are no breaking changes in SQL schemas, configuration, or commands API. If you develop an ejabberd module, notice two hooks have changed: muc_subscribed and muc_unsubscribed.
    "},{"location":"archive/22.10/upgrade/#hook-changes","title":"Hook Changes","text":"
    Two hooks have changed: muc_subscribed and muc_unsubscribed. Now they get the packet and room state, and can modify the sent packets. If you write source code that adds functions to those hooks, please notice that previously they were ran like:
     
    ejabberd_hooks:run(muc_subscribed, ServerHost, [ServerHost, Room, Host, BareJID]);\n
     
    and now they are ran like this: 
    {Packet2a, Packet2b} = ejabberd_hooks:run_fold(muc_subscribed, ServerHost, {Packet1a, Packet1b},\n[ServerHost, Room, Host, BareJID, StateData]),\n
     being Packet1b a copy of Packet1a without the jid attribute in the muc_subscribe element.
    "},{"location":"archive/23.01/","title":"Archived Documentation for 23.01","text":"
    This section contains some archived sections for ejabberd 23.01.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 23.01 release announcement
      •  
    • Docs Github Compare from 22.10
      •  
    • ejabberd Github Compare from 22.10
      •  
    "},{"location":"archive/23.01/upgrade/","title":"Upgrade to ejabberd 23.01","text":"
    There is a new module, new hooks, new options, and some option accepts additional values, but there are no breaking changes in SQL schemas, configuration, or commands API.
     
    Please check the ejabberd 23.01 release announcement for details about the improvements.
    "},{"location":"archive/23.01/upgrade/#changes-in-option-outgoing_s2s_families","title":"Changes in option outgoing_s2s_families","text":"
    The outgoing_s2s_families top-level option specifies which address families to try, in what order.
     
    The default value has now been changed to try IPv6 first, as servers are within data centers where IPv6 is more commonly enabled (contrary to clients). And if it\u2019s not present, then it\u2019ll just fall back to IPv4.
     
    By the way, this option is obsolete and irrelevant when using ejabberd 23.01 and Erlang/OTP 22, or newer versions of them.
    "},{"location":"archive/23.04/","title":"Archived Documentation for 23.04","text":"
    This section contains some archived sections for ejabberd 23.04.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 23.04 release announcement
      •  
    • Docs Github Compare from 23.01
      •  
    • ejabberd Github Compare from 23.01
      •  
    "},{"location":"archive/23.04/upgrade/","title":"Upgrade to ejabberd 23.04","text":"
    There is a new module, new hooks, new options, and some option accepts additional values, and more importantly, there are many improvements in the SQL schemas, and a change in the ecs container image.
     
    Please check the ejabberd 23.04 release announcement for details about the improvements.
    "},{"location":"archive/23.04/upgrade/#many-improvements-in-sql-databases","title":"Many improvements in SQL databases","text":"
    There are many improvements in the SQL databases field (see #3980 and #3982):
     
       
    • Added support to migrate MySQL and MS SQL to new schema, fixed a long standing bug, and many other improvements.
      •  
    • Regarding MS SQL, there are schema fixes, added support to new schema, and the corresponding schema migration, along other minor improvements and bugfixes.
      •  
    • The automated ejabberd testing now also runs tests on upgraded schema databases, and supports for running tests on MS SQL
      •  
    • And also fixed other minor SQL schema inconsistencies, removed unnecessary indexes and changed PostgreSQL SERIAL to BIGSERIAL columns.
      •  
     
    Please upgrade your existing SQL database, check the notes later in this document!
    "},{"location":"archive/23.04/upgrade/#erlang-node-name-in-ecs-container-image","title":"Erlang node name in ecs container image","text":"
    The ecs container image is built using the files from docker-ejabberd/ecs, and published in docker.io/ejabberd/ecs. This image in general gets only minimal fixes, no major or breaking changes, but in this release it got a change that will require the administrator intervention.
     
    The Erlang node name is now by default fixed to ejabberd@localhost, instead of being variably set by the container host name. If you previously allowed ejabberd to decide its node name (which was random), then it will now create a new mnesia database instead of using the previous one: 
    $ docker exec -it ejabberd ls /home/ejabberd/database/\nejabberd@1ca968a0301a\nejabberd@localhost\n...\n
     
    A simple solution is to create the container providing ERLANG_NODE_ARG with the old erlang node name, for example: 
    docker run ... -e ERLANG_NODE_ARG=ejabberd@1ca968a0301a\n
     or in docker-compose.yml 
    version: '3.7'\nservices:\n  main:\n    image: ejabberd/ecs\n    environment:\n      - ERLANG_NODE_ARG=ejabberd@1ca968a0301a\n
     
    Another solution is to change the mnesia node name in the mnesia spool files.
    "},{"location":"archive/23.04/upgrade/#sql-databases-update","title":"SQL databases update","text":"
    Those notes allow to apply the improvements in the SQL database schemas from this ejabberd release to your existing SQL database. Please take into account what database you use, and whether it is the default or the new schema.
    "},{"location":"archive/23.04/upgrade/#postgresql-new-schema","title":"PostgreSQL new schema","text":"
    Fix a long standing bug in new schema on PostgreSQL. The fix for any existing impacted installations is the same: 
    ALTER TABLE vcard_search DROP CONSTRAINT vcard_search_pkey;\nALTER TABLE vcard_search ADD PRIMARY KEY (server_host, lusername);\n
    "},{"location":"archive/23.04/upgrade/#postgresql-defaultnew-schema","title":"PostgreSQL default/new schema","text":"
    To convert columns to allow up to 2 billion rows in these tables. This conversion will require full table rebuilds, and will take a long time if tables already have lots of rows. Optional: this is not necessary if the tables are never likely to grow large.
     
    ALTER TABLE archive ALTER COLUMN id TYPE BIGINT;\nALTER TABLE privacy_list ALTER COLUMN id TYPE BIGINT;\nALTER TABLE pubsub_node ALTER COLUMN nodeid TYPE BIGINT;\nALTER TABLE pubsub_state ALTER COLUMN stateid TYPE BIGINT;\nALTER TABLE spool ALTER COLUMN seq TYPE BIGINT;\n
    "},{"location":"archive/23.04/upgrade/#postgresqlsqlite-default-schema","title":"PostgreSQL/SQLite default schema","text":"
    DROP INDEX i_rosteru_username;\nDROP INDEX i_sr_user_jid;\nDROP INDEX i_privacy_list_username;\nDROP INDEX i_private_storage_username;\nDROP INDEX i_muc_online_users_us;\nDROP INDEX i_route_domain;\nDROP INDEX i_mix_participant_chan_serv;\nDROP INDEX i_mix_subscription_chan_serv_ud;\nDROP INDEX i_mix_subscription_chan_serv;\nDROP INDEX i_mix_pam_us;\n
    "},{"location":"archive/23.04/upgrade/#postgresqlsqlite-new-schema","title":"PostgreSQL/SQLite new schema","text":"
    DROP INDEX i_rosteru_sh_username;\nDROP INDEX i_sr_user_sh_jid;\nDROP INDEX i_privacy_list_sh_username;\nDROP INDEX i_private_storage_sh_username;\nDROP INDEX i_muc_online_users_us;\nDROP INDEX i_route_domain;\nDROP INDEX i_mix_participant_chan_serv;\nDROP INDEX i_mix_subscription_chan_serv_ud;\nDROP INDEX i_mix_subscription_chan_serv;\nDROP INDEX i_mix_pam_us;\n
     
    And now add index that might be missing
     
    In PostgreSQL: 
    CREATE INDEX i_push_session_sh_username_timestamp ON push_session USING btree (server_host, username, timestamp);\n
     
    In SQLite: 
    CREATE INDEX i_push_session_sh_username_timestamp ON push_session (server_host, username, timestamp);\n
    "},{"location":"archive/23.04/upgrade/#mysql-default-schema","title":"MySQL default schema","text":"
    ALTER TABLE rosterusers DROP INDEX i_rosteru_username;\nALTER TABLE sr_user DROP INDEX i_sr_user_jid;\nALTER TABLE privacy_list DROP INDEX i_privacy_list_username;\nALTER TABLE private_storage DROP INDEX i_private_storage_username;\nALTER TABLE muc_online_users DROP INDEX i_muc_online_users_us;\nALTER TABLE route DROP INDEX i_route_domain;\nALTER TABLE mix_participant DROP INDEX i_mix_participant_chan_serv;\nALTER TABLE mix_subscription DROP INDEX i_mix_subscription_chan_serv_ud;\nALTER TABLE mix_subscription DROP INDEX i_mix_subscription_chan_serv;\nALTER TABLE mix_pam DROP INDEX i_mix_pam_u;\n
    "},{"location":"archive/23.04/upgrade/#mysql-new-schema","title":"MySQL new schema","text":"
    ALTER TABLE rosterusers DROP INDEX i_rosteru_sh_username;\nALTER TABLE sr_user DROP INDEX i_sr_user_sh_jid;\nALTER TABLE privacy_list DROP INDEX i_privacy_list_sh_username;\nALTER TABLE private_storage DROP INDEX i_private_storage_sh_username;\nALTER TABLE muc_online_users DROP INDEX i_muc_online_users_us;\nALTER TABLE route DROP INDEX i_route_domain;\nALTER TABLE mix_participant DROP INDEX i_mix_participant_chan_serv;\nALTER TABLE mix_subscription DROP INDEX i_mix_subscription_chan_serv_ud;\nALTER TABLE mix_subscription DROP INDEX i_mix_subscription_chan_serv;\nALTER TABLE mix_pam DROP INDEX i_mix_pam_us;\n
     Add index that might be missing: 
    CREATE INDEX i_push_session_sh_username_timestamp ON push_session (server_host, username(191), timestamp);\n
    "},{"location":"archive/23.04/upgrade/#ms-sql","title":"MS SQL","text":"
    DROP INDEX [rosterusers_username] ON [rosterusers];\nDROP INDEX [sr_user_jid] ON [sr_user];\nDROP INDEX [privacy_list_username] ON [privacy_list];\nDROP INDEX [private_storage_username] ON [private_storage];\nDROP INDEX [muc_online_users_us] ON [muc_online_users];\nDROP INDEX [route_domain] ON [route];\ngo\n
     
    MS SQL schema was missing some tables added in earlier versions of ejabberd:
     
    CREATE TABLE [dbo].[mix_channel] (\n    [channel] [varchar] (250) NOT NULL,\n    [service] [varchar] (250) NOT NULL,\n    [username] [varchar] (250) NOT NULL,\n    [domain] [varchar] (250) NOT NULL,\n    [jid] [varchar] (250) NOT NULL,\n    [hidden] [smallint] NOT NULL,\n    [hmac_key] [text] NOT NULL,\n    [created_at] [datetime] NOT NULL DEFAULT GETDATE()\n) TEXTIMAGE_ON [PRIMARY];\n\nCREATE UNIQUE CLUSTERED INDEX [mix_channel] ON [mix_channel] (channel, service)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE INDEX [mix_channel_serv] ON [mix_channel] (service)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE TABLE [dbo].[mix_participant] (\n    [channel] [varchar] (250) NOT NULL,\n    [service] [varchar] (250) NOT NULL,\n    [username] [varchar] (250) NOT NULL,\n    [domain] [varchar] (250) NOT NULL,\n    [jid] [varchar] (250) NOT NULL,\n    [id] [text] NOT NULL,\n    [nick] [text] NOT NULL,\n    [created_at] [datetime] NOT NULL DEFAULT GETDATE()\n) TEXTIMAGE_ON [PRIMARY];\n\nCREATE UNIQUE INDEX [mix_participant] ON [mix_participant] (channel, service, username, domain)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE INDEX [mix_participant_chan_serv] ON [mix_participant] (channel, service)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE TABLE [dbo].[mix_subscription] (\n    [channel] [varchar] (250) NOT NULL,\n    [service] [varchar] (250) NOT NULL,\n    [username] [varchar] (250) NOT NULL,\n    [domain] [varchar] (250) NOT NULL,\n    [node] [varchar] (250) NOT NULL,\n    [jid] [varchar] (250) NOT NULL\n);\n\nCREATE UNIQUE INDEX [mix_subscription] ON [mix_subscription] (channel, service, username, domain, node)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE INDEX [mix_subscription_chan_serv_ud] ON [mix_subscription] (channel, service, username, domain)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE INDEX [mix_subscription_chan_serv_node] ON [mix_subscription] (channel, service, node)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE INDEX [mix_subscription_chan_serv] ON [mix_subscription] (channel, service)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE TABLE [dbo].[mix_pam] (\n    [username] [varchar] (250) NOT NULL,\n    [channel] [varchar] (250) NOT NULL,\n    [service] [varchar] (250) NOT NULL,\n    [id] [text] NOT NULL,\n    [created_at] [datetime] NOT NULL DEFAULT GETDATE()\n) TEXTIMAGE_ON [PRIMARY];\n\nCREATE UNIQUE CLUSTERED INDEX [mix_pam] ON [mix_pam] (username, channel, service)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\ngo\n
     
    MS SQL also had some incompatible column types:
     
    ALTER TABLE [dbo].[muc_online_room] ALTER COLUMN [node] VARCHAR (250);\nALTER TABLE [dbo].[muc_online_room] ALTER COLUMN [pid] VARCHAR (100);\nALTER TABLE [dbo].[muc_online_users] ALTER COLUMN [node] VARCHAR (250);\nALTER TABLE [dbo].[pubsub_node_option] ALTER COLUMN [name] VARCHAR (250);\nALTER TABLE [dbo].[pubsub_node_option] ALTER COLUMN [val] VARCHAR (250);\nALTER TABLE [dbo].[pubsub_node] ALTER COLUMN [plugin] VARCHAR (32);\ngo\n
     
    ... and mqtt_pub table was incorrectly defined in old schema:
     
    ALTER TABLE [dbo].[mqtt_pub] DROP CONSTRAINT [i_mqtt_topic_server];\nALTER TABLE [dbo].[mqtt_pub] DROP COLUMN [server_host];\nALTER TABLE [dbo].[mqtt_pub] ALTER COLUMN [resource] VARCHAR (250);\nALTER TABLE [dbo].[mqtt_pub] ALTER COLUMN [topic] VARCHAR (250);\nALTER TABLE [dbo].[mqtt_pub] ALTER COLUMN [username] VARCHAR (250);\nCREATE UNIQUE CLUSTERED INDEX [dbo].[mqtt_topic] ON [mqtt_pub] (topic)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\ngo\n
     
    ... and sr_group index/PK was inconsistent with other DBs:
     
    ALTER TABLE [dbo].[sr_group] DROP CONSTRAINT [sr_group_PRIMARY];\nCREATE UNIQUE CLUSTERED INDEX [sr_group_name] ON [sr_group] ([name])\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\ngo\n
    "},{"location":"archive/23.10/","title":"Archived Documentation for 23.10","text":"
    This section contains some archived sections for ejabberd 23.10.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 23.10 release announcement
      •  
    • Docs Github Compare from 23.04
      •  
    • ejabberd Github Compare from 23.04
      •  
    "},{"location":"archive/23.10/upgrade/","title":"Upgrade to ejabberd 23.10","text":"
    There is a new module, several new options, an API command has changed, but there are no breaking changes in the configuration, SQL schema.
     
    The get_roster API command has a different output, please check the release announcement for details.
     
    The MUC room option allow_private_messages is converted to allowpm. This conversion is automatic, you don't need to perform any task. However, once you update to ejabberd 23.10, the stored rooms options will be converted, and you should not attempt to use that content with ejabberd versions older than 23.10.
     
    gen_mod API is simplified. If you write your own ejabberd modules, you can optionally use that new API.
     
    In summary, you can update from previous ejabberd version to this one without performing any upgrade tasks.
     
    Please check the ejabberd 23.10 release announcement for details about the improvements.
    "},{"location":"archive/24.02/","title":"Archived Documentation for 24.02","text":"
    This section contains some archived sections for ejabberd 24.02.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 24.02 release announcement
      •  
    • Docs Github Compare from 24.02
      •  
    • ejabberd Github Compare from 24.02
      •  
    "},{"location":"archive/24.02/upgrade/","title":"Upgrade to ejabberd 24.02","text":"
    If you upgrade ejabberd from a previous release to 24.02, please review those changes:
     
       
    • Update the SQL schema
      •  
    • Update API commands as explained below, or use API versioning
      •  
    • Mix or Rebar3 used by default instead of Rebar to compile ejabberd
      •  
    • Authentication workaround for Converse.js and Strophe.js
      •  
    "},{"location":"archive/24.02/upgrade/#update-the-sql-schema","title":"Update the SQL schema","text":"
    The table archive has a text column named origin_id (see commit 975681). You have two methods to update the SQL schema of your existing database:
     
    If using MySQL or PosgreSQL, you can enable the option update_sql_schema and ejabberd will take care to update the SQL schema when needed: add in your ejabberd configuration file the line update_sql_schema: true
     
    If you are using other database, or prefer to update manually the SQL schema:
     
       
    •  
      MySQL default schema: 
      ALTER TABLE archive ADD COLUMN origin_id text NOT NULL DEFAULT '';\nALTER TABLE archive ALTER COLUMN origin_id DROP DEFAULT;\nCREATE INDEX i_archive_username_origin_id USING BTREE ON archive(username(191), origin_id(191));\n
       
      •  
    •  
      MySQL new schema: 
      ALTER TABLE archive ADD COLUMN origin_id text NOT NULL DEFAULT '';\nALTER TABLE archive ALTER COLUMN origin_id DROP DEFAULT;\nCREATE INDEX i_archive_sh_username_origin_id USING BTREE ON archive(server_host(191), username(191), origin_id(191));\n
       
      •  
    •  
      PostgreSQL default schema: 
      ALTER TABLE archive ADD COLUMN origin_id text NOT NULL DEFAULT '';\nALTER TABLE archive ALTER COLUMN origin_id DROP DEFAULT;\nCREATE INDEX i_archive_username_origin_id ON archive USING btree (username, origin_id);\n
       
      •  
    •  
      PostgreSQL new schema: 
      ALTER TABLE archive ADD COLUMN origin_id text NOT NULL DEFAULT '';\nALTER TABLE archive ALTER COLUMN origin_id DROP DEFAULT;\nCREATE INDEX i_archive_sh_username_origin_id ON archive USING btree (server_host, username, origin_id);\n
       
      •  
    •  
      MSSQL default schema: 
      ALTER TABLE [dbo].[archive] ADD [origin_id] VARCHAR (250) NOT NULL;\nCREATE INDEX [archive_username_origin_id] ON [archive] (username, origin_id)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n
       
      •  
    •  
      MSSQL new schema: 
      ALTER TABLE [dbo].[archive] ADD [origin_id] VARCHAR (250) NOT NULL;\nCREATE INDEX [archive_sh_username_origin_id] ON [archive] (server_host, username, origin_id)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n
       
      •  
    •  
      SQLite default schema: 
      ALTER TABLE archive ADD COLUMN origin_id text NOT NULL DEFAULT '';\nCREATE INDEX i_archive_username_origin_id ON archive (username, origin_id);\n
       
      •  
    •  
      SQLite new schema: 
      ALTER TABLE archive ADD COLUMN origin_id text NOT NULL DEFAULT '';\nCREATE INDEX i_archive_sh_username_origin_id ON archive (server_host, username, origin_id);\n
       
      •  
    "},{"location":"archive/24.02/upgrade/#support-for-api-versioning","title":"Support for API versioning","text":"
    Until now, when a new ejabberd release changed some API command (an argument renamed, a result in a different format...), then you had to update your API client to the new API at the same time that you updated ejabberd.
     
    Now the ejabberd API commands can have different versions, by default the most recent one is used, and the API client can specify the API version it supports.
     
    In fact, this feature was implemented seven years ago, included in ejabberd 16.04, documented in ejabberd Docs: API Versioning... but it was never actually used!
     
    This ejabberd release includes many fixes to get API versioning up to date, and it starts being used by several commands.
     
    Let's say that ejabberd 23.10 implemented API version 0, and this ejabberd 24.02 adds API version 1. You may want to update your API client to use the new API version 1... or you can continue using API version 0 and delay API update a few weeks or months.
     
    To continue using API version 0: - if using ejabberdctl, use the switch --version 0. For example: ejabberdctl --version 0 get_roster admin localhost - if using mod_http_api, in ejabberd configuration file add v0 to the request_handlers path. For example: /api/v0: mod_http_api
     
    Check the ejabberd 24.02 full release notes for more details about the changed commands.
     
    Check the full documentation in ejabberd Docs: API Versioning.
    "},{"location":"archive/24.02/upgrade/#use-mix-or-rebar3-by-default-instead-of-rebar-to-compile-ejabberd","title":"Use Mix or Rebar3 by default instead of Rebar to compile ejabberd","text":"
    ejabberd uses Rebar to manage dependencies and compilation since ejabberd 13.10 4d8f770. However, that tool is obsolete and unmaintained since years ago, because there is a complete replacement:
     
    Rebar3 is supported by ejabberd since 20.12 0fc1aea. Among other benefits, this allows to download dependencies from hex.pm and cache them in your system instead of downloading them from git every time, and allows to compile Elixir files and Elixir dependencies.
     
    In fact, ejabberd can be compiled using mix (a tool included with the Elixir programming language) since ejabberd 15.04 ea8db99 (with improvements in ejabberd 21.07 4c5641a)
     
    For those reasons, the tool selection performed by ./configure will now be:
     
       
    • If --with-rebar=rebar3 but Rebar3 not found installed in the system, use the rebar3 binary included with ejabberd
      •  
    • Use the program specified in option: --with-rebar=/path/to/bin
      •  
    • If none is specified, use the system mix
      •  
    • If Elixir not found, use the system rebar3
      •  
    • If Rebar3 not found, use the rebar3 binary included with ejabberd
      •  
    "},{"location":"archive/24.02/upgrade/#authentication-workaround-for-conversejs-and-strophejs","title":"Authentication workaround for Converse.js and Strophe.js","text":"
    This ejabberd release includes support for XEP-0474: SASL SCRAM Downgrade Protection, and some clients may not support it correctly yet.
     
    If you are using Converse.js 10.1.6 or older, Movim 0.23 Kojima or older, or any other client based in Strophe.js v1.6.2 or older, you may notice that they cannot authenticate correctly to ejabberd.
     
    To solve that problem, either update to newer versions of those programs (if they exist), or you can enable temporarily the option disable_sasl_scram_downgrade_protection in the ejabberd configuration file ejabberd.yml like this: 
    disable_sasl_scram_downgrade_protection: true\n
    "},{"location":"archive/older-releases/from_15.11_to_16.02/","title":"Upgrade to ejabberd 16.02","text":"
    The MySQL schema changed to UTF-8 encoding. If you are using MySQL backend you must upgrade the schema before starting ejabberd 16.02.
    "},{"location":"archive/older-releases/from_15.11_to_16.02/#sql-database-upgrade","title":"SQL database upgrade","text":"
    Example for MySQL: 
    mysql -h host -u user database -p << EOF\nALTER DATABASE ejabberd CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nALTER TABLE users CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE users MODIFY username varchar(191);\n\nALTER TABLE last CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE last MODIFY username varchar(191);\n\nALTER TABLE rosterusers CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE rosterusers MODIFY username varchar(191);\nALTER TABLE rosterusers MODIFY jid varchar(191);\n\nALTER TABLE rostergroups CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE rostergroups MODIFY username varchar(191);\nALTER TABLE rostergroups MODIFY jid varchar(191);\n\nALTER TABLE sr_group CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE sr_group MODIFY username varchar(191);\n\nALTER TABLE spool CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE spool MODIFY username varchar(191);\nALTER TABLE spool MODIFY xml BLOB NOT NULL;\n\nALTER TABLE archive CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE archive MODIFY username varchar(191);\nALTER TABLE archive MODIFY peer varchar(191);\nALTER TABLE archive MODIFY bare_peer varchar(191);\nALTER TABLE archive MODIFY nick varchar(191);\n\nALTER TABLE archive_prefs CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE archive_prefs MODIFY username varchar(191);\n\nALTER TABLE vcard CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE vcard MODIFY username varchar(191);\n\nALTER TABLE vcard_xupdate CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE vcard_xupdate MODIFY username varchar(191);\n\nALTER TABLE vcard_search CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE vcard_search MODIFY username varchar(191);\nALTER TABLE vcard_search MODIFY lusername varchar(191);\nALTER TABLE vcard_search MODIFY lfn varchar(191);\nALTER TABLE vcard_search MODIFY lfamily varchar(191);\nALTER TABLE vcard_search MODIFY lgiven varchar(191);\nALTER TABLE vcard_search MODIFY lmiddle varchar(191);\nALTER TABLE vcard_search MODIFY lnickname varchar(191);\nALTER TABLE vcard_search MODIFY lbday varchar(191);\nALTER TABLE vcard_search MODIFY lctry varchar(191);\nALTER TABLE vcard_search MODIFY llocality varchar(191);\nALTER TABLE vcard_search MODIFY lemail varchar(191);\nALTER TABLE vcard_search MODIFY lorgname varchar(191);\nALTER TABLE vcard_search MODIFY lorgunit varchar(191);\n\nALTER TABLE privacy_default_list CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE privacy_default_list MODIFY username varchar(191);\nALTER TABLE privacy_default_list MODIFY name varchar(191);\n\nALTER TABLE privacy_list CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE privacy_list MODIFY username varchar(191);\nALTER TABLE privacy_list MODIFY name varchar(191);\n\nALTER TABLE privacy_list_data CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nALTER TABLE private_storage CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE private_storage MODIFY username varchar(191);\nALTER TABLE private_storage MODIFY namespace varchar(191);\n\nALTER TABLE roster_version CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE roster_version MODIFY username varchar(191);\n\nALTER TABLE pubsub_node CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE pubsub_node_option CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE pubsub_node_state CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE pubsub_node_item CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE pubsub_subscription_opt CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nALTER TABLE muc_room CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE muc_registered CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nALTER TABLE irc_custom CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nALTER TABLE motd CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE motd MODIFY username varchar(191);\n\nALTER TABLE caps_features CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE caps_features MODIFY node varchar(191);\nALTER TABLE caps_features MODIFY subnode varchar(191);\n\nALTER TABLE sm CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE sm MODIFY username varchar(191);\nALTER TABLE sm MODIFY resource varchar(191);\n\nALTER TABLE  CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE  MODIFY username varchar(191);\nEOF\n
    "},{"location":"archive/older-releases/from_16.02_to_16.03/","title":"Upgrade to ejabberd 16.03","text":"
    If you are using an sql backend for authentication, you must upgrade your schema before starting ejabberd 16.03. This can be safely done while a previous version of ejabberd is actually running.
    "},{"location":"archive/older-releases/from_16.02_to_16.03/#sql-database-upgrade","title":"SQL database upgrade","text":"
    Example for MySQL: 
    mysql -h host -u user database -p << EOF\nALTER TABLE users ADD COLUMN serverkey text NOT NULL DEFAULT '';\nALTER TABLE users ADD COLUMN salt text NOT NULL DEFAULT '';\nALTER TABLE users ADD COLUMN iterationcount integer NOT NULL DEFAULT 0;\nEOF\n
    "},{"location":"archive/older-releases/from_16.03_to_16.04/","title":"Upgrade to ejabberd 16.04","text":"
    Two data type must be changed on the users table. This can be done at any time while ejabberd 16.03 is running. If you run an older version of ejabberd you must follow database upgrade process for 16.03 first.
     
    Note: this applies only to MySQL. Other backend does not need upgrade.
    "},{"location":"archive/older-releases/from_16.03_to_16.04/#mysql-database-upgrade","title":"MySQL database upgrade","text":"
    mysql -h host -u user database -p << EOF\nALTER TABLE users MODIFY serverkey varchar(64) NOT NULL DEFAULT '';\nALTER TABLE users MODIFY salt varchar(64) NOT NULL DEFAULT '';\nEOF\n
    "},{"location":"archive/older-releases/from_16.04_to_16.06/","title":"Upgrade to ejabberd 16.06","text":"
    One data type must be changed on the users table. This can be done at any time while ejabberd 16.04 is running. If you run an older version of ejabberd you must follow database upgrade process for 16.03 and 16.04 first.
     
    Note: this applies only to MySQL. Other backend does not need upgrade.
    "},{"location":"archive/older-releases/from_16.04_to_16.06/#mysql-database-upgrade","title":"MySQL database upgrade","text":"
    mysql -h host -u user database -p << EOF\nALTER TABLE muc_room MODIFY opts mediumtext NOT NULL;\nEOF\n
    "},{"location":"archive/older-releases/from_16.06_to_16.08/","title":"Upgrade to ejabberd 16.08","text":"
    You need to create a new table to support the new OAuth feature before starting ejabberd 16.08.
    "},{"location":"archive/older-releases/from_16.06_to_16.08/#sql-database-upgrade","title":"SQL database upgrade","text":"
    Example for MySQL: 
    mysql -h host -u user database -p << EOF\nCREATE TABLE oauth_token (\n  token varchar(191) NOT NULL PRIMARY KEY,\n  jid text NOT NULL,\n  scope text NOT NULL,\n  expire bigint NOT NULL\n) ENGINE=InnoDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nEOF\n
    "},{"location":"archive/older-releases/from_16.08_to_17.03/","title":"Upgrade to ejabberd 17.03","text":"
    If you are upgrading from ejabberd 16.08, 16.09, 16.12 or 17.01, and are using an SQL backend, you need to alter tables for better PubSub support before starting ejabberd 17.03.
    "},{"location":"archive/older-releases/from_16.08_to_17.03/#mysql-database-upgrade","title":"MySQL database upgrade","text":"
    If you're running MySQL, this change in not mandatory but highly recommended
     
    mysql -h host -u user database -p << EOF\nALTER TABLE rosterusers MODIFY subscribe text NOT NULL;\n\nUPDATE pubsub_node SET parent='' WHERE parent=NULL;\n\nALTER TABLE pubsub_node\n MODIFY host TEXT NOT NULL,\n MODIFY node TEXT NOT NULL,\n MODIFY parent VARCHAR(191) NOT NULL DEFAULT '',\n MODIFY type TEXT NOT NULL;\n\nALTER TABLE pubsub_node_option \n MODIFY name text NOT NULL,\n MODIFY val text NOT NULL;\n\nALTER TABLE pubsub_node_owner\n MODIFY owner text NOT NULL;\n\nUPDATE pubsub_state SET subscriptions='' WHERE subscriptions=NULL;\n\nALTER TABLE pubsub_state\n MODIFY jid text NOT NULL,\n MODIFY subscriptions VARCHAR(191) NOT NULL DEFAULT '';\n\nALTER TABLE pubsub_item\n MODIFY itemid text NOT NULL,\n MODIFY publisher text NOT NULL,\n MODIFY creation text NOT NULL,\n MODIFY modification text NOT NULL,\n MODIFY payload text NOT NULL;\n\nALTER TABLE pubsub_subscription_opt\n MODIFY subid text NOT NULL,\n MODIFY opt_value text NOT NULL;\nEOF\n
    "},{"location":"archive/older-releases/from_16.08_to_17.03/#postgresql-database-upgrade","title":"PostgreSQL database upgrade","text":"
    If you're running PostgreSQL, this change is mandatory.
     
    psql -W -h host database user << EOF\nALTER TABLE rosterusers ALTER COLUMN subscribe SET NOT NULL;\n\nUPDATE pubsub_node SET parent='' WHERE parent=NULL;\n\nALTER TABLE pubsub_node\nALTER COLUMN host SET NOT NULL,\nALTER COLUMN node SET NOT NULL,\nALTER COLUMN parent SET NOT NULL,\nALTER COLUMN parent SET DEFAULT '',\nALTER COLUMN type SET NOT NULL;\n\nALTER TABLE pubsub_node_option \nALTER COLUMN name SET NOT NULL,\nALTER COLUMN val SET NOT NULL;\n\nALTER TABLE pubsub_node_owner\nALTER COLUMN  owner SET NOT NULL;\n\nUPDATE pubsub_state SET subscriptions='' WHERE subscriptions=NULL;\n\nALTER TABLE pubsub_state\nALTER COLUMN jid SET NOT NULL,\nALTER COLUMN subscriptions SET NOT NULL,\nALTER COLUMN subscriptions SET DEFAULT '';\n\nALTER TABLE pubsub_item\nALTER COLUMN itemid SET NOT NULL,\nALTER COLUMN publisher SET NOT NULL,\nALTER COLUMN creation SET NOT NULL,\nALTER COLUMN modification SET NOT NULL,\nALTER COLUMN payload SET NOT NULL;\n\nALTER TABLE pubsub_subscription_opt\nALTER COLUMN subid SET NOT NULL,\nALTER COLUMN opt_value SET NOT NULL;\nEOF\n
    "},{"location":"archive/older-releases/from_16.08_to_17.03/#sqlite-database-upgrade","title":"SQLite database upgrade","text":"
    If you're running SQLite, you have to create a new database with schema file provided in ejabberd 17.03 sources. Then you have to export all data from your current database and import into the newly created database.
    "},{"location":"archive/older-releases/from_16.08_to_17.03/#mssql-database-upgrade","title":"MsSQL database upgrade","text":"
    We do not provide tested upgrade procedure on MsSQL Server. The upgrade may not be mandatory (this was not tested) but highly recommended. You have to create a new database with schema file provided in ejabberd 17.03 sources. Then you have to export all data from your current database and import into the newly created database.
    "},{"location":"archive/older-releases/from_17.03_to_17.06/","title":"Upgrade to ejabberd 17.06","text":"
    You may have to apply few changes if you are upgrading from ejabberd 17.03 or 17.04. While this is not mandatory, it's recommended to follow this procedure.
    "},{"location":"archive/older-releases/from_17.03_to_17.06/#ejabberdctl-script","title":"ejabberdctl script","text":"
    Due to a major refactor of the ejabberdctl script, which also remove all bashisms, you should check your packaging and your system's version of ejabberdctl script. While old script still works, you are encouraged to use the new one. This may depends on media you install ejabberd from.
    "},{"location":"archive/older-releases/from_17.03_to_17.06/#database","title":"Database","text":"
    There are no changes on database schema since 17.03 which requires migration procedure. However, we removed the vcard_xupdate table. If you want to cleanup your database, you can remove that table, as it is no longer used by the module.
    "},{"location":"archive/older-releases/from_17.06_to_17.09/","title":"Upgrade to ejabberd 17.09","text":"
    You should follow this procedure if you are upgrading from ejabberd 17.06, 17.07 or 17.08.
    "},{"location":"archive/older-releases/from_17.06_to_17.09/#ejabberdctl-script","title":"ejabberdctl script","text":"
    Due to a major refactor of the ejabberdctl script, you should check your packaging and your system's version of ejabberdctl script. While old script still works, you are encouraged to use the new one. This may depends on media you install ejabberd from.
    "},{"location":"archive/older-releases/from_17.09_to_17.11/","title":"Upgrade to ejabberd 17.11","text":"
    You should follow this procedure if you are upgrading from ejabberd 17.09 and running an SQL backend for archives (mod_mam) and/or PubSub (mod_pubsub) and/or MucSub (mod_muc) and/or push (mod_push).
    "},{"location":"archive/older-releases/from_17.09_to_17.11/#system","title":"System","text":"
    For best experience with new ACME features, it's recommended to install inotify-tools package on Linux. This allows automatic certificates reload. Other systems should be fine without adding extra dependency.
    "},{"location":"archive/older-releases/from_17.09_to_17.11/#database","title":"Database","text":"
    There is a minor change on indexes of archive table on SQL backend. This change gives speed improvements on archive requests. You have to open a client connected to your ejabberd database, and run the following commands. Note: if your archive table is big, this action may take a while to complete.
     
    There is a column rename in pubsub_node table, to avoid using reserved words and need extra quoting which may not be supported on all backends. You MUST apply this upgrade procedure if you're using PubSub with an SQL backend.
     
    There are two new tables, one which allows optimization on mucsub subscriptions, and another one needed by mod_push.
    "},{"location":"archive/older-releases/from_17.09_to_17.11/#mysql","title":"MySQL","text":"
    DROP INDEX i_username ON archive;\nCREATE INDEX i_username_timestamp USING BTREE ON archive(username,timestamp);\n\nALTER TABLE pubsub_node CHANGE type plugin text NOT NULL;\n\nCREATE TABLE muc_room_subscribers (\n   room varchar(191) NOT NULL,\n   host varchar(191) NOT NULL,\n   jid varchar(191) NOT NULL,\n   nick text NOT NULL,\n   nodes text NOT NULL,\n   created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,\n  UNIQUE KEY i_muc_room_subscribers_host_room_jid (host, room, jid)\n) ENGINE=InnoDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nCREATE INDEX i_muc_room_subscribers_host_jid USING BTREE ON muc_room_subscribers(host, jid);\n\nCREATE TABLE push_session (\n    username text NOT NULL,\n    timestamp bigint NOT NULL,\n    service text NOT NULL,\n    node text NOT NULL,\n    xml text NOT NULL\n);\n\nCREATE UNIQUE INDEX i_push_usn ON push_session (username(191), service(191), node(191));\nCREATE UNIQUE INDEX i_push_ut ON push_session (username(191), timestamp);\n
    "},{"location":"archive/older-releases/from_17.09_to_17.11/#postgresql","title":"PostgreSQL","text":"
    DROP INDEX i_username;\nCREATE INDEX i_username_timestamp ON archive USING btree (username, timestamp);\n\nALTER TABLE pubsub_node RENAME COLUMN type TO plugin;\n\nCREATE TABLE muc_room_subscribers (\n   room text NOT NULL,\n   host text NOT NULL,\n   jid text NOT NULL,\n   nick text NOT NULL,\n   nodes text NOT NULL,\n   created_at TIMESTAMP NOT NULL DEFAULT now()\n);\n\nCREATE INDEX i_muc_room_subscribers_host_jid ON muc_room_subscribers USING btree (host, jid);\nCREATE UNIQUE INDEX i_muc_room_subscribers_host_room_jid ON muc_room_subscribers USING btree (host, room, jid);\n\nCREATE TABLE push_session (\n    username text NOT NULL,\n    timestamp bigint NOT NULL,\n    service text NOT NULL,\n    node text NOT NULL,\n    xml text NOT NULL\n);\n\nCREATE UNIQUE INDEX i_push_usn ON push_session USING btree (username, service, node);\nCREATE UNIQUE INDEX i_push_ut ON push_session USING btree (username, timestamp);\n
    "},{"location":"archive/older-releases/from_17.09_to_17.11/#sqlite","title":"SQLite","text":"
    DROP INDEX i_username ON archive;\nCREATE INDEX i_username_timestamp ON archive(username, timestamp);\n\nALTER TABLE pubsub_node ADD plugin text NOT NULL;\nUPDATE pubsub_node SET plugin = type;\nALTER TABLE pubsub_node DROP COLUMN type;\n\nCREATE TABLE muc_room_subscribers (\n   room text NOT NULL,\n   host text NOT NULL,\n   jid text NOT NULL,\n   nick text NOT NULL,\n   nodes text NOT NULL,\n   created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE INDEX i_muc_room_subscribers_host_jid ON muc_room_subscribers(host, jid);\nCREATE UNIQUE INDEX i_muc_room_subscribers_host_room_jid ON muc_room_subscribers(host, room, jid);\n\nCREATE TABLE push_session (\n    username text NOT NULL,\n    timestamp bigint NOT NULL,\n    service text NOT NULL,\n    node text NOT NULL,\n    xml text NOT NULL\n);\n\nCREATE UNIQUE INDEX i_push_usn ON push_session (username, service, node);\nCREATE UNIQUE INDEX i_push_ut ON push_session (username, timestamp);\n
    "},{"location":"archive/older-releases/from_17.09_to_17.11/#mssql","title":"MsSQL","text":"
    DROP INDEX [archive_username] ON [archive];\nCREATE INDEX [archive_username_timestamp] ON [archive] (username, timestamp)\n WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nEXEC sp_rename '[dbo].[pubsub_node].[type]', 'plugin';\n\nCREATE TABLE [dbo].[muc_room_subscribers] (\n        [room] [varchar] (191) NOT NULL,\n        [host] [varchar] (191) NOT NULL,\n        [jid] [varchar] (191) NOT NULL,\n        [nick] [text] NOT NULL,\n        [nodes] [text] NOT NULL,\n        [created_at] [datetime] NOT NULL DEFAULT GETDATE()\n);\n\nCREATE UNIQUE CLUSTERED INDEX [muc_room_subscribers_host_room_jid] ON [muc_room_subscribers] (host, room, jid);\nCREATE INDEX [muc_room_subscribers_host_jid] ON [muc_room_subscribers] (host, jid);\n\nCREATE TABLE [dbo].[push_session] (\n    [username] [varchar] (255) NOT NULL,\n    [timestamp] [bigint] NOT NULL,\n    [service] [varchar] (255) NOT NULL,\n    [node] [varchar] (255) NOT NULL,\n    [xml] [varchar] (255) NOT NULL\n);\n\nCREATE UNIQUE CLUSTERED INDEX [i_push_usn] ON [push_session] (username, service, node)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE UNIQUE CLUSTERED INDEX [i_push_ut] ON [push_session] (username, timestamp)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n
    "},{"location":"archive/older-releases/from_17.11_to_18.01/","title":"Upgrade to ejabberd 18.01","text":"
    There is no significant change in code and database since 17.11. There is no specific upgrade procedure. Anyway, due to TLS improvements and ACME support, you need to check your configuration to keep it up-to-date with latest patterns.
    "},{"location":"archive/older-releases/from_17.11_to_18.01/#ejabberd-configuration","title":"ejabberd configuration","text":"
    While your old ejabberd.yml is still supported, you may prefer to simplify it thanks to latest TLS driver which enables good defaults by itself. You may also need to use the new ACME feature, which requires minor changes in ejabberd configuration file. See ejabberd.yml.example in ejabberd sources for reference.
    "},{"location":"archive/older-releases/from_18.01_to_18.03/","title":"Upgrade to ejabberd 18.03","text":"
    You should follow this procedure if you are upgrading from ejabberd 18.01 and running an SQL backend for archives (mod_mam). You should also have a look at all new configuration options.
    "},{"location":"archive/older-releases/from_18.01_to_18.03/#database","title":"Database","text":"
    There is a change on indexes of archive table on SQL backend. Peer is now indexed and old indexes must be updated to reflect this change. You must open an sql client connected to your ejabberd database, and run the following commands. Note: if your archive table is big, this action may take a while to complete.
    "},{"location":"archive/older-releases/from_18.01_to_18.03/#mysql","title":"MySQL","text":"
    DROP INDEX i_username_timestamp ON archive;\nDROP INDEX i_peer ON archive;\nDROP INDEX i_bare_peer ON archive;\nCREATE INDEX i_username_timestamp USING BTREE ON archive(username(191), timestamp);\nCREATE INDEX i_username_peer USING BTREE ON archive(username(191), peer(191));\nCREATE INDEX i_username_bare_peer USING BTREE ON archive(username(191), bare_peer(191));\n
    "},{"location":"archive/older-releases/from_18.01_to_18.03/#postgresql","title":"PostgreSQL","text":"
    DROP INDEX i_peer ON archive;\nDROP INDEX i_bare_peer ON archive;\nCREATE INDEX i_username_peer ON archive USING btree (username, peer);\nCREATE INDEX i_username_bare_peer ON archive USING btree (username, bare_peer);\n
    "},{"location":"archive/older-releases/from_18.01_to_18.03/#sqlite","title":"Sqlite","text":"
    DROP INDEX i_peer ON archive;\nDROP INDEX i_bare_peer ON archive;\nCREATE INDEX i_archive_username_peer ON archive (username, peer);\nCREATE INDEX i_archive_username_bare_peer ON archive (username, bare_peer);\n
    "},{"location":"archive/older-releases/from_18.01_to_18.03/#mssql","title":"MsSql","text":"
    DROP INDEX [archive_username_timestamp] ON [archive];\nDROP INDEX [archive_peer] ON [archive];\nDROP INDEX [archive_bare_peer] ON [archive];\nCREATE INDEX [archive_username_peer] ON [archive] (username, peer)\n WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\nCREATE INDEX [archive_username_bare_peer] ON [archive] (username, bare_peer)\n WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\nCREATE INDEX [archive_timestamp] ON [archive] (timestamp)\n WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n
    "},{"location":"archive/older-releases/from_18.01_to_18.03/#ejabberd-configuration","title":"ejabberd configuration","text":"
    There are many new configuration option. We highly recommend to read details on release blogpost for good understanding of changes that may impact your configuration.
    "},{"location":"archive/older-releases/from_18.03_to_18.04/","title":"Upgrade to ejabberd 18.04","text":"
    You may follow this procedure if you are upgrading from ejabberd 18.03 or older, and running an SQL backend for PubSub.
    "},{"location":"archive/older-releases/from_18.03_to_18.04/#database","title":"Database","text":"
    There is a change on pubsub_item table on SQL backend. The type of creation and modification changed from 'text' to 'varchar(32)'. This change will speedup requests reading and sorting items. Note: if you're happy with performances, you don't need to apply this change.
    "},{"location":"archive/older-releases/from_18.03_to_18.04/#mysql","title":"MySQL","text":"
    ALTER TABLE pubsub_item\n MODIFY creation varchar(32) NOT NULL,\n MODIFY modification varchar(32) NOT NULL;\n
    "},{"location":"archive/older-releases/from_18.03_to_18.04/#postgresql","title":"PostgreSQL","text":"
    ALTER TABLE pubsub_item\n ALTER COLUMN creation TYPE varchar(32),\n ALTER COLUMN creation SET NOT NULL,\n ALTER COLUMN modification TYPE varchar(32),\n ALTER COLUMN modification SET NOT NULL;\n
    "},{"location":"archive/older-releases/from_18.03_to_18.04/#sqlite","title":"Sqlite","text":"
    ALTER TABLE pubsub_item\n MODIFY creation varchar(32) NOT NULL,\n MODIFY modification varchar(32) NOT NULL;\n
    "},{"location":"archive/older-releases/from_18.03_to_18.04/#mssql","title":"MsSql","text":"
    Note: We do not provide tested upgrade procedure on MsSQL Server. Following query should to the conversion. If you have problems with it please create an issue on ejabberd's github page. 
    ALTER TABLE [pubsub_item]\n ALTER COLUMN creation varchar(32) NOT NULL,\n ALTER COLUMN modification varchar(32) NOT NULL;\n
    "},{"location":"archive/older-releases/from_18.04_to_18.06/","title":"Upgrade to ejabberd 18.06","text":"
    There are few option changes in this version. Please check the blogpost: https://www.process-one.net/blog/ejabberd-18-06/
     
    Note: Starting with ejabberd 18.06, ejabberd will not ignore unknown options and doesn't allow to have options with malformed values. The rationale for this is to avoid unexpected behaviour during runtime, i.e. to conform to \u201cfail early\u201d approach. FOR PACKAGE BUILDERS: You must ensure your configuration is valid.
     
    You may cleanup SQL database if you are upgrading from ejabberd 18.04 or older, and running an SQL backend for mod_irc.
    "},{"location":"archive/older-releases/from_18.04_to_18.06/#database","title":"Database","text":"
    mod_irc had been obsoleted, the module is still available in ejabberd-contrib and can be installed as external module anyway. If you're not using that module or stop using it, you can safely remove the irc_custom SQL table.
    "},{"location":"archive/older-releases/from_18.06_to_18.09/","title":"Upgrade to ejabberd 18.09","text":"
    You need to update your database schema if you're using MySQL. Else there is no special upgrade process for this version.
    "},{"location":"archive/older-releases/from_18.06_to_18.09/#database","title":"Database","text":""},{"location":"archive/older-releases/from_18.06_to_18.09/#mysql","title":"MySQL","text":"
    When using stanza larger than 64 KiB, payload were silently trunced by MySQL. This raised errors when ejabberd was trying to read the content of the database.
     
    You need to alter your MySQL schema if you're using big stanzas and archive on offline table. Else you can simply dismiss this change. Note: this operation can take a long time with large archives.
     
    mysql -h host -u user database -p << EOF\nALTER TABLE spool MODIFY xml mediumtext NOT NULL;\nALTER TABLE archive MODIFY xml mediumtext NOT NULL;\nALTER TABLE archive MODIFY txt mediumtext;\nALTER TABLE pubsub_item MODIFY payload mediumtext NOT NULL;\nEOF\n
    "},{"location":"archive/older-releases/from_18.09_to_18.12/","title":"Upgrade to ejabberd 18.12","text":"
    You may need to update your database schema if you're using MySQL. A minor change on pubsub_item table was added right after 18.09 release and your schema may not have been updated already.
     
    If your users are using bookmarks, you also must migrate them to PEP before starting the service.
     
    If you're using ProcessOne installers, you must be aware API and all web ports can use TLS, and served on port 5443 instead of 5280 in this case. Using TLS requires you to generate a valid certificate. If you're a packager, we recommend to apply this change when possible.
    "},{"location":"archive/older-releases/from_18.09_to_18.12/#bookmarks-and-xep-0411","title":"Bookmarks and XEP-0411","text":"
    As ejabberd now supports XEP-0411, you must perform some actions before starting the service. If your users are NOT USING bookmarks, you can dismiss this. 
    $ for host in $(ejabberdctl registered-vhosts); do\n      ejabberdctl registered-users \"$host\" | while read user; do\n          ejabberdctl bookmarks-to-pep \"$user\" \"$host\"\n      done\n  done\n
     This might take a while if the number of users is large. Also note that this will overwrite any preexisting PEP bookmarks. However, if this is not performed, users might end up with empty bookmark lists after upgrading to the new ejabberd version, as clients might rely on PEP bookmarks once they detect that ejabberd's XEP-0411 support.  
    "},{"location":"archive/older-releases/from_18.09_to_18.12/#database","title":"Database","text":""},{"location":"archive/older-releases/from_18.09_to_18.12/#mysql","title":"MySQL","text":"
    When using stanza larger than 64 KiB, payload were silently trunced by MySQL. This raised errors when ejabberd was trying to read the content of the database.
     
    You not done yet, you need to alter your MySQL schema if you're using big stanzas on for pubsub items. Else you can simply dismiss this change.
     
    mysql -h host -u user database -p << EOF\nALTER TABLE pubsub_item MODIFY payload mediumtext NOT NULL;\nEOF\n
    "},{"location":"archive/older-releases/from_18.12_to_19.02/","title":"Upgrade to ejabberd 19.02","text":"
    19.02 adds support of latest MIX specification and MQTT protocol. You may improve your current configuration or SQL schema depending on your needs.
    "},{"location":"archive/older-releases/from_18.12_to_19.02/#configuration","title":"Configuration","text":"
    To enable MQTT, you need to add a new listener and enable mod_mqtt. Here is example of configuration:
     
    listen:\n  -\n    port: 1883\n    ip: \"::\"\n    module: mod_mqtt\n    backlog: 1000\n\nmodules:\n  mod_mqtt: {}\n
    "},{"location":"archive/older-releases/from_18.12_to_19.02/#database","title":"Database","text":"
    If you want to use latest MIX (XEP-0369) with an SQL backend then you have to create new tables.
     
    If you have issues using PEP and MySQL, you should update your schema.
    "},{"location":"archive/older-releases/from_18.12_to_19.02/#mysql","title":"MySQL","text":"
    When using PEP with MySQL, due to limitation in size of indexes, some long JIDs could have broken support. Index size on pubsub_node was modified to fix use of PEP. This change is optional and required only if you have issues when using PEP.
     
    mysql -h host -u user database -p << EOF\nDROP INDEX i_pubsub_node_tuple ON pubsub_node;\nCREATE UNIQUE INDEX i_pubsub_node_tuple ON pubsub_node(host(71), node(120));\nEOF\n
     
    If you want to use new MIX implementation, you must create some tables.
     
    CREATE TABLE mix_channel (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    jid text NOT NULL,\n    hidden boolean NOT NULL,\n    hmac_key text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n) ENGINE=InnoDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nCREATE UNIQUE INDEX i_mix_channel ON mix_channel (channel(191), service(191));\nCREATE INDEX i_mix_channel_serv ON mix_channel (service(191));\n\nCREATE TABLE mix_participant (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    jid text NOT NULL,\n    id text NOT NULL,\n    nick text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n) ENGINE=InnoDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nCREATE UNIQUE INDEX i_mix_participant ON mix_participant (channel(191), service(191), username(191), domain(191));\nCREATE INDEX i_mix_participant_chan_serv ON mix_participant (channel(191), service(191));\n\nCREATE TABLE mix_subscription (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    node text NOT NULL,\n    jid text NOT NULL\n) ENGINE=InnoDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nCREATE UNIQUE INDEX i_mix_subscription ON mix_subscription (channel(153), service(153), username(153), domain(153), node(153));\nCREATE INDEX i_mix_subscription_chan_serv_ud ON mix_subscription (channel(191), service(191), username(191), domain(191));\nCREATE INDEX i_mix_subscription_chan_serv_node ON mix_subscription (channel(191), service(191), node(191));\nCREATE INDEX i_mix_subscription_chan_serv ON mix_subscription (channel(191), service(191));\n\nCREATE TABLE mix_pam (\n    username text NOT NULL,\n    channel text NOT NULL,\n    service text NOT NULL,\n    id text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n) ENGINE=InnoDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nCREATE UNIQUE INDEX i_mix_pam ON mix_pam (username(191), channel(191), service(191));\nCREATE INDEX i_mix_pam_u ON mix_pam (username(191));\n
     
    If you want to use new MQTT feature, you need to create a table.
     
    If you're using the new schema (new_sql_schema):
     
    CREATE TABLE mqtt_pub (\n    username varchar(191) NOT NULL,\n    server_host varchar(191) NOT NULL,\n    resource varchar(191) NOT NULL,\n    topic text NOT NULL,\n    qos tinyint NOT NULL,\n    payload blob NOT NULL,\n    payload_format tinyint NOT NULL,\n    content_type text NOT NULL,\n    response_topic text NOT NULL,\n    correlation_data blob NOT NULL,\n    user_properties blob NOT NULL,\n    expiry int unsigned NOT NULL,\n    UNIQUE KEY i_mqtt_topic_server (topic(191))\n);\n
     
    If you're using the old schema:
     
    CREATE TABLE mqtt_pub (\n    username varchar(191) NOT NULL,\n    resource varchar(191) NOT NULL,\n    topic text NOT NULL,\n    qos tinyint NOT NULL,\n    payload blob NOT NULL,\n    payload_format tinyint NOT NULL,\n    content_type text NOT NULL,\n    response_topic text NOT NULL,\n    correlation_data blob NOT NULL,\n    user_properties blob NOT NULL,\n    expiry int unsigned NOT NULL,\n    UNIQUE KEY i_mqtt_topic (topic(191))\n);\n
    "},{"location":"archive/older-releases/from_18.12_to_19.02/#postgresql","title":"PostgreSQL","text":"
    If you want to use new MIX implementation, you must create some tables.
     
    CREATE TABLE mix_channel (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    jid text NOT NULL,\n    hidden boolean NOT NULL,\n    hmac_key text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE UNIQUE INDEX i_mix_channel ON mix_channel (channel, service);\nCREATE INDEX i_mix_channel_serv ON mix_channel (service);\n\nCREATE TABLE mix_participant (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    jid text NOT NULL,\n    id text NOT NULL,\n    nick text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE UNIQUE INDEX i_mix_participant ON mix_participant (channel, service, username, domain);\nCREATE INDEX i_mix_participant_chan_serv ON mix_participant (channel, service);\n\nCREATE TABLE mix_subscription (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    node text NOT NULL,\n    jid text NOT NULL\n);\n\nCREATE UNIQUE INDEX i_mix_subscription ON mix_subscription (channel, service, username, domain, node);\nCREATE INDEX i_mix_subscription_chan_serv_ud ON mix_subscription (channel, service, username, domain);\nCREATE INDEX i_mix_subscription_chan_serv_node ON mix_subscription (channel, service, node);\nCREATE INDEX i_mix_subscription_chan_serv ON mix_subscription (channel, service);\n\nCREATE TABLE mix_pam (\n    username text NOT NULL,\n    channel text NOT NULL,\n    service text NOT NULL,\n    id text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE UNIQUE INDEX i_mix_pam ON mix_pam (username, channel, service);\nCREATE INDEX i_mix_pam_us ON mix_pam (username);\n
     
    If you want to use new MQTT feature, you need to create a table.
     
    If you're using the new schema (new_sql_schema):
     
    CREATE TABLE mqtt_pub (\n    username text NOT NULL,\n    server_host text NOT NULL,\n    resource text NOT NULL,\n    topic text NOT NULL,\n    qos smallint NOT NULL,\n    payload bytea NOT NULL,\n    payload_format smallint NOT NULL,\n    content_type text NOT NULL,\n    response_topic text NOT NULL,\n    correlation_data bytea NOT NULL,\n    user_properties bytea NOT NULL,\n    expiry bigint NOT NULL\n);\n\nCREATE UNIQUE INDEX i_mqtt_topic_server ON mqtt_pub (topic, server_host);\n
     
    If you're using the old schema:
     
    CREATE TABLE mqtt_pub (\n    username text NOT NULL,\n    resource text NOT NULL,\n    topic text NOT NULL,\n    qos smallint NOT NULL,\n    payload bytea NOT NULL,\n    payload_format smallint NOT NULL,\n    content_type text NOT NULL,\n    response_topic text NOT NULL,\n    correlation_data bytea NOT NULL,\n    user_properties bytea NOT NULL,\n    expiry bigint NOT NULL\n);\n\nCREATE UNIQUE INDEX i_mqtt_topic ON mqtt_pub (topic, server_host);\n
    "},{"location":"archive/older-releases/from_18.12_to_19.02/#sqlite","title":"SQLite","text":"
    If you want to use new MIX implementation, you must create some tables.
     
    CREATE TABLE mix_channel (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    jid text NOT NULL,\n    hidden boolean NOT NULL,\n    hmac_key text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE UNIQUE INDEX i_mix_channel ON mix_channel (channel, service);\nCREATE INDEX i_mix_channel_serv ON mix_channel (service);\n\nCREATE TABLE mix_participant (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    jid text NOT NULL,\n    id text NOT NULL,\n    nick text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE UNIQUE INDEX i_mix_participant ON mix_participant (channel, service, username, domain);\nCREATE INDEX i_mix_participant_chan_serv ON mix_participant (channel, service);\n\nCREATE TABLE mix_subscription (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    node text NOT NULL,\n    jid text NOT NULL\n);\n\nCREATE UNIQUE INDEX i_mix_subscription ON mix_subscription (channel, service, username, domain, node);\nCREATE INDEX i_mix_subscription_chan_serv_ud ON mix_subscription (channel, service, username, domain);\nCREATE INDEX i_mix_subscription_chan_serv_node ON mix_subscription (channel, service, node);\nCREATE INDEX i_mix_subscription_chan_serv ON mix_subscription (channel, service);\n\nCREATE TABLE mix_pam (\n    username text NOT NULL,\n    channel text NOT NULL,\n    service text NOT NULL,\n    id text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE UNIQUE INDEX i_mix_pam ON mix_pam (username, channel, service);\nCREATE INDEX i_mix_pam_us ON mix_pam (username);\n
     
    If you want to use new MQTT feature, you need to create a table.
     
    If you're using the new schema (new_sql_schema):
     
    CREATE TABLE mqtt_pub (\n    username text NOT NULL,\n    server_host text NOT NULL,\n    resource text NOT NULL,\n    topic text NOT NULL,\n    qos smallint NOT NULL,\n    payload blob NOT NULL,\n    payload_format smallint NOT NULL,\n    content_type text NOT NULL,\n    response_topic text NOT NULL,\n    correlation_data blob NOT NULL,\n    user_properties blob NOT NULL,\n    expiry bigint NOT NULL\n);\n\nCREATE UNIQUE INDEX i_mqtt_topic_server ON mqtt_pub (topic);\n
     
    If you're using the old schema:
     
    CREATE TABLE mqtt_pub (\n    username text NOT NULL,\n    resource text NOT NULL,\n    topic text NOT NULL,\n    qos smallint NOT NULL,\n    payload blob NOT NULL,\n    payload_format smallint NOT NULL,\n    content_type text NOT NULL,\n    response_topic text NOT NULL,\n    correlation_data blob NOT NULL,\n    user_properties blob NOT NULL,\n    expiry bigint NOT NULL\n);\n\nCREATE UNIQUE INDEX i_mqtt_topic ON mqtt_pub (topic);\n
    "},{"location":"archive/older-releases/from_19.02_to_19.05/","title":"Upgrade to ejabberd 19.05","text":"
    19.05 don't add changes on data or configuration. You may alter your configuration if you want to use new feature to store offline messages in archives anyway. See more details on blogpost.
    "},{"location":"archive/older-releases/from_19.02_to_19.05/#database","title":"Database","text":"
    Schema for MQTT tables was added after 19.02 release despite full support was already available. If you're using MQTT and need SQL backend, in case you dismissed the change, please report to ejabberd 19.02 upgrade note
    "},{"location":"archive/older-releases/from_19.05_to_19.08/","title":"Upgrade to ejabberd 19.08","text":""},{"location":"archive/older-releases/from_19.05_to_19.08/#database","title":"Database","text":"
    Riak support has been removed in this version, so don't upgrade to 19.08 if you store data in Riak.
     
    The only SQL schema that changed since 19.05 is mysql.new.sql.
    "},{"location":"archive/older-releases/from_19.05_to_19.08/#mysql","title":"MySQL","text":"
    mysql.new.sql from 19.05 schema can work 19.08, so the migration to 19.08 schema is optional, as it's just a type change from TEXT to VARCHAR for performances reason, but it will improve index utilization.
     
    ALTER TABLE users MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE last MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE rosterusers MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE rostergroups MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE sr_group MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE sr_user MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE spool MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE archive MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE archive_prefs MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE vcard MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE vcard_search MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE privacy_default_list MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE privacy_list MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE private_storage MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE roster_version MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE muc_room MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE muc_registered MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE muc_online_room MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE muc_online_users MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE motd MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE sm MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE route MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE push_session MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE mix_pam MODIFY server_host varchar(191) NOT NULL;\n
    "},{"location":"archive/older-releases/from_19.05_to_19.08/#api-changes","title":"API changes","text":""},{"location":"archive/older-releases/from_19.05_to_19.08/#renamed-arguments-from-server-to-host","title":"Renamed arguments from Server to Host","text":"
    Several ejabberd commands still used as argument name Server, instead of the more common Host. Such arguments have been renamed, and backward support allows old calls to work correctly.
     
    The eight commands affected are: \u2013 add_rosteritem \u2013 bookmarks_to_pep \u2013 delete_rosteritem \u2013 get_offline_count \u2013 get_presence \u2013 get_roster \u2013 remove_mam_for_user \u2013 remove_mam_for_user_with_peer
     
    If you are using this calls, please start updating your parameter names to Host when moving to ejabberd 19.08. You will thus use a more consistent API and be future proof.
    "},{"location":"archive/older-releases/from_2.1.1x_to_16.02/","title":"Upgrade from 2.1.1x to 16.02","text":""},{"location":"archive/older-releases/from_2.1.1x_to_16.02/#compilation","title":"Compilation","text":"
    Compilation requires Erlang/OTP R17 or higher. Requires OpenSSL 1.0.0 or higher. exmpp is not required anymore. The mysql and pgsql erlang libraries are now included in ejabberd source code.
     
    The source code structure has improved: - The compilation scripts are moved from src/ to /, including configure and Makefile. - Source code of complex modules is moved from src/*/*.erl to src/*.erl - The SQL example files are moved from src/odbc/*.sql to sql/*.sql
     
    The configuration file now uses YAML syntax, not the Erlang syntax. For that reason, the file is now named ejabberd.yml, not ejabberd.cfg You have three options: - You can use and adapt the new file ejabberd.yml.example - You can still use your old ejabberd.cfg - You can convert your old config file to YAML with the command: ejabberdctl convert_to_yaml
    "},{"location":"archive/older-releases/from_2.1.1x_to_16.02/#ejabberd-upgrade-process","title":"Ejabberd upgrade process","text":"
    If you are using an sql backend for authentication, you need to upgrade your schema before starting ejabberd 16.02. This can be safely done while a previous version of ejabberd is actually running.
    "},{"location":"archive/older-releases/from_2.1.1x_to_16.02/#mysql-database-upgrade","title":"MySQL database upgrade","text":"
    mysql -h host -u user database -p << EOF\n\n-- Table for mod_caps: Entity Capabilities (XEP-0115)\nCREATE TABLE caps_features (\n    node varchar(250) NOT NULL,\n    subnode varchar(250) NOT NULL,\n    feature text,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n) CHARACTER SET utf8;\nCREATE INDEX i_caps_features_node_subnode ON caps_features(node(75), subnode(75));\n\n-- Make it possible to use SQL as an SM backend:\nCREATE TABLE sm (\n    usec bigint NOT NULL,\n    pid text NOT NULL,\n    node text NOT NULL,\n    username varchar(250) NOT NULL,\n    resource varchar(250) NOT NULL,\n    priority text NOT NULL,\n    info text NOT NULL\n) ENGINE=InnoDB CHARACTER SET utf8;\nCREATE UNIQUE INDEX i_sid ON sm(usec, pid(75));\nCREATE INDEX i_node ON sm(node(75));\nCREATE INDEX i_username ON sm(username);\n\n-- Support delete_old_messages (offline) command:\nCREATE INDEX i_spool_created_at USING BTREE ON spool(created_at);\n\n-- Add a missed SQL index on privacy_list_data table\nCREATE INDEX i_privacy_list_data_id ON privacy_list_data(id);\n\n-- Add SCRAM support to ejabberd_auth_odbc\nALTER TABLE users ADD COLUMN serverkey text NOT NULL;\nALTER TABLE users ADD COLUMN salt text NOT NULL;\nALTER TABLE users ADD COLUMN iterationcount integer NOT NULL DEFAULT 0;\n\n-- mod_mam (XEP-0313) support\nCREATE TABLE archive (\n    username varchar(250) NOT NULL,\n    timestamp BIGINT UNSIGNED NOT NULL,\n    peer varchar(250) NOT NULL,\n    bare_peer varchar(250) NOT NULL,\n    xml text NOT NULL,\n    txt text,\n    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT UNIQUE,\n    kind varchar(10),\n    nick varchar(250),\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n) ENGINE=InnoDB CHARACTER SET utf8;\nCREATE FULLTEXT INDEX i_text ON archive(txt);\nCREATE INDEX i_username USING BTREE ON archive(username);\nCREATE INDEX i_timestamp USING BTREE ON archive(timestamp);\nCREATE INDEX i_peer USING BTREE ON archive(peer);\nCREATE INDEX i_bare_peer USING BTREE ON archive(bare_peer);\nCREATE TABLE archive_prefs (\n    username varchar(250) NOT NULL PRIMARY KEY,\n    def text NOT NULL,\n    always text NOT NULL,\n    never text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n) ENGINE=InnoDB CHARACTER SET utf8;\n\n-- In Offline storage use BLOB instead of TEXT\nALTER TABLE spool MODIFY xml BLOB NOT NULL;\n\n-- Use UTF8MB4 character set in MySQL tables\n--\n-- TODO\n-- Commit: Use UTF8MB4 character set in MySQL tables\n--         7d1c75d0e817db0e04fe1133e06ba35cd367d76e\n--\nEOF\n
    "},{"location":"archive/older-releases/from_2.1.1x_to_16.02/#pgsql-database-upgrade","title":"PgSQL database upgrade","text":"
    psql -W -h host database user << EOF\n\n-- Table for mod_caps: Entity Capabilities (XEP-0115)\nCREATE TABLE caps_features (\n    node text NOT NULL,\n    subnode text NOT NULL,\n    feature text,\n    created_at TIMESTAMP NOT NULL DEFAULT now()\n);\nCREATE INDEX i_caps_features_node_subnode ON caps_features USING btree (node, subnode);\n\n-- Make it possible to use SQL as an SM backend:\nCREATE TABLE sm (\n    usec bigint NOT NULL,\n    pid text NOT NULL,\n    node text NOT NULL,\n    username text NOT NULL,\n    resource text NOT NULL,\n    priority text NOT NULL,\n    info text NOT NULL\n);\nCREATE UNIQUE INDEX i_sm_sid ON sm USING btree (usec, pid);\nCREATE INDEX i_sm_node ON sm USING btree (node);\nCREATE INDEX i_sm_username ON sm USING btree (username);\n\n-- Add a missed SQL index on privacy_list_data table\nCREATE INDEX i_privacy_list_data_id ON privacy_list_data USING btree (id);\n\n-- Add SCRAM support to ejabberd_auth_odbc\nALTER TABLE users ADD COLUMN serverkey text NOT NULL DEFAULT '';\nALTER TABLE users ADD COLUMN salt text NOT NULL DEFAULT '';\nALTER TABLE users ADD COLUMN iterationcount integer NOT NULL DEFAULT 0;\n\n-- mod_mam (XEP-0313) support\nCREATE TABLE archive (\n    username text NOT NULL,\n    timestamp BIGINT NOT NULL,\n    peer text NOT NULL,\n    bare_peer text NOT NULL,\n    xml text NOT NULL,\n    txt text,\n    id SERIAL,\n    kind text,\n    nick text,\n    created_at TIMESTAMP NOT NULL DEFAULT now()\n);\nCREATE INDEX i_username ON archive USING btree (username);\nCREATE INDEX i_timestamp ON archive USING btree (timestamp);\nCREATE INDEX i_peer ON archive USING btree (peer);\nCREATE INDEX i_bare_peer ON archive USING btree (bare_peer);\nCREATE TABLE archive_prefs (\n    username text NOT NULL PRIMARY KEY,\n    def text NOT NULL,\n    always text NOT NULL,\n    never text NOT NULL,\n    created_at TIMESTAMP NOT NULL DEFAULT now()\n);\nEOF\n
    "},{"location":"archive/older-releases/from_2.1.1x_to_16.02/#pubsub-database-upgrade","title":"PubSub database upgrade","text":"
    If you were using PubSub with sql backend and need to keep your pubsub data, you must alter the content of pubsub_node tables, changing type 'pep' instead of 'pep_odbc', 'flat' instead of 'flat_odbc', and 'hometree' instead of 'hometree_odbc'.
     
    UPDATE pubsub_node SET type='pep' WHERE type='pep_odbc';\nUPDATE pubsub_node SET type='flat' WHERE type='flat_odbc';\nUPDATE pubsub_node SET type='hometree' WHERE type='hometree_odbc';\n
    "},{"location":"contributing/","title":"Contributing to ejabberd","text":"
    We'd love for you to contribute to our source code and to make ejabberd even better than it is today! Here are the guidelines we'd like you to follow:
     
       
    • Code of Conduct
      •  
    • Questions and Problems
      •  
    • Issues and Bugs
      •  
    • Feature Requests
      •  
    • Issue Submission Guidelines
      •  
    • Pull Request Submission Guidelines
      •  
    • Signing the CLA
      •  
    "},{"location":"contributing/#code-of-conduct","title":"Code of Conduct","text":"
    Help us keep ejabberd community open-minded and inclusive. Please read and follow our Code of Conduct.
    "},{"location":"contributing/#questions-bugs-features","title":"Questions, Bugs, Features","text":""},{"location":"contributing/#got-a-question-or-problem","title":"Got a Question or Problem?","text":"
    Do not open issues for general support questions as we want to keep GitHub issues for bug reports and feature requests. You've got much better chances of getting your question answered on dedicated support platforms, the best being Stack Overflow.
     
    Stack Overflow is a much better place to ask questions since:
     
       
    • there are thousands of people willing to help on Stack Overflow
      •  
    • questions and answers stay available for public viewing so your question / answer might help   someone else
      •  
    • Stack Overflow's voting system assures that the best answers are prominently visible.
      •  
     
    To save your and our time, we will systematically close all issues that are requests for general support and redirect people to the section you are reading right now.
     
    Other channels for support are: - ejabberd XMPP room: ejabberd@conference.process-one.net - ejabberd XMPP room logs - ejabberd Mailing List
    "},{"location":"contributing/#found-an-issue-or-bug","title":"Found an Issue or Bug?","text":"
    If you find a bug in the source code, you can help us by submitting an issue to our GitHub Repository. Even better, you can submit a Pull Request with a fix.
    "},{"location":"contributing/#missing-a-feature","title":"Missing a Feature?","text":"
    You can request a new feature by submitting an issue to our GitHub Repository.
     
    If you would like to implement a new feature then consider what kind of change it is:
     
       
    • Major Changes that you wish to contribute to the project should be discussed first in an   GitHub issue that clearly outlines the changes and benefits of the feature.
      •  
    • Small Changes can directly be crafted and submitted to the GitHub Repository   as a Pull Request. See the section about Pull Request Submission Guidelines.
      •  
    "},{"location":"contributing/#issue-submission-guidelines","title":"Issue Submission Guidelines","text":"
    Before you submit your issue search the archive, maybe your question was already answered.
     
    If your issue appears to be a bug, and hasn't been reported, open a new issue. Help us to maximize the effort we can spend fixing issues and adding new features, by not reporting duplicate issues.
     
    The \"new issue\" form contains a number of prompts that you should fill out to make it easier to understand and categorize the issue.
    "},{"location":"contributing/#pull-request-submission-guidelines","title":"Pull Request Submission Guidelines","text":"
    By submitting a pull request for a code or doc contribution, you need to have the right to grant your contribution's copyright license to ProcessOne. Please check ProcessOne CLA for details.
     
    Before you submit your pull request consider the following guidelines:
     
       
    • Search GitHub for an open or closed Pull Request   that relates to your submission. You don't want to duplicate effort.
      •  
    • Create the development environment
      •  
    •  
      Make your changes in a new git branch:
       
      git checkout -b my-fix-branch master\n
       * Test your changes and, if relevant, expand the automated test suite. * Create your patch commit, including appropriate test cases. * If the changes affect public APIs, change or add relevant documentation. * Commit your changes using a descriptive commit message.
       
      git commit -a\n
         Note: the optional commit -a command line option will automatically \"add\" and \"rm\" edited files.
       
      •  
    •  
      Push your branch to GitHub:
       
      git push origin my-fix-branch\n
       
      •  
    •  
      In GitHub, send a pull request to ejabberd:master. This will trigger the automated testing. We will also notify you if you have not yet signed the contribution agreement.
       
      •  
    •  
      If you find that the tests have failed, look into the logs to find out if your changes caused test failures, the commit message was malformed etc. If you find that the tests failed or times out for unrelated reasons, you can ping a team member so that the build can be restarted.
       
      •  
    •  
      If we suggest changes, then:
       
      •  
    •  
      Make the required updates.
       
      •  
    • Test your changes and test cases.
      •  
    • Commit your changes to your branch (e.g. my-fix-branch).
      •  
    •  
      Push the changes to your GitHub repository (this will update your Pull Request).
       
      You can also amend the initial commits and force push them to the branch.
       
      git rebase master -i\ngit push origin my-fix-branch -f\n
       
      This is generally easier to follow, but separate commits are useful if the Pull Request contains iterations that might be interesting to see side-by-side.
       
      •  
     
    That's it! Thank you for your contribution!
    "},{"location":"contributing/#signing-the-contributor-license-agreement-cla","title":"Signing the Contributor License Agreement (CLA)","text":"
    Upon submitting a Pull Request, we will ask you to sign our CLA if you haven't done so before. It's a quick process, we promise, and you will be able to do it all online
     
    You can read ProcessOne Contribution License Agreement in PDF.
     
    This is part of the legal framework of the open-source ecosystem that adds some red tape, but protects both the contributor and the company / foundation behind the project. It also gives us the option to relicense the code with a more permissive license in the future.
    "},{"location":"contributing/CODE_OF_CONDUCT/","title":"Contributor Covenant Code of Conduct","text":""},{"location":"contributing/CODE_OF_CONDUCT/#our-pledge","title":"Our Pledge","text":"
    In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
    "},{"location":"contributing/CODE_OF_CONDUCT/#our-standards","title":"Our Standards","text":"
    Examples of behavior that contributes to creating a positive environment include:
     
       
    • Using welcoming and inclusive language
      •  
    • Being respectful of differing viewpoints and experiences
      •  
    • Gracefully accepting constructive criticism
      •  
    • Focusing on what is best for the community
      •  
    • Showing empathy towards other community members
      •  
     
    Examples of unacceptable behavior by participants include:
     
       
    • The use of sexualized language or imagery and unwelcome sexual attention or advances
      •  
    • Trolling, insulting/derogatory comments, and personal or political attacks
      •  
    • Public or private harassment
      •  
    • Publishing others' private information, such as a physical or electronic address, without explicit permission
      •  
    • Other conduct which could reasonably be considered inappropriate in a professional setting
      •  
    "},{"location":"contributing/CODE_OF_CONDUCT/#our-responsibilities","title":"Our Responsibilities","text":"
    Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
     
    Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
    "},{"location":"contributing/CODE_OF_CONDUCT/#scope","title":"Scope","text":"
    This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
    "},{"location":"contributing/CODE_OF_CONDUCT/#enforcement","title":"Enforcement","text":"
    Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at the email address: conduct AT process-one.net. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
     
    Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
    "},{"location":"contributing/CODE_OF_CONDUCT/#attribution","title":"Attribution","text":"
    This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at http://contributor-covenant.org/version/1/4
    "},{"location":"contributing/CONTRIBUTORS/","title":"Contributors","text":"
    We would like to thanks official ejabberd source code contributors:
     
       
    • Sergey Abramyan
      •  
    • Badlop
      •  
    • Ludovic Bocquet
      •  
    • Emilio Bustos
      •  
    • Thiago Camargo
      •  
    • Juan Pablo Carlino
      •  
    • Pawe\u0142 Chmielowski
      •  
    • Gabriel Gatu
      •  
    • Tsukasa Hamano
      •  
    • Konstantinos Kallas
      •  
    • Evgeny Khramtsov
      •  
    • Ben Langfeld
      •  
    • Peter Lemenkov
      •  
    • Anna Mukharram
      •  
    • Johan Oudinet
      •  
    • Pablo Polvorin
      •  
    • Micka\u00ebl R\u00e9mond
      •  
    • Matthias Rieber
      •  
    • Rafael Roemhild
      •  
    • Christophe Romain
      •  
    • J\u00e9r\u00f4me Sautret
      •  
    • Sonny Scroggin
      •  
    • Alexey Shchepin
      •  
    • Shelley Shyan
      •  
    • Radoslaw Szymczyszyn
      •  
    • Stu Tomlinson
      •  
    • Christian Ulrich
      •  
    • Holger Wei\u00df
      •  
     
    Please, if you think we are missing your contribution, do not hesitate to contact us at ProcessOne. In case you do not want to appear in this list, please, let us know as well.
     
    Thanks !
    "},{"location":"developer/","title":"ejabberd for Developers","text":"
    As a developer, you can customize ejabberd to design almost every type of XMPP related type of solutions.
     
    As a starting point, we recommend that you get extremely familiar with both the core XMPP protocol itself and its extensions.
     
    From that, once you understand well XMPP, you can tame ejabberd to build your dream messaging system.
    "},{"location":"developer/#getting-started","title":"Getting started","text":""},{"location":"developer/#source-code","title":"Source code","text":"
    ejabberd source is available on Github: ejabberd
     
    You will need to get familiar with it to start learning about ejabberd module writing. The first place to start? You should read the time module. This is one of the simplest possible module for ejabberd.
     
    Another great source of inspiration and knowledge is to read the source code of the many contributed ejabberd modules. Many of them are available from ejabberd-contribs repository.
     
    For a complete overview of ejabberd source code and its dependencies, please refer to ejabberd and related repositories
    "},{"location":"developer/#development-environment","title":"Development Environment","text":"
    The first step to develop for ejabberd is to install and configure your development environment:
     
       
    • Check the Source Code Installation section
      •  
    • If using Emacs, install erlang-mode in your operating system
      •  
    • If using OSX, check the OSX development environment section
      •  
    • For Visual Studio Code and alternatives, check the Developing ejabberd with VSCode section
      •  
    "},{"location":"developer/#customizing-ejabberd","title":"Customizing ejabberd","text":"
       
    • ejabberd development guide
      •  
    • ejabberd modules development
      •  
    "},{"location":"developer/guide/","title":"ejabberd developer guide","text":""},{"location":"developer/guide/#introduction","title":"Introduction","text":"
    ejabberd is a free and open source instant messaging server written in Erlang/OTP.
     
    ejabberd is cross-platform, distributed, fault-tolerant, and based on open standards to achieve real-time communication.
     
    ejabberd is designed to be a rock-solid and feature rich XMPP server.
     
    ejabberd is suitable for small deployments, whether they need to be scalable or not, as well as extremely big deployments.
    "},{"location":"developer/guide/#goals","title":"Goals","text":"
    This guide is a brief explanation of ejabberd internals. It is not intended to be a comprehensive ejabberd's internal API documentation. You still need to read and understand ejabberd's source code. However, the guide is believed to help you understanding ejabberd's code faster: it provides entry points from where to start reading relevant parts of the code and ignore irrelevant ones. Note that there is absolutely no need to know every line of code of ejabberd, but some parts are crucial to understand.
    "},{"location":"developer/guide/#requirements","title":"Requirements","text":"
    In order to read and understand the guide you must be pretty fluent with Erlang programming language and understand basics of the XMPP protocol: there is no detailed explanation of Erlang syntax and/or features and it's assumed that you're familiar with such terms as xml stream, stanza, c2s, s2s and so on. If you see these words for the first time in your life you're unlikely to understand the guide.
    "},{"location":"developer/guide/#version","title":"Version","text":"
    The guide describes ejabberd 17.03. Previous and next versions can differ drastically from the one described herein.
    "},{"location":"developer/guide/#coding-style-convention","title":"Coding style convention","text":"
    NOTE: this section is only relevant for ejabberd contributors. If you're hacking ejabberd for internal needs, you are free to choose whatever coding style you like.
     
    ejabberd follows Erlang Coding Standards & Guidelines or at least tries to do so: there is still a lot of poorly written legacy code (which is being leisurely rewritten), but the new code should be written with keeping these rules in mind. In some cases the rules can be bypassed, but the reason doing so should be really weighty. The rules shouldn't be ignored just because a contributor doesn't like them.
     
    The typical coding style rules found violated in contributors' code are:
     
       
    • 100 column per line: in fact we have defined 80 columns as a soft and 100 columns as a hard limit, which means most of your lines should be no longer than 80 characters and the rest must never be longer than 100 characters.
      •  
    • no deep nesting
      •  
    • no boolean parameters in case control
      •  
    • only CamelCase variables name
      •  
    • no macros
      •  
    • no case-catch
      •  
     
    It's worth noting that the code itself should be indented using Emacs indentation style (that is the standard indentation style for Erlang programs). If you're not using Emacs for ejabberd development, indent the code using it first before making a PR/commit.
    "},{"location":"developer/guide/#start-up-procedure","title":"Start-up procedure","text":"
    ejabberd is written as a standard OTP application, so the startup module can be found in src/ejabberd.app.src or, if ejabberd is compiled, in ebin/ejabberd.app file: that is, ejabberd_app.erl module from where start/2 function is called by Erlang application controller. This function makes some initialization (such as logger, mnesia, configuration file, etc.) and ends up by starting the main ejabberd supervisor - ejabberd_sup. Thus, for further startup order refer to ejabberd_sup.erl module (this is a simple list-like module with supervisor childspecs).
     
    WARNING: only \"core stuff\" should be attached to ejabberd_sup. For attaching modules use gen_mod's supervisor (via gen_mod:start_child/3,4 functions), for attaching database backend modules use ejabberd_backend_sup supervisor, etc.
     
    Once ejabberd_sup is started, ejabberd application is considered to be started.
    "},{"location":"developer/guide/#core","title":"Core","text":"
    The ejabberd core is not well-defined. Moreover, the described core layers are pure abstraction grouping several modules together by some criteria for better understanding of ejabberd internal processing rules.
    "},{"location":"developer/guide/#network-layer","title":"Network Layer","text":"
    Once ejabberd is started, some external events should obviously make it doing something. Besides explicit administrative commands, the most relevant such events are incoming connections. Incoming connections are handled inside Network Layer. The layer implemented by ejabberd_listener.erl, ejabberd_receiver.erl and ejabberd_socket.erl modules.
     
    NOTE: ejabberd_listner.erl is able to handle raw TCP and UDP connections, however only XMPP connections are described here.
     
    Once a connection is accepted by ejabberd_listener.erl, an instance (a process) of ejabberd_receiver.erl is started and it becomes the socket owner, where it performs the following operations:
     
       
    • Throttles a connection using shapers from shaper.erl module
      •  
    • Performs TLS decoding using fast_tls library
      •  
    • Performs stream decompression using ezlib library
      •  
    • Parses incoming raw XML data into #xmlel{} packets using fast_xml library
      •  
     
    ejabberd_socket.erl does the same but in a reverse order, i.e. it performs stream compression and/or TLS encoding, serializes #xmlel{} packets into raw XML data and puts them into a socket (note that shapers do not apply for outgoing data).
     
    Once xmlel{} packet is constructed by ejabberd_receiver.erl it's passed to XMPP Stream Layer.
    "},{"location":"developer/guide/#xmpp-stream-layer","title":"XMPP Stream Layer","text":"
    XMPP Stream Layer is represented by xmpp_stream_in.erl and xmpp_stream_out.erl modules. An instance (i.e. a process) of xmpp_stream_in.erl is started along with an instance of ejabberd_receiver.erl and all incoming #xmlel{} packets are passed from the latter to the former. xmpp_stream_in.erl module does the following:
     
       
    • Encodes/decodes #xmlel{} packets using xmpp library from/to internal structures (records) defined in xmpp_codec.hrl.
      •  
    • Performs negotiation of inbound XMPP streams
      •  
    • Performs STARTTLS negotiation (if needed)
      •  
    • Performs compression negotiation (if needed)
      •  
    • Performs SASL authentication
      •  
     
    NOTE: XMPP Stream Layer was only introduced in ejabberd 17.03. Prior to this XMPP stream negotiation was handled inside ejabberd_c2s.erl, ejabberd_s2s_in.erl, ejabberd_service.erl and ejabberd_s2s_out.erl. This has lead to unmaintainable monolithic spaghetti code with a lot of code duplication between these modules. It's believed introducing xmpp_stream_in.erl and xmpp_stream_out.erl modules now solves this problem.
     
    During these procedures xmpp_stream_in.erl calls functions from its callback modules, i.e. the modules of xmpp_stream_in behaviour: ejabberd_c2s.erl, ejabberd_s2s_in.erl or ejabberd_service.erl, depending on the stream namespace.
     
    xmpp_stream_out.erl does the same but for outbound XMPP streams. The only its callback module is ejabberd_s2s_out.erl.
     
    NOTE: xmpp_stream_in.erl shares the same process and state with its callback modules, i.e. functions from xmpp_stream_in.erl and functions from ejabberd_c2s/s2s_in/service.erl modules are evaluated inside the same process. This is also true for xmpp_stream_out.erl and ejabberd_s2s_out.erl. The state is represented by a map() in both cases.
    "},{"location":"developer/guide/#ejabberd_c2s-ejabberd_s2s_in-and-ejabberd_service","title":"ejabberd_c2s, ejabberd_s2s_in and ejabberd_service","text":"
    These are modules of xmpp_stream_in behaviour. The only purpose of these modules is to provide callback functions for xmpp_stream_in.erl module. Examples of such callback functions are:
     
       
    • tls_enabled/1: tells whether or not TLS is enabled in the configuration
      •  
    • check_password_fun/1: provides a function for SASL authentication
      •  
    • handle_authenticated_packet/2: what to do with packets after authentication is completed
      •  
     
    Roughly, they represent an intermediate (or \"glue\") code between XMPP Stream Layer and Routing Layer for inbound XMPP streams.
     
    ejabberd_s2s_out.erl is described elsewhere
    "},{"location":"developer/guide/#routing-layer","title":"Routing Layer","text":""},{"location":"developer/guide/#ejabberd_router","title":"ejabberd_router","text":"
    ejabberd_router.erl module is the main dispatcher of XMPP stanzas.
     
    It's pretty small and straightforward module whose the only task is to find the \"route\" for a stanza. ejabberd_router.erl only operates with #message{}, #presence{} and #iq{} packets (defined in xmpp_codec.hrl), so please note, that it is not possible to route arbitrary #xmlel{} packets or any other Erlang terms through ejabberd_router.
     
    The only valid routes are:
     
       
    • local route: stanzas of this route type are destined to the local server itself, i.e. stanzas with to attribute in the form of domain.com or domain.com/resource, where domain.com is a virtual host serviced by ejabberd. ejabberd_router passes such stanzas to ejabberd_local.erl module via ejabberd_local:route/1 function call.
      •  
    • session manager route: stanzas of this route type are destined to local users, i.e. stanzas with to attribute in the form of user@domain.com or user@domain.com/resource where domain.com is a virtual host serviced by ejabberd. ejabberd_router passes such stanzas to ejabberd_sm.erl module via ejabberd_sm:route/1 function call.
      •  
    • registered route: if a stanza is not destined to local virtual host, ejabberd first checks if there is a \"registered\" route for the stanza, i.e. a domain registered via ejabberd_router:register_route/2 function. For doing this it looks up the routing table and if there is a process Pid registered on this domain, ejabberd routes the stanza as Pid ! {route, Stanza}. The routing table is backend-dependent and is implemented in the corresponding backend module such as ejabberd_router_mnesia.erl.
      •  
    • s2s route: if a stanza is neither destined to local virtual host nor to registered route, ejabberd_router passes it to ejabberd_s2s.erl module via ejabberd_s2s:route/1 function call.
      •  
     
    Mentioned modules are explained in more details in the following sections. You're encouraged to inspect exported functions of ejabberd_router.erl, because most likely you will use some of them.
    "},{"location":"developer/guide/#ejabberd_local","title":"ejabberd_local","text":"
    ejabberd_local.erl handles stanzas destined to the local server itself. For #message{} and #presence{} it only calls hooks, while for #iq{} it finds the corresponding \"IQ handler\" by looking up its internal table to find a correspondence between a namespace of IQ's child element and the handler. Once the handler (an erlang function) is found, it passes further IQ processing to gen_iq_handler.erl via gen_iq_handler:handle/5 call.
     
    ejabberd_local.erl is also able to send IQ requests and to process responses for them. This is implemented in ejabberd_local:route_iq/2,3 functions. This is also the most notable function of the module. Calling to other functions is not recommended.
    "},{"location":"developer/guide/#ejabberd_sm","title":"ejabberd_sm","text":"
    ejabberd_sm.erl handles stanzas destined to local users. For #message{}, #presence{} and full-JID #iq{} it looks up its internal table (aka session table) for the corresponding ejabberd_c2s process and, if the process is found, it routes the stanza to this process via ejabberd_c2s:route/2 call.
     
    Bare-JID #iq{} stanzas are processed in a similar way as in ejabberd_local.erl. The internal session table is backend-dependent and is implemented in the corresponding backend module: ejabberd_sm_mnesia.erl, ejabberd_sm_redis.erl and so on.
     
    The most notable functions of the module are:
     
       
    • get_user_resources/2
      •  
    • dirty_get_sessions_list/0
      •  
    • dirty_get_my_sessions_list/0
      •  
    • get_vh_session_list/1
      •  
    • get_vh_session_number/1
      •  
    • get_vh_by_backend/1
      •  
    • get_session_pid/3
      •  
    • get_user_info/2
      •  
    • get_user_info/3
      •  
    • get_user_ip/3
      •  
    • is_existing_resource/3
      •  
    "},{"location":"developer/guide/#route-registered-processes","title":"route-registered processes","text":"
    Any process can register a route to itself. It's done by calling to ejabberd_router:route/2 function. Note that a route should be unregistered via ejabberd_router:unregister_route/1 function if the registering process terminates or the route is no longer needed. Once a route is registered to a process, this process will receive Erlang messages in the form of {route, Stanza}.
     
    NOTE: from and to fields are always set in the Stanza, so it's safe to assume that xmpp:get_from(Stanza) and xmpp:get_to(Stanza) always return #jid{} and never undefined.
     
    Refer to the code of mod_muc.erl or ejabberd_service.erl for an example of a route-registered process.
    "},{"location":"developer/guide/#ejabberd_s2s-and-ejabberd_s2s_out","title":"ejabberd_s2s and ejabberd_s2s_out","text":"
    If a stanza is destined neither to local virtual host not to a route-registered process, it's passed to ejabberd_s2s.erl module via ejabberd_s2s:route/1 function call. ejabberd_s2s in its turn will look up the internal table (currently it's s2s Mnesia table) for the ejabberd_s2s_out process and, if found, passes the stanza to this process or, otherwise, will start new ejabberd_s2s_out process.
     
    ejabberd_s2s_out.erl handles outbound XMPP S2S streams. This is the only callback module of xmpp_stream_out behaviour.
    "},{"location":"developer/guide/#adding-new-functionality","title":"Adding new functionality","text":"
    There are two common ways to add new functionality to ejabberd:
     
       
    • using IQ Handlers
      •  
    • using hooks
      •  
     
    Here is a rule of thumb on which way to choose:
     
       
    • if you want to handle newly introduced IQs (that is, to generate replies for them), use IQ handlers
      •  
    • if you want to modify ejabberd behaviour along the way of a stanza passing through all layers or want to \"listen\" for some internal events (like ejabberd configuration change), use hooks.
      •  
    "},{"location":"developer/guide/#iq-handlers","title":"IQ Handlers","text":"
    An IQ Handler is a function processing an IQ stanza (internally represented as #iq{} record). There are two types of IQ handlers: local and sm.
     
       
    • local IQ handler is a function processing IQs coming from ejabberd_local, that is, an IQ destined to the local server itself as described in ejabberd_local.
      •  
    • sm IQ handler is a function processing IQs coming from ejabberd_sm, that is, a bare-JID IQ destined to a local user as described in ejabberd_sm.
      •  
     
    An IQ handler is registered as:
     
    gen_iq_handler:add_iq_handler(Type :: ejabberd_local | ejabberd_sm,\n                              Host :: binary(),\n                              Namespace :: binary(),\n                              Module :: module(),\n                              Function :: atom()) -> ok\n
     
    where:
     
       
    • Type is ejabberd_local for local handlers or ejabberd_sm for sm handlers
      •  
    • Host is a virtual host for which the IQ is to be processed
      •  
    • Namespace is an XML namespace of IQ's child element
      •  
     
    Once registered, matching IQ stanzas are handled by calling Module:Function(IQ). The result should be in the form of #iq{} or ignore. When #iq{} is returned, it's treated as a reply and routed back to the IQ originator, otherwise, if ignore is returned, the further processing stops.
     
    NOTE: from and to fields are always set in the IQ, so it's safe to assume that xmpp:get_from(IQ) and xmpp:get_to(IQ) always return #jid{} and never undefined.
     
    If a handler is no longer needed it should be unregistered as:
     
    gen_iq_handler:remove_iq_handler(Type :: ejabberd_local | ejabberd_sm,\n                                 Host :: binary(),\n                                 Namespace :: binary()) -> ok\n
     
    with the same meaning of the arguments.
    "},{"location":"developer/guide/#hooks","title":"Hooks","text":"
    When ejabberd is processing an arbitrary event (incoming IQ, outgoing presence, configuration change, etc), it is convenient to consider some of them notable. In order for someone to be notified of such events, ejabberd executes \"hooks\". A hook is represented by a unique name. All functions associated with the hook's name will be called in some specified order.
     
    NOTE: The conception of hooking is not ejabberd specific, see Hooking Wikipedia page for a general description.
     
    For example, when a packet is received on a client connection, ejabberd runs user_send_packet hook. Several modules need to listen for an event represented by this hook (that is, a packet and a C2S state), so they associate their internal functions with it: mod_ping.erl associates user_send/1 function, mod_privacy.erl associates user_send_packet/1 function and so on. The event is passed as an argument to the \"hooked\" functions, thus, the function from mod_ping.erl will be called as mod_ping:user_send({Stanza, C2SState}), the function from mod_privacy.erl will be called as mod_privacy:user_send_packet({Stanza, C2SState}) and so on.
     
    There are two types of hooks: with an accumulator and without an accumulator.
     
       
    • a hook with an accumulator, as its name suggests, accumulates some state during execution of a list of associated functions: the first argument of the hooked function will always be an accumulator and the function must return the new value for the accumulator (whether it's modified or not) in the form of NewAcc or {stop, NewAcc}. If {stop, NewAcc} is returned, a hook is considered evaluated and next functions in its associated list are not called. Otherwise, the new value NewAcc is passed to the next function in the associated list. An example of hooks with accumulator are: disco_info, filter_packet, muc_process_iq and so on.
      •  
    • a hook without accumulator doesn't accumulate anything during execution of a list of associated functions: the returning values of such functions are simply ignored unless stop is returned. In the latter case, evaluation of next functions in the associated list is not performed. An example of hooks without accumulator are: config_reloaded, component_init and so on.
      •  
     
    Both types of hooks have local or global scope.
     
       
    • a hook with local scope is associated with particular virtual host and is run only when an event is matching this host. Most of the hooks have local scope.
      •  
    • a hook with global scope is not associated with any virtual host and is run for an event matching any hosts. A very few hooks have global scope.
      •  
     
    A function gets associated with a local hook as follows (the type of a hook doesn't matter):
     
    ejabberd_hooks:add(Hook :: atom(),\n                   Host :: binary(),\n                   Module :: module(),\n                   Function :: atom(),\n                   Seq :: integer() -> ok\n
     
    where:
     
       
    • Hook is a hook name
      •  
    • Host is a virtual host
      •  
    • Seq is a sequence number. This number defines position of the function in the list to maintain execution order. Functions with lower sequence number are executed before those with bigger sequence number. For functions with the same sequence number the order is unspecified. A function associated with an accumulating hook is called as Module:Function(Acc, Arg1, Arg2, ...) where Acc is an accumulator value, Arg1, Arg2, ... - arguments of the hook. Recall that such function must return a new accumulator value (whether it's modified or not) in the form of NewAcc or {stop, NewAcc} where NewAcc is the new accumulator value. A function associated with a hook without an accumulator is called as Module:Function(Arg1, Arg2, ...). All returning values except stop are ignored.
      •  
     
    WARNING: a Function with the corresponding arity should be exported by a Module
     
    A function for a global hook gets associated as follows (the type of a hook doesn't matter):
     
    ejabberd_hooks:add(Hook :: atom(),\n                   Module :: module(),\n                   Function :: atom(),\n                   Seq :: integer()) -> ok\n
     
    with the same meaning of the arguments. Note that Host argument is omitted in this case.
     
    For any types of hooks, if an association is no longer needed, it can be deleted by calling ejabberd_hooks:delete/5,6 functions with exactly the same arguments used to create an association.
     
    In some cases a new hook should be introduced. There is no need to explicitly register the new hook, one only needs to run a hook in the required place. The following functions can be used for this:
     
       
    • for local hooks with accumulator: ejabberd_hooks:run_fold(Hook, Host, Acc, Args). The function returns a new accumulator value.
      •  
    • for local hooks without accumulator: ejabberd_hooks:run(Hook, Host, Args). The function always returns ok.
      •  
    • for global hooks with accumulator: ejabberd_hooks:run_fold(Hook, Acc, Args). The function returns a new accumulator value.
      •  
    • for global hooks without accumulator: ejabbed_hooks:run(Hook, Args). The function always returns ok.
      •  
     
    where Args is a list of arguments (other variables have the same meaning as above).
     
    There is a helper script that you can use to check hook correctness and find mishooked functions. The script also generates a module src/hooks_type_test.erl from where you can learn about existing hooks and check execution order. You can place your code inside src directory (if any), and run:
     
    make hooks\n
    "},{"location":"developer/guide/#modules","title":"Modules","text":""},{"location":"developer/guide/#gen_mod-behaviour","title":"gen_mod behaviour","text":"
    As you might know, ejabberd is a modular software. The best method to add new functionality to it is to write a new module. For doing this one should create an Erlang module of gen_mod behaviour:
     
    %% file mod_foo.erl\n-module(mod_foo).\n...\n-behaviour(gen_mod).\n...\n
     
    Several callbacks should be defined in the module:
     
       
    • Module:start(Host, Opts) where Host is a virtual host where the module is about to start and Opts is an option list (typically defined in the modules section of ejabberd.yml). The function is executed when a module is being started. It is intended to initialize a module. This is a good place to register hooks and IQ handlers, as well as to create an initial state of a module (if needed). The function should return either ok or {ok, pid()}.
      •  
    • Module:stop(Host) where Host is a virtual host. The function is executed when a module is being stopped. It is intended to make some module cleanup: most likely unregistering hooks and IQ handlers. The returning value is ignored
      •  
    • Module:reload(Host, NewOpts, OldOpts) where NewOpts and OldOpts is the new and old options list respectively. The function is called every time a module is being reloaded. This is the only optional callback, thus, if undefined, the module will be reloaded by calling sequentially Module:stop/1 and Module:start/2.
      •  
    • Module:depends(Host, Opts) where the meaning of the arguments is the same. The function is called to build modules dependencies on startup. The function must return a list of type [{module(), DependencyType}], where DependencyType is one of hard or soft. The hard dependency means the module is non-functional if the other module is not loaded. The soft dependency means the module has suboptimal functionality if the other module is not loaded.
      •  
    • Module:mod_opt_type(Option). The function is used to process configuration options of Module. The function has the same meaning as Module:opt_type/1 callback described in Configuration validation section.
      •  
    "},{"location":"developer/guide/#stateful-modules","title":"Stateful modules","text":"
    While some modules don't need to maintain an internal state (\"stateless\" modules), others are required to do this (\"stateful\" modules). The common practice is to implement a stateful module as a gen_server process. There is a couple of helpers to deal with such modules:
     
       
    • gen_mod:start_child(Module, Host, Opts) where Module is a name of a stateful module. This function should be called as the last function inside of Module:start/2. It will create a gen_server process with a registered name and will attach it to ejabberd_gen_mod_sup supervisor.
      •  
    • gen_mod:stop_child(Module, Host) should be used inside of Module:stop/1 function and will terminate the corresponding registered gen_server process.
      •  
    • gen_mod:get_module_proc(Host, Module) can be used to obtain a registered name of a stateful module (i.e. its gen_server's name).
      •  
     
    WARNING: don't forget to set process_flag(trap_exit, true) inside Module:init/1 callback function, otherwise, Module:terminate/2 callback will never be called when a module is being stopped.
     
    WARNING: keeping module's configuration options in an internal state is not recommended. Use gen_mod:get_module_opt/4,5 functions to retrieve the options: in this case you don't need to re-initialize options in the state inside Module:reload/3 callback.
     
    If a stateful module is intended to maintain a state in the form of a table, ETS can be used for this. In this case there is no need to implement it as a gen_server process. But make sure you're not calling ets:new/2 several times for several virtual hosts (badarg will be raised in this case). E.g., the following code is incorrect:
     
    start(Host, Opts) ->\n    ...\n    ets:new(some_table, named_table, ...]),\n    ...\n
     
    The correct code will look something like that:
     
    start(Host, Opts) ->\n    ...\n    try ets:new(some_table, [named_table, ...])\n    catch _:badarg -> ok end,\n    ...\n
     
    There is a plenty of examples of modules: pick up any file starting with mod_ inside src directory.
    "},{"location":"developer/guide/#gen_mod-module","title":"gen_mod module","text":"
    Module gen_mod.erl has various useful functions to work with modules, the most notable are:
     
       
    • is_loaded/2: whether or not the module in question is loaded at a given virtual host
      •  
    • get_opt/3,4: gets a value of an option from module's options list (see description of ejabberd_config:get_option/3 function from Fetching configuration options for details)
      •  
    • get_module_opt/4,5: the same as above, but an option is referenced by a virtual host and a module.
      •  
    "},{"location":"developer/guide/#configuration","title":"Configuration","text":"
    ejabberd has quite powerful configuration processor - ejabberd_config.erl. It performs configuration file parsing and validation.
    "},{"location":"developer/guide/#validation","title":"Validation","text":"
    In order to validate options ejabberd_config has to install feedback with the rest of the code. For doing this, it provides ejabberd_config behaviour with a single callback function: Module:opt_type/1. The callback accepts an option name as an atom() and must return either validating function if an option is known for the Module or a list of available options (as a list of atoms). A validating function is a fun() of a single argument - the value of the option. The validating function must return any new value for the option (whether it's modified or not) or should crash if the value doesn't match expected format. Here is an example:
     
    %% file: some.erl\n-module(some).\n-behaviour(ejabberd_config).\n-export([opt_type/1]).\n...\nopt_type(max_connections_number) ->\n    %% max_connections_number should be non-negative integer\n    %% if the condition is satisfied, return this integer\n    %% fail with function_clause otherwise\n    fun(I) when is_integer(I), I>=0 -> I end;\nopt_type(_) ->\n    %% only max_connections_number is known\n    [max_connections_number].\n
     
    NOTE: gen_mod behaviour defines a very similar callback - Module:mod_opt_type/1 with the same meaning of arguments and returning values, except the callback is called to validate the Module's specific options (i.e. options defined in the corresponding subsection of the modules section of a configuration file).
    "},{"location":"developer/guide/#fetching-options","title":"Fetching options","text":"
    The most notable function of the module is:
     
    get_option(Option :: atom() | {atom(), binary() | global},\n           ValidatingFun :: fun(),\n           Default :: term()) -> Value :: term().\n
     
    The function is used to get a value Value of a configuration option Option. The ValidatingFun is a validating function described in the previous section and Default is the default value if the option is not defined in the config.
    "},{"location":"developer/guide/#using-xmpp-library","title":"Using XMPP library","text":""},{"location":"developer/guide/#xmpp-module","title":"xmpp module","text":"
    Prior to version 16.12, ejabberd used to operate with #xmlel{} packets directly: fast_xml API functions have been used for manipulating with #xmlel{} packets (such as fast_xml:get_subtag/2, fast_xml:get_attr_s/2, fast_xml:get_path_s/2 and so on) as well as some functions from jlib.erl module.
     
    This is now deprecated and actually not possible. Instead, the new API functions are used from brand new xmpp library.
     
    NOTE: although direct calling of fast_xml API is deprecated, there are still two useful functions: fxml_stream:parse_element/1 and fxml:element_to_binary/1. You can use these functions for (de)serialization of data stored on disc or in a database.
     
    The library is built on top of XMPP Codec: a number of decoding/encoding modules automatically generated by Fast XML generator from the specification file xmpp_codec.spec. The goal is to avoid manual processing of XML trees and, instead, using well-typed auto-generated structures defined in xmpp_codec.hrl. Every particular XML packet within some namespace has to have a specification defined in xmpp_codec.spec. The advantage of such approach is that you tell the generator what to parse instead of taming fast_xml library how to parse.
     
    NOTE: describing how to write XMPP codec specification is out of scope of this guide
     
    WARNING: you should never use functions from xmpp_codec.erl module directly: use functions from xmpp.erl module. The same is true for header files: do NOT include xmpp_codec.hrl -- include xmpp.hrl instead
    "},{"location":"developer/guide/#xmpp-codec","title":"XMPP codec","text":"
    Once a raw XML packet is parsed by ejabberd_receiver.erl into #xmlel{} record, it's passed to xmpp_stream_in.erl module, where decoding of #xmlel{} into xmpp_element() format (i.e. into well-known record type defined in xmpp_codec.hrl) is performed (refer to XMPP Stream Layer section for details). At that level \"lazy\" decoding is applied: only top-level element is decoded. For example, an xmlel() packet
     
    #xmlel{name = <<\"message\">>,\n       attrs = [{<<\"type\">>,<<\"chat\">>}],\n       children = [#xmlel{name = <<\"composing\">>,\n                          attrs = [{<<\"xmlns\">>,\n                                    <<\"http://jabber.org/protocol/chatstates\">>}],\n                          children = []}]}\n
     
    is decoded into the following xmpp_element():
     
    #message{id = <<>>,type = chat,lang = <<>>,from = undefined,\n         to = undefined,subject = [],body = [],thread = undefined,\n         sub_els = [#xmlel{name = <<\"composing\">>,\n                           attrs = [{<<\"xmlns\">>,\n                                     <<\"http://jabber.org/protocol/chatstates\">>}],\n                           children = []}],\n         meta =\n
     
    Note that the sub-element is still in xmlel() format. This \"semi-decoded\" packet is then passed upstream (at the Routing Layer). Thus, a programmer should explicitly decode sub-elements if needed. To accomplish this one can use the following function:
     
    xmpp:decode(El :: xmlel(), Namespace :: binary(), [Option]) -> xmpp_element()`\n
     
    where the only supported Option is ignore_els: with this option lazy decoding is performed. By default, full decoding is applied, i.e. all known sub-elements get decoded. Namespace is a \"top-level\" namespace: it should be provided only if <<\"xmlns\">> attribute is omitted in El, otherwise decoding would fail (see below).
     
    There is also xmpp:decode(El :: xmlel()) -> xmpp_element() function, which is a short-hand for xmpp:decode(El, ?NS_CLIENT, []) (where ?NS_CLIENT is a predefined namespace for <<\"jabber:client\">>, see Namespaces section).
     
    Both functions might fail with {xmpp_codec, Why} exception. The value of Why can be used to format the failure reason into human readable description using xmpp:format_error/1 function, e.g., using sub-element from example #message{} above, we can write:
     
    try xmpp:decode(El) of\n    #chatstate{} = ChatState -> process_chatstate(ChatState)\ncatch _:{xmpp_codec, Why} ->\n    Text = xmpp:format_error(Why),\n    ?ERROR_MSG(\"failed to decode element: ~s\", [Txt])\nend\n
     
    To apply reverse operation use xmpp:encode/2 functions:
     
    xmpp:encode(Pkt :: xmpp_element(), Namespace :: binary()) -> El :: xmlel()\n
     
    There is also xmpp:encode(Pkt :: xmpp_element()) -> El :: xmlel() function which is a short-hand for xmpp:encode(Pkt, <<>>).
     
    Namespace is a \"top-level\" namespace: it is used to tell the codec whether to include <<\"xmlns\">> attribute into resulting #xmlel{} element or not -- if the Pkt is within the same Namespace, <<\"xmlns\">> attribute will be omitted in the result. For example:
     
    > rr(xmpp).\n...\n> Msg.\n#message{id = <<>>,type = chat,lang = <<>>,from = undefined,\n         to = undefined,subject = [],body = [],thread = undefined,\n         sub_els = [#chatstate{type = composing}],\n         meta =\n> xmpp:encode(Msg).\n#xmlel{name = <<\"message\">>,\n       attrs = [{<<\"type\">>,<<\"chat\">>},\n                {<<\"xmlns\">>,<<\"jabber:client\">>}],\n       children = [#xmlel{name = <<\"composing\">>,\n                          attrs = [{<<\"xmlns\">>,\n                                    <<\"http://jabber.org/protocol/chatstates\">>}],\n                          children = []}]}\n> xmpp:encode(Msg, <<\"jabber:client\">>).\n#xmlel{name = <<\"message\">>,\n       attrs = [{<<\"type\">>,<<\"chat\">>}],\n       children = [#xmlel{name = <<\"composing\">>,\n                          attrs = [{<<\"xmlns\">>,\n                                    <<\"http://jabber.org/protocol/chatstates\">>}],\n                          children = []}]}\n
     
    NOTE: xmpp:encode/1,2 functions would never fail as long as the provided input is a valid xmpp_element() with valid values of its record fields. Use dialyzer checks of your code for validation.
     
    NOTE: there is no need to explicitly decode a sub-element of an IQ passed into an IQ handler because decoding is performed inside gen_iq_handler.erl module and a handler actually will never receive malformed sub-elements.
     
    Luckily, there is a helper function for sub-elements decoding, described in the next section and in a lot of cases it's more convenient to use it.
    "},{"location":"developer/guide/#getting-sub-elements","title":"Getting sub-elements","text":"
    Once a programmer gets a stanza in xmpp_element() format, (s)he might want to get its subelement. To accomplish this the following function can be used:
     
    xmpp:get_subtag(Stanza :: stanza(), Tag :: xmpp_element()) -> Pkt :: xmpp_element() | false\n
     
    This function finds a Tag by its well-known record inside sub-elements of the Stanza. It automatically performs decoding (if needed) and returns either found xmpp_element() or false if no elements have matched. Note that the function doesn't fail if some of sub-elements are invalid.
     
    Example:
     
    > rr(xmpp).\n...\n> Msg.\n#message{id = <<>>,type = chat,lang = <<>>,from = undefined,\n         to = undefined,subject = [],body = [],thread = undefined,\n         sub_els = [#xmlel{name = <<\"composing\">>,\n                           attrs = [{<<\"xmlns\">>,\n                                     <<\"http://jabber.org/protocol/chatstates\">>}],\n                           children = []}],\n         meta =\n> xmpp:get_subtag(Msg, #chatstate{type = composing}).\n#chatstate{type = composing}\n> xmpp:get_subtag(Msg, #chatstate{type = inactive}).\nfalse\n> xmpp:get_subtag(Msg, #disco_info{}).\nfalse\n
    "},{"location":"developer/guide/#setting-and-removing-sub-elements","title":"Setting and removing sub-elements","text":"
    In order to inject a sub-element into or delete one from arbitrary stanza() one can use xmpp:set_subtag/2 and xmpp:remove_subtag/2 respectively.
    "},{"location":"developer/guide/#from-and-to","title":"from and to","text":"
    Every stanza() element has from and to record fields. In order to get/set them one can manipulate with these record fields directly, e.g. via Msg#message.from or Pres#presence.to expressions, or, use xmpp:get_from/1, xmpp:get_to/1, xmpp:set_from/2, xmpp:set_to/2 and xmpp:set_from_to/3 functions, depending on which approach is more convenient in the current situation.
     
    NOTE: although in general from and to fields may have undefined values, these fields are always filled with correct #jid{} records at XMPP Stream Layer, thus, it is safe to assume that the fields always possess valid #jid{} values.
    "},{"location":"developer/guide/#metadata","title":"Metadata","text":"
    Every stanza() element has meta field represented as a map(). It's useful when there is a need to attach some metadata to the stanza before routing it further. A programmer can manipulate with this field directly using maps module, or use xmpp:get_meta/1,2,3, xmpp:set_meta/2, xmpp:put_meta/3, xmpp:update_meta/3 and xmpp:del_meta/2 functions, which is almost always more convenient (except pattern matching).
    "},{"location":"developer/guide/#text-elements","title":"Text elements","text":"
    Some xmpp_element()s has fields defined in [#text{}] format. The example is #message.body and #presence.status fields. To avoid writing a lot of extracting code the following functions can be used: xmpp:mk_text/1,2 to convert some binary text written in some language into [#text{}] term, or xmpp:get_text/1,2 to extract binary text from the [#text{}] element by a language.
    "},{"location":"developer/guide/#generating-errors","title":"Generating errors","text":"
    In order to generate stanza errors or stream errors xmpp:err_/0,2 or xmpp:serr_*/0,2 can be used respectively, such as xmpp:err_service_unavailable() or xmpp:serr_not_authorized(). If a stanza should be bounced back with an error, xmpp:make_error/2 function can be used
    "},{"location":"developer/guide/#namespaces","title":"Namespaces","text":"
    There are many predefined macros for XML namespaces in ns.hrl. However, this file must NOT be included, as it's already included in xmpp.hrl.
     
    A function xmpp:get_ns/1 can be used to retrieve a namespace from xmpp_element() or from xmlel() directly:
     
    > rr(xmpp).\n...\n> xmpp:get_ns(#message{}).\n<<\"jabber:client\">>.\n> xmpp:get_ns(xmpp:encode(#presence{})).\n<<\"jabber:client\">>.\n
    "},{"location":"developer/guide/#jid-module","title":"jid module","text":"
    jid.erl module provides functions to work with XMPP addresses (aka \"JIDs\"). There are two common types of internal representation of JIDs:
     
       
    • jid(): a JID is represented by a record #jid{} defined in   jid.hrl
      •  
    • ljid(): a JID is represented by a tuple {User, Server, Resource} where   User, Server and Resource are stringprepped version of a nodepart,   namepart and resourcepart of a JID respectively. This representation is useful to   use for JIDs comparison and when a JID should be used as a key (in a Mnesia   database, ETS table, etc.)
      •  
     
    The most notable functions in this module are:
     
       
    • decode(Input :: binary()) -> jid():   decodes binary data into jid(). Fails with {bad_jid, Input} otherwise.
      •  
    • encode(JID :: jid() | ljid()) -> binary():   encodes JID into binary data
      •  
    • remove_resource(JID :: jid() | ljid()) -> jid() | ljid():   removes resource part of a JID
      •  
    • replace_resource(JID :: jid() | ljid(), Resource :: binary()) -> jid() | ljid():   replaces resource part of a JID
      •  
    • tolower(JID :: jid() | ljid()) -> ljid():   transforms JID into ljid() representation
      •  
    • make(LJID :: ljid() | jid()) -> jid():   transforms LJID into jid() representation
      •  
     
    Inspect exported functions of jid.erl for more details.
    "},{"location":"developer/guide/#external-authentication","title":"External Authentication","text":"
    You can configure ejabberd to use as authentication method an external script, as described in the Administrator section: External Script.
     
    Let's see the interface between ejabberd and your script, and several example scripts. There are also several old example scripts.
    "},{"location":"developer/guide/#extauth-interface","title":"Extauth Interface","text":"
    The external authentication script follows the Erlang port driver API.
     
    That script is supposed to do these actions, in an infinite loop:
     
       
    •  
      read from stdin: AABBBBBBBBB.....
       
      •  
    •  
      A: 2 bytes of length data (a short in network byte order)
       
      •  
    •  
      B: a string of length found in A that contains operation in         plain text operation are as follows:
       
         
      •  
        auth:User:Server:Password (check if a username/password pair         is correct)
         
        •  
      •  
        isuser:User:Server (check if it\u2019s a valid user)
         
        •  
      •  
        setpass:User:Server:Password (set user\u2019s password)
         
        •  
      •  
        tryregister:User:Server:Password (try to register an         account)
         
        •  
      •  
        removeuser:User:Server (remove this account)
         
        •  
      •  
        removeuser3:User:Server:Password (remove this account if the         password is correct)
         
        •  
       
      •  
    •  
      write to stdout: AABB
       
      •  
    •  
      A: the number 2 (coded as a short, which is bytes length of         following result)
       
      •  
    •  
      B: the result code (coded as a short), should be 1 for         success/valid, or 0 for failure/invalid
       
      •  
     
    As you noticed, the : character is used to separate the fields. This is possible because the User and Server fields can't contain the : character; and Password can have that character, but is always the last field. So it is always possible to parse the input characters unambiguously.
    "},{"location":"developer/guide/#perl-example-script","title":"Perl Example Script","text":"
    This is a simple example Perl script; for example if the file is copied to the path /etc/ejabberd/check_pass_null.pl then configure ejabberd like this:
     
    auth_method: [external]\nextauth_program: /etc/ejabberd/check_pass_null.pl\n
     
    Content of check_pass_null.pl:
     
    #!/usr/bin/perl\n\nuse Unix::Syslog qw(:macros :subs);\n\nmy $domain = $ARGV[0] || \"example.com\";\n\nwhile(1)\n  {\n   # my $rin = '',$rout;\n   # vec($rin,fileno(STDIN),1) = 1;\n   # $ein = $rin;\n   # my $nfound = select($rout=$rin,undef,undef,undef);\n\n    my $buf = \"\";\n    syslog LOG_INFO,\"waiting for packet\";\n    my $nread = sysread STDIN,$buf,2;\n    do { syslog LOG_INFO,\"port closed\"; exit; } unless $nread == 2;\n    my $len = unpack \"n\",$buf;\n    my $nread = sysread STDIN,$buf,$len;\n\n    my ($op,$user,$host,$password) = split /:/,$buf;\n    #$user =~ s/\\./\\//og;\n    my $jid = \"$user\\@$domain\";\n    my $result;\n\n    syslog(LOG_INFO,\"request (%s)\", $op);\n\n  SWITCH:\n      {\n $op eq 'auth' and do\n   {\n             $result = 1;\n   },last SWITCH;\n\n $op eq 'setpass' and do\n   {\n             $result = 1;\n   },last SWITCH;\n\n        $op eq 'isuser' and do\n          {\n             # password is null. Return 1 if the user $user\\@$domain exitst.\n             $result = 1;\n          },last SWITCH;\n\n        $op eq 'tryregister' and do\n          {\n             $result = 1;\n          },last SWITCH;\n\n        $op eq 'removeuser' and do\n          {\n             # password is null. Return 1 if the user $user\\@$domain exitst.\n             $result = 1;\n          },last SWITCH;\n\n        $op eq 'removeuser3' and do\n          {\n             $result = 1;\n          },last SWITCH;\n      };\n    my $out = pack \"nn\",2,$result ? 1 : 0;\n    syswrite STDOUT,$out;\n  }\n\ncloselog;\n
    "},{"location":"developer/guide/#python-example-script","title":"Python Example Script","text":"
    Example Python script:
     
    #!/usr/bin/python\n\nimport sys\nimport struct\n\ndef read_from_stdin(bytes):\n  if hasattr(sys.stdin, 'buffer'):\n    return sys.stdin.buffer.read(bytes)\n  else:\n    return sys.stdin.read(bytes)\n\ndef read():\n    (pkt_size,) = struct.unpack('>H', read_from_stdin(2))\n    pkt = sys.stdin.read(pkt_size)\n    cmd = pkt.split(':')[0]\n    if cmd == 'auth':\n        u, s, p = pkt.split(':', 3)[1:]\n        if u == \"wrong\":\n            write(False)\n        else:\n            write(True)\n    elif cmd == 'isuser':\n        u, s = pkt.split(':', 2)[1:]\n        if u == \"wrong\":\n            write(False)\n        else:\n            write(True)\n    elif cmd == 'setpass':\n        u, s, p = pkt.split(':', 3)[1:]\n        write(True)\n    elif cmd == 'tryregister':\n        u, s, p = pkt.split(':', 3)[1:]\n        write(True)\n    elif cmd == 'removeuser':\n        u, s = pkt.split(':', 2)[1:]\n        write(True)\n    elif cmd == 'removeuser3':\n        u, s, p = pkt.split(':', 3)[1:]\n        write(True)\n    else:\n        write(False)\n    read()\n\ndef write(result):\n    if result:\n        sys.stdout.write('\\x00\\x02\\x00\\x01')\n    else:\n        sys.stdout.write('\\x00\\x02\\x00\\x00')\n    sys.stdout.flush()\n\nif __name__ == \"__main__\":\n    try:\n        read()\n    except struct.error:\n        pass\n
    "},{"location":"developer/hosts/","title":"Understanding ejabberd hosts","text":"
    The host parameter is very commonly used through ejabberd code base. It is very important to understand what it means and how it is used.
    "},{"location":"developer/hosts/#component-subdomains","title":"Component subdomains","text":"
    Most XMPP service are reference as subdomain of the main XMPP domain. For example, Multi User Chat or Publish-Subscribe are available as subdomains of the main XMPP domain served by an installation.
     
    You can also plug external components to an ejabberd server. External components will have their own subdomain as well and will be exchanging data with ejabberd using a simplified XML stream.
     
    Components can be written in any programming language. ejabberd supports XEP-0114: Jabber Component Protocol.
     
    Note the external component have limited rights on the XMPP server. As such, it is less powerful than an ejabberd module written in Erlang or Elixir. Some proposed XMPP extensions, like Privilege Entities, may grant more privileges in the future to external components.
    "},{"location":"developer/hosts/#virtual-hosts","title":"Virtual hosts","text":"
    ejabberd fully support virtual hosting. It means that the same ejabberd cluster can provide the service for multiple user bases using a single deployment. Each virtual hosts is totally independent from the other domain. They can have a different configurations.
    "},{"location":"developer/install-osx/","title":"Installing ejabberd development environment on OSX","text":"
    This short guide will show you how to compile ejabberd from source code on Mac OS X, and get users chatting right away.
    "},{"location":"developer/install-osx/#before-you-start","title":"Before you start","text":"
    ejabberd is supported on Mac OS X 10.6.8 and later. Before you can compile and run ejabberd, you also need the following to be installed on your system:
     
       
    • Gnu Make and GCC (the GNU Compiler Collection). To ensure that these   are installed, you can install the Command Line Tools for Xcode,   available via Xcode or from the Apple Developer website.
      •  
    • Git
      •  
    • Erlang/OTP 19.1 or higher. We recommend using Erlang 21.2.
      •  
    • Autotools
      •  
    "},{"location":"developer/install-osx/#homebrew","title":"Homebrew","text":"
    An easy way to install some of the dependencies is by using a package manager, such as Homebrew \u2013 the Homebrew commands are provided here:
     
       
    • Git: brew install git
      •  
    • Erlang /OTP: brew install erlang
      •  
    • Elixir: brew install elixir
      •  
    • Autoconf: brew install autoconf
      •  
    • Automake: brew install automake
      •  
    • Openssl: brew install openssl
      •  
    • Expat: brew install expat
      •  
    • Libyaml: brew install libyaml
      •  
    • Libiconv: brew install libiconv
      •  
    • Sqlite: brew install sqlite
      •  
    • GD: brew install gd
      •  
    • Rebar: brew install rebar rebar3
      •  
     
    You can install everything with a single command:
     
    brew install erlang elixir openssl expat libyaml libiconv libgd sqlite rebar rebar3 automake autoconf\n
    "},{"location":"developer/install-osx/#installation","title":"Installation","text":"
    To build and install ejabberd from source code, do the following:
     
       
    1. Clone the Git repository: git clone git@github.com:processone/ejabberd.git
      2.  
    2. Go to your ejabberd build directory: cd ejabberd
      3.  
    3.  
      Run the following commands, assuming you want to install your    ejabberd deployment into your home directory:
       
      chmod +x autogen.sh\n./autogen.sh\nexport LDFLAGS=\"-L/usr/local/opt/openssl/lib -L/usr/local/lib -L/usr/local/opt/expat/lib\"\nexport CFLAGS=\"-I/usr/local/opt/openssl/include/ -I/usr/local/include -I/usr/local/opt/expat/include\"\nexport CPPFLAGS=\"-I/usr/local/opt/openssl/include/ -I/usr/local/include -I/usr/local/opt/expat/include\"\n./configure --prefix=$HOME/my-ejabberd --enable-sqlite\nmake && make install\n
       
      4.  
     
    Note that the previous command reference the previously installed dependencies from Homebrew.
    "},{"location":"developer/install-osx/#running-ejabberd","title":"Running ejabberd","text":"
       
    • From your ejabberd build directory, go to the installation directory: cd $HOME/my-ejabberd
      •  
    • To start the ejabberd server, run the following command: sbin/ejabberdctl start
      •  
    •  
      To verify that ejabberd is running, enter the following: sbin/ejabberdctl status   If the server is running, response should be as follow:
       
      $ sbin/ejabberdctl status\nThe node ejabberd@localhost is started with status: started\nejabberd 14.12.40 is running in that node\n
       
      •  
    •  
      To connect to the ejabberd console after starting the server: sbin/ejabberdctl debug
       
      •  
    • Alternatively, you can also run the server in interactive mode: sbin/ejabberdctl live
      •  
    "},{"location":"developer/install-osx/#registering-a-user","title":"Registering a user","text":"
    The default XMPP domain served by ejabberd right after the build is localhost. This is different from the IP address, DNS name of the server. It means remote users can connect to ejabberd even if it is running on your machine with localhost XMPP domain, by using your computer IP address or DNS name. This can prove handy in development phase to get more testers.
    "},{"location":"developer/install-osx/#adium","title":"Adium","text":"
    Adium is a popular XMPP client on OSX. You can use it
     
       
    1. Launch Adium. If the Adium Setup Assistant opens, close it.
      2.  
    2. In the Adium menu, select Preferences, and then select the Accounts tab.
      3.  
    3. Click the + button and select XMPP (Jabber).
      4.  
    4. Enter a Jabber ID (for example, \u201cuser1@localhost\u201d) and password, and then click Register New Account.
      5.  
    5. In the Server field, enter the following:
      6.  
    6. Users registering on the computer on which ejabberd is running: localhost
      7.  
    7. Users registering from a different computer: the ejabberd server\u2019s IP address
      8.  
    8. Click Request New Account.
      9.  
     
    After registration, the user will connect automatically.
     
    Registered users wishing to add an existing account to Adium should enter the ejabberd server\u2019s IP address in the Connect Server field on the Options tab.
    "},{"location":"developer/install-osx/#command-line","title":"Command line","text":"
    You can register a user with the ejabberdctl utility: ejabberdctl register user domain password
     
    For example: ejabberdctl register user1 localhost myp4ssw0rd
    "},{"location":"developer/install-osx/#domains","title":"Domains","text":"
    To use your system\u2019s domain name instead of localhost, edit the following ejabberd configuration file: $HOME/my-ejabberd/etc/ejabberd.yml (point to the place of your real installation).
     
    Note: You may find example ejabberd.cfg files. This is the old obsolete format for configuration file. You can ignore the and focus on the new and more user friendly Yaml format.
     
    Find the line listing the hosts:
     
    hosts:\n  - \"localhost\"\n
     
    Replace localhost with your XMPP domain name, for example:
     
    hosts:\n  - \"example.org\"\n
     
    Save the configuration file and restart the ejabberd server. A user\u2019s Jabber ID will then use the domain instead of localhost, for example: user1@example.org
     
    You can also configure multiple (virtual) domains for one server:
     
    hosts:\n  - \"example1.org\"\n  - \"example2.org\"\n
    "},{"location":"developer/install-osx/#get-chatting","title":"Get chatting","text":"
    Users that are registered on your server can now add their accounts in a chat application like Adium (specifying either the server\u2019s IP address or domain name), add each other as contacts, and start chatting.
    "},{"location":"developer/repositories/","title":"Understanding ejabberd and its dependencies","text":"
    We wanted to make sure that ejabberd is modular and that parts that can be of interest for other Erlang projects can be reused.
     
    Not only we are massive open source contributors to Erlang community and ecosystem, but we are also trying to help even more by reviewing your pull requests. Do not hesitate to submit some on any of the many repositories mentioned here.
    "},{"location":"developer/repositories/#ejabberd-dependencies","title":"ejabberd dependencies","text":"
    ejabberd code based is split among several repositories so effectively ejabberd code is much more than what is in its primary repository.
    "},{"location":"developer/repositories/#required-dependencies","title":"Required dependencies","text":"
    The main ejabberd repository is processone/ejabberd
     
    There is hundreds of forks, but we actively maintain ejabberd to make it the most reliable and up to date version. This is thus your best starting point.
     
    When you build ejabberd yourself, the build chain will download a few Erlang dependencies:
     
       
    • processone/cache_tab:   Flexible in-memory Erlang caching module.
      •  
    • processone/iconv: Native iconv driver for Erlang. This is use for fast character encoding conversion.
      •  
    • processone/fast_xml: Fast native Expat based Erlang XML parsing library. XML is the core of XMPP so we needed to provide the fast and more robust XML parsing stack as possible. It means that if you are looking for a great XML parser, reusing p1_xml is probably a great idea.
      •  
    • processone/stringprep: Fast and efficient Erlang Stringprep native driver. Stringprep is heavily used in XMPP to define encoding rules of various XMPP objects.
      •  
    • processone/fast_yaml: Native Erlang interface to libyaml, for fast robust YAML parsing. This is needed by our new config file format.
      •  
    • processone/ezlib: Native zlib driver for Erlang. Used for fast / efficient stream compression.
      •  
    • processone/fast_tls: Erlang native driver for TLS / SSL. It is build for performance and is more scalable that Erlang SSL driver. If your Erlang server is handling heavy load and is using TLS, we strongly recommend you check / compare with this driver.
      •  
    • processone/esip: ProcessOne SIP protocol support to add SIP-based voice capabilities to ejabberd.
      •  
    • processone/stun: Implementation of Session Traversal Utilities for NAT. It is used for XMPP and SIP media capabilities, to help client discover their visible IP address and allow them to get in touch through NAT. This is basically useful for voice and file transfers.
      •  
    • processone/p1_utils: This is extra Erlang modules developed for ejabberd but that can be useful in other Erlang applications.
      •  
    • processone/p1_logger: Logger wrapper to allow selecting your preferred logger at build time.
      •  
    • basho/lager: Erlang logger module.
      •  
    • DeadZen/goldrush: Small Erlang app that provides fast event stream processing. It is used by lager.
      •  
    • vaxelfel/eHyperLogLog: HyperLogLog, a distinct values estimator, in Erlang. Used for analytics.
      •  
    "},{"location":"developer/repositories/#optional-dependencies","title":"Optional dependencies","text":"
    Then, we use a few other dependent repositories that may be used if you have enabled support in the configure script.
     
    Here are the dependencies for relational database support:
     
       
    • processone/mysql: Pure Erlang MySQL driver.
      •  
    • processone/pgsql: Pure Erlang PostgreSQL driver
      •  
     
    Here are the dependencies for Elixir support:
     
       
    • elixir-lang/elixir: Used to write ejabberd modules in Elixir programming language.
      •  
    • yrashk/rebar_elixir_plugin: Plugin for rebar build tool to support Elixir modules compilation.
      •  
     
    After you have build ejabberd from source, you will find all the dependencies downloaded and build in the deps directory.
     
    As you see, there is much more Erlang code produce at ProcessOne and contributed to the Erlang community than just ejabberd repository.
    "},{"location":"developer/repositories/#ejabberd-contributions","title":"ejabberd contributions","text":"
    This is not dependencies, but simply modules that you may find nice to add to your ejabberd deployment.
     
    We attempted to gather some of the more useful ejabberd modules in a contribution repository to ease discovery.
     
    This repository is available on Github: ejabberd-contribs
     
    We are thinking about a better approach for ejabberd contributions discovery. More on that soon.
    "},{"location":"developer/sql-schema/","title":"ejabberd SQL Database Schema","text":"
    We present the tables that might be in use, depending on your server configuration, together with a short explanation of the fields involved and their intended use. Tables are presented roughly grouped by related functionality.
     
    Consider this document a work in progress, not all tables are documented yet.
     
    Latest version of database schema are available in ejabberd Github repository:
     
       
    • MySQL schema
      •  
    • Postgres schema
      •  
    • SQLite schema
      •  
    • MS SQL Server schema. This   schema need testing / feedback and possibly improvement from SQL   Server users.
      •  
    "},{"location":"developer/sql-schema/#authentication","title":"Authentication","text":""},{"location":"developer/sql-schema/#table-users","title":"Table users","text":"
    Contains the information required to authenticate users.
     Field Type Usage username string User password string User password, can be hashed created_at timestamp When the user account was created 
    The password are hashed if you use SCRAM authentication. In that case the next fields are also defined
     Field Type Usage serverkey string support for salted passwords salt string support for salted passwords iterationcount integer support for salted passwords"},{"location":"developer/sql-schema/#rosters","title":"Rosters","text":""},{"location":"developer/sql-schema/#table-rosterusers","title":"Table rosterusers","text":"
    This is a quite complex table, used as a store for a quite complex protocol that is the one defined to manage rosters and subscriptions on rfc6121.  
     
    In the common case of two users adding each other as contacts, entries in the roster table follows a series of steps  as they moves from a subscription request to the final approval and bi-directional subscription being established. This process can be initiated either by the user, or by the (possible remote) peer. Also need to account for the case where the user, or the contact, might not be online at the moment of the subscription request is made.
     
    Steps are further complicated by the fact that entries in the roster aren't required to have corresponding subscriptions. For details of the meaning of the different fields, refer to the protocol itself, as these are mostly a direct mapping of it.
     
    Note: If you manage users contacts from outside the roster workflow of XMPP (for example your site backends perform the linking between users),  it is likely that you only need to care about the  username, jid and nick fields,  and set the subscription field to be always 'B' for a mutual link between users.
     Field Type Usage username string User jid string Contact jid nick string Contact nickname subscription char 'B'=both | 'T'=To | 'F'=From | 'N'=none ask char 'S'=subscribe | 'U'=unsubscribe | B='both' | 'O'=out | 'I'=in | 'N'=none askmessage string Message to be displayed on the subscription request server char 'N' for normal users contacts subscribe string type string \"item\" created_at timestamp Creation date of this roster entry"},{"location":"developer/sql-schema/#table-rostergroups","title":"Table rostergroups","text":""},{"location":"developer/sql-schema/#table-sr_group","title":"Table sr_group","text":""},{"location":"developer/sql-schema/#table-sr_user","title":"Table sr_user","text":""},{"location":"developer/sql-schema/#messages","title":"Messages","text":""},{"location":"developer/sql-schema/#table-spool","title":"Table spool","text":"
    Messages sent to users that are offline are stored in this table. Do not confuse this with general message archiving: messages are only temporarily stored in this table, removed as soon as the target user is back online and the pending messages delivered to it.
     Field Type Usage username string User xml blob Raw packet seq integer Unique, autoincrement sequence number. created_at timestamp When the message was stored 
    The seq field is used for sorting, and to easily identify a particular user message.
    "},{"location":"developer/sql-schema/#table-privacy_list_data","title":"Table privacy_list_data","text":"
    The table is used to store privacy rules.
     
    The table is a direct translation of the XMPP packet used to set privacy lists. For more details, please read XEP-0016: Privacy Lists, Syntax and Semantics. Here is an example packet coming from privacy list specification:
     
    <item\n     type='[jid|group|subscription]'\n     value='bar'\n     action='[allow|deny]'\n     order='unsignedInt'>\n    [<message/>]\n    [<presence-in/>]\n    [<presence-out/>]\n    [<iq/>]\n </item>\n
     
    The table fields are defined as follow:
     Field Type Usage id int Privacy list rule id. t char Privacy rule type: 'j' for jid, 'g' for group and 's' for subscription. value string Privacy list value for match, whose content depends on privacy list rule type. action char Privacy list action: 'd' for deny and 'a' for allow. ord int Order for applying the privacy list rule. match_all boolean (0 or 1) If true (1), means any packet types will be matched. Other matches should be false (0). match_iq boolean (0 or 1) If true (1), means iq packets will be matched by rule. match_message boolean (0 or 1) If true (1), means message packets type will be matched by rule. match_presence_in boolean (0 or 1) If true (1), means inbound presence packets type will be matched by rule. match_presence_out boolean (0 or 1) If true (1), means outbound packets type will be matched by rule."},{"location":"developer/sql-schema/#multiuser-chat-rooms","title":"Multiuser Chat Rooms","text":""},{"location":"developer/sql-schema/#table-muc_room","title":"Table muc_room","text":"
    It is used to store persistent rooms, that is, rooms that must be automatically started with the server.
     Field Type Usage name string Room name host string Hostname of the conference component opts string Room options, encoded as erlang terms created_at timestamp Creation date 
    The opts field is legible, but not mean to be modified directly. It contents depends on the implementation of mod_muc. It contains the room configuration and affiliations.
    "},{"location":"developer/sql-schema/#table-muc_registered","title":"Table muc_registered","text":"
    Contains a map of user to nicknames.  When a user register a nickname with the conference module, that nick is reserved and can't be used by anyone else, in any room from that conference host.
     Field Type Usage jid string User jid host string Hostname of the conference component nick string Room options, encoded as erlang terms created_at timestamp Creation date"},{"location":"developer/sql-schema/#table-room_history","title":"Table room_history","text":"
    In ejabberd Business Edition, this table is used if persistent room history is enabled. If so, recent room history is saved to the DB before ejabberd is stopped, allowing the recent history to survive server restarts.
     Field Type Usage room string Room jid nick string Nickname that sent the message packet string XML stanza with the message have_subject boolean True if the message stanza had subject created_at timestamp Creation date size integer Size in bytes of the xml packet"},{"location":"developer/sql-schema/#table-muc_online_room","title":"Table muc_online_room","text":"
    This table is used to store rooms that actually exists in the memory of the server.
     Field Type Usage name string Room name host string Hostname of the conference component node string Erlang node where the room is pid string Pid of the thread running the room"},{"location":"developer/sql-schema/#table-muc_online_users","title":"Table muc_online_users","text":"
    This table is used to store MucSub subscriptions.
     Field Type Usage username string User server string Hostname of the user resource string User resource name string Name of the room host string Hostname of the conference component node string Erlang node"},{"location":"developer/sql-schema/#table-muc_room_subscribers","title":"Table muc_room_subscribers","text":"
    This table is used to store MucSub subscriptions.
     Field Type Usage room string Room name host string Hostname of the conference component jid string User jid nick string User nick nodes string MucSub nodes created_at timestamp Creation date"},{"location":"developer/sql-schema/#vcard","title":"VCard","text":""},{"location":"developer/sql-schema/#table-vcard","title":"Table vcard","text":"
    The table is used to store raw vCard content for delivery of the vCard \"as is\".
     
    The table fields are defined as follow:
     Field Type Usage username string Owner of the Vcard vcard text Raw Vcard created_at timestamp Record creation date"},{"location":"developer/sql-schema/#table-vcard_search","title":"Table vcard_search","text":"
    The table is used to store vCard index on a few of the Vcard field used for vCard search in users directory.
     
    You can learn more about the vCard specification on Wikipedia vCard page.
     
    The table fields are defined as follow:
     Field Type Usage username string Raw username for display lusername string Lowercase username for search fn string Raw fullname for display lfn string Lowercase fullname for search family string Raw family name for display lfamilly string Lowercase family name for search given string Raw given name for display lgiven string Lowercase given name for search middle string Raw middle name for display lmiddle string Lowercase middle name for search nickname string Raw nickname for display lnickname string Lowercase nickname for search bday string Raw birthday for display lbday string Lowercase and processed birthday for search ctry string Raw country for display lctry string Lowercase country for search locality string Raw city for display llocality string Lowercase city for search email string Raw email for display lemail string Lowercase email for search orgname string Raw organisation name for display lorgname string Lowercase organisation name for search orgunit string Raw organisation department name for display lorgunit string Lowercase organisation department for search"},{"location":"developer/sql-schema/#others","title":"Others","text":""},{"location":"developer/sql-schema/#table-last","title":"Table last","text":"
    This table is used to store the last time the user was seen online. It is defined as follow:
     Field Type Usage username string User seconds string Timestamp for the last time the user was seen online state string Why user got disconnected. Usually is empty 
    Note that the table is not updated while the user has the session open.
    "},{"location":"developer/sql-schema/#table-caps_features","title":"Table caps_features","text":"
    Ejabberd uses this table to keep a list of the entity capabilities discovered.
     Field Type Usage node string Node subnode string Subnode feature string Entity feature created_at timestamp Creation date 
    The subnode field correspond to the 'ver' (\"verification string\") of XEP-0115. There is one entry in this table for each feature advertised by the given (node,subnode) pair.
    "},{"location":"developer/sql-schema/#table-private_storage","title":"Table private_storage","text":"
    Used for user private data storage.
     Field Type Usage username string User namespace string XEP-0049 namespace of the stored data data string Raw xml created_at timestamp Creation date"},{"location":"developer/vscode/","title":"Developing ejabberd with VSCode","text":"
     added in 23.01
     
    The ejabberd git repository includes basic configuration and a few scripts to get started with ejabberd development using Visual Studio Code.
     
    There are several Visual Studio Code flavours suitable for ejabberd development:
     
       
    • Visual Studio Code desktop app \u2013  local development with no dependencies
      •  
    • VSCodium desktop app \u2013  local development installing dependencies
      •  
    • Coder's code-server container image \u2013  local or remote development
      •  
    • GitHub Codespaces service \u2013  quick and short remote development
      •  
    "},{"location":"developer/vscode/#visual-studio-code","title":"Visual Studio Code","text":"
    The official Visual Studio Code installers provided by Microsoft can use the official marketplace. That allows to install the Dev Container extension to compile and run ejabberd inside a prepared container, which includes Erlang/OTP and all the required libraries, so you don't need to install them in your machine.
     
    However that installer is licensed under a not-FLOSS license and contains telemetry/tracking.
     
    Once installed: install Git as suggested, clone the ejabberd git repository locally, let it install the Dev Container extension, then let it reopen the path inside the devcontainer.
    "},{"location":"developer/vscode/#vscodium","title":"VSCodium","text":"
    VSCodium provides Free/Libre Open Source Software Binaries of VSCode. This is a great alternative to the official VSCode installer.
     
    However, it can't use the official marketplace, uses instead the open-vsx.com marketplace, and the Dev Containers extension is not available. This means that you must install the ejabberd dependencies in your system to compile and debug ejabberd.
     
    Once installed: open your local ejabberd git clone. It's highly recommended to go the EXTENSIONS tab and install the Erlang LS extension.
    "},{"location":"developer/vscode/#coders-code-server","title":"Coder's code-server","text":"
    An easy, zero-cost, way to use VSCode in a web browser is through the ejabberd's code-server container image. This image is based in the Debian docker image and includes Coder's code-server, Erlang/OTP, Elixir, and all the required libraries.
     
    Download and start the container, and provide as volume the path of your local ejabberd git clone:
     
    docker run \\\n    --name coder \\\n    -it \\\n    -p 5208:5208 \\\n    -v $(pwd)/ejabberd:/workspaces/ejabberd \\\n    ghcr.io/processone/code-server\n
     
    Now open in your web browser: http://0.0.0.0:5208/
     
    The next time it can be started with docker start -i coder
    "},{"location":"developer/vscode/#github-codespaces","title":"GitHub Codespaces","text":"
    The ejabberd git repository contains default configuration to use it in the GitHub Codespaces service.
     
    This can be used remotely over a web browser, no need to install anything. Notice this is a service that can be used for free several hours each month, and later requires a subscription.
     
    To start using it:
     
       
    1. Go to https://github.com/codespaces
      2.  
    2. Click \"New codespace\"
      3.  
    3. Select ejabberd repository, desired branch, click \"Create codespace\"
      4.  
    "},{"location":"developer/vscode/#basic-usage","title":"Basic Usage","text":"
    Once you have VSCode running and ejabberd git repository opened, open some erlang file, so Erlang LS extension gets started, and now you can go to RUN and run ejabberd for the first time. The first time it will take some time to compile, be patient.
     
    Now you can:
     
       
    • In RUN click \u25b7 Relive to compile and start ejabberd
      •  
    • In EXPLORER open any source code, and add a breakpoint
      •  
    • In TERMINAL you can call: ejabberdctl register admin localhost somepass
      •  
    • In PORTS you can view the addresses you can use to connect to the running ejabberd
      •  
     
    The ejabberd configuration file is in _build/relive/conf/ejabberd.yml.
     
    You can connect to ejabberd using a XMPP client using HTTPS BOSH or WS on port 5443. Webadmin is on port 5280, if it complains 404, add admin/ to the URL.
    "},{"location":"developer/ejabberd-api/","title":"ejabberd Rest API","text":""},{"location":"developer/ejabberd-api/#introduction","title":"Introduction","text":"
    ejabberd comes with a powerful API serving two goals:
     
       
    1. Manage the XMPP service and integrate the platform with back-end platforms and script tools.
      2.  
    2. Allow users to perform tasks via the client, allowing simple basic clients that do not need to use XMPP protocol.    This can be handy, for example to send a message from your smartwatch, or show the number of offline messages.
      3.  
     
    The system is powerful and very versatile and you can configure it very finely, but it can be quite daunting to set up.
     
    This section is written to demystify ejabberd API configuration and help you integrate ejabberd with your other back-ends or script through an HTTP / HTTPS ReST API.
    "},{"location":"developer/ejabberd-api/#understanding-ejabberd-commands","title":"Understanding ejabberd \"commands\"","text":"
    ejabberd operations are organised around the concept of commands. ejabberd standard modules already provide many commands, but the mechanism is generic and any module can provide its own set of commands. This exposition of commands for third-party modules make it very powerful.
     
    All commands can be exposed through interfaces. Available interfaces are:
     
       
    • ejabberdctl command-line tool,
      •  
    • mod_http_api for ReST calls using JSON data,
      •  
    • ejabberd_xmlrpc for XML-RPC calls,
      •  
    • to some extend, XMPP protocol itself through discovery and adhoc commands, using mod_configure.
      •  
     
    The ejabberd-contrib Github repository provides other interfaces that can be installed to execute ejabberd commands in different ways: mod_rest (HTTP POST service), mod_shcommands (ejabberd WebAdmin page).
     
    Any module in ejabberd can add its own command(s) through ejabberd Erlang/Elixir API, making the whole system totally extensible. A third-party module can expose its own command(s) and feel like a real part of the system. A module that exposes commands allows server admins to expose it the way they want.
     
    ejabberd commands are universal, extensible and widely available through various configurable entrypoints.
     
    Note: The XML-RPC API still works but is deprecated in favor of the ReST API. You should migrate to ReST if you are using it.
    "},{"location":"developer/ejabberd-api/#the-role-of-ejabberd-api","title":"The role of ejabberd API","text":"
    As we have seen, ejabberd API role is to provide and control access to ejabberd commands over HTTP/HTTPS.
     
    Thus, ejabberd API primary goal is to grant access to some or all ejabberd \"commands\".
     
    An admin ejabberd ReST API requires:
     
       
    • At least one admin user, if you plan to check credentials for command access (You can alternatively rely on originating IP addresses).
      •  
    • HTTP/HTTPS handlers configured to expose the desired commands.
      •  
    • The selection of authentication mechanisms that can be used to access the API.   Two mechanisms are available to access the HTTP API:
      •  
    • Basic authentication. This mechanism is enabled by default.
      •  
    • OAuth 2.0 token based authentication. It has to be explicitly added to the config file.
      •  
    "},{"location":"developer/ejabberd-api/#learning-the-basics","title":"Learning the basics","text":"
    The first resources to read to learn about ejabberd ReST API configuration are the following:
     
       
    • Simple API configuration
      •  
    • Using ejabberd client API libraries and tools
      •  
     
    The list of available commands is available in the API Reference section. Additionally, you can check at runtime what commands are available in your installed server using ejabberdctl:
     
    \u276f ejabberdctl\nUsage: ejabberdctl [--no-timeout] [--node nodename] [--version api_version] command [arguments]\n\nAvailable commands in this ejabberd node:\n  backup file\n             Store internal Mnesia database to binary backup file\n  ban_account user host reason\n             Ban an account: kick sessions and set random password\n  ...\n\n\u276f ejabberdctl help\n  ...\n\n\u276f ejabberdctl help ban_account\n  ...\n
    "},{"location":"developer/ejabberd-api/#next-steps","title":"Next steps","text":"
    You can dig deeper into ejabberd ReST API configuration on the following pages:
     
       
    • API Permissions
      •  
    • OAuth Support
      •  
    • Administration API Commands
      •  
    "},{"location":"developer/ejabberd-api/admin-api/","title":"API Reference","text":"
    This section describes API commands of ejabberd 24.02.  If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the Archive. The commands that changed in this version are marked with \ud83d\udfe4.
    "},{"location":"developer/ejabberd-api/admin-api/#abort_delete_old_mam_messages","title":"abort_delete_old_mam_messages","text":"
     added in 22.05
     
    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
     
    Module: mod_mam
     
    Examples:
     
    POST /api/abort_delete_old_mam_messages\n{\n  \"host\": \"localhost\"\n}\n\nHTTP/1.1 200 OK\n\"Operation aborted\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#abort_delete_old_messages","title":"abort_delete_old_messages","text":"
     added in 22.05
     
    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
     
    Examples:
     
    POST /api/abort_delete_old_messages\n{\n  \"host\": \"localhost\"\n}\n\nHTTP/1.1 200 OK\n\"Operation aborted\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#add_rosteritem","title":"add_rosteritem \ud83d\udfe4","text":"
     updated in 24.02
     
    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, v1
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/add_rosteritem\n{\n  \"localuser\": \"user1\",\n  \"localhost\": \"myserver.com\",\n  \"user\": \"user2\",\n  \"host\": \"myserver.com\",\n  \"nick\": \"User 2\",\n  \"groups\": [\n    \"Friends\",\n    \"Team 1\"\n  ],\n  \"subs\": \"both\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#backup","title":"backup","text":"
    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
     
    Examples:
     
    POST /api/backup\n{\n  \"file\": \"/var/lib/ejabberd/database.backup\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#ban_account","title":"ban_account","text":"
    Ban an account: kick sessions and set random password
     
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/ban_account\n{\n  \"user\": \"attacker\",\n  \"host\": \"myserver.com\",\n  \"reason\": \"Spaming other users\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#bookmarks_to_pep","title":"bookmarks_to_pep","text":"
    Export private XML storage bookmarks to PEP
     
    Arguments:
     
       
    • user :: string : Username
      •  
    • host :: string : Server
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: private
     
    Module: mod_private
     
    Examples:
     
    POST /api/bookmarks_to_pep\n{\n  \"user\": \"bob\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n\"Bookmarks exported\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#change_password","title":"change_password","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/change_password\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\",\n  \"newpass\": \"blank\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#change_room_option","title":"change_room_option","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/change_room_option\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\",\n  \"option\": \"members_only\",\n  \"value\": \"true\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#check_account","title":"check_account","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/check_account\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#check_password","title":"check_password","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/check_password\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\",\n  \"password\": \"secret\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#check_password_hash","title":"check_password_hash","text":"
    Check if the password hash is correct
     
    Allows hash methods from the Erlang/OTP 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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/check_password_hash\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\",\n  \"passwordhash\": \"5ebe2294ecd0e0f08eab7690d2a6ee69\",\n  \"hashmethod\": \"md5\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#clear_cache","title":"clear_cache","text":"
    Clear database cache on all nodes
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/clear_cache\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#compile","title":"compile","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/compile\n{\n  \"file\": \"/home/me/srcs/ejabberd/mod_example.erl\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#connected_users","title":"connected_users","text":"
    List all established sessions
     
    Arguments:
     
    Result:
     
       
    • connected_users :: [sessions::string] : List of users sessions
      •  
     
    Tags: session
     
    Examples:
     
    POST /api/connected_users\n{\n\n}\n\nHTTP/1.1 200 OK\n[\n  \"user1@example.com\",\n  \"user2@example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#connected_users_info","title":"connected_users_info","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/connected_users_info\n{\n\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"jid\": \"user1@myserver.com/tka\",\n    \"connection\": \"c2s\",\n    \"ip\": \"127.0.0.1\",\n    \"port\": 42656,\n    \"priority\": 8,\n    \"node\": \"ejabberd@localhost\",\n    \"uptime\": 231,\n    \"status\": \"dnd\",\n    \"resource\": \"tka\",\n    \"statustext\": \"\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#connected_users_number","title":"connected_users_number","text":"
    Get the number of established sessions
     
    Arguments:
     
    Result:
     
       
    • num_sessions :: integer
      •  
     
    Tags: session, statistics
     
    Examples:
     
    POST /api/connected_users_number\n{\n\n}\n\nHTTP/1.1 200 OK\n2\n
    "},{"location":"developer/ejabberd-api/admin-api/#connected_users_vhost","title":"connected_users_vhost","text":"
    Get the list of established sessions in a vhost
     
    Arguments:
     
       
    • host :: string : Server name
      •  
     
    Result:
     
       
    • connected_users_vhost :: [sessions::string]
      •  
     
    Tags: session
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/connected_users_vhost\n{\n  \"host\": \"myexample.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"user1@myserver.com/tka\",\n  \"user2@localhost/tka\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#convert_to_scram","title":"convert_to_scram","text":"
    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
     
    Examples:
     
    POST /api/convert_to_scram\n{\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#convert_to_yaml","title":"convert_to_yaml","text":"
    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
     
    Examples:
     
    POST /api/convert_to_yaml\n{\n  \"in\": \"/etc/ejabberd/ejabberd.cfg\",\n  \"out\": \"/etc/ejabberd/ejabberd.yml\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#create_room","title":"create_room","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/create_room\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#create_room_with_opts","title":"create_room_with_opts","text":"
    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, muc_sub
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/create_room_with_opts\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\",\n  \"host\": \"localhost\",\n  \"options\": [\n    {\n      \"name\": \"members_only\",\n      \"value\": \"true\"\n    },\n    {\n      \"name\": \"affiliations\",\n      \"value\": \"owner:bob@example.com,member:peter@example.com\"\n    },\n    {\n      \"name\": \"subscribers\",\n      \"value\": \"bob@example.com:Bob:messages:subject,anne@example.com:Anne:messages\"\n    }\n  ]\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#create_rooms_file","title":"create_rooms_file","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/create_rooms_file\n{\n  \"file\": \"/home/ejabberd/rooms.txt\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_expired_messages","title":"delete_expired_messages","text":"
    Delete expired offline messages from database
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: purge
     
    Examples:
     
    POST /api/delete_expired_messages\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_expired_pubsub_items","title":"delete_expired_pubsub_items","text":"
     added in 21.12
     
    Delete expired PubSub items
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: purge
     
    Module: mod_pubsub
     
    Examples:
     
    POST /api/delete_expired_pubsub_items\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_mnesia","title":"delete_mnesia","text":"
    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
     
    Examples:
     
    POST /api/delete_mnesia\n{\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_mam_messages","title":"delete_old_mam_messages","text":"
    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
     
    Module: mod_mam
     
    Examples:
     
    POST /api/delete_old_mam_messages\n{\n  \"type\": \"all\",\n  \"days\": 31\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_mam_messages_batch","title":"delete_old_mam_messages_batch","text":"
     added in 22.05
     
    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
     
    Module: mod_mam
     
    Examples:
     
    POST /api/delete_old_mam_messages_batch\n{\n  \"host\": \"localhost\",\n  \"type\": \"all\",\n  \"days\": 31,\n  \"batch_size\": 1000,\n  \"rate\": 10000\n}\n\nHTTP/1.1 200 OK\n\"Removal of 5000 messages in progress\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_mam_messages_status","title":"delete_old_mam_messages_status","text":"
     added in 22.05
     
    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
     
    Module: mod_mam
     
    Examples:
     
    POST /api/delete_old_mam_messages_status\n{\n  \"host\": \"localhost\"\n}\n\nHTTP/1.1 200 OK\n\"Operation in progress, delete 5000 messages\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_messages","title":"delete_old_messages","text":"
    Delete offline messages older than DAYS
     
    Arguments:
     
       
    • days :: integer : Number of days
      •  
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: purge
     
    Examples:
     
    POST /api/delete_old_messages\n{\n  \"days\": 31\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_messages_batch","title":"delete_old_messages_batch","text":"
     added in 22.05
     
    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
     
    Examples:
     
    POST /api/delete_old_messages_batch\n{\n  \"host\": \"localhost\",\n  \"days\": 31,\n  \"batch_size\": 1000,\n  \"rate\": 10000\n}\n\nHTTP/1.1 200 OK\n\"Removal of 5000 messages in progress\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_messages_status","title":"delete_old_messages_status","text":"
     added in 22.05
     
    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
     
    Examples:
     
    POST /api/delete_old_messages_status\n{\n  \"host\": \"localhost\"\n}\n\nHTTP/1.1 200 OK\n\"Operation in progress, delete 5000 messages\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_pubsub_items","title":"delete_old_pubsub_items","text":"
     added in 21.12
     
    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
     
    Module: mod_pubsub
     
    Examples:
     
    POST /api/delete_old_pubsub_items\n{\n  \"number\": 1000\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_push_sessions","title":"delete_old_push_sessions","text":"
    Remove push sessions older than DAYS
     
    Arguments:
     
       
    • days :: integer
      •  
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: purge
     
    Module: mod_push
     
    Examples:
     
    POST /api/delete_old_push_sessions\n{\n  \"days\": 1\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_users","title":"delete_old_users","text":"
    Delete users that didn't log in last days, or that never logged
     
    To protect admin accounts, configure this for example: 
    access_rules:\n  protect_old_users:\n    - allow: admin\n    - deny: all\n
     
    Arguments:
     
       
    • days :: integer : Last login age in days of accounts that should be removed
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: accounts, purge
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/delete_old_users\n{\n  \"days\": 30\n}\n\nHTTP/1.1 200 OK\n\"Deleted 2 users: [\"oldman@myserver.com\", \"test@myserver.com\"]\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_users_vhost","title":"delete_old_users_vhost","text":"
    Delete users that didn't log in last days in vhost, or that never logged
     
    To protect admin accounts, configure this for example: 
    access_rules:\n  delete_old_users:\n    - deny: admin\n    - allow: all\n
     
    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, purge
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/delete_old_users_vhost\n{\n  \"host\": \"myserver.com\",\n  \"days\": 30\n}\n\nHTTP/1.1 200 OK\n\"Deleted 2 users: [\"oldman@myserver.com\", \"test@myserver.com\"]\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_rosteritem","title":"delete_rosteritem","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/delete_rosteritem\n{\n  \"localuser\": \"user1\",\n  \"localhost\": \"myserver.com\",\n  \"user\": \"user2\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#destroy_room","title":"destroy_room","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/destroy_room\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#destroy_rooms_file","title":"destroy_rooms_file","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/destroy_rooms_file\n{\n  \"file\": \"/home/ejabberd/rooms.txt\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#dump","title":"dump","text":"
    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
     
    Examples:
     
    POST /api/dump\n{\n  \"file\": \"/var/lib/ejabberd/database.txt\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#dump_config","title":"dump_config","text":"
    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
     
    Examples:
     
    POST /api/dump_config\n{\n  \"out\": \"/tmp/ejabberd.yml\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#dump_table","title":"dump_table","text":"
    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
     
    Examples:
     
    POST /api/dump_table\n{\n  \"file\": \"/var/lib/ejabberd/table-muc-registered.txt\",\n  \"table\": \"muc_registered\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#export2sql","title":"export2sql","text":"
    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 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
     
    Examples:
     
    POST /api/export2sql\n{\n  \"host\": \"example.com\",\n  \"file\": \"/var/lib/ejabberd/example.com.sql\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#export_piefxis","title":"export_piefxis","text":"
    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
     
    Examples:
     
    POST /api/export_piefxis\n{\n  \"dir\": \"/var/lib/ejabberd/\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#export_piefxis_host","title":"export_piefxis_host","text":"
    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
     
    Examples:
     
    POST /api/export_piefxis_host\n{\n  \"dir\": \"/var/lib/ejabberd/\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#gc","title":"gc","text":"
     added in 20.01
     
    Force full garbage collection
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/gc\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#gen_html_doc_for_commands","title":"gen_html_doc_for_commands","text":"
    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
     
    Examples:
     
    POST /api/gen_html_doc_for_commands\n{\n  \"file\": \"/home/me/docs/api.html\",\n  \"regexp\": \"mod_admin\",\n  \"examples\": \"java,json\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#gen_markdown_doc_for_commands","title":"gen_markdown_doc_for_commands","text":"
    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
     
    Examples:
     
    POST /api/gen_markdown_doc_for_commands\n{\n  \"file\": \"/home/me/docs/api.html\",\n  \"regexp\": \"mod_admin\",\n  \"examples\": \"java,json\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#gen_markdown_doc_for_tags","title":"gen_markdown_doc_for_tags","text":"
     added in 21.12
     
    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
     
    Examples:
     
    POST /api/gen_markdown_doc_for_tags\n{\n  \"file\": \"/home/me/docs/tags.md\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_cookie","title":"get_cookie","text":"
    Get the Erlang cookie of this node
     
    Arguments:
     
    Result:
     
       
    • cookie :: string : Erlang cookie used for authentication by ejabberd
      •  
     
    Tags: erlang
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_cookie\n{\n\n}\n\nHTTP/1.1 200 OK\n\"MWTAVMODFELNLSMYXPPD\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_last","title":"get_last","text":"
    Get last activity information
     
    Timestamp is UTC and XEP-0082 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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_last\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n{\n  \"timestamp\": \"2017-06-30T14:32:16.060684Z\",\n  \"status\": \"ONLINE\"\n}\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_loglevel","title":"get_loglevel","text":"
    Get the current loglevel
     
    Arguments:
     
    Result:
     
       
    • levelatom :: string : Tuple with the log level number, its keyword and description
      •  
     
    Tags: logs
     
    Examples:
     
    POST /api/get_loglevel\n{\n\n}\n\nHTTP/1.1 200 OK\n\"warning\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_offline_count","title":"get_offline_count","text":"
    Get the number of unread offline messages
     
    Arguments:
     
       
    • user :: string
      •  
    • host :: string
      •  
     
    Result:
     
       
    • value :: integer : Number
      •  
     
    Tags: offline
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_offline_count\n{\n  \"user\": \"aaaaa\",\n  \"host\": \"bbbbb\"\n}\n\nHTTP/1.1 200 OK\n5\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_presence","title":"get_presence","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_presence\n{\n  \"user\": \"peter\",\n  \"host\": \"myexample.com\"\n}\n\nHTTP/1.1 200 OK\n{\n  \"jid\": \"user1@myserver.com/tka\",\n  \"show\": \"dnd\",\n  \"status\": \"Busy\"\n}\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_room_affiliation","title":"get_room_affiliation","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_room_affiliation\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\",\n  \"jid\": \"user1@example.com\"\n}\n\nHTTP/1.1 200 OK\n\"member\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_room_affiliations","title":"get_room_affiliations","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_room_affiliations\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"username\": \"user1\",\n    \"domain\": \"example.com\",\n    \"affiliation\": \"member\",\n    \"reason\": \"member\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_room_history","title":"get_room_history","text":"
     added in 23.04
     
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_room_history\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"timestamp\": \"aaaaa\",\n    \"message\": \"bbbbb\"\n  },\n  {\n    \"timestamp\": \"ccccc\",\n    \"message\": \"ddddd\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_room_occupants","title":"get_room_occupants","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_room_occupants\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"jid\": \"user1@example.com/psi\",\n    \"nick\": \"User 1\",\n    \"role\": \"owner\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_room_occupants_number","title":"get_room_occupants_number","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_room_occupants_number\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n7\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_room_options","title":"get_room_options","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_room_options\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"name\": \"members_only\",\n    \"value\": \"true\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_roster","title":"get_roster","text":"
     improved in 23.10
     
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_roster\n{\n  \"user\": \"aaaaa\",\n  \"host\": \"bbbbb\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"jid\": \"aaaaa\",\n    \"nick\": \"bbbbb\",\n    \"subscription\": \"ccccc\",\n    \"pending\": \"ddddd\",\n    \"groups\": [\n      \"eeeee\",\n      \"fffff\"\n    ]\n  },\n  {\n    \"jid\": \"ggggg\",\n    \"nick\": \"hhhhh\",\n    \"subscription\": \"iiiii\",\n    \"pending\": \"jjjjj\",\n    \"groups\": [\n      \"kkkkk\",\n      \"lllll\"\n    ]\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_subscribers","title":"get_subscribers","text":"
    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, muc_sub
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_subscribers\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"user2@example.com\",\n  \"user3@example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_user_rooms","title":"get_user_rooms","text":"
    Get the list of rooms where this user is occupant
     
    Arguments:
     
       
    • user :: string : Username
      •  
    • host :: string : Server host
      •  
     
    Result:
     
       
    • rooms :: [room::string]
      •  
     
    Tags: muc
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_user_rooms\n{\n  \"user\": \"tom\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"room1@muc.example.com\",\n  \"room2@muc.example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_user_subscriptions","title":"get_user_subscriptions","text":"
     added in 21.04
     
    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, muc_sub
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_user_subscriptions\n{\n  \"user\": \"tom\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"roomjid\": \"room1@muc.example.com\",\n    \"usernick\": \"Tommy\",\n    \"nodes\": [\n      \"mucsub:config\"\n    ]\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_vcard","title":"get_vcard","text":"
    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
     
    Arguments:
     
       
    • user :: string : User name
      •  
    • host :: string : Server name
      •  
    • name :: string : Field name
      •  
     
    Result:
     
       
    • content :: string : Field content
      •  
     
    Tags: vcard
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_vcard\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"name\": \"NICKNAME\"\n}\n\nHTTP/1.1 200 OK\n\"User 1\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_vcard2","title":"get_vcard2","text":"
    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
     
    Arguments:
     
       
    • user :: string : User name
      •  
    • host :: string : Server name
      •  
    • name :: string : Field name
      •  
    • subname :: string : Subfield name
      •  
     
    Result:
     
       
    • content :: string : Field content
      •  
     
    Tags: vcard
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_vcard2\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"name\": \"N\",\n  \"subname\": \"FAMILY\"\n}\n\nHTTP/1.1 200 OK\n\"Schubert\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_vcard2_multi","title":"get_vcard2_multi","text":"
    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
     
    Arguments:
     
       
    • user :: string
      •  
    • host :: string
      •  
    • name :: string
      •  
    • subname :: string
      •  
     
    Result:
     
       
    • contents :: [value::string]
      •  
     
    Tags: vcard
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_vcard2_multi\n{\n  \"user\": \"aaaaa\",\n  \"host\": \"bbbbb\",\n  \"name\": \"ccccc\",\n  \"subname\": \"ddddd\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"aaaaa\",\n  \"bbbbb\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#halt","title":"halt","text":"
     added in 23.10
     
    Halt ejabberd abruptly with status code 1
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/halt\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#help","title":"help","text":"
    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
     
    Examples:
     
    POST /api/help\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#import_dir","title":"import_dir","text":"
    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
     
    Examples:
     
    POST /api/import_dir\n{\n  \"file\": \"/var/lib/ejabberd/jabberd14/\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#import_file","title":"import_file","text":"
    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
     
    Examples:
     
    POST /api/import_file\n{\n  \"file\": \"/var/lib/ejabberd/jabberd14.spool\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#import_piefxis","title":"import_piefxis","text":"
    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
     
    Examples:
     
    POST /api/import_piefxis\n{\n  \"file\": \"/var/lib/ejabberd/example.com.xml\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#import_prosody","title":"import_prosody","text":"
    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, sql
     
    Examples:
     
    POST /api/import_prosody\n{\n  \"dir\": \"/var/lib/prosody/datadump/\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#incoming_s2s_number","title":"incoming_s2s_number","text":"
    Number of incoming s2s connections on the node
     
    Arguments:
     
    Result:
     
       
    • s2s_incoming :: integer
      •  
     
    Tags: statistics, s2s
     
    Examples:
     
    POST /api/incoming_s2s_number\n{\n\n}\n\nHTTP/1.1 200 OK\n1\n
    "},{"location":"developer/ejabberd-api/admin-api/#install_fallback","title":"install_fallback","text":"
    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 API.
     
    Arguments:
     
       
    • file :: string : Full path to the fallback file
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: mnesia
     
    Examples:
     
    POST /api/install_fallback\n{\n  \"file\": \"/var/lib/ejabberd/database.fallback\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#join_cluster","title":"join_cluster","text":"
    Join this node into the cluster handled by Node
     
    This command works only with ejabberdctl, not mod_http_api or other code that runs inside the same ejabberd node that will be joined.
     
    Arguments:
     
       
    • node :: string : Nodename of the node to join
      •  
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: cluster
     
    Examples:
     
    POST /api/join_cluster\n{\n  \"node\": \"ejabberd1@machine7\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#kick_session","title":"kick_session","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/kick_session\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\",\n  \"resource\": \"Psi\",\n  \"reason\": \"Stuck connection\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#kick_user","title":"kick_user","text":"
    Disconnect user's active sessions
     
    Arguments:
     
       
    • user :: string : User name
      •  
    • host :: string : Server name
      •  
     
    Result:
     
       
    • num_resources :: integer : Number of resources that were kicked
      •  
     
    Tags: session
     
    Examples:
     
    POST /api/kick_user\n{\n  \"user\": \"user1\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n3\n
    "},{"location":"developer/ejabberd-api/admin-api/#leave_cluster","title":"leave_cluster","text":"
    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
     
    Examples:
     
    POST /api/leave_cluster\n{\n  \"node\": \"ejabberd1@machine8\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#list_certificates","title":"list_certificates","text":"
    Lists all ACME certificates
     
    Arguments:
     
    Result:
     
       
    • certificates :: [{domain::string, file::string, used::string}]
      •  
     
    Tags: acme
     
    Examples:
     
    POST /api/list_certificates\n{\n\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"domain\": \"aaaaa\",\n    \"file\": \"bbbbb\",\n    \"used\": \"ccccc\"\n  },\n  {\n    \"domain\": \"ddddd\",\n    \"file\": \"eeeee\",\n    \"used\": \"fffff\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#list_cluster","title":"list_cluster","text":"
    List nodes that are part of the cluster handled by Node
     
    Arguments:
     
    Result:
     
       
    • nodes :: [node::string]
      •  
     
    Tags: cluster
     
    Examples:
     
    POST /api/list_cluster\n{\n\n}\n\nHTTP/1.1 200 OK\n[\n  \"ejabberd1@machine7\",\n  \"ejabberd1@machine8\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#load","title":"load","text":"
    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 API and install_fallback API.
     
    Arguments:
     
       
    • file :: string : Full path to the text file
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: mnesia
     
    Examples:
     
    POST /api/load\n{\n  \"file\": \"/var/lib/ejabberd/database.txt\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#man","title":"man","text":"
     added in 20.01
     
    Generate Unix manpage for current ejabberd version
     
    Arguments:
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: documentation
     
    Examples:
     
    POST /api/man\n{\n\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#mnesia_change_nodename","title":"mnesia_change_nodename","text":"
    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
     
    Examples:
     
    POST /api/mnesia_change_nodename\n{\n  \"oldnodename\": \"ejabberd@machine1\",\n  \"newnodename\": \"ejabberd@machine2\",\n  \"oldbackup\": \"/var/lib/ejabberd/old.backup\",\n  \"newbackup\": \"/var/lib/ejabberd/new.backup\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#mnesia_info","title":"mnesia_info","text":"
    Dump info on global Mnesia state
     
    Arguments:
     
    Result:
     
       
    • res :: string
      •  
     
    Tags: mnesia
     
    Examples:
     
    POST /api/mnesia_info\n{\n\n}\n\nHTTP/1.1 200 OK\n\"aaaaa\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#mnesia_info_ctl","title":"mnesia_info_ctl \ud83d\udfe4","text":"
     renamed in 24.02
     
    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, mnesia
     
    Examples:
     
    POST /api/mnesia_info_ctl\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#mnesia_table_info","title":"mnesia_table_info","text":"
    Dump info on Mnesia table state
     
    Arguments:
     
       
    • table :: string : Mnesia table name
      •  
     
    Result:
     
       
    • res :: string
      •  
     
    Tags: mnesia
     
    Examples:
     
    POST /api/mnesia_table_info\n{\n  \"table\": \"roster\"\n}\n\nHTTP/1.1 200 OK\n\"aaaaa\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#module_check","title":"module_check","text":"
    Check the contributed module repository compliance
     
    Arguments:
     
       
    • module :: string : Module name
      •  
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: modules
     
    Examples:
     
    POST /api/module_check\n{\n  \"module\": \"mod_rest\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#module_install","title":"module_install","text":"
    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
     
    Examples:
     
    POST /api/module_install\n{\n  \"module\": \"mod_rest\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#module_uninstall","title":"module_uninstall","text":"
    Uninstall a contributed module
     
    Arguments:
     
       
    • module :: string : Module name
      •  
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: modules
     
    Examples:
     
    POST /api/module_uninstall\n{\n  \"module\": \"mod_rest\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#module_upgrade","title":"module_upgrade","text":"
    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
     
    Examples:
     
    POST /api/module_upgrade\n{\n  \"module\": \"mod_rest\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#modules_available","title":"modules_available","text":"
    List the contributed modules available to install
     
    Arguments:
     
    Result:
     
       
    • modules :: [{name::string, summary::string}] : List of tuples with module name and description
      •  
     
    Tags: modules
     
    Examples:
     
    POST /api/modules_available\n{\n\n}\n\nHTTP/1.1 200 OK\n{\n  \"mod_cron\": \"Execute scheduled commands\",\n  \"mod_rest\": \"ReST frontend\"\n}\n
    "},{"location":"developer/ejabberd-api/admin-api/#modules_installed","title":"modules_installed","text":"
    List the contributed modules already installed
     
    Arguments:
     
    Result:
     
       
    • modules :: [{name::string, summary::string}] : List of tuples with module name and description
      •  
     
    Tags: modules
     
    Examples:
     
    POST /api/modules_installed\n{\n\n}\n\nHTTP/1.1 200 OK\n{\n  \"mod_cron\": \"Execute scheduled commands\",\n  \"mod_rest\": \"ReST frontend\"\n}\n
    "},{"location":"developer/ejabberd-api/admin-api/#modules_update_specs","title":"modules_update_specs","text":"
    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
     
    Examples:
     
    POST /api/modules_update_specs\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#muc_online_rooms","title":"muc_online_rooms","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/muc_online_rooms\n{\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"room1@muc.example.com\",\n  \"room2@muc.example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#muc_online_rooms_by_regex","title":"muc_online_rooms_by_regex","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/muc_online_rooms_by_regex\n{\n  \"service\": \"muc.example.com\",\n  \"regex\": \"^prefix\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"jid\": \"room1@muc.example.com\",\n    \"public\": \"true\",\n    \"participants\": 10\n  },\n  {\n    \"jid\": \"room2@muc.example.com\",\n    \"public\": \"false\",\n    \"participants\": 10\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#muc_register_nick","title":"muc_register_nick","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/muc_register_nick\n{\n  \"nick\": \"Tim\",\n  \"jid\": \"tim@example.org\",\n  \"service\": \"muc.example.org\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#muc_unregister_nick","title":"muc_unregister_nick","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/muc_unregister_nick\n{\n  \"jid\": \"tim@example.org\",\n  \"service\": \"muc.example.org\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#num_resources","title":"num_resources","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/num_resources\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n5\n
    "},{"location":"developer/ejabberd-api/admin-api/#oauth_add_client_implicit","title":"oauth_add_client_implicit","text":"
    Add OAuth client_id with implicit grant type
     
    Arguments:
     
       
    • client_id :: string
      •  
    • client_name :: string
      •  
    • redirect_uri :: string
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: oauth
     
    Examples:
     
    POST /api/oauth_add_client_implicit\n{\n  \"client_id\": \"aaaaa\",\n  \"client_name\": \"bbbbb\",\n  \"redirect_uri\": \"ccccc\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#oauth_add_client_password","title":"oauth_add_client_password","text":"
    Add OAuth client_id with password grant type
     
    Arguments:
     
       
    • client_id :: string
      •  
    • client_name :: string
      •  
    • secret :: string
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: oauth
     
    Examples:
     
    POST /api/oauth_add_client_password\n{\n  \"client_id\": \"aaaaa\",\n  \"client_name\": \"bbbbb\",\n  \"secret\": \"ccccc\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#oauth_issue_token","title":"oauth_issue_token \ud83d\udfe4","text":"
     updated in 24.02
     
    Issue an OAuth 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, v1
     
    Examples:
     
    POST /api/oauth_issue_token\n{\n  \"jid\": \"user@server.com\",\n  \"ttl\": 3600,\n  \"scopes\": [\n    \"connected_users_number\",\n    \"muc_online_rooms\"\n  ]\n}\n\nHTTP/1.1 200 OK\n{\n  \"token\": \"aaaaa\",\n  \"scopes\": [\n    \"bbbbb\",\n    \"ccccc\"\n  ],\n  \"expires_in\": \"ddddd\"\n}\n
    "},{"location":"developer/ejabberd-api/admin-api/#oauth_list_tokens","title":"oauth_list_tokens","text":"
    List OAuth 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
     
    Examples:
     
    POST /api/oauth_list_tokens\n{\n\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"token\": \"aaaaa\",\n    \"user\": \"bbbbb\",\n    \"scope\": \"ccccc\",\n    \"expires_in\": \"ddddd\"\n  },\n  {\n    \"token\": \"eeeee\",\n    \"user\": \"fffff\",\n    \"scope\": \"ggggg\",\n    \"expires_in\": \"hhhhh\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#oauth_remove_client","title":"oauth_remove_client","text":"
    Remove OAuth client_id
     
    Arguments:
     
       
    • client_id :: string
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: oauth
     
    Examples:
     
    POST /api/oauth_remove_client\n{\n  \"client_id\": \"aaaaa\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#oauth_revoke_token","title":"oauth_revoke_token","text":"
     changed in 22.05
     
    Revoke authorization for an OAuth token
     
    Arguments:
     
       
    • token :: string
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: oauth
     
    Examples:
     
    POST /api/oauth_revoke_token\n{\n  \"token\": \"aaaaa\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#outgoing_s2s_number","title":"outgoing_s2s_number","text":"
    Number of outgoing s2s connections on the node
     
    Arguments:
     
    Result:
     
       
    • s2s_outgoing :: integer
      •  
     
    Tags: statistics, s2s
     
    Examples:
     
    POST /api/outgoing_s2s_number\n{\n\n}\n\nHTTP/1.1 200 OK\n1\n
    "},{"location":"developer/ejabberd-api/admin-api/#print_sql_schema","title":"print_sql_schema \ud83d\udfe4","text":"
     added in 24.02
     
    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, sql
     
    Examples:
     
    POST /api/print_sql_schema\n{\n  \"db_type\": \"pgsql\",\n  \"db_version\": \"16.1\",\n  \"new_schema\": \"true\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#privacy_set","title":"privacy_set","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/privacy_set\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"xmlquery\": \"<query xmlns='jabber:iq:privacy'>...\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#private_get","title":"private_get","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/private_get\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"element\": \"storage\",\n  \"ns\": \"storage:rosternotes\"\n}\n\nHTTP/1.1 200 OK\n\"aaaaa\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#private_set","title":"private_set","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/private_set\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"element\": \"<storage xmlns='storage:rosternotes'/>\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#process_rosteritems","title":"process_rosteritems","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/process_rosteritems\n{\n  \"action\": \"aaaaa\",\n  \"subs\": \"bbbbb\",\n  \"asks\": \"ccccc\",\n  \"users\": \"ddddd\",\n  \"contacts\": \"eeeee\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"user\": \"aaaaa\",\n    \"contact\": \"bbbbb\"\n  },\n  {\n    \"user\": \"ccccc\",\n    \"contact\": \"ddddd\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#push_alltoall","title":"push_alltoall","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/push_alltoall\n{\n  \"host\": \"myserver.com\",\n  \"group\": \"Everybody\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#push_roster","title":"push_roster","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/push_roster\n{\n  \"file\": \"/home/ejabberd/roster.txt\",\n  \"user\": \"user1\",\n  \"host\": \"localhost\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#push_roster_all","title":"push_roster_all","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/push_roster_all\n{\n  \"file\": \"/home/ejabberd/roster.txt\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#register","title":"register","text":"
    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
     
    Examples:
     
    POST /api/register\n{\n  \"user\": \"bob\",\n  \"host\": \"example.com\",\n  \"password\": \"SomEPass44\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#registered_users","title":"registered_users","text":"
    List all registered users in HOST
     
    Arguments:
     
       
    • host :: string : Local vhost
      •  
     
    Result:
     
       
    • users :: [username::string] : List of registered accounts usernames
      •  
     
    Tags: accounts
     
    Examples:
     
    POST /api/registered_users\n{\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"user1\",\n  \"user2\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#registered_vhosts","title":"registered_vhosts","text":"
    List all registered vhosts in SERVER
     
    Arguments:
     
    Result:
     
       
    • vhosts :: [vhost::string] : List of available vhosts
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/registered_vhosts\n{\n\n}\n\nHTTP/1.1 200 OK\n[\n  \"example.com\",\n  \"anon.example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#reload_config","title":"reload_config","text":"
    Reload config file in memory
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: config
     
    Examples:
     
    POST /api/reload_config\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#remove_mam_for_user","title":"remove_mam_for_user","text":"
    Remove mam archive for user
     
    Arguments:
     
       
    • user :: string : Username
      •  
    • host :: string : Server
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: mam
     
    Module: mod_mam
     
    Examples:
     
    POST /api/remove_mam_for_user\n{\n  \"user\": \"bob\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n\"MAM archive removed\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#remove_mam_for_user_with_peer","title":"remove_mam_for_user_with_peer","text":"
    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
     
    Module: mod_mam
     
    Examples:
     
    POST /api/remove_mam_for_user_with_peer\n{\n  \"user\": \"bob\",\n  \"host\": \"example.com\",\n  \"with\": \"anne@example.com\"\n}\n\nHTTP/1.1 200 OK\n\"MAM archive removed\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#reopen_log","title":"reopen_log","text":"
    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.
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: logs
     
    Examples:
     
    POST /api/reopen_log\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#request_certificate","title":"request_certificate","text":"
    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
     
    Examples:
     
    POST /api/request_certificate\n{\n  \"domains\": \"example.com,domain.tld,conference.domain.tld\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#resource_num","title":"resource_num","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/resource_num\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\",\n  \"num\": 2\n}\n\nHTTP/1.1 200 OK\n\"Psi\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#restart","title":"restart","text":"
    Restart ejabberd gracefully
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/restart\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#restart_module","title":"restart_module","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/restart_module\n{\n  \"host\": \"myserver.com\",\n  \"module\": \"mod_admin_extra\"\n}\n\nHTTP/1.1 200 OK\n0\n
    "},{"location":"developer/ejabberd-api/admin-api/#restore","title":"restore","text":"
    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 API.
     
    Arguments:
     
       
    • file :: string : Full path to the backup file
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: mnesia
     
    Examples:
     
    POST /api/restore\n{\n  \"file\": \"/var/lib/ejabberd/database.backup\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#revoke_certificate","title":"revoke_certificate","text":"
    Revokes the selected ACME certificate
     
    Arguments:
     
       
    • file :: string : Filename of the certificate
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: acme
     
    Examples:
     
    POST /api/revoke_certificate\n{\n  \"file\": \"aaaaa\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#rooms_empty_destroy","title":"rooms_empty_destroy","text":"
    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:
     
       
    • rooms :: [room::string] : List of empty rooms that have been destroyed
      •  
     
    Tags: muc
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/rooms_empty_destroy\n{\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"room1@muc.example.com\",\n  \"room2@muc.example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#rooms_empty_list","title":"rooms_empty_list","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/rooms_empty_list\n{\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"room1@muc.example.com\",\n  \"room2@muc.example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#rooms_unused_destroy","title":"rooms_unused_destroy","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/rooms_unused_destroy\n{\n  \"service\": \"muc.example.com\",\n  \"days\": 31\n}\n\nHTTP/1.1 200 OK\n[\n  \"room1@muc.example.com\",\n  \"room2@muc.example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#rooms_unused_list","title":"rooms_unused_list","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/rooms_unused_list\n{\n  \"service\": \"muc.example.com\",\n  \"days\": 31\n}\n\nHTTP/1.1 200 OK\n[\n  \"room1@muc.example.com\",\n  \"room2@muc.example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#rotate_log","title":"rotate_log","text":"
    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
     
    Examples:
     
    POST /api/rotate_log\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#send_direct_invitation","title":"send_direct_invitation \ud83d\udfe4","text":"
     updated in 24.02
     
    Send a direct invitation to several destinations
     
    Since ejabberd 20.12, 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, v1
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/send_direct_invitation\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\",\n  \"password\": \"\",\n  \"reason\": \"Check this out!\",\n  \"users\": [\n    \"user2@localhost\",\n    \"user3@example.com\"\n  ]\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#send_message","title":"send_message","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/send_message\n{\n  \"type\": \"headline\",\n  \"from\": \"admin@localhost\",\n  \"to\": \"user1@localhost\",\n  \"subject\": \"Restart\",\n  \"body\": \"In 5 minutes\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#send_stanza","title":"send_stanza","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/send_stanza\n{\n  \"from\": \"admin@localhost\",\n  \"to\": \"user1@localhost\",\n  \"stanza\": \"<message><ext attr='value'/></message>\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#send_stanza_c2s","title":"send_stanza_c2s","text":"
    Send a stanza from an existing C2S session
     
    user@host/resource must be an existing C2S session. As an alternative, use 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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/send_stanza_c2s\n{\n  \"user\": \"admin\",\n  \"host\": \"myserver.com\",\n  \"resource\": \"bot\",\n  \"stanza\": \"<message to='user1@localhost'><ext attr='value'/></message>\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_last","title":"set_last","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/set_last\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"timestamp\": 1500045311,\n  \"status\": \"GoSleeping\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_loglevel","title":"set_loglevel","text":"
    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
     
    Examples:
     
    POST /api/set_loglevel\n{\n  \"loglevel\": \"debug\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_master","title":"set_master","text":"
    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
     
    Examples:
     
    POST /api/set_master\n{\n  \"nodename\": \"ejabberd@machine7\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_nickname","title":"set_nickname","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/set_nickname\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"nickname\": \"User 1\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_presence","title":"set_presence \ud83d\udfe4","text":"
     updated in 24.02
     
    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, v1
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/set_presence\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"resource\": \"tka1\",\n  \"type\": \"available\",\n  \"show\": \"away\",\n  \"status\": \"BB\",\n  \"priority\": 7\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_room_affiliation","title":"set_room_affiliation","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/set_room_affiliation\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\",\n  \"jid\": \"user2@example.com\",\n  \"affiliation\": \"member\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_vcard","title":"set_vcard","text":"
    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
     
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/set_vcard\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"name\": \"URL\",\n  \"content\": \"www.example.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_vcard2","title":"set_vcard2","text":"
    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
     
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/set_vcard2\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"name\": \"TEL\",\n  \"subname\": \"NUMBER\",\n  \"content\": \"123456\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_vcard2_multi","title":"set_vcard2_multi","text":"
    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
     
    Arguments:
     
       
    • user :: string
      •  
    • host :: string
      •  
    • name :: string
      •  
    • subname :: string
      •  
    • contents :: [value::string]
      •  
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: vcard
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/set_vcard2_multi\n{\n  \"user\": \"aaaaa\",\n  \"host\": \"bbbbb\",\n  \"name\": \"ccccc\",\n  \"subname\": \"ddddd\",\n  \"contents\": [\n    \"eeeee\",\n    \"fffff\"\n  ]\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#srg_create","title":"srg_create \ud83d\udfe4","text":"
     updated in 24.02
     
    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, v1
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/srg_create\n{\n  \"group\": \"group3\",\n  \"host\": \"myserver.com\",\n  \"label\": \"Group3\",\n  \"description\": \"Third group\",\n  \"display\": [\n    \"group1\",\n    \"group2\"\n  ]\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#srg_delete","title":"srg_delete","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/srg_delete\n{\n  \"group\": \"group3\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#srg_get_info","title":"srg_get_info","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/srg_get_info\n{\n  \"group\": \"group3\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"key\": \"name\",\n    \"value\": \"Group 3\"\n  },\n  {\n    \"key\": \"displayed_groups\",\n    \"value\": \"group1\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#srg_get_members","title":"srg_get_members","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/srg_get_members\n{\n  \"group\": \"group3\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"user1@localhost\",\n  \"user2@localhost\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#srg_list","title":"srg_list","text":"
    List the Shared Roster Groups in Host
     
    Arguments:
     
       
    • host :: string : Server name
      •  
     
    Result:
     
       
    • groups :: [id::string] : List of group identifiers
      •  
     
    Tags: shared_roster_group
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/srg_list\n{\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"group1\",\n  \"group2\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#srg_user_add","title":"srg_user_add","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/srg_user_add\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"group\": \"group3\",\n  \"grouphost\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#srg_user_del","title":"srg_user_del","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/srg_user_del\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"group\": \"group3\",\n  \"grouphost\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#stats","title":"stats","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/stats\n{\n  \"name\": \"registeredusers\"\n}\n\nHTTP/1.1 200 OK\n6\n
    "},{"location":"developer/ejabberd-api/admin-api/#stats_host","title":"stats_host","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/stats_host\n{\n  \"name\": \"registeredusers\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n6\n
    "},{"location":"developer/ejabberd-api/admin-api/#status","title":"status","text":"
    Get status of the ejabberd server
     
    Arguments:
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/status\n{\n\n}\n\nHTTP/1.1 200 OK\n\"The node ejabberd@localhost is started with status: startedejabberd X.X is running in that node\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#status_list","title":"status_list","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/status_list\n{\n  \"status\": \"dnd\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"user\": \"peter\",\n    \"host\": \"myserver.com\",\n    \"resource\": \"tka\",\n    \"priority\": 6,\n    \"status\": \"Busy\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#status_list_host","title":"status_list_host","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/status_list_host\n{\n  \"host\": \"myserver.com\",\n  \"status\": \"dnd\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"user\": \"peter\",\n    \"host\": \"myserver.com\",\n    \"resource\": \"tka\",\n    \"priority\": 6,\n    \"status\": \"Busy\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#status_num","title":"status_num","text":"
    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, statistics
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/status_num\n{\n  \"status\": \"dnd\"\n}\n\nHTTP/1.1 200 OK\n23\n
    "},{"location":"developer/ejabberd-api/admin-api/#status_num_host","title":"status_num_host","text":"
    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, statistics
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/status_num_host\n{\n  \"host\": \"myserver.com\",\n  \"status\": \"dnd\"\n}\n\nHTTP/1.1 200 OK\n23\n
    "},{"location":"developer/ejabberd-api/admin-api/#stop","title":"stop","text":"
    Stop ejabberd gracefully
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/stop\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#stop_kindly","title":"stop_kindly","text":"
    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
     
    Examples:
     
    POST /api/stop_kindly\n{\n  \"delay\": 60,\n  \"announcement\": \"Server will stop now.\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#stop_s2s_connections","title":"stop_s2s_connections","text":"
    Stop all s2s outgoing and incoming connections
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: s2s
     
    Examples:
     
    POST /api/stop_s2s_connections\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#subscribe_room","title":"subscribe_room \ud83d\udfe4","text":"
     updated in 24.02
     
    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, muc_sub, v1
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/subscribe_room\n{\n  \"user\": \"tom@localhost\",\n  \"nick\": \"Tom\",\n  \"room\": \"room1@conference.localhost\",\n  \"nodes\": [\n    \"urn:xmpp:mucsub:nodes:messages\",\n    \"urn:xmpp:mucsub:nodes:affiliations\"\n  ]\n}\n\nHTTP/1.1 200 OK\n[\n  \"urn:xmpp:mucsub:nodes:messages\",\n  \"urn:xmpp:mucsub:nodes:affiliations\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#subscribe_room_many","title":"subscribe_room_many \ud83d\udfe4","text":"
     updated in 24.02
     
    Subscribe several users to a MUC conference
     
    This command accepts up to 50 users at once (this is configurable with the 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, muc_sub, v1
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/subscribe_room_many\n{\n  \"users\": [\n    {\n      \"jid\": \"tom@localhost\",\n      \"nick\": \"Tom\"\n    },\n    {\n      \"jid\": \"jerry@localhost\",\n      \"nick\": \"Jerry\"\n    }\n  ],\n  \"room\": \"room1@conference.localhost\",\n  \"nodes\": [\n    \"urn:xmpp:mucsub:nodes:messages\",\n    \"urn:xmpp:mucsub:nodes:affiliations\"\n  ]\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#unban_ip","title":"unban_ip","text":"
    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
     
    Module: mod_fail2ban
     
    Examples:
     
    <<<<<<< HEAD\n    POST /api/unban_ip\n    {\n      \"address\": \"::FFFF:127.0.0.1/128\"\n    }\n\n    HTTP/1.1 200 OK\n    3\n=======\nPOST /api/unban_ip\n{\n  \"address\": \"::FFFF:127.0.0.1/128\"\n}\n\nHTTP/1.1 200 OK\n{\"unbanned\": 3}\n>>>>>>> a2c15f3 (Result of running \"make all\" with updated ejabberd)\n
    "},{"location":"developer/ejabberd-api/admin-api/#unregister","title":"unregister","text":"
    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
     
    Examples:
     
    POST /api/unregister\n{\n  \"user\": \"bob\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#unsubscribe_room","title":"unsubscribe_room","text":"
    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, muc_sub
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/unsubscribe_room\n{\n  \"user\": \"tom@localhost\",\n  \"room\": \"room1@conference.localhost\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#update","title":"update","text":"
    Update the given module
     
    To update all the possible modules, use all.
     
    Arguments:
     
       
    • module :: string
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/update\n{\n  \"module\": \"mod_vcard\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#update_list","title":"update_list","text":"
    List modified modules that can be updated
     
    Arguments:
     
    Result:
     
       
    • modules :: [module::string]
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/update_list\n{\n\n}\n\nHTTP/1.1 200 OK\n[\n  \"mod_configure\",\n  \"mod_vcard\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#user_resources","title":"user_resources","text":"
    List user's connected resources
     
    Arguments:
     
       
    • user :: string : User name
      •  
    • host :: string : Server name
      •  
     
    Result:
     
       
    • resources :: [resource::string]
      •  
     
    Tags: session
     
    Examples:
     
    POST /api/user_resources\n{\n  \"user\": \"user1\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"tka1\",\n  \"Gajim\",\n  \"mobile-app\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#user_sessions_info","title":"user_sessions_info","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/user_sessions_info\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"connection\": \"c2s\",\n    \"ip\": \"127.0.0.1\",\n    \"port\": 42656,\n    \"priority\": 8,\n    \"node\": \"ejabberd@localhost\",\n    \"uptime\": 231,\n    \"status\": \"dnd\",\n    \"resource\": \"tka\",\n    \"statustext\": \"\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-tags/","title":"API Tags","text":"
    This section enumerates the API tags of ejabberd 24.02.  If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the Archive. 
    "},{"location":"developer/ejabberd-api/admin-tags/#accounts","title":"accounts","text":"
       
    •  
      ban_account
       
      •  
    •  
      change_password
       
      •  
    •  
      check_account
       
      •  
    •  
      check_password
       
      •  
    •  
      check_password_hash
       
      •  
    •  
      delete_old_users
       
      •  
    •  
      delete_old_users_vhost
       
      •  
    •  
      register
       
      •  
    •  
      registered_users
       
      •  
    •  
      unban_ip
       
      •  
    •  
      unregister
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#acme","title":"acme","text":"
       
    •  
      list_certificates
       
      •  
    •  
      request_certificate
       
      •  
    •  
      revoke_certificate
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#cluster","title":"cluster","text":"
       
    •  
      join_cluster
       
      •  
    •  
      leave_cluster
       
      •  
    •  
      list_cluster
       
      •  
    •  
      set_master
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#config","title":"config","text":"
       
    •  
      convert_to_yaml
       
      •  
    •  
      dump_config
       
      •  
    •  
      reload_config
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#documentation","title":"documentation","text":"
       
    •  
      gen_html_doc_for_commands
       
      •  
    •  
      gen_markdown_doc_for_commands
       
      •  
    •  
      gen_markdown_doc_for_tags
       
      •  
    •  
      man
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#ejabberdctl","title":"ejabberdctl","text":"
       
    •  
      help
       
      •  
    •  
      mnesia_info_ctl
       
      •  
    •  
      print_sql_schema
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#erlang","title":"erlang","text":"
       
    •  
      compile
       
      •  
    •  
      get_cookie
       
      •  
    •  
      restart_module
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#last","title":"last","text":"
       
    •  
      get_last
       
      •  
    •  
      set_last
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#logs","title":"logs","text":"
       
    •  
      get_loglevel
       
      •  
    •  
      reopen_log
       
      •  
    •  
      rotate_log
       
      •  
    •  
      set_loglevel
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#mam","title":"mam","text":"
       
    •  
      remove_mam_for_user
       
      •  
    •  
      remove_mam_for_user_with_peer
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#mnesia","title":"mnesia","text":"
       
    •  
      backup
       
      •  
    •  
      delete_mnesia
       
      •  
    •  
      dump
       
      •  
    •  
      dump_table
       
      •  
    •  
      export2sql
       
      •  
    •  
      export_piefxis
       
      •  
    •  
      export_piefxis_host
       
      •  
    •  
      import_dir
       
      •  
    •  
      import_file
       
      •  
    •  
      import_piefxis
       
      •  
    •  
      import_prosody
       
      •  
    •  
      install_fallback
       
      •  
    •  
      load
       
      •  
    •  
      mnesia_change_nodename
       
      •  
    •  
      mnesia_info
       
      •  
    •  
      mnesia_info_ctl
       
      •  
    •  
      mnesia_table_info
       
      •  
    •  
      restore
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#modules","title":"modules","text":"
       
    •  
      module_check
       
      •  
    •  
      module_install
       
      •  
    •  
      module_uninstall
       
      •  
    •  
      module_upgrade
       
      •  
    •  
      modules_available
       
      •  
    •  
      modules_installed
       
      •  
    •  
      modules_update_specs
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#muc","title":"muc","text":"
       
    •  
      create_rooms_file
       
      •  
    •  
      destroy_rooms_file
       
      •  
    •  
      get_user_rooms
       
      •  
    •  
      get_user_subscriptions
       
      •  
    •  
      muc_online_rooms
       
      •  
    •  
      muc_online_rooms_by_regex
       
      •  
    •  
      muc_register_nick
       
      •  
    •  
      muc_unregister_nick
       
      •  
    •  
      rooms_empty_destroy
       
      •  
    •  
      rooms_empty_list
       
      •  
    •  
      rooms_unused_destroy
       
      •  
    •  
      rooms_unused_list
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#muc_room","title":"muc_room","text":"
       
    •  
      change_room_option
       
      •  
    •  
      create_room
       
      •  
    •  
      create_room_with_opts
       
      •  
    •  
      destroy_room
       
      •  
    •  
      get_room_affiliation
       
      •  
    •  
      get_room_affiliations
       
      •  
    •  
      get_room_history
       
      •  
    •  
      get_room_occupants
       
      •  
    •  
      get_room_occupants_number
       
      •  
    •  
      get_room_options
       
      •  
    •  
      get_subscribers
       
      •  
    •  
      send_direct_invitation
       
      •  
    •  
      set_room_affiliation
       
      •  
    •  
      subscribe_room
       
      •  
    •  
      subscribe_room_many
       
      •  
    •  
      unsubscribe_room
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#muc_sub","title":"muc_sub","text":"
       
    •  
      create_room_with_opts
       
      •  
    •  
      get_subscribers
       
      •  
    •  
      get_user_subscriptions
       
      •  
    •  
      subscribe_room
       
      •  
    •  
      subscribe_room_many
       
      •  
    •  
      unsubscribe_room
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#oauth","title":"oauth","text":"
       
    •  
      oauth_add_client_implicit
       
      •  
    •  
      oauth_add_client_password
       
      •  
    •  
      oauth_issue_token
       
      •  
    •  
      oauth_list_tokens
       
      •  
    •  
      oauth_remove_client
       
      •  
    •  
      oauth_revoke_token
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#offline","title":"offline","text":"
       
    • get_offline_count
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#private","title":"private","text":"
       
    •  
      bookmarks_to_pep
       
      •  
    •  
      private_get
       
      •  
    •  
      private_set
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#purge","title":"purge","text":"
       
    •  
      abort_delete_old_mam_messages
       
      •  
    •  
      abort_delete_old_messages
       
      •  
    •  
      delete_expired_messages
       
      •  
    •  
      delete_expired_pubsub_items
       
      •  
    •  
      delete_old_mam_messages
       
      •  
    •  
      delete_old_mam_messages_batch
       
      •  
    •  
      delete_old_mam_messages_status
       
      •  
    •  
      delete_old_messages
       
      •  
    •  
      delete_old_messages_batch
       
      •  
    •  
      delete_old_messages_status
       
      •  
    •  
      delete_old_pubsub_items
       
      •  
    •  
      delete_old_push_sessions
       
      •  
    •  
      delete_old_users
       
      •  
    •  
      delete_old_users_vhost
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#roster","title":"roster","text":"
       
    •  
      add_rosteritem
       
      •  
    •  
      delete_rosteritem
       
      •  
    •  
      get_roster
       
      •  
    •  
      process_rosteritems
       
      •  
    •  
      push_alltoall
       
      •  
    •  
      push_roster
       
      •  
    •  
      push_roster_all
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#s2s","title":"s2s","text":"
       
    •  
      incoming_s2s_number
       
      •  
    •  
      outgoing_s2s_number
       
      •  
    •  
      stop_s2s_connections
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#server","title":"server","text":"
       
    •  
      clear_cache
       
      •  
    •  
      gc
       
      •  
    •  
      halt
       
      •  
    •  
      registered_vhosts
       
      •  
    •  
      restart
       
      •  
    •  
      status
       
      •  
    •  
      stop
       
      •  
    •  
      stop_kindly
       
      •  
    •  
      update
       
      •  
    •  
      update_list
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#session","title":"session","text":"
       
    •  
      connected_users
       
      •  
    •  
      connected_users_info
       
      •  
    •  
      connected_users_number
       
      •  
    •  
      connected_users_vhost
       
      •  
    •  
      get_presence
       
      •  
    •  
      kick_session
       
      •  
    •  
      kick_user
       
      •  
    •  
      num_resources
       
      •  
    •  
      resource_num
       
      •  
    •  
      set_presence
       
      •  
    •  
      status_list
       
      •  
    •  
      status_list_host
       
      •  
    •  
      status_num
       
      •  
    •  
      status_num_host
       
      •  
    •  
      user_resources
       
      •  
    •  
      user_sessions_info
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#shared_roster_group","title":"shared_roster_group","text":"
       
    •  
      srg_create
       
      •  
    •  
      srg_delete
       
      •  
    •  
      srg_get_info
       
      •  
    •  
      srg_get_members
       
      •  
    •  
      srg_list
       
      •  
    •  
      srg_user_add
       
      •  
    •  
      srg_user_del
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#sql","title":"sql","text":"
       
    •  
      convert_to_scram
       
      •  
    •  
      import_prosody
       
      •  
    •  
      print_sql_schema
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#stanza","title":"stanza","text":"
       
    •  
      privacy_set
       
      •  
    •  
      send_message
       
      •  
    •  
      send_stanza
       
      •  
    •  
      send_stanza_c2s
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#statistics","title":"statistics","text":"
       
    •  
      connected_users_number
       
      •  
    •  
      incoming_s2s_number
       
      •  
    •  
      outgoing_s2s_number
       
      •  
    •  
      stats
       
      •  
    •  
      stats_host
       
      •  
    •  
      status_num
       
      •  
    •  
      status_num_host
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#v1","title":"v1","text":"
       
    •  
      add_rosteritem
       
      •  
    •  
      oauth_issue_token
       
      •  
    •  
      send_direct_invitation
       
      •  
    •  
      set_presence
       
      •  
    •  
      srg_create
       
      •  
    •  
      subscribe_room
       
      •  
    •  
      subscribe_room_many
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#vcard","title":"vcard","text":"
       
    •  
      get_vcard
       
      •  
    •  
      get_vcard2
       
      •  
    •  
      get_vcard2_multi
       
      •  
    •  
      set_nickname
       
      •  
    •  
      set_vcard
       
      •  
    •  
      set_vcard2
       
      •  
    •  
      set_vcard2_multi
       
      •  
    "},{"location":"developer/ejabberd-api/api_versioning/","title":"API Versioning","text":"
     added in 24.02
    "},{"location":"developer/ejabberd-api/api_versioning/#introduction","title":"Introduction","text":"
    It is possible to support different versions of the ejabberd API. Versioning is used to ensure compatibility with third party backend that uses the API.
     
    When a command is modified (either its declaration or its definition, breaking compatibility), those modifications can be done in a new version of the API, keeping the old command still available in the previous API version. An API version is an integer (sub-versions are not supported).
     
    If the API client does not specify the API version, ejabberd uses by default the most recent available API version.
     
    Alternatively, the API client can specify an API version, and ejabberd will use that one to process the query, or the most recent to the one specified. For example: if a command is defined in API versions 0, 2, 3, 7, and 9, and a client declares to support up to API version 5, then ejabberd uses the command API version 3, which is the most recent available for the one supported by the client.
     
    API versioning is supported by mod_http_api ReST interface and ejabberdctl command line script. However ejabberd_xmlrpc doesn't support API versioning, and consequently it can only use the latest API version.
    "},{"location":"developer/ejabberd-api/api_versioning/#command-definition","title":"Command Definition","text":"
    If a command is modified, a new #ejabberd_commands record should be defined with a version attribute set to the API version (an integer) where this command version is available. There is no need to add a new #ejabberd_commands record for commands that are not modified in a given API version, immediate inferior version is used.
     
    By default, all commands are in API version 0, and latest API is used if no version is specified when calling ejabberd_commands directly without specifying a version.
    "},{"location":"developer/ejabberd-api/api_versioning/#api-documentation","title":"API Documentation","text":"
    The command documentation indicates the api version as a tag: v1, v2... Commands not versioned do not have such a tag: they are version 0.
     
    The ejabberd Docs: API Tags page lists the most recent API versions, and what commands are included.
     
    To know exactly what is the format expected for a command in a specific API version, use ejabberdctl specifying what API version you want to consult and the command name, for example:
     
    ejabberdctl --version 0 help get_roster\n
    "},{"location":"developer/ejabberd-api/api_versioning/#mod_http_api","title":"mod_http_api","text":"
    The server administrator can set the default version when configuring request_handlers, by including a vN in its path, where N is an integer corresponding to the version.
     
    In any case, the API client can specify a version when sending the request, by appending vN to the request path.
     
    For example, when configured like:
     
    listen:\n  -\n    request_handlers:\n      /api/v0: mod_http_api\n      /v1/api: mod_http_api\n      /api: mod_http_api\n
     
    See what API version will be used depending on the URL:
     
       
    • api/command use the latest available version
      •  
    • api/command/v0 use version 0
      •  
    • api/command/v1 use version 1
      •  
    • v1/api/command use version 1
      •  
    • v1/api/command/v0 use version 0
      •  
    • api/v0/command use version 0
      •  
    • api/v0/command/v1 use version 1
      •  
     
    In this example, the server administrator configured the default API version to 0:
     
    listen:\n  -\n    request_handlers:\n      /api/v0: mod_http_api\n
     
    The client doesn't specify any version, so 0 is used:
     
    $ curl -k -X POST -H \"Content-type: application/json\" \\\n  -d '{}' \"http://localhost:5280/api/v0/get_loglevel\"\n{\"levelatom\":\"info\"}\n
     
    This time the client requests the API version 2:
     
    $ curl -k -X POST -H \"Content-type: application/json\" \\\n  -d '{}' \"http://localhost:5280/api/v0/get_loglevel/v2\"\n\"info\"\n
    "},{"location":"developer/ejabberd-api/api_versioning/#ejabberdctl","title":"ejabberdctl","text":"
    By default the latest version of a given command is used. To use a command in a specific API version, use the --version switch, followed by the version number, and then the command name.
     
    Example:
     
    ejabberdctl --version 2 set_loglevel 4\n
     
    Use the most recent API version:
     
    $ ejabberdctl get_roster admin localhost\njan@localhost jan   none    subscribe       group1,group2\ntom@localhost tom   none    subscribe       group3\n
     
    Use version 0:
     
    $ ejabberdctl --version 0 get_roster admin localhost\njan@localhost jan   none    subscribe       group1;group2\ntom@localhost tom   none    subscribe       group3\n
    "},{"location":"developer/ejabberd-api/commands/","title":"ejabberd commands","text":"
    By defining command using api available through ejabberd_commands module, it's possible to add operations that would be available to users through ejabberdctl command, XML-RPC socket or JSON based REST service.
     
    Each command needs to provide information about required arguments and produced result by filling #ejabberd_commands record and registering it in dispatcher by calling ejabberd_commands:register_commands([ListOfEjabberdCommandsRecords]).
    "},{"location":"developer/ejabberd-api/commands/#structure-of-ejabberd_commands-record","title":"Structure of #ejabberd_commands record","text":""},{"location":"developer/ejabberd-api/commands/#writing-ejabberd-commands-supporting-oauth","title":"Writing ejabberd commands supporting OAuth","text":"
    If you have existing commands that you want to make OAuth compliant, you can make them OAuth compliant very easily.
     
    An ejabberd command is defined by an #ejabberd_commands Erlang record. The record requires a few fields:
     
       
    • name: This is an atom defining the name of the command.
      •  
    • tags: This is a list of atoms used to group the command into consistent group of commands. This is mostly used to group commands in ejabberdctl command-line tool. Existing categories are:
      •  
    • session: For commands related to user XMPP sessions.
      •  
    •  
      roster: Commands related to contact list management.   
       
      •  
    •  
      desc: Description of the command for online help.
       
      •  
    • module and function: Module and function to call to execute the command logic.
      •  
    • args: Argument of the command. An argument is defined by a tuple of atoms of the form {argument_name, data_type}. data_type can be one of:
      •  
    •  
      binary   
       
      •  
    •  
      result: defines what the command will return.
       
      •  
    • policy: Is an optional field, containing an atom that define restriction policy of the command. It can be on of: open, admin, user, restricted. Default is restricted, meaning the command can be used from ejabberdctl command-line tool.
      •  
    • version: API version number where this command is available (see API versioning documentation for details).
      •  
     
    To define a command that can be used by server user over ReST or XML-RPC API, you just have to define it with policy user. Then, you have to make sure that the function will take a user binary and a host binary as first parameter of the function. They do not have to be put in the args list in #ejabberd_commands record as the `user policy implicitly expect them.
     
    That's all you need to have commands that can be used in a variety of ways.
     
    Here is a example way to register commands when
     
    start(_Host, _Opts) ->\n    ejabberd_commands:register_commands(commands()).\n\nstop(_Host) ->\n    ejabberd_commands:unregister_commands(commands()).\n\n%%%\n%%% Register commands\n%%%\n\ncommands() ->\n    [#ejabberd_commands{name = user_get_roster,\n                        tags = [roster],\n                        desc = \"Retrieve the roster\",\n                        longdesc =\n                            \"Returns a list of the contacts in a \"\n                            \"user roster.\\n\\nAlso returns the state \"\n                            \"of the contact subscription. Subscription \"\n                            \"can be either  \\\"none\\\", \\\"from\\\", \\\"to\\\", \"\n                            \"\\\"both\\\". Pending can be \\\"in\\\", \\\"out\\\" \"\n                            \"or \\\"none\\\".\",\n                        module = ?MODULE, function = get_roster,\n                        args = [],\n                        policy = user,\n                        result =\n                            {contacts,\n                             {list,\n                              {contact,\n                               {tuple,\n                                [{jid, string},\n                                 {groups, {list, {group, string}}},\n                                 {nick, string}, {subscription, string},\n                                 {pending, string}]}}}}}\n        ].\n
    "},{"location":"developer/ejabberd-api/oauth/","title":"OAuth Support","text":"
     added in 15.09
    "},{"location":"developer/ejabberd-api/oauth/#introduction","title":"Introduction","text":"
    ejabberd includes a full support OAuth 2.0 deep inside the ejabberd stack.
     
    This OAuth integration makes ejabberd:
     
       
    •  
      an ideal project to develop XMPP applications with Web in mind, as it exposes ejabberd features as ReST or XML-RPC HTTP based API endpoints. OAuth makes ejabberd the ideal XMPP server to integrate in a  larger Web / HTTP ecosystem.
       
      •  
    •  
      a more secure tool that can leverage the use of oAuth token to authenticate, hiding your real password from the client itself. As your password is never shared with client directly with our X-OAUTH2 authentication mechanism, user have less risks of having their primary password leaked.
       
      •  
    •  
      a tool that can be used at the core of larger platforms as oauth token can be used by users and admins to delegate rights to subcomponents / subservices.
       
      •  
    •  
      a tool that is friendly to other online services as users can delegate rights to others SaaS platform they are using. This will be possible to let services access your message archive, show your offline message count or with future commands send message to users and chatrooms on your behalf. This is done in a granular way, with a scope limited to a specific function. And the delegation rights for a specific app / third party can always be revoked at any time as this is usually the case with OAuth services.
       
      •  
     
    You can read more on OAuth from OAuth website.
    "},{"location":"developer/ejabberd-api/oauth/#configuration","title":"Configuration","text":""},{"location":"developer/ejabberd-api/oauth/#authentication-method","title":"Authentication method","text":"
    An X-OAUTH2 SASL authentication mechanism is enabled by default in ejabberd.
     
    However, if the ejabberd_oauth HTTP request handler is not enabled, there is no way to generate token from outside ejabberd. In this case, you may want to disable X-OAUTH2 with the disable_sasl_mechanisms top-level option in ejabberd.yml file, either at global or at virtual host level:
     
    disable_sasl_mechanisms: [\"X-OAUTH2\"]\n
    "},{"location":"developer/ejabberd-api/oauth/#ejabberd-listeners","title":"ejabberd listeners","text":"
    To enable OAuth support in ejabberd, you need to edit your ejabberd.yml file to add the following snippets.
     
    You first need to expose more HTTP endpoint in ejabberd_http modules:
     
       
    • ejabberd_oauth is the request handler that will allow generating token for third-parties (clients, services). It is usually exposed on \"/oauth\" endpoint. This handler is mandatory to support OAuth.
      •  
    • mod_http_api request handler enables ReST API endpoint to perform delegated actions on ejabberd using an HTTP JSON API. This handler is usually exposed on \"/api\" endpoint. It is optional.
      •  
    • ejabberd_xmlrpc listener can be set on a separate port to query commands using the XML-RPC protocol.
      •  
     
    Here is a example of the listen section in ejabberd configuration file, focusing on HTTP handlers:
     
    listen:\n  -\n    port: 4560\n    module: ejabberd_http\n    request_handlers:\n      ## Handle ejabberd commands using XML-RPC\n      /: ejabberd_xmlrpc\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /websocket: ejabberd_http_ws\n      /log: mod_log_http\n      # OAuth support:\n      /oauth: ejabberd_oauth\n      # ReST API:\n      /api: mod_http_api\n
    "},{"location":"developer/ejabberd-api/oauth/#module-configuration","title":"Module configuration","text":"
    Some commands are implemented by ejabberd internals and are always available, but other commands are implemented by optional modules. If the documentation of a command you want to use mentions a module, make sure you have enabled that module in ejabberd.yml. For example the add_rosteritem command is implemented in the mod_admin_extra module.
     
    By the way, ejabberd implements several commands to manage OAuth, check the oauth tag documentation.
    "},{"location":"developer/ejabberd-api/oauth/#oauth-specific-parameters","title":"OAuth specific parameters","text":"
    OAuth is configured using those top-level options:
     
       
    • oauth_access
      •  
    • oauth_cache_life_time
      •  
    • oauth_cache_missed
      •  
    • oauth_cache_rest_failure_life_time
      •  
    • oauth_cache_size
      •  
    • oauth_client_id_check
      •  
    • oauth_db_type
      •  
    • oauth_expire
      •  
    • oauth_use_cache
      •  
     
    A basic setup is to allow all accounts to create tokens, and tokens expire after an hour:
     
    oauth_access: all\noauth_expire: 3600\n
    "},{"location":"developer/ejabberd-api/oauth/#authorization_token","title":"authorization_token","text":"
    An easy way to generate a token is using the oauth_issue_token command with the ejabberdctl shell script:
     
    ejabberdctl oauth_issue_token user1@localhost 3600 ejabberd:admin\n\nr9KFladBTYJS71OggKCifo0GJwyT7oY4 [<<\"ejabberd:admin\">>]  3600 seconds\n
     
    The users can generate tokens themselves by visiting /oauth/authorization_token in a webview in your application or in a web browser. For example, URL can be:
     
    `http://example.net:5280/oauth/authorization_token?response_type=token&client_id=Client1&redirect_uri=http://client.uri&scope=get_roster+sasl_auth`\n
     
    Note: To use the get_roster scope, enable mod_admin_extra, because the get_roster  API is defined in that module. Otherwise, the command is unknown and you will get an invalid_scope error. See Module configuration for details.
     
    Parameters are described in OAuth 2.0 specification:
     
       
    • response_type: Should be token.
      •  
    • client_id: This is the name of the application that is asking for Oauth token.
      •  
    • scope: This is the scope of the rights being delegated to the application. It will limit the feature the application can perform and thus ensure the user is not giving away more right than expected by the application. As a developer, you should always limit the scope to what you actually need.
      •  
    • redirect_uri: After token is generated, token is passed to the application using the redirect URI. It can obviously work for web applications, but also for mobile applications, using a redirect URI that the mobile application have registered: Proper code for handling the token will thus be executed directly in the mobile application.
      •  
    • state: State parameter is optional and use by client to pass information that will be passed as well as state parameter in the redirect URI.
      •  
     
    Directing the user to this URL will present an authentication form summarizing what is the app requiring the token and the scope / rights that are going to be granted.
     
    The user can then put their login and password to confirm that they accept granting delegating rights and confirm the token generation. If the provided credentials are valid, the browser or webview will redirect the user to the redirect_uri, to actually let ejabberd pass the token to the app that requested it. It can be either a Web app or `a mobile / desktop application.
    "},{"location":"developer/ejabberd-api/oauth/#redirect_uri","title":"redirect_uri","text":"
    The redirect_uri originally passed in the authorization_token request will be called on successful validation of user credentials, with added parameters.
     
    For example, redirect URI called by ejabberd can be:
     
    http://client.uri/?access_token=RHIT8DoudzOctdzBhYL9bYvXz28xQ4Oj&token_type=bearer&expires_in=3600&scope=user_get_roster+sasl_auth&state=
     
    Parameters are described in OAuth specification:
     
       
    • access_token: This is the actual token that the client application can use for OAuth authentication.
      •  
    • token_type: ejabberd supports bearer token type.
      •  
    • expires_in: This is the validity duration of the token, in seconds. When the token expires, a new authorization token will need to be generated an approved by the user.
      •  
     
       
    • scope: Confirms the granted scope to the requesting application. Several scopes can be passed, separated by '+'.
      •  
    • state: If a state parameter was passed by requesting application in authorization_token URL, it will be passed back to the   application as a parameter of the redirect_uri to help with the client workflow.
      •  
    "},{"location":"developer/ejabberd-api/oauth/#scopes","title":"Scopes","text":"
       
    • sasl_auth: This scope is use to generate a token that can login over XMPP using SASL X-OAUTH2 mechanism.
      •  
    • ejabberd:admin
      •  
    • ejabberd:user
      •  
    • Scopes for each existing API command.   For example, there is a scope registered_users  because there is a command called registered_users.   Ensure you enable the module that defines the command that you want to use, see Module configuration for details.
      •  
    "},{"location":"developer/ejabberd-api/oauth/#x-oauth2-authentication","title":"X-OAuth2 Authentication","text":"
    You can connect to ejabberd using an X-OAUTH2 token that is valid in the scope sasl_auth. You can use an OAuth token as generated in the previous steps instead of a password when connecting to ejabberd servers support OAuth SASL mechanism.
     
    When enabled, X-OAUTH2 SASL mechanism is advertised in server stream features:
     
    <stream:features>\n  <c xmlns=\"http://jabber.org/protocol/caps\" node=\"http://www.process-one.net/en/ejabberd/\" ver=\"nM19M+JK0ZBMXK7iJAvKnmDuQus=\" hash=\"sha-1\"/>\n  <register xmlns=\"http://jabber.org/features/iq-register\"/>\n  <mechanisms xmlns=\"urn:ietf:params:xml:ns:xmpp-sasl\">\n    <mechanism>PLAIN</mechanism>\n    <mechanism>DIGEST-MD5</mechanism>\n    <mechanism>X-OAUTH2</mechanism>\n    <mechanism>SCRAM-SHA-1</mechanism>\n  </mechanisms>\n</stream:features>\n
     
    Authentication with X-OAUTH2 is done by modifying the SASL auth element as follow:
     
    <auth mechanism='X-OAUTH2'\n      xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>\n  base64(\"\\0\" + user_name + \"\\0\" + oauth_token)\n</auth>\n
     
    The content in the auth element should be the base64 encoding of a string containing a null byte, followed by the user name, another null byte and the string representation of the user\u2019s OAuth token. This is similar to how to authenticate with a password using the PLAIN mechanism, except the token is added instead of the user\u2019s password.
     
    The response is standard for SASL XMPP authentication. For example, on success, server will reply with:
     
    <success xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/>\n
    "},{"location":"developer/ejabberd-api/oauth/#rest-example","title":"ReST Example","text":"
    It is possible to use OAuth to authenticate a client when attempting to perform a ReST or XML-RPC query.
    "},{"location":"developer/ejabberd-api/oauth/#configuring","title":"Configuring","text":"
    First of all check all the required options are setup (listener, OAuth, API and ACL):
     
    listen:\n  -\n    port: 5280\n    ip: \"::\"\n    module: ejabberd_http\n    request_handlers:\n      /api: mod_http_api\n      /oauth: ejabberd_oauth\n\noauth_expire: 3600\noauth_access: all\n\napi_permissions:\n  \"admin access\":\n    who:\n      oauth:\n        scope: \"ejabberd:admin\"\n        access:\n          allow:\n            - acl: loopback\n            - acl: admin\n    what:\n      - \"*\"\n      - \"!stop\"\n      - \"!start\"\n\nacl:\n  admin:\n    user:\n      - user1@localhost\n\nmodules:\n  mod_admin_extra: {}\n  mod_roster: {}\n
     
    Register the account with admin rights, and another one used for the queries:
     
    ejabberdctl register user1 localhost asd\nejabberdctl register user2 localhost asd\nejabberdctl add_rosteritem user2 localhost tom localhost Tom \"\" none\n
    "},{"location":"developer/ejabberd-api/oauth/#obtain-bearer-token","title":"Obtain bearer token","text":"
    Obtain a bearer token as explained in authorization_token, either using ejabberdctl:
     
    ejabberdctl oauth_issue_token user1@localhost 3600 ejabberd:admin\nr9KFladBTYJS71OggKCifo0GJwyT7oY4        [<<\"ejabberd:admin\">>]  3600 seconds\n
     
    Or using a web browser:
     
       
    • visit the URL http://localhost:5280/oauth/authorization_token?response_type=token&scope=ejabberd:admin
      •  
    • User (jid): user1@localhost
      •  
    • Password: asd
      •  
    • and click Accept
      •  
     
    This redirects to a new URL which contains the access_token, for example:
     
    http://localhost:5280/oauth/authorization_token?access_token=r9KFladBTYJS71OggKCifo0GJwyT7oY4&token_type=bearer&expires_in=31536000&scope=ejabberd:admin&state=
    "},{"location":"developer/ejabberd-api/oauth/#passing-credentials","title":"Passing credentials","text":"
    When using ReST, the client authorization is done by using a bearer token (no need to pass the user and host parameters). For that, include an Authorization HTTP header like:
     
    Authorization: Bearer r9KFladBTYJS71OggKCifo0GJwyT7oY4\n
    "},{"location":"developer/ejabberd-api/oauth/#query-examples","title":"Query examples","text":"
    Let's use curl to get the list of registered_users with a HTTP GET query:
     
    curl -X GET \\\n     -H \"Authorization: Bearer r9KFladBTYJS71OggKCifo0GJwyT7oY4\" \\\n     http://localhost:5280/api/registered_users?host=localhost\n\n[\"user1\",\"user2\"]\n
     
    Or provide the bearer token with this option:
     
    curl -X GET \\\n     --oauth2-bearer r9KFladBTYJS71OggKCifo0GJwyT7oY4 \\\n     http://localhost:5280/api/registered_users?host=localhost\n
     
    With a command like get_roster you can get your own roster, or act as an admin to get any user roster.
     
    The HTTP endpoint does not take any parameter, so we can just do an HTTP POST with empty JSON structure list (see -d option).
     
    In this example let's use a HTTP POST query:
     
    curl -v -X POST \\\n     --oauth2-bearer r9KFladBTYJS71OggKCifo0GJwyT7oY4 \\\n     http://localhost:5280/api/get_roster \\\n     -d '{\"user\": \"user2\", \"server\": \"localhost\"}'\n\n[{\"jid\":\"tom@localhost\",\"nick\":\"Tom\",\"subscription\":\"none\",\"ask\":\"none\",\"group\":\"\"}]\n
    "},{"location":"developer/ejabberd-api/oauth/#xml-rpc-example","title":"XML-RPC Example","text":"
    For XML-RPC, credentials must be passed as XML-RPC parameters, including token but also user and host parameters. This is for legacy reason, but will likely change in a future version, making user and host implicit, thanks to bearer token.
     
    Here is an (Erlang) XML-RPC example on how to get your own roster:
     
    xmlrpc:call({127, 0, 0, 1}, 4560, \"/\",\n  {call, get_roster, [\n    {struct, [{user, \"peter\"},\n              {server, \"example.com\"},\n              {token, \"0n6LaEjyAOxVDyZChzZfoKMYxc8uUk6L\"}]}]},\n  false, 60000, \"Host: localhost\\r\\n\", []).\n
     
    This will lead to sending this XML-RPC payload to server:
     
    <?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<methodCall>\n  <methodName>get_roster</methodName>\n  <params>\n    <param>\n      <value>\n        <struct>\n          <member>\n            <name>server</name>\n            <value>\n              <string>example.com</string>\n            </value>\n          </member>\n          <member>\n            <name>user</name>\n            <value>\n              <string>peter</string>\n            </value>\n          </member>\n          <member>\n            <name>token</name>\n            <value>\n              <string>0n6LaEjyAOxVDyZChzZfoKMYxc8uUk6L</string>\n            </value>\n          </member>\n        </struct>\n      </value>\n    </param>\n  </params>\n</methodCall>\n
     
    To get roster of other user using admin authorization, this erlang XML-RPC code can be used:
     
    xmlrpc:call({127, 0, 0, 1}, 4560, \"/\",\n  {call, get_roster, [\n    {struct, [{user, \"admin\"},\n              {server, \"example.com\"},\n              {token, \"0n6LaEjyAOxVDyZChzZfoKMYxc8uUk6L\"}\n              {admin, true}]},\n    {struct, [{user, \"peter\"},\n              {server, \"example.com\"}]}]},\n  false, 60000, \"Host: localhost\\r\\n\", []).\n
     
    This is an equivalent Python 2 script:
     
    import xmlrpclib\n\nserver_url = 'http://127.0.0.1:4560'\nserver = xmlrpclib.ServerProxy(server_url)\n\nLOGIN = {'user': 'admin',\n         'server': 'example.com',\n         'token': '0n6LaEjyAOxVDyZChzZfoKMYxc8uUk6L',\n         'admin': True}\n\ndef calling(command, data):\n    fn = getattr(server, command)\n    return fn(LOGIN, data)\n\nprint calling('get_roster', {'user':'peter', 'server':'example.com'})\n
     
    And this is an equivalent Python 3 script:
     
    from xmlrpc import client\n\nserver_url = 'http://127.0.0.1:4560'\nserver = client.ServerProxy(server_url)\n\nLOGIN = {'user': 'admin',\n         'server': 'example.com',\n         'token': '0n6LaEjyAOxVDyZChzZfoKMYxc8uUk6L',\n         'admin': True}\n\ndef calling(command, data):\n    fn = getattr(server, command)\n    return fn(LOGIN, data)\n\nresult = calling('get_roster', {'user':'peter', 'server':'example.com'})\nprint(result)\n
     
    Those calls would send this XML to server:
     
    <?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<methodCall>\n  <methodName>get_roster</methodName>\n  <params>\n    <param>\n      <value>\n        <struct>\n          <member>\n            <name>admin</name>\n            <value>\n              <boolean>1</boolean>\n            </value>\n          </member>\n          <member>\n            <name>server</name>\n            <value>\n              <string>example.com</string>\n            </value>\n          </member>\n          <member>\n            <name>user</name>\n            <value>\n              <string>admin</string>\n            </value>\n          </member>\n          <member>\n            <name>token</name>\n            <value>\n              <string>0n6LaEjyAOxVDyZChzZfoKMYxc8uUk6L</string>\n            </value>\n          </member>\n        </struct>\n      </value>\n    </param>\n    <param>\n      <value>\n        <struct>\n          <member>\n            <name>user</name>\n            <value>\n              <string>peter</string>\n            </value>\n          </member>\n          <member>\n            <name>server</name>\n            <value>\n              <string>example.com</string>\n            </value>\n          </member>\n        </struct>\n      </value>\n    </param>\n  </params>\n</methodCall>\n
    "},{"location":"developer/ejabberd-api/permissions/","title":"API Permissions","text":"
     added in 16.12
     
    This page describes ejabberd's flexible permission mechanism.
     
    Access to all available endpoints are configured using api_permissions option.
     
    It allows to define multiple groups, each one with separate list of filters on who and what are allowed by rules specified inside it.
     
    Basic rule looks like this:
     
    api_permissions:\n  \"admin access\":\n    who:\n      - admin\n    what:\n      - \"*\"\n      - \"!stop\"\n    from:\n      - ejabberd_ctl\n      - mod_http_api\n
     
    It tells that group named Admin access allows all users that are accepted by ACL rule admin to execute all commands except command stop, using the command-line tool ejabberdctl or sending a ReST query handled by mod_http_api.
     
    Each group has associated name (that is just used in log messages), who section for rules that authentication details must match, what section for specifying list of command, and from with list of modules that API was delivered to.
    "},{"location":"developer/ejabberd-api/permissions/#rules-inside-who-section","title":"Rules inside who section","text":"
    There are 3 types of rules that can be placed in who section:
     
       
    •  
      acl: Name | ACLDefinition   or the short version: Name | ACLRule   This accepts a command when the authentication provided matches   rules of Name Access Control List   (or inline rules from ACLDefinition or ACLRule)
       
      •  
    •  
      access: Name | AccessDefinition   This allows execution if   the Access Rule Name or inline AccessDefinition   returns allowed for command's authentication details
       
      •  
    •  
      oauth: ListOfRules   This rule (and only this) will match for commands that were executed   with OAuth authentication.   Inside ListOfRules you can use any rule   described above (acl: Name, AClName, access: Name) and   additionally you must include scope: ListOfScopeNames with OAuth   scope names that must match scope used to generate OAuth token used   in command authentication.
       
      •  
     
    who allows the command to be executed if at least one rule matches.
     
    If you want to require several rules to match at this same time, use access (see examples below).
     
    Missing who rule is equivalent to who: none which will stop group from accepting any command.
    "},{"location":"developer/ejabberd-api/permissions/#examples-of-who-rules","title":"Examples of who rules","text":"
    This accepts user admin@server.com or commands originating from localhost:
     
    who:\n  user: admin@server.com\n  ip: 127.0.0.1/8\n
     
    This only allows execution of a command if it's invoked by user admin@server.com and comes from localhost address. If one of those restrictions isn't satisfied, execution will fail:
     
    who:\n  access:\n    allow:\n      user: admin@server.com\n      ip: 127.0.0.1/8\n
     
    Those rules match for users from muc_admin ACL both using regular authentication and OAuth:
     
    who:\n  access:\n    allow:\n      acl: muc_admin\n  oauth:\n    scope: \"ejabberd:admin\"\n    access:\n      allow:\n        acl: muc_admin\n
    "},{"location":"developer/ejabberd-api/permissions/#rules-in-what-section","title":"Rules in what section","text":"
    Rules in what section are constructed from \"strings\" literals. You can use:
     
       
    • \"command_name\" of an existing API command
      •  
    • command_name is same as before, but no need to provide \"
      •  
    • \"*\" is a wildcard rule to match all commands
      •  
    • \"[tag: tagname ]\" allows all commands that have been declared with tag tagname.   You can consult the list of tags and their commands with: ejabberdctl help tags
      •  
     
    Additionally each rule can be prepended with ! character to change it into negative assertion rule. Command names that would match what is after ! character will be removed from list of allowed commands.
     
    Missing what rule is equivalent to what: \"!*\" which will stop group from accepting any command.
    "},{"location":"developer/ejabberd-api/permissions/#example-of-what-rules","title":"Example of what rules","text":"
    This allows execution of all commands except command stop:
     
    what:\n  - \"*\"\n  - \"!stop\"\n
     
    This allows execution of status and commands with tag session (like num_resources or status_list):
     
    what:\n  - status\n  - \"[tag:account]\"\n
     
    This matches no command:
     
    what:\n  - start\n  - \"!*\"\n
    "},{"location":"developer/ejabberd-api/permissions/#rules-in-from-section","title":"Rules in from section","text":"
    This section allows to specify list of allowed module names that expose API to outside world. Currently those modules are ejabberd_xmlrpc, mod_http_api and ejabberd_ctl.
     
    If from section is missing from group then all endpoints are accepted, if it's specified endpoint must be listed inside it to be allowed to execute.
    "},{"location":"developer/ejabberd-api/permissions/#examples","title":"Examples","text":"
    Those rules allow execution of any command invoked by ejabberdctl shell command, or all command except start and stop for users in ACL admin, with regular authentication or ejabberd:admin scoped OAuth tokens.
     
    api_permissions:\n  \"console commands\":\n    from:\n      - ejabberd_ctl\n    who: all\n    what: \"*\"\n  \"admin access\":\n    who:\n      access:\n        allow:\n          - acl: admin\n      oauth:\n        scope: \"ejabberd:admin\"\n        access:\n          allow:\n            - acl: admin\n    what:\n      - \"*\"\n      - \"!stop\"\n      - \"!start\"\n
    "},{"location":"developer/ejabberd-api/simple-configuration/","title":"Simple ejabberd Rest API Configuration","text":""},{"location":"developer/ejabberd-api/simple-configuration/#restrict-to-local-network","title":"Restrict to Local network","text":"
    If you are planning to use ejabberd API for admin purpose, it is often enough to configure it to be available local commands. Access is thus generally limited by IP addresses, either restricted to localhost only, or restricted to one of your platform back-end.
     
       
    1.  
      Make sure an ejabberd_http listener is using mod_http_api on a given root URL and on a desired port:
       
      listen:\n  -\n    port: 5281\n    module: ejabberd_http\n    ip: 127.0.0.1\n    request_handlers:\n      /api: mod_http_api\n
       
      The ip option ensures it listens only on the local interface (127.0.0.1) instead of listening on all interface (0.0.0.0).
       
      2.  
    2.  
      By defining api_permissions, you can then allow HTTP request from a specific IP to trigger API commands execution without user credentials:
       
      api_permissions:\n  \"API used from localhost allows all calls\":\n    who:\n      ip: 127.0.0.1/8\n    what:\n      - \"*\"\n      - \"!stop\"\n      - \"!start\"\n
       
      Note: stop and start commands are disabled in that example as they are usually restricted to ejabberdctl command-line tool. They are consider too sensitive to be exposed through API.
       
      3.  
    3.  
      Now you can query the API, for example:
       
      curl '127.0.0.1:5281/api/registered_users?host=localhost'\n\n[\"user2\",\"user8\"]\n
       
      4.  
    "},{"location":"developer/ejabberd-api/simple-configuration/#encryption","title":"Encryption","text":"
    If you already defined certificates and your connection is not on a local network, you may want to use encryption.
     
       
    1.  
      Setup encryption like this:
       
      listen:\n  -\n    port: 5281\n    module: ejabberd_http\n    tls: true\n    request_handlers:\n      /api: mod_http_api\n
       
      2.  
    2.  
      Now you can query using HTTPS:
       
      curl 'https://127.0.0.1:5281/api/registered_users?host=localhost'\n\n[\"user2\",\"user8\"]\n
       
      3.  
    3.  
      If you are using a self-signed certificate, you can bypass the corresponding error message:
       
      curl --insecure 'https://127.0.0.1:5281/api/registered_users?host=localhost'\n\n[\"user2\",\"user8\"]\n
       
      4.  
    "},{"location":"developer/ejabberd-api/simple-configuration/#basic-authentication","title":"Basic Authentication","text":"
    Quite probably you will want to require authentication to execute API queries, either using basic auth or OAuth.
     
       
    1.  
      Assuming you have the simple listener:
       
      listen:\n  -\n    port: 5281\n    module: ejabberd_http\n    ip: 127.0.0.1\n    request_handlers:\n      /api: mod_http_api\n
       
      2.  
    2.  
      Define an ACL with the account that you will use to authenticate:
       
      acl:\n  apicommands:\n    user: john@localhost\n
       
      3.  
    3.  
      Allow only that ACL to use the API:
       
      api_permissions:\n  \"some playing\":\n    from:\n      - ejabberd_ctl\n      - mod_http_api\n    who:\n      acl: apicommands\n    what: \"*\"\n
       
      4.  
    4.  
      If that account does not yet exist, register it:
       
      ejabberdctl register john localhost somePass\n
       
      5.  
    5.  
      Now, when sending an API query, provide the authentication for that account:
       
      curl --basic --user john@localhost:somePass \\\n     '127.0.0.1:5281/api/registered_users?host=localhost'\n\n[\"user2\",\"user8\",\"john\"]\n
       
      6.  
    6.  
      Example Python code:
       
      import requests\n\nurl = \"http://localhost:5281/api/registered_users\"\ndata = {\n    \"host\": \"localhost\"\n}\n\nres = requests.post(url, json=data, auth=(\"john@localhost\", \"somePass\"))\n\nprint(res.text)\n
       
      7.  
    "},{"location":"developer/ejabberd-api/simple-configuration/#oauth-authentication","title":"OAuth Authentication","text":"
    Before using OAuth to interact with ejabberd API, you need to configure OAuth support in ejabberd.
     
    Here are example entries to check / change in your ejabberd configuration file:
     
       
    1.  
      Add a request handler for OAuth:
       
      listen:\n  -\n    # Using a separate port for oauth and API to make it easy to protect it\n    # differently than BOSH and WebSocket HTTP interface.\n    port: 5281\n    # oauth and API only listen on localhost interface for security reason\n    # You can set ip to 0.0.0.0 to open it widely, but be careful!\n    ip: 127.0.0.1\n    module: ejabberd_http\n    request_handlers:\n      /api: mod_http_api\n      /oauth: ejabberd_oauth\n
       
      2.  
    2.  
      Set the oauth_access    top-level option to allow token creation:
       
      oauth_access: all\n
       
      3.  
    3.  
      Define an ACL with the account that you will use to authenticate:
       
      acl:\n  apicommands:\n    user: john@localhost\n
       
      4.  
    4.  
      You can then configure the OAuth commands you want to expose and who can use them:
       
      api_permissions:\n  \"admin access\":\n    who:\n      oauth:\n        scope: \"ejabberd:admin\"\n        scope: \"registered_users\"\n        access:\n          allow:\n            acl: apicommands\n    what: \"*\"\n
       
      5.  
    5.  
      If that account does not yet exist,    register it:
       
      ejabberdctl register john localhost somePass\n
       
      6.  
    6.  
      Request an authorization token. A quick way is using ejabberdctl:
       
      ejabberdctl oauth_issue_token user123@localhost 3600 ejabberd:admin\nerHymcBiT2r0QsuOpDjIrsEvnOS4grkj   [<<\"ejabberd:admin\">>]   3600 seconds\n
       
      7.  
    7.  
      Now, when sending an API query, provide the authentication for that account:
       
      curl -H \"Authorization: Bearer erHymcBiT2r0QsuOpDjIrsEvnOS4grkj\" \\\n     '127.0.0.1:5281/api/registered_users?host=localhost'\n\n[\"user2\",\"user8\",\"john\"]\n
       
      Or quite simply:
       
      curl --oauth2-bearer erHymcBiT2r0QsuOpDjIrsEvnOS4grkj \\\n     '127.0.0.1:5281/api/registered_users?host=localhost'\n\n[\"user2\",\"user8\",\"john\"]\n
       
      8.  
    "},{"location":"developer/extending-ejabberd/","title":"Extending ejabberd","text":"
    This section will help you learn how to develop ejabberd module to customize it to your own needs.
    "},{"location":"developer/extending-ejabberd/architecture/","title":"Architecture","text":"
    This section contains information to help your understand ejabberd architecture and will explain how to integrate ejabberd properly into your overall infrastructure.
    "},{"location":"developer/extending-ejabberd/architecture/#overview","title":"Overview","text":"
    ejabberd is a configurable system where modules can be enabled or disabled based on customer requirements. Users can connect not only from a regular PC but also from mobile devices and from the web. User data can be stored internally in Mnesia or in one of the support SQL or NoSQL backend. Users can be totally managed by your own backend through a ReST interface.
     
    ejabberd internal architecture is organised around its router. Most of the other elements are plugins that can be adapted, enhanced or replaced to build a custom solution tailored to your needs.
     
    ejabberd support a core concept of XMPP: Federation. Federation is a mechanism allowing different independent XMPP servers and clusters to communicate with each other.
     
    Here is a high level diagram of ejabberd internal architecture:
     
    "},{"location":"developer/extending-ejabberd/architecture/#typical-large-scale-deployments","title":"Typical large scale deployments","text":"
    Here is a diagram for a typical ejabberd large scale deployment. It can scale massively and rely on several back-ends.
     
     
    Note that ejabberd ejabberd support a core concept of XMPP: Federation. Federation is a mechanism allowing different independent XMPP servers and clusters to communicate with each other. This is a purely optional layer, but it can help integrate with the rest of the world. It is also sometimes internally by companies to group users in subsidiaries or regions.
    "},{"location":"developer/extending-ejabberd/architecture/#virtual-hosting","title":"Virtual hosting","text":"
    If you need to manage several small XMPP domains, ejabberd supports virtual hosting.  It means you can host as many domain as you want on a single ejabberd deployment.
     
    Instances can be made to be totally independent and invisible for each other if needed (or they can communicate as they would through federation).
    "},{"location":"developer/extending-ejabberd/elixir/","title":"ejabberd for Elixir Developers","text":"
     improved in 21.07
    "},{"location":"developer/extending-ejabberd/elixir/#building-ejabberd-with-mix","title":"Building ejabberd with Mix","text":"
    You can build ejabberd with Elixir mix tool. This allows ejabberd to use Elixir libraries and ejabberd modules written in Elixir.
     
    Please note: Elixir 1.10.3 or higher is required to build a release. Also, if using Erlang/OTP 24, then Elixir 1.11.4 or higher is required.
     
       
    1.  
      Make sure you have the    requirements    installed. On MacOS you need to use Homebrew and    set up your environment.
       
      2.  
    2.  
      Clone ejabberd project from Github:
       
      git clone https://github.com/processone/ejabberd.git\ncd ejabberd\n
       
      3.  
    3.  
      Compile ejabberd:
       
      ./autogen.sh\n./configure --with-rebar=mix\nmake\n
       
      4.  
    4.  
      Build a development release:
       
      make dev\n
       
      5.  
    5.  
      There are many ways to start ejabberd, using the ejabberdctl or ejabberd scripts:
       
      _build/prod/rel/ejabberd/bin/ejabberdctl iexlive\n_build/prod/rel/ejabberd/bin/ejabberdctl live\n_build/prod/rel/ejabberd/bin/ejabberd start_iex\n
       
      6.  
    6.  
      You should see that ejabberd is properly started:
       
      Erlang/OTP 23 [erts-11.1.8] [source] [64-bit] [smp:2:2] [ds:2:2:10] [async-threads:1]\n\n2021-08-03 13:37:36.561603+02:00 [info] Loading configuration from /home/bernar/e/git/ejabberd/_build/dev/rel/ejabberd/etc/ejabberd/ejabberd.yml\n2021-08-03 13:37:37.541688+02:00 [info] Configuration loaded successfully\n...\n2021-08-03 13:37:40.201590+02:00 [info] ejabberd 21.7.9 is started in the node ejabberd@atenea in 3.86s\n2021-08-03 13:37:40.203678+02:00 [info] Start accepting TCP connections at [::]:5222 for ejabberd_c2s\n\nInteractive Elixir (1.10.3) - press Ctrl+C to exit (type h() ENTER for help)\niex(ejabberd@localhost)1>\n
       
      7.  
    7.  
      Now that ejabberd starts correctly, adapt to your needs the default ejabberd    configuration file located at _build/dev/rel/ejabberd/etc/ejabberd/ejabberd.yml    For example, enable this example Elixir ejabberd module:
       
      modules:\n  'ModPresenceDemo': {}\n  mod_adhoc: {}\n
       
      8.  
    "},{"location":"developer/extending-ejabberd/elixir/#embed-ejabberd-in-an-elixir-app","title":"Embed ejabberd in an elixir app","text":"
    ejabberd is available as an Hex.pm application: ejabberd on hex.pm.
     
    This means you can build a customized XMPP messaging platform with Elixir on top of ejabberd by leveraging ejabberd code base in your app and providing only your custom modules. This makes the management of your ejabberd plugins easier and cleaner.
     
    To create your own application depending on ejabberd, you can go through the following steps:
     
       
    1.  
      Create a new Elixir app using mix:
       
      mix new ejapp\ncd ejapp\n
       
      2.  
    2.  
      Add ejabberd package as a    dependency in your mix.exs file:
       
      defmodule Ejapp.MixProject do\n  defp deps do\n    [\n     {:ejabberd, \"~> 21.7\"}\n    ]\n  end\nend\n
       
      3.  
    3.  
      Compile everything:
       
      mix do deps.get, compile\n
       
      4.  
    4.  
      Create paths and files for ejabberd:
       
      mkdir config\nmkdir logs\nmkdir mnesia\nwget -O config/ejabberd.yml https://raw.githubusercontent.com/processone/ejabberd/master/ejabberd.yml.example\n
       
      5.  
    5.  
      Define those paths in config/config.exs:
       
      import Config\nconfig :ejabberd,\n  file: \"config/ejabberd.yml\",\n  log_path: 'logs/ejabberd.log'\nconfig :mnesia,\n  dir: 'mnesia/'\n
       
      6.  
    6.  
      Start your app, ejabberd will be started as a dependency:
       
      iex -S mix\n
       
      7.  
    7.  
      You should see that ejabberd is properly started:
       
      Erlang/OTP 23 [erts-11.1.8] [source] [64-bit] [smp:2:2] [ds:2:2:10] [async-threads:1]\n\nCompiling 1 file (.ex)\nGenerated ejapp app\n\n17:58:35.955 [info]  Loading configuration from config/ejabberd.yml\n\n17:58:36.459 [info]  Configuration loaded successfully\n...\n17:58:39.897 [info]  ejabberd 21.7.0 is started in the node :nonode@nohost in 4.07s\n...\n17:58:39.908 [info]  Start accepting TCP connections at [::]:5222 for :ejabberd_c2s\n\nInteractive Elixir (1.10.3) - press Ctrl+C to exit (type h() ENTER for help)\niex(1)>\n
       
      8.  
    8.  
      Register user from Elixir console:
       
      :ejabberd_auth.try_register(\"test\", \"localhost\", \"passw0rd\")\n
       
      9.  
    9.  
      You are all set, you can now connect with an XMPP client !
       
      10.  
    "},{"location":"developer/extending-ejabberd/elixir/#call-elixir-code-in-erlang-code","title":"Call elixir code in erlang code","text":"
    It's possible to use Elixir libraries in an Erlang module, both the ones included in Elixir, or any other you add as a dependency.
     
    This simple example invokes Elixir's String.duplicate/2 function as shown in one of its documentation examples, and uses the result in the ejabberd vCard nickname field:
     
    --- a/src/mod_vcard.erl\n+++ b/src/mod_vcard.erl\n@@ -209,6 +209,7 @@ process_local_iq(#iq{type = get, to = To, lang = Lang} = IQ) ->\n     VCard = case mod_vcard_opt:vcard(ServerHost) of\n   undefined ->\n       #vcard_temp{fn = <<\"ejabberd\">>,\n+    nickname = 'Elixir.String':duplicate(<<\"abc\">>, 2),\n     url = ejabberd_config:get_uri(),\n     desc = misc:get_descr(Lang, ?T(\"Erlang XMPP Server\")),\n     bday = <<\"2002-11-16\">>};\n
     
    Notice that the elixir code:
     
    String.duplicate(\"abc\", 2)\n
     
    is written in erlang as:
     
    'Elixir.String':duplicate(<<\"abc\">>, 2),\n
     
    Check Erlang/Elixir Syntax: A Crash Course for details.
    "},{"location":"developer/extending-ejabberd/elixir/#use-elixir-library-in-erlang-code","title":"Use elixir library in erlang code","text":"
    This example demonstrates how to add an elixir library as a dependency in ejabberd, and use it in an ejabberd module written in erlang.
     
    It will use QRCodeEx elixir library to build a QR code of ejabberd's URI and return it as the server vCard photo.
     
    First add the dependency to mix.exs:
     
    --- a/mix.exs\n+++ b/mix.exs\n@@ -46,7 +46,7 @@ defmodule Ejabberd.MixProject do\n                     :p1_utils, :stringprep, :yconf],\n      included_applications: [:mnesia, :os_mon,\n                              :cache_tab, :eimp, :mqtree, :p1_acme,\n-                             :p1_oauth2, :pkix, :xmpp]\n+                             :p1_oauth2, :pkix, :xmpp, :qrcode_ex]\n      ++ cond_apps()]\n   end\n\n@@ -113,6 +113,7 @@ defmodule Ejabberd.MixProject do\n      {:p1_oauth2, \"~> 0.6\"},\n      {:p1_utils, \"~> 1.0\"},\n      {:pkix, \"~> 1.0\"},\n+     {:qrcode_ex, \"~> 0.1.1\"},\n      {:stringprep, \">= 1.0.26\"},\n      {:xmpp, \"~> 1.5\"},\n      {:yconf, \"~> 1.0\"}]\n
     
    Then call QRCodeEx.encode/2, QRCodeEx.png/2, and provide the result as the photo in the server vcard:
     
    --- a/src/mod_vcard.erl\n+++ b/src/mod_vcard.erl\n@@ -206,9 +206,13 @@ process_local_iq(#iq{type = set, lang = Lang} = IQ) ->\n     xmpp:make_error(IQ, xmpp:err_not_allowed(Txt, Lang));\n process_local_iq(#iq{type = get, to = To, lang = Lang} = IQ) ->\n     ServerHost = ejabberd_router:host_of_route(To#jid.lserver),\n+    PhotoEncoded = 'Elixir.QRCodeEx':encode(ejabberd_config:get_uri()),\n+    PhotoBin = 'Elixir.QRCodeEx':png(PhotoEncoded, [{color, <<17, 120, 0>>}]),\n+    PhotoEl = #vcard_photo{type = <<\"image/png\">>, binval = PhotoBin},\n     VCard = case mod_vcard_opt:vcard(ServerHost) of\n   undefined ->\n       #vcard_temp{fn = <<\"ejabberd\">>,\n+    photo = PhotoEl,\n     url = ejabberd_config:get_uri(),\n     desc = misc:get_descr(Lang, ?T(\"Erlang XMPP Server\")),\n     bday = <<\"2002-11-16\">>};\n
    "},{"location":"developer/extending-ejabberd/elixir/#write-ejabberd-module-in-elixir","title":"Write ejabberd module in elixir","text":"
    If you plan to write an ejabberd module that heavily depends on Elixir dependencies, you may want to write it in elixir from scratch.
     
    The Elixir source code is placed in the ejabberd's lib/ path. Any elixir module placed in lib/ will be compiled by Mix, installed with all the other erlang modules, and available for you to use.
     
    As you can see, there's a file named mod_presence_demo.ex which defines an ejabberd module written in elixir called ModPresenceDemo. To enable ModPresenceDemo, add it to ejabberd.yml like this:
     
    modules:\n  'Elixir.ModPresenceDemo': {}\n
     
    Let's write a new ejabberd module in elixir, add it to ejabberd's source code, compile and install it. This example module requires the QRCodeEx Elixir library, and adds a simple web page that generates QR code of any given JID.
     
       
    1.  
      Copy the mod_qrcode.ex source code to ejabberd's lib/ path:
       
      lib/mod_qrcode.ex\n
       
      2.  
    2.  
      Recompile and reinstall ejabberd.
       
      3.  
    3.  
      Enable the module in ejabberd.yml:
       
      listen:\n  -\n    port: 5280\n    request_handlers:\n      /qrcode: 'Elixir.ModQrcode'\n\nmodules:\n  'Elixir.ModQrcode': {}\n
       
      4.  
    4.  
      When restarting ejabberd, it will show in the logs:
       
      2022-07-06 13:14:35.363081+02:00 [info] Starting ejabberd module Qrcode\n
       
      5.  
    5.  
      Now the ejabberd internal web server provides QR codes of any given JID.    Try visiting an URL like http://localhost:5280/qrcode/anyusername/somedomain/
       
      6.  
    "},{"location":"developer/extending-ejabberd/elixir/#elixir-module-in-ejabberd-contrib","title":"Elixir module in ejabberd-contrib","text":"
    Using ejabberd-contrib it's possible to install additional ejabberd modules without compiling ejabberd, or requiring ejabberd source code. This is useful if you install ejabberd using binary installers or a container image.
     
    And it's possible to write a custom module and Add your module to an existing ejabberd installation...
     
    Let's write a new ejabberd module in elixir, compile and install in an existing ejabberd deployment without requiring its source code. This example module adds a simple section listing PIDs in the users page in ejabberd WebAdmin.
     
       
    1.  
      First, create this path
       
      $HOME/.ejabberd-modules/sources/mod_webadmin_pid/lib/\n
       
      2.  
    2.  
      and copy the mod_webadmin_pid.ex source code to:
       
      $HOME/.ejabberd-modules/sources/mod_webadmin_pid/lib/mod_webadmin_pid.ex\n
       
      3.  
    3.  
      Create a specification file in YAML format as mod_webadmin_pid.spec (see examples from ejabberd-contrib). So, create the file
       
      $HOME/.ejabberd-modules/sources/mod_webadmin_pid/mod_webadmin_pid.spec\n
       
      with this content:
       
      summary: \"Display PIDs in User page in Web Admin\"\n
       
      4.  
    4.  
      From that point you should see it as available module:
       
      ejabberdctl modules_available\nmod_webadmin_pid Display PIDs in User page in Web Admin\n
       
      5.  
    5.  
      Now you can compile and install that module:
       
      ejabberdctl module_install mod_webadmin_pid\n
       
      6.  
    6.  
      Enable the module in ejabberd.yml:
       
      modules:\n  'Elixir.ModWebAdminPid': {}\n
       
      7.  
    7.  
      When restarting ejabberd, it will show in the logs:
       
      2022-07-06 13:14:35.363081+02:00 [info] Starting ejabberd module WebAdminPid\n
       
      8.  
    8.  
      Finally, go to ejabberd WebAdmin -> Virtual Hosts -> your vhost -> Users ->    some online user -> and there will be a new section \"PIDs\".
       
      9.  
    "},{"location":"developer/extending-ejabberd/elixir/#record-definition","title":"Record definition","text":"
    To use an erlang record defined in ejabberd's header file, use Elixir's Record to extract the fields and define an Elixir record with its usage macros.
     
    For example, add this to the beginning of mod_presence_demo.ex:
     
    require Record\n\nRecord.defrecord(:presence,\n  Record.extract(:presence, from_lib: \"xmpp/include/xmpp.hrl\"))\n
     
    Later you can use those macros, named like your record, see the examples.
     
    In our example, let's improve the on_presence function and use the presence macros to get the to field:
     
    def on_presence(_user, _server, _resource, packet) do\n  to_jid = presence(packet, :to)\n  to_str = :jid.to_string(to_jid)\n  info('Received presence for #{to_str}:~n~p', [packet])\n  :none\nend\n
    "},{"location":"developer/extending-ejabberd/elixir/#mod_qrcodeex","title":"mod_qrcode.ex","text":"
    Example ejabberd module written in elixir:
     mod_qrcode.ex
    defmodule ModQrcode do\n  use Ejabberd.Module\n\n  def start(host, _opts) do\n    info('Starting ejabberd module Qrcode')\n    :ok\n  end\n\n  def stop(host) do\n    info('Stopping ejabberd module Qrcode')\n    :ok\n  end\n\n  def process([username, hostname] = _path, _query) do\n    uri = <<\"xmpp:\", username::binary, \"@\", hostname::binary>>\n    qr = QRCodeEx.svg(QRCodeEx.encode(uri), [{:color, \"#3fb0d2\"}])\n    qxmlel = :fxml_stream.parse_element(qr)\n    {200,\n     [{<<\"Server\">>, <<\"ejabberd\">>},\n      {<<\"Content-Type\">>, <<\"image/svg+xml\">>}],\n     :ejabberd_web.make_xhtml([], [qxmlel])}\n  end\n\n  def process(path, _query) do\n    info('Received HTTP query with path: ~p', [path])\n    {404, [], \"Not Found\"}\n  end\n\n  def depends(_host, _opts) do\n    []\n  end\n\n  def mod_options(_host) do\n    []\n  end\n\n  def mod_doc() do\n    %{:desc => 'This is just a demonstration.'}\n  end\n\nend\n
    "},{"location":"developer/extending-ejabberd/elixir/#mod_webadmin_pidex","title":"mod_webadmin_pid.ex","text":"
    Example ejabberd module written in elixir:
     mod_webadmin_pid.ex
    defmodule ModWebAdminPid do\n  use Ejabberd.Module\n\n  require Record\n\n  Record.defrecord(:xmlel,\n    Record.extract(:xmlel, from_lib: \"xmpp/include/xmpp.hrl\"))\n\n  Record.defrecord(:request,\n    Record.extract(:request, from: \"include/ejabberd_http.hrl\"))\n\n  ##====================================================================\n  ## gen_mod callbacks\n  ##====================================================================\n\n  def start(host, _opts) do\n    info('Starting ejabberd module WebAdminPid')\n    :ejabberd_hooks.add(:webadmin_user, host, __MODULE__, :webadmin_user, 60)\n    :ejabberd_hooks.add(:webadmin_page_host, host, __MODULE__, :webadmin_page, 60)\n    :ok\n  end\n\n  def stop(host) do\n    info('Stopping ejabberd module WebAdminPid')\n    :ejabberd_hooks.delete(:webadmin_user, host, __MODULE__, :webadmin_user, 60)\n    :ejabberd_hooks.delete(:webadmin_page_host, host, __MODULE__, :webadmin_page, 60)\n    :ok\n  end\n\n  def depends(_host, _opts) do\n    []\n  end\n\n  def mod_options(_host) do\n    []\n  end\n\n  def mod_doc() do\n    %{:desc => 'This is just a demonstration.'}\n  end\n\n  ##====================================================================\n  ## Web Admin\n  ##====================================================================\n\n  def webadmin_user(acc, user, server, _lang) do\n    resources = :ejabberd_sm.get_user_resources(user, server)\n\n    pids_elements = Enum.map(resources,\n      fn resource ->\n        pid = :ejabberd_sm.get_session_pid(user, server, resource)\n        pid_string = :erlang.pid_to_list(pid)\n        xmlel(name: \"a\", attrs: [{\"href\", \"pid/#{pid_string}\"}], children: [xmlcdata: pid_string])\n      end)\n\n    pids_separated = Enum.intersperse(pids_elements, {:xmlcdata, \", \"})\n\n    new_element = xmlel(name: \"h3\", children: [xmlcdata: \"PIDs:\"])\n\n    acc ++ [new_element] ++ pids_separated\n  end\n\n  def webadmin_page(_acc, host, request(path: [\"user\", user, \"pid\", pid])) do\n    res = webadmin_pid(user, host, pid)\n    {:stop, res}\n  end\n\n  def webadmin_page(acc, _host, _request) do\n    acc\n  end\n\n  def webadmin_pid(user, host, pid_string) do\n    us = :jid.to_string(:jid.make(user, host))\n    page_title = 'Pid #{pid_string} of #{us}'\n\n    pid = :erlang.list_to_pid(String.to_charlist(pid_string))\n    pid_info = Process.info(pid)\n    pid_info_string = :io_lib.format(\"~p\", [pid_info])\n\n    [xmlel(name: \"h1\", children: [xmlcdata: page_title]),\n     xmlel(name: \"pre\", children: [xmlcdata: pid_info_string])]\n  end\n\nend\n
    "},{"location":"developer/extending-ejabberd/localization/","title":"Internationalization and Localization","text":"
    The source code of ejabberd supports localization: all built-in modules support the xml:lang attribute inside IQ queries, and the Web Admin supports the Accept-Language HTTP header.
     
    There are two ways to improve the translation of a language:
     
       
    •  
      Edit the corresponding .po file in ejabberd-po git repository with a gettext-compatible program (Poedit, KBabel, Lokalize, ...). Then submit a Pull Request.
       
      •  
    •  
      Using the ejabberd-po Weblate online service.
       
      •  
     
    Once the translators have improved the po files, you can run make translations. With that command, the translatable strings are extracted from source code to generate the file ejabberd.pot. This file is merged with each .po file to produce updated .po files. Finally those .po files are exported to .msg files, that have a format easily readable by ejabberd.
    "},{"location":"developer/extending-ejabberd/modules/","title":"ejabberd Modules Development","text":""},{"location":"developer/extending-ejabberd/modules/#introduction","title":"Introduction","text":"
    ejabberd is based on a modular architecture that makes it highly customizable and infinitely extensible.
     
    Here is an overview of ejabberd internal architecture:
     
    "},{"location":"developer/extending-ejabberd/modules/#what-is-a-module","title":"What is a module ?","text":"
    Outside of a few infrastructure core components most of ejabberd features are developed as modules. Modules are used to extend the features of ejabberd (plugins).
    "},{"location":"developer/extending-ejabberd/modules/#how-to-write-a-custom-module","title":"How to write a custom module ?","text":"
    Ejabberd comes with a lot of modules, but sometimes you may need an unsupported feature from the official sources or maybe you need to write your own custom implementation for your very special needs.
     
    Each modules is written in either Erlang or Elixir. To use them, you typically declare them in ejabberd configuration file. That's also the place where you can configure the module, by passing supported options to overload its default behaviour.
     
    On ejabberd launch, the server will start all the declared modules. You can start (or stop) them manually from Erlang shell as well.
     
    As a convention, module names starts with \"mod_\", but you can actually call them as you want.
    "},{"location":"developer/extending-ejabberd/modules/#the-gen_mod-behaviour","title":"The gen_mod behaviour","text":"
    All ejabberd modules are implementing the gen_mod behaviour. It means that a module must provide the following API:
     
    start(Host, Opts) -> ok\nstop(Host) -> ok\ndepends(Host, Opts) -> []\nmod_options(Host) -> []\n
     
    Parameters are:
     
       
    • Host = string()
      •  
    • Opts = [{Name, Value}]
      •  
    • Name = Value = string()
      •  
     
    Host is the name of the virtual host running the module. The start/2 and stop/1 functions are called for each virtual host at start and stop time of the server.
     
    Opts is a lists of options as defined in the configuration file for the module. They can be retrieved with the gen_mod:get_opt/3 function.
    "},{"location":"developer/extending-ejabberd/modules/#mod_hello_world","title":"mod_hello_world","text":"
    The following code shows the simplest possible module.
     mod_hello_world.erl
    -module(mod_hello_world).\n\n-behaviour(gen_mod).\n\n%% Required by ?INFO_MSG macros\n-include(\"logger.hrl\").\n\n%% Required by ?T macro\n-include(\"translate.hrl\").\n\n%% gen_mod API callbacks\n-export([start/2, stop/1, depends/2, mod_options/1, mod_doc/0]).\n\nstart(_Host, _Opts) ->\n    ?INFO_MSG(\"Hello, ejabberd world!\", []),\n    ok.\n\nstop(_Host) ->\n    ?INFO_MSG(\"Bye bye, ejabberd world!\", []),\n    ok.\n\ndepends(_Host, _Opts) ->\n    [].\n\nmod_options(_Host) ->\n    [].\n\nmod_doc() ->\n    #{desc =>\n          ?T(\"This is an example module.\")}.\n
     
    Now you have two ways to compile and install the module: If you compiled ejabberd from source code, you can copy that source code file with all the other ejabberd source code files, so it will be compiled and installed with them. If you installed some compiled ejabberd package, you can create your own module dir, see Add Your Module.
     
    You can enable your new module by adding it in the ejabberd config file. Adding the following snippet in the config file will integrate the module in ejabberd module lifecycle management. It means the module will be started at ejabberd launch and stopped during ejabberd shutdown process:
     
    modules:\n  ...\n  mod_hello_world: {}\n
     
    Or you can start / stop it manually by typing the following commands in an Erlang shell running ejabberd:
     
       
    •  
      To manually start your module:
       
      gen_mod:start_module(<<\"localhost\">>, mod_hello_world, []).\n
       
      •  
    •  
      To manually stop your module:
       
      gen_mod:stop_module(<<\"localhost\">>, mod_hello_world).\n
       
      •  
     
    When the module is started, either on ejabberd start or manually, you should see the following message in ejabberd log file:
     
    19:13:29.717 [info] Hello, ejabberd world!\n
    "},{"location":"developer/extending-ejabberd/modules/#ejabberd-contrib","title":"ejabberd-contrib","text":"
    ejabberd is able to fetch module sources by itself, compile with correct flags and install in a local repository, without any external dependencies. You do not need to know Erlang and have it installed in order to use the contributed modules. The contributed modules repository is ejabberd-contrib on github. It contains most used contributions and also can link to any other external repository. This works with ejabberd modules written in Erlang and will also support new Elixir modules.
    "},{"location":"developer/extending-ejabberd/modules/#basic-usage","title":"Basic usage","text":"
    As a user, this is how it works:
     
       
    1.  
      First you need to get/update the list of available modules.  This must be     done before anything else to let module related features to work correctly.     You may want to repeat this command before you need installing a new module     or an attended server upgrade.
       
      ejabberdctl modules_update_specs\n
       
      2.  
    2.  
      Then you can list available modules:
       
      ejabberdctl modules_available\n...\nmod_admin_extra Additional ejabberd commands\nmod_archive Supports almost all the XEP-0136 version 0.6 except otr\nmod_cron Execute scheduled commands\nmod_log_chat Logging chat messages in text files\n...\n
       
      3.  
    3.  
      Let\u2019s install mod_cron from ejabberd-contrib repository:
       
      ejabberdctl module_install mod_cron\nok\n
       
      4.  
    4.  
      You can check anytime what modules are installed:
       
      ejabberdctl modules_installed\nmod_cron\n
       
      5.  
    5.  
      An example default configuration is installed, and will be read by ejabberd     when it starts. You can find that small configuration in:
       
      $HOME/.ejabberd-modules/mod_cron/conf/mod_cron.yml\n
       
      6.  
    6.  
      And finally, you can remove the module:
       
      ejabberdctl module_uninstall mod_cron\nok\n
       
      7.  
    "},{"location":"developer/extending-ejabberd/modules/#add-your-module","title":"Add your module","text":"
    If you install ejabberd using the official ProcessOne installer, it includes everything needed to build ejabberd modules on its own.
     
       
    1.  
      First, create this path
       
      $HOME/.ejabberd-modules/sources/mod_hello_world/src/\n
       
      2.  
    2.  
      and copy your source code to this location:
       
      $HOME/.ejabberd-modules/sources/mod_hello_world/src/mod_hello_world.erl\n
       
      3.  
    3.  
      Create a specification file in YAML format as mod_hello_world.spec (see examples from ejabberd-contrib). So, create the file
       
      $HOME/.ejabberd-modules/sources/mod_hello_world/mod_hello_world.spec\n
       
      with this content:
       mod_hello_world.spec
      summary: \"Hello World example module\"\n
       
      4.  
    4.  
      From that point you should see it as available module:
       
      ejabberdctl modules_available\nmod_hello_world Hello World example module\n
       
      5.  
    5.  
      Now you can install and uninstall that module like any other,     as described in the previous section.
       
      6.  
    6.  
      If you plan to publish your module, you should check if your module     follows the policy and if it compiles correctly:
       
      ejabberdctl module_check mod_mysupermodule\nok\n
       
      If all is OK, your\u2019re done ! Else, just follow the warning/error messages to fix the issues.
       
      7.  
     
    You may consider publishing your module as a tgz/zip archive or git repository, and send your spec file for integration in ejabberd-contrib repository. ejabberd-contrib will only host a copy of your spec file and does not need your code to make it available to all ejabberd users.
    "},{"location":"developer/extending-ejabberd/modules/#your-module-with-docker","title":"Your module with Docker","text":"
    If you installed ejabberd using the Docker image, these specific instructions allow you to use your module with your Docker image:
     
       
    1.  
      Create a local directory for the contributed modules:
       
      mkdir docker-modules\n
       
      2.  
    2.  
      Then create the directory structure for your custom module:
       
      cd docker-modules\n\nmkdir -p sources/mod_hello_world/\ntouch sources/mod_hello_world/mod_hello_world.spec\n\nmkdir sources/mod_hello_world/src/\nmv mod_hello_world.erl sources/mod_hello_world/src/\n\nmkdir sources/mod_hello_world/conf/\necho -e \"modules:\\n  mod_hello_world: {}\" > sources/mod_hello_world/conf/mod_hello_world.yml\n\ncd ..\n
       
      3.  
    3.  
      Grant ownership of that directory to the UID that ejabberd will use inside the Docker image:
       
      sudo chown 9000 -R docker-modules/\n
       
      4.  
    4.  
      Start ejabberd in Docker:
       
      sudo docker run \\\n  --name hellotest \\\n  -d \\\n  --volume \"$(pwd)/docker-modules:/home/ejabberd/.ejabberd-modules/\" \\\n  -p 5222:5222 \\\n  -p 5280:5280 \\\n  ejabberd/ecs\n
       
      5.  
    5.  
      Check the module is available for installing, and then install it:
       
      sudo docker exec -it hellotest bin/ejabberdctl modules_available\nmod_hello_world []\n\nsudo docker exec -it hellotest bin/ejabberdctl module_install mod_hello_world\n
       
      6.  
    6.  
      If the module works correctly, you will see the Hello string in the ejabberd logs when it starts:
       
      sudo docker exec -it hellotest grep Hello logs/ejabberd.log\n2020-10-06 13:40:13.154335+00:00 [info]\n  <0.492.0>@mod_hello_world:start/2:15 Hello, ejabberd world!\n
       
      7.  
    "},{"location":"developer/extending-ejabberd/modules/#status","title":"Status","text":"
    Please note this is provided as a beta version. We want the work in progress to be released early to gather feedback from developers and users.
     
    For now, you need to edit the configuration snippet provided in module\u2019s conf directory and copy it into your ejabberd\u2019s main configuration. Then you\u2019ll need to restart ejabberd or manually start the module.
     
    However, our plan is to keep iterating on the tool and to make our best to make module installation as easy as possible and avoid need to change main configuration: ejabberd should be able to include module configuration snippets on the fly in a near future.
    "},{"location":"developer/extending-ejabberd/modules/#next-steps","title":"Next steps","text":"
    From there, you know how to package a module to integrate it inside ejabberd environment. Packaging a module allows you to:
     
       
    • Integrate in ejabberd overall application life cycle, i.e. with the   start and stop mechanism.
      •  
    • Get data from ejabberd configuration file.
      •  
     
    Now, to do useful stuff, you need to integrate with ejabberd data flow. You have two mechanisms available from ejabberd modules:
     
       
    •  
      Events and Hooks: This is to handle internal ejabberd triggers and   subscribe to them to perform actions or provide data.
       
      •  
    •  
      IQ Handlers: This is a way to register ejabberd module to handle   XMPP Info Queries. This is the XMPP way to provide new services.
       
      •  
    "},{"location":"developer/extending-ejabberd/pubsub/","title":"PubSub overview","text":"
    This document describes ejabberd's PubSub architecture to understand how to write custom plugins.
     
    XEP-0060 (PubSub) is more than 100 pages of specifications, with 12 very detailed use cases with many possibles options and possible situations:
     
       
    • Subscribe
      •  
    • Unsubscribe
      •  
    • Configure subscription
      •  
    • Retrieve items
      •  
    • Publish item
      •  
    • Delete item
      •  
    • Create node
      •  
    • Configure node
      •  
    • Delete node
      •  
    • Purge node
      •  
    • Manage subscriptions
      •  
    • Manage affiliations
      •  
     
    XEP-0163 (PEP) is based on PubSub XEP-0248 (deprecated) for Collection Nodes and uses generic PubSub functionality, specified in XEP-0060.
    "},{"location":"developer/extending-ejabberd/pubsub/#history","title":"History","text":"
    Initial implementation made by Aleksey Shchepin, ability to organise nodes in a tree added by Christophe Romain in 2007. First attempt to create a flexible API for plugins started in 2007, and improved until 2015.
    "},{"location":"developer/extending-ejabberd/pubsub/#implementation","title":"Implementation","text":"
    PubSub service comes in several parts:
     
       
    • A poll of iq handlers handled by ejabberd router
      •  
    • A sending process
      •  
    • A core router to perform high level actions for every use case
      •  
    • Plugins to handle nodes, affiliations/subscriptions, and items at lower level and interface with data backend
      •  
    "},{"location":"developer/extending-ejabberd/pubsub/#nodetree-plugins","title":"Nodetree plugins","text":"
    They handles storage and organisation of PubSub nodes. Called on get, create and delete node. Default implementation includes three plugins:
     
       
    • tree: (default) both internal and odbc backend.
      •  
    • virtual: no backend, no configurable nodes.
      •  
    • dag: handles XEP-0248.
      •  
     
    If all nodes shares same configuration, I/O on pubsub_node can be avoided using virtual nodetree.
    "},{"location":"developer/extending-ejabberd/pubsub/#node-plugins","title":"Node plugins","text":"
    They handle affiliations, subscriptions and items. They provide default node configuration and features. Called on every pubsub use cases. Each plugin is responsible of checks to handle all possibles cases and reply action result to PubSub engine to let it handle the routing. The most common plugins available in default installation are:
     
       
    • flat: (default) all nodes are in a flat namespace, there are no parent/child nodes
      •  
    • hometree: all nodes are organized as in a filesystem under /home/hostname/user/...
      •  
    • pep: handles XEP-0163
      •  
    • dag: handles XEP-0248.
      •  
    • public, private, ... which are derivate of flat, with different default node configuration.
      •  
    "},{"location":"developer/extending-ejabberd/pubsub/#node_flat","title":"node_flat","text":"
    node_flat is the default plugin, without node hierarchy, which handles standard PubSub case. The default node configuration with this plugin is:
     
    [{deliver_payloads, true},\n {notify_config, false},\n {notify_delete, false},\n {notify_retract, true},\n {purge_offline, false},\n {persist_items, true},\n {max_items, 10},\n {subscribe, true},\n {access_model, open},\n {roster_groups_allowed, []},\n {publish_model, publishers},\n {notification_type, headline},\n {max_payload_size, 60000},\n {send_last_published_item, on_sub_and_presence},\n {deliver_notifications, true},\n {presence_based_delivery, false}].\n
    "},{"location":"developer/extending-ejabberd/pubsub/#node_hometree","title":"node_hometree","text":"
    node_hometree use exact same features as flat plugin, but organise nodes in a tree following same scheme as path in filesystem. Every user can create nodes in its own home. Each node can contain items and/or sub-nodes. Example:
     
    /home/user\n/home/domain/user\n/home/domain/user/my_node\n/home/domain/user/my_node/child_node\n
    "},{"location":"developer/extending-ejabberd/pubsub/#node_pep","title":"node_pep","text":"
    node_pep handles XEP-0163: Personal Eventing Protocol It do not persist items, just keeping last item in memory cache. Node names are raw namespace attached to a given bare JID. Every user can have its own node with a common namespace sharing with others.
    "},{"location":"developer/extending-ejabberd/pubsub/#node_dag","title":"node_dag","text":"
    node_dag handles XEP-0248: PubSub Collection Nodes Contribution from Brian Cully. Every node takes places in a tree and is either a collection node (have only sub-nodes) or a leaf node (contains only items). No restriction on the tree structure
    "},{"location":"developer/extending-ejabberd/pubsub/#plugin-design","title":"Plugin design","text":"
    Due to complexity of XEP-0060, PubSub engine do successive calls to nodetree and node plugins in order to check validity, perform corresponding action and return result or appropriate error to users. Plugin design follows this requirement and divide actions by type of data to allow transient backend implementation without any PubSub engine change.
    "},{"location":"developer/extending-ejabberd/pubsub/#create-node","title":"Create Node","text":""},{"location":"developer/extending-ejabberd/pubsub/#delete-node","title":"Delete Node","text":""},{"location":"developer/extending-ejabberd/pubsub/#subscribe","title":"Subscribe","text":""},{"location":"developer/extending-ejabberd/pubsub/#unsubscribe","title":"Unsubscribe","text":""},{"location":"developer/extending-ejabberd/pubsub/#publish-item","title":"Publish item","text":""},{"location":"developer/extending-ejabberd/pubsub/#delete-item","title":"Delete item","text":""},{"location":"developer/extending-ejabberd/pubsub/#purge-node","title":"Purge Node","text":""},{"location":"developer/extending-ejabberd/pubsub/#get-item","title":"Get item","text":""},{"location":"developer/extending-ejabberd/pubsub/#available-backends","title":"Available backends","text":"
    Flat, hometree and PEP supports mnesia and SQL backends. Any derivated plugin can support the same (public, private, club, buddy...). Adding backend does not require any PubSub engine change. Plugin just need to comply API. Business Edition also supports optimized ets and mdb.
    "},{"location":"developer/extending-ejabberd/pubsub/#customisation","title":"Customisation","text":"
    To write your own plugin, you need to implement needed functions:
     
    [init/3, terminate/2, options/0, features/0,\n create_node_permission/6, create_node/2, delete_node/1,\n purge_node/2, subscribe_node/8, unsubscribe_node/4,\n publish_item/6, delete_item/4, remove_extra_items/3,\n get_entity_affiliations/2, get_node_affiliations/1,\n get_affiliation/2, set_affiliation/3,\n get_entity_subscriptions/2, get_node_subscriptions/1,\n get_subscriptions/2, set_subscriptions/4,\n get_pending_nodes/2, get_states/1, get_state/2,\n set_state/1, get_items/7, get_items/3, get_item/7,\n get_item/2, set_item/1, get_item_name/3, node_to_path/1,\n path_to_node/1]\n
     
    Generic function must call their corresponding partner in node_flat.
     
    Simple plugin would just call node_flat and override some defaults such as:
     
       
    • options/0 and features/0 to match your needs. This triggers the way PubSub controls calls to your plugins.
      •  
    • create_node_permission/6 for example to check an LDAP directory against an access flag
      •  
    • Write your own tests on publish or create node, forbids explicit access to items, etc...
      •  
    "},{"location":"developer/extending-ejabberd/pubsub/#clustering","title":"Clustering","text":"
    ejabberd's implementation tends to cover most generic and standard uses. It's good for common use, but far from optimal for edges or specific cases. Nodes, affiliations, subscriptions and items are stored in a replicated database. Each ejabberd node have access to all the data. Each ejabberd node handles part of the load, but keep locking database cluster wide on node records write (pubsub_node) Affiliations, subscriptions and items uses non blocking write (pubsub_state and pubsub_item)
    "},{"location":"developer/extending-ejabberd/stanza-routing/","title":"ejabberd Stanza Routing","text":""},{"location":"developer/extending-ejabberd/stanza-routing/#message-routing","title":"Message Routing","text":"
    In case of a message sent from User A to User B, both of whom are served by the same domain, the flow of the message through the system is as follows:
     
       
    1. User A's ejabberd_receiver receives the stanza and passes it to    ejabberd_c2s.
      2.  
    2. After some consistency check, user_send_packet is called if the    stanza is correct.
      3.  
    3. The stanza is matched against any privacy lists in use and, in case    of being allowed, routed by ejabberd_router:route/3.
      4.  
    4. ejabberd_router:route/3 runs the filter_packet    hook. filter_packet hook can drop of modify the stanza.
      5.  
    5.  
      ejabberd_router will then consult the routing table to know what    do to next. It is easier to understand by looking at an example of    actual routing table content:
       
      (ejabberd@localhost)2> ets:tab2list(route).\n[{route,<<\"pubsub.localhost\">>,\n  {apply_fun,#Fun<ejabberd_router.2.122122122>}},\n{route,<<\"muc.localhost\">>,\n  {apply_fun,#Fun<mod_muc.2.122122123>}},\n{route,<<\"localhost\">>,{apply,ejabberd_local,route}}]\n
       
      6.  
     
    In that case, user is local so we need to route to same domain (in    our case localhost). We then can see that we have to call    ejabberd_local:route to route the message to local user. As both    user are local (no server-to-server involved), it matches our    expectations.
     
       
    1.  
      ejabberd_local routes the stanza to ejabberd_sm given it's got at    least a bare JID as the recipient.
       
      2.  
    2.  
      ejabberd_sm determines the available resources of User B, takes    into account their session priorities and whether the message is    addressed to a particular resource or a bare JID and appropriately    replicates (or not) the message and sends it to the recipient's    ejabberd_c2s process(es).
       
      3.  
     
    In case no resources are available for delivery (hence no    ejabberd_c2s processes to pass the message to),    offline_message_hook is run to delegate offline message storage.
     
       
    1. ejabberd_c2s verifies the stanza against any relevant privacy    lists and sends it on the user socket if it does exist. In the case    of ejabberd Business Edition and ejabberd Saas, session can be    detached and push notifications can be used as a fallback.    user_receive_packet hook is run to notify the rest of the system    about stanza delivery to User B.
      2.  
     
    Here is a broader diagram, including server-to-server routing:
     
    "},{"location":"developer/extending-ejabberd/testing/","title":"ejabberd Test Suites","text":"
    ejabberd comes with a comprehensive test suite to cover various part of the software platform.
    "},{"location":"developer/extending-ejabberd/testing/#xmpp-end-to-end-protocol-test-suite","title":"XMPP end-to-end protocol test suite","text":""},{"location":"developer/extending-ejabberd/testing/#running-ejabberd-test-suite","title":"Running ejabberd test suite","text":"
    This test suite is a set of end-2-end integration tests that act like XMPP clients connecting with the server and is testing ejabberd at the protocol level.  It also contains tests for the various backends that ejabberd supports.
     
    The test suite is modular and can be run in parts (to focus on a group of features) or run for a specific backend.
     
    The CT_BACKENDS environment variable specifies which backend tests to run. Current CT_BACKENDS values:
     
       
    • extauth
      •  
    • ldap
      •  
    • mnesia
      •  
    • mssql
      •  
    • mysql
      •  
    • odbc
      •  
    • pgsql
      •  
    • redis
      •  
    • sqlite
      •  
     
    Note: You must build ejabberd with proper backend support for the tests to work. If the tests fail and you aren't sure why, check the configure build options to make sure ejabberd is compiled with adequate backend support.
     
    Note: these tests are e2e tests that operate a full ejabberd instance.  So the ports that ejabberd needs must be available for testing.  So you can't run an ejabberd instance at the same time you test.
     
    Other options you can use to limit the tests that will be run is to pass a list of groups to test. Some groups examples:
     
       
    • no_db: Runs subgroups generic and test_proxy65.
      •  
    • component
      •  
    • extauth
      •  
    • ldap
      •  
    • mnesia
      •  
    • mssql
      •  
    • mysql
      •  
    • pgsql
      •  
    • redis
      •  
    • s2s
      •  
    • sqlite
      •  
     
    Usually, it is enough to just limit tests with CT_BACKENDS and let the test suite decide which relevant tests to run. Sometimes you may want to only focus on a specific backend, skipping the generic no_db tests.
     
    Some example commands for running the XMPP end-to-end test suite using rebar and rebar3 ct:
     
    CT_BACKENDS=mnesia rebar  ct suites=ejabberd\nCT_BACKENDS=mnesia rebar  ct suites=ejabberd groups=mnesia\nCT_BACKENDS=mnesia rebar  ct suites=ejabberd groups=generic\nCT_BACKENDS=mnesia rebar3 ct --suite=test/ejabberd_SUITE --group=offline_flex,offline_send_all\nCT_BACKENDS=redis  rebar3 ct --suite=test/ejabberd_SUITE --group=offline_flex,offline_send_all\n
     
    If you have every backend configured, you can run all the tests with:
     
    make test\n
    "},{"location":"developer/extending-ejabberd/testing/#test-suite-conventions","title":"Test suite conventions","text":"
    The records used in test suite are autogenerated and come from tools/xmpp_codec.hrl. This is handy to match packets/results against expected values.
    "},{"location":"developer/extending-ejabberd/testing/#dependency-tests","title":"Dependency tests","text":"
    ejabberd depends on a lot of dependent modules. The dependencies can be tested independently by checking them out and running their test suites directly.
    "},{"location":"developer/extending-ejabberd/testing/#build-test-status","title":"Build test status","text":"
    We run tests for ejabberd and dependencies automatically via Github Actions. We have a Dashboard available on Github to check the overall test status for all projects: ProcessOne Github Dashboard
    "},{"location":"developer/xmpp-clients-bots/","title":"XMPP clients & bots","text":"
    As an XMPP developer, you will have to learn the basic of the XMPP protocol to developer clients and bots.
     
    This section is here to help you get started in writing XMPP powered software.
    "},{"location":"developer/xmpp-clients-bots/#xmpp-extensions","title":"XMPP Extensions","text":"
    Here is a section gathering proposed XMPP extensions:
     
       
    • Muc Sub: Extension to ease use of MUC on mobile by mixing Multi-User Chat with Subscription approach.
      •  
    • Simplified Roster Versioning: ejabberd implements a simplified roster versioning approach, compliant with roster versioning as defined in XEP-0237.
      •  
    "},{"location":"developer/xmpp-clients-bots/#xmpp-development","title":"XMPP Development","text":"
       
    • iOS Development: Getting started with XMPPFramework on iOS.
      •  
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/","title":"MucSub: Multi-User Chat Subscriptions","text":""},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#motivation","title":"Motivation","text":"
    In XMPP, Multi-User Chat rooms design rely on presence. To participate in a MUC room, you need to send a presence to the room. When you get disconnected, you leave the room and stopped being part of the room. User involvement in MUC rooms is not permanent.
     
    This is an issue with the rise of mobile applications. Chatting with friends in a room is a big part of messaging usage on mobile. However, to save battery life, mobile devices will freeze mobile XMPP application after a while when they get to background. It means that the connection is lost and that the session is usually terminated.
     
    Some workaround have been used to try letting user keep on receiving messages from MUC room when the app is in background. The most common one is to keep the session open for a while until a timeout happens. This is the approach promoted on mobile by XEP-0198 - Stream Management. When messages are received and no TCP/IP connection is attached, server usually fallback sending the message to the user using mobile push notification service to warn the user that a message has been received.
     
    This approach has many drawbacks:
     
       
    1. It is not permanent. The idea of having the session kept into    memory for a while is interesting but it is just a long    timeout. After that timeout, the session is closed and the user    will leave the room. No message will be received anymore.
      2.  
    2. It does not play well with normal server / cluster operations. If    you restart the service where the user session is kept, it will    disappear. You can dump them to disk and recreate them on start,    but it means that if the node crashes, your session will be lost    and user will stop receiving messages.
      3.  
    3. It does not change the fundamental nature of MUC chat room. They    are still presence-based. It means that if you need to restart the    MUC service, or if it crashes, presence are lost. For connected    clients, they are expected to join the MUC room again. However, for    mobile clients, it cannot happens until user reopens the    app. Moreover, it means that on new session start, user client is    expected to join all the MUC rooms they want to keep track of on    connect.
      4.  
     
    This specification tries to solve those issues by keeping most of the logic of the MUC room intact. There is attempt to rewrite XMPP Multi-User chat rooms by splitting presence from ability to receive and send messages (XEP-0369: Mediated Information eXchange (MIX)). However, the features covered by the MUC protocol are quite comprehensive and the MIX protocol is not yet ready to cover all the MUC use cases yet. The goal is to produce an intermediate state that is compliant with MUC and leverage most of the MUC features, while adding the most basic feature possible to implement the MUC/Sub extension.
     
    This specifications tries to merge ideas to produce a MUC extension that make MUC rooms mobile clients friendly.
     
    To play well with mobile, MUC room need to support the following features:
     
       
    • Add the ability to send and receive messages to a room without   having to send presence to the room. More generally allow other type   of interaction with the room (like configuration changes for example   or kick and ban). We will leverage existing publish and subscribe   approach.
      •  
    • Add the ability to resync the client for missed messages on   reconnect. We will leverage Message Archive Management service for   MUC.
      •  
    • Finally, ensure that a server can implement push notification   service to ensure alerting of offline users when MUC messages are   received.
      •  
     
    The goal is to learn from real life working implementation to help feeding MIX with feedback from the field, without having to reinvent a complete new protocol.
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#general-principle","title":"General principle","text":"
    The core idea is to expose MUC rooms as PubSub nodes and to introduce the concept of MUC rooms subscribers.
     
    A user affiliated to a MUC room should be able to subscribe to MUC node events and have them routed to their JID, even if they are not a participant in the room. It means that a user can receive messages without having to send presence to the room. In that sense, \"joining the room\" in XEP-0045 becomes more \"Being available in the MUC room\".
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#discovering-support","title":"Discovering support","text":""},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#discovering-support-on-muc-service","title":"Discovering support on MUC service","text":"
    You can check if MUC/Sub feature is available on MUC service by sending Disco Info IQ:
     
    <iq from='hag66@shakespeare.example/pda'\n    to='muc.shakespeare.example'\n    type='get'\n    id='ik3vs715'>\n  <query xmlns='http://jabber.org/protocol/disco#info'/>\n</iq>\n
     
    MUC service will show a feature of type 'urn:xmpp:mucsub:0' to the response if the feature is supported and enabled:
     
    <iq from=\"muc.shakespeare.example\"\n    to=\"hag66@shakespeare.example/pda\"\n    type=\"result\"\n    id=\"ik3vs715\">\n  <query xmlns=\"http://jabber.org/protocol/disco#info\">\n    <identity category=\"conference\"\n              type=\"text\"\n              name=\"Chatrooms\" />\n    ...\n    <feature var=\"urn:xmpp:mucsub:0\" />\n    ...\n  </query>\n</iq>\n
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#discovering-support-on-a-specific-muc","title":"Discovering support on a specific MUC","text":"
    A user can discover support for MUC/Sub feature on a MUC room as follow:
     
    <iq from='hag66@shakespeare.example/pda'\n    to='coven@muc.shakespeare.example'\n    type='get'\n    id='ik3vs715'>\n  <query xmlns='http://jabber.org/protocol/disco#info'/>\n</iq>\n
     
    A conference MUST add 'urn:xmpp:mucsub:0' to the response if the feature is supported and enabled:
     
    <iq from='coven@muc.shakespeare.example'\n    to='hag66@shakespeare.example/pda'\n    type='result'\n    id='ik3vs715'>\n  <query xmlns='http://jabber.org/protocol/disco#info'>\n    <identity category='conference'\n              name='A Dark Cave'\n              type='text' />\n    <feature var='http://jabber.org/protocol/muc' />\n    ...\n    <feature var='urn:xmpp:mucsub:0' />\n    ...\n  </query>\n</iq>\n
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#option-muc-room-support-for-subscriptions","title":"Option MUC room support for subscriptions","text":"
    Even if MUC room supports MUC/Sub feature, it MAY be explicitly enabled or disabled thanks to a new configuration option:
     
       
    • Allow subscription: Users can subscribe to MUC/Sub events.
      •  
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#subscriber-role","title":"Subscriber role","text":"
    Until a subscriber is not joined a conference (see Joining a MUC Room), a subscriber role MUST be 'none'. When a subscriber is joined a conference its role is changed according to XEP-0045 rules, that is, it becomes either 'visitor', 'participant' or 'moderator'.
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#subscribing-to-mucsub-events","title":"Subscribing to MUC/Sub events","text":"
    User can subscribe to the following events, by subscribing to specific nodes:
     
       
    • urn:xmpp:mucsub:nodes:presence
      •  
    • urn:xmpp:mucsub:nodes:messages
      •  
    • urn:xmpp:mucsub:nodes:affiliations
      •  
    • urn:xmpp:mucsub:nodes:subscribers
      •  
    • urn:xmpp:mucsub:nodes:config
      •  
    • urn:xmpp:mucsub:nodes:subject
      •  
    • urn:xmpp:mucsub:nodes:system
      •  
     
    Example: User Subscribes to MUC/Sub events
     
    <iq from='hag66@shakespeare.example'\n    to='coven@muc.shakespeare.example'\n    type='set'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscribe xmlns='urn:xmpp:mucsub:0'\n             nick='mynick'\n             password='roompassword'>\n    <event node='urn:xmpp:mucsub:nodes:messages' />\n    <event node='urn:xmpp:mucsub:nodes:affiliations' />\n    <event node='urn:xmpp:mucsub:nodes:subject' />\n    <event node='urn:xmpp:mucsub:nodes:config' />\n  </subscribe>\n</iq>\n
     
    If user is allowed to subscribe, server replies with success. The password attribute can be provided when subscribing to a password-protected room.
     
    Example: Server replies with success
     
    <iq from='coven@muc.shakespeare.example'\n    to='hag66@shakespeare.example'\n    type='result'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscribe xmlns='urn:xmpp:mucsub:0'>\n    <event node='urn:xmpp:mucsub:nodes:messages' />\n    <event node='urn:xmpp:mucsub:nodes:affiliations' />\n    <event node='urn:xmpp:mucsub:nodes:subject' />\n    <event node='urn:xmpp:mucsub:nodes:config' />\n  </subscribe>\n</iq>\n
     
    Subscription is associated with a nick. It will implicitly register the nick. Server should otherwise make sure that subscription match the user registered nickname in that room. In order to change the nick and/or subscription nodes, the same request MUST be sent with a different nick or nodes information.
     
    Example: User changes subscription data
     
    <iq from='hag66@shakespeare.example'\n    to='coven@muc.shakespeare.example'\n    type='set'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscribe xmlns='urn:xmpp:mucsub:0'\n             nick='newnick'>\n    <event node='urn:xmpp:mucsub:nodes:messages' />\n    <event node='urn:xmpp:mucsub:nodes:presence' />\n  </subscribe>\n</iq>\n
     
    A room moderator can subscribe another user to MUC Room events by providing the user JID as an attribute in the <subscribe/> element.
     
    Example: Room moderator subscribes another user
     
    <iq from='king@shakespeare.example'\n    to='coven@muc.shakespeare.example'\n    type='set'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscribe xmlns='urn:xmpp:mucsub:0'\n             jid='hag66@shakespeare.example'\n             nick='mynick'\n             password='roompassword'>\n    <event node='urn:xmpp:mucsub:nodes:messages' />\n    <event node='urn:xmpp:mucsub:nodes:affiliations' />\n    <event node='urn:xmpp:mucsub:nodes:subject' />\n    <event node='urn:xmpp:mucsub:nodes:config' />\n  </subscribe>\n</iq>\n
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#unsubscribing-from-a-muc-room","title":"Unsubscribing from a MUC Room","text":"
    At any time a user can unsubscribe from MUC Room events.
     
    Example: User unsubscribes from a MUC Room
     
    <iq from='hag66@shakespeare.example'\n    to='coven@muc.shakespeare.example'\n    type='set'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <unsubscribe xmlns='urn:xmpp:mucsub:0' />\n</iq>\n
     
    Example: A MUC Room responds to unsubscribe request
     
    <iq from='coven@muc.shakespeare.example'\n    to='hag66@shakespeare.example'\n    type='result'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7' />\n
     
    A room moderator can unsubscribe another room user from MUC Room events by providing the user JID as an attribute in the <unsubscribe/> element.
     
    Example: Room moderator unsubscribes another room user
     
    <iq from='king@shakespeare.example'\n    to='coven@muc.shakespeare.example'\n    type='set'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <unsubscribe xmlns='urn:xmpp:mucsub:0'\n               jid='hag66@shakespeare.example'/>\n</iq>\n
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#subscriber-actions","title":"Subscriber actions","text":"
    If not stated otherwise in this document, a subscriber MUST perform any actions in the conference as described in XEP-0045. For example, it MUST send messages to all occupants according to 7.4 Sending a Message to All Occupants, it MUST configure a conference according to 10.2 Subsequent Room Configuration and so on.
     
    Here are a few examples:
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#sending-a-message","title":"Sending a message","text":"
    Sending a message is like sending a standard groupchat message in MUC room:
     
    <message from=\"hag66@shakespeare.example\"\n         to=\"coven@muc.shakespeare.example\"\n         type=\"groupchat\">\n  <body>Test</body>\n</message>\n
     
    No need to join it after you connect. As a subscriber, you can send messages at any time.
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#joining-a-muc-room","title":"Joining a MUC Room","text":"
    If a user wants to be present in the room, they just have to join the room as defined in XEP-0045.
     
    A subscriber MAY decide to join a conference (in the XEP-0045 sense). In this case a conference MUST behave as described in XEP-0045 7.2 Entering a Room. A conference MUST process events as described under XEP-0045 7.1 Order of Events except it MUST not send room history. When a subscriber is joined, a conference MUST stop sending subscription events and MUST switch to a regular groupchat protocol (as described in XEP-0045) until a subscriber leaves.
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#receiving-events","title":"Receiving events","text":"
    Here is as an example message received by a subscriber when a message is posted to a MUC room when subscriber is subscribed to node urn:xmpp:mucsub:nodes:messages:
     
    <message from=\"coven@muc.shakespeare.example\"\n         to=\"hag66@shakespeare.example/pda\">\n  <event xmlns=\"http://jabber.org/protocol/pubsub#event\">\n    <items node=\"urn:xmpp:mucsub:nodes:messages\">\n      <item id=\"18277869892147515942\">\n        <message from=\"coven@muc.shakespeare.example/secondwitch\"\n                 to=\"hag66@shakespeare.example/pda\"\n                 type=\"groupchat\"\n                 xmlns=\"jabber:client\">\n          <archived xmlns=\"urn:xmpp:mam:tmp\"\n                    by=\"muc.shakespeare.example\"\n                    id=\"1467896732929849\" />\n          <stanza-id xmlns=\"urn:xmpp:sid:0\"\n                     by=\"muc.shakespeare.example\"\n                     id=\"1467896732929849\" />\n          <body>Hello from the MUC room !</body>\n        </message>\n      </item>\n    </items>\n  </event>\n</message>\n
     
    Presence changes in the MUC room are received wrapped in the same way by subscribers which subscribed to node urn:xmpp:mucsub:nodes:presence:
     
    <message from=\"coven@muc.shakespeare.example\"\n         to=\"hag66@shakespeare.example/pda\">\n  <event xmlns=\"http://jabber.org/protocol/pubsub#event\">\n    <items node=\"urn:xmpp:mucsub:nodes:presences\">\n      <item id=\"8170705750417052518\">\n        <presence xmlns=\"jabber:client\"\n                  from=\"coven@muc.shakespeare.example/secondwitch\"\n                  type=\"unavailable\"\n                  to=\"hag66@shakespeare.example/pda\">\n          <x xmlns=\"http://jabber.org/protocol/muc#user\">\n            <item affiliation=\"none\"\n                  role=\"none\" />\n          </x>\n        </presence>\n      </item>\n    </items>\n  </event>\n</message>\n
     
    If subscriber is subscribed to node urn:xmpp:mucsub:nodes:subscribers, message will ne sent for every mucsub subscription change. When a user becomes a subscriber:
     
    <message from=\"coven@muc.shakespeare.example\"\n         to=\"hag66@shakespeare.example/pda\">\n   <event xmlns=\"http://jabber.org/protocol/pubsub#event\">\n     <items node=\"urn:xmpp:mucsub:nodes:subscribers\">\n       <item id=\"17895981155977588737\">\n         <subscribe xmlns=\"urn:xmpp:mucsub:0\"\n                    jid=\"bob@server.com\"\n                    nick=\"bob\"/>\n       </item>\n     </items>\n   </event>\n</message>\n
     
    When a user lost its subscription:
     
    <message from=\"coven@muc.shakespeare.example\"\n         to=\"hag66@shakespeare.example/pda\">\n   <event xmlns=\"http://jabber.org/protocol/pubsub#event\">\n     <items node=\"urn:xmpp:mucsub:nodes:subscribers\">\n       <item id=\"10776102417321261057\">\n         <unsubscribe xmlns=\"urn:xmpp:mucsub:0\"\n                      jid=\"bob@server.com\"\n                      nick=\"bob\"/>\n       </item>\n     </items>\n   </event>\n</message>\n
     
    Note: Sometimes jid in subscribe/unsubscribe event may be missing if room is set to anonymous and user is not moderator.
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#getting-list-of-subscribed-rooms","title":"Getting List of subscribed rooms","text":"
    A user can query the MUC service to get their list of subscriptions.
     
    Example: User asks for subscriptions list
     
    <iq from='hag66@shakespeare.example'\n    to='muc.shakespeare.example'\n    type='get'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscriptions xmlns='urn:xmpp:mucsub:0' />\n</iq>\n
     
    Example: Server replies with subscriptions list
     
    <iq from='muc.shakespeare.example'\n    to='hag66@shakespeare.example'\n    type='result'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscriptions xmlns='urn:xmpp:mucsub:0'>\n    <subscription nick='mynick'\n                  jid='coven@muc.shakespeare.example'>\n      <event node='urn:xmpp:mucsub:nodes:messages'/>\n      <event node='urn:xmpp:mucsub:nodes:affiliations'/>\n      <event node='urn:xmpp:mucsub:nodes:subject'/>\n      <event node='urn:xmpp:mucsub:nodes:config'/>\n    </subscription>\n    <subscription nick='MyNick'\n                  jid='chat@muc.shakespeare.example'>\n      <event node='urn:xmpp:mucsub:nodes:messages'/>\n    </subscription>\n  </subscriptions>\n</iq>\n
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#getting-list-of-subscribers-of-a-room","title":"Getting list of subscribers of a room","text":"
    A subscriber or room moderator can get the list of subscribers by sending <subscriptions/> request directly to the room JID.
     
    Example: Asks for subscribers list
     
    <iq from='hag66@shakespeare.example'\n    to='coven@muc.shakespeare.example'\n    type='get'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscriptions xmlns='urn:xmpp:mucsub:0' />\n</iq>\n
     
    Example: Server replies with subscribers list
     
    <iq from='coven@muc.shakespeare.example'\n    to='hag66@shakespeare.example'\n    type='result'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscriptions xmlns='urn:xmpp:mucsub:0'>\n    <subscription nick='Juliet'\n                  jid='juliet@shakespeare.example'>\n      <event node='urn:xmpp:mucsub:nodes:messages'/>\n      <event node='urn:xmpp:mucsub:nodes:affiliations'/>\n    </subscription>\n    <subscription nick='Romeo'\n                  jid='romeo@shakespeare.example'>\n      <event node='urn:xmpp:mucsub:nodes:messages'/>\n    </subscription>\n  </subscriptions>\n</iq>\n
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#compliance-with-existing-muc-clients","title":"Compliance with existing MUC clients","text":"
    MUC/Sub approach is compliant with existing MUC service and MUC clients. MUC clients compliant with XEP-0045 will receive messages posted by subscribers. They may not see the user's presence, but it should not be an issue for most clients. Most clients already support receiving messages from users that are not currently in the MUC room through history retrieval.
     
    This approach should also help most clients to support better integration with third-party services posting to MUC room through API (as )
     
    However, a server could choose to send presence on behalf of subscribers when a user joins the room (in the XEP-0045 sense) so that the subscriber will be shown in MUC roster of legacy clients.
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#synchronization-of-muc-messages-leveraging-mam-support","title":"Synchronization of MUC messages: Leveraging MAM support","text":"
    To be friendly with mobile, the MAM service should allow a user to connect and easily resync their history for all MUC subscriptions. For details about MAM, see XEP-0313 Message Archive Management and your software's documentation, for instance ejabberd's mod_mam.
     
    Thanks to ability to get the list of all the existing subscription, client can get a starting point to interact with MAM service to resync history and get the messages that were missed while the user was offline.
     
    If you subscribe to MucSub, MAM will add the message to your own user JID on new messages. You will simply be able to query them using your own JID from the standard MAM service.
     
    It means, you can get all new MUC message in subscribed room thanks to MucSub, with a single query. For example, if you ask for all messages sent since a specific date, the result will contain both normal chat and MucSub messages.
     
    You would only need to query MUC for MAM for rooms for which you do not use MucSub as with MucSub you will be \"delivered\" each message (in that case, each message is added your MAM archive).
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#push-support-compliance","title":"Push support compliance","text":"
    Subscriptions are compliant with push mechanism. It is supported out of the box when using ProcessOne p1:push implementation (deployed on ejabberd SaaS for example).
     
    More generally, it is straightforward to handle them through ejabberd developer API to implement custom mechanisms.
     
    Subscriptions are delivered to online users. If the user has no active session, the server can choose to broadcast to the user through a push notification.
     
    When a session is opened, if the server detects that the user has not been recently active, or for any other reason, the server can still forward the message to a push notification service to warn the user that new messages are available in a MUC room.
    "},{"location":"developer/xmpp-clients-bots/extensions/roster-versioning/","title":"Roster versioning","text":"
    Roster versioning as implemented currently by ejabberd is a simplified approach to roster versioning.
     
    This is an all-or-nothing approach that does not support the granular diff as explained in RFC-6121.
     
    Our implementation conforms to version 0.6 of XEP-0237, sending the full roster in case of change or empty result if the roster did not change.
     
    As a result, as a client developer, when implementing support for roster versioning, you should expect both the traditional form for returning the roster, with version (iq result) and the incremental roster changes (iq set).
    "},{"location":"developer/xmpp-clients-bots/extensions/roster-versioning/#example","title":"Example","text":"
    As a summary, here is how you should expect it to work.
     
    First, you can check that the feature is advertised in the stream:features as urn:xmpp:features:rosterver:
     
    <stream:features>\n <bind xmlns=\"urn:ietf:params:xml:ns:xmpp-bind\"/>\n <session xmlns=\"urn:ietf:params:xml:ns:xmpp-session\">\n  <optional/>\n  </session>\n  <c xmlns=\"http://jabber.org/protocol/caps\" node=\"http://www.process-one.net/en/ejabberd/\" ver=\"/lmQr0llUEtX/pIt+6BDAbnIT/U=\" hash=\"sha-1\"/>\n  <sm xmlns=\"urn:xmpp:sm:2\"/>\n  <sm xmlns=\"urn:xmpp:sm:3\"/>\n  <ver xmlns=\"urn:xmpp:features:rosterver\"/>\n</stream:features>\n
     
    You can then bootstrap the use of roster versioning using empty ver attribute when sending your roster get iq:
     
    <iq id='roster1' to='myuser@domain.com' type='get'>\n <query xmlns='jabber:iq:roster' ver=''/>\n</iq>\n
     
    In return, you get a full roster with the current version:
     
    <iq from=\"myuser@domain.com\" type=\"result\" xml:lang=\"en\" to=\"myuser@domain.com/resource\" id=\"roster1\">\n <query xmlns=\"jabber:iq:roster\" ver=\"81cb523a7b77c7011552be85a3dde55189297590\">\n  <item subscription=\"both\" jid=\"contact@domain.com\">\n   <group>Test</group>\n  </item>\n  ...\n </query>\n</iq>\n
     
    The client can store this version to send subsequent roster queries.
     
    If client send a roster query with reference version it received get an empty iq result meaning the roster did not change:
     
    <iq id=\"roster2\" to=\"myuser@domain.com\" type=\"get\">\n <query xmlns='jabber:iq:roster' ver='81cb523a7b77c7011552be85a3dde55189297590'/>\n</iq>\n
     
    <iq from=\"myuser@domain.com\" type=\"result\" xml:lang=\"en\" to=\"myuser@domain.com/resource\" id=\"roster2\"/>\n
     
    If client send roster query with any other reference version, it will receive the full roster again in the roster iq result.
    "},{"location":"developer/xmpp-clients-bots/ios/getting-started-xmppframework/","title":"Getting Started with XMPPFramework","text":""},{"location":"developer/xmpp-clients-bots/ios/getting-started-xmppframework/#introduction","title":"Introduction","text":"
    XMPP development on smartphone has always been challenging given the constraints on mobile platform.
     
    This area will help you understand the challenges and help you get started with XMPP development on Apple iOS platform.
     
    The main library to support XMPP on iOS is XMPPFramework.
    "},{"location":"developer/xmpp-clients-bots/ios/getting-started-xmppframework/#xmppframework","title":"XMPPFramework","text":"
    XMPPFramework is a large framework relying on several dependencies. The easiest way to get started is to use Cocoapods to integrate XMPPFramework in your own project. It will take care of adding all dependencies and perform all the required configuration steps.
     
    Here are the steps needed to get started:
     
       
    1.  
      Create a new iOS project in Xcode, if you do not have one.
       
      2.  
    2.  
      If you do not yet have a Podfile, create it if pod init command    from the project root directory.
       
      3.  
    3.  
      Edit your Podfile to use XMPPFramework as a target. It may looks like:
       
      4.  
     
    platform :ios, '6.0'\nuse_frameworks!\n\ntarget 'projectname' do\n   pod 'XMPPFramework'\nend\n
     
       
    1.  
      Run pod install command. It should download, install and    configure three pods.
       
      2.  
    2.  
      Open your XCode project with the newly created workspace file    instead of the project file. This is required by Cocoapods so that    you can use the installed Pods.
       
      3.  
    3.  
      At this stage, you should be able to build your project    successfully with the XMPP framework setup.
       
      4.  
    "},{"location":"ejabberd-faq/","title":"Frequently Asked Questions","text":""},{"location":"ejabberd-faq/#development-process","title":"Development process","text":""},{"location":"ejabberd-faq/#why-is-there-a-commercial-version-of-ejabberd","title":"Why is there a commercial version of ejabberd?","text":"
    Different needs for different users. Corporations and large scale deployments are very different from smaller deployments and community projects.
     
    While we put a huge development effort to have a product that is on the edge of innovation with ejabberd community version, we are requested to provide a stable version with long term commitment and high level of quality, testing, audit, etc.
     
    Maintaining such a version in parallel to the community version, along with extremely strong commitment in terms of availability and 24/7 support has a tangible cost. With ejabberd business edition we commit to a level of scalability and optimize the software until it is performing to the level agreed with the customer.
     
    Covering all those costs, along with all our Research and Development cost on ejabberd community in general is the real reason we need a business edition.
     
    The business edition is also a way for our customers to share the code between our customers only, thus retaining a huge competitive edge for a limited time (See next section).
     
    So, even if you are not using our business edition, this is a great benefit for you as a user of the community edition and the reason you have seen so many improvements since 2002. Thanks to our business edition customers, ejabberd project itself is a major contributor to Erlang and Elixir community.
    "},{"location":"ejabberd-faq/#does-processone-voluntarily-hold-some-code-in-ejabberd-community-to-push-toward-the-business-edition","title":"Does ProcessOne voluntarily hold some code in ejabberd community to push toward the business edition?","text":"
    No. We never do that and have no plan doing so with the code we produce and we own.
     
    However, when the code is paid by customer, they retain the ownership of the code. Part of our agreement is that the code produced for them will be limited to a restricted user base, ejabberd business edition until an agreed time expires, generally between 6 months and 1 year.
     
    This is extremely important for both the users of the commercial edition and the users of the community edition:
     
       
    •  
      For the business edition customers, this is a way to keep their business advantage. This is   fair as they paid for the development.
       
      •  
    •  
      This is also a great incentive for our customers as they benefit from   development for other customers (I guess they agree for the   reciprocal sharing of their own code with customers).
       
      •  
    •  
      This is fair for the community as the community edition users know   they will benefit from new extremely advanced features in a relatively near future.    For example, websocket module was contributed to   ejabberd community as part of this process.
       
      •  
     
    This is the model we have found to be fair to our broader user base and lets us produce an amazing code base that benefits all our users.
     
    This dual model is the core strength of our approach and our secret sauce to make sure everyone benefits.
    "},{"location":"ejabberd-faq/#performance","title":"Performance","text":""},{"location":"ejabberd-faq/#is-ejabberd-the-most-scalable-version","title":"Is ejabberd the most scalable version?","text":"
    Yes. Definitely. Despite claims that there is small change you can make to make it more scalable, we already performed the changes during the past year, that make those claims unfunded:
     
       
    •  
      ejabberd reduced memory consumption in 2013 by switching to binary   representation of string instead of list. This can reduce given   string by 8.
       
      •  
    •  
      We have improved the C code performance a lot, using new Erlang   NIF. This provides better performance, removes bottlenecks
       
      •  
    •  
      We have a different clustering mechanism available to make sure we can   scale to large clusters
       
      •  
     
    This is a common misconception, but our feedback for production service on various customer sites shows that ejabberd is the most scalable version. Once it is properly configured, optimized and tuned, you can handle tens of millions of users on ejabberd systems.
     
    ... And we are still improving :)
     
    As a reference, you should read the following blog post: ejabberd Massive Scalability: 1 Node \u2014 2+ Million Concurrent Users
    "},{"location":"ejabberd-faq/#what-are-the-tips-to-optimize-performance","title":"What are the tips to optimize performance?","text":"
    Optimisation of XMPP servers performance, including ejabberd, is highly dependent on the use case. You really need to find your bottleneck(s) by monitoring the process queues, finding out what is your limiting factor, tune that and then move to the next one.
     
    The first step is to make sure you run the latest ejabberd. Each new release comes with a bunch of optimisations and a specific bottleneck you are facing may have gone away in the latest version.
     
    For perspective, ejabberd 15.07 is 2 to 3 times more efficient in memory, latency and CPU compared to ejabberd 2.1.
     
    You should also make sure that you are using the latest Erlang version. Each release of Erlang comes with more optimisation regarding locks, especially on SMP servers, and using the latest Erlang version can also help tremendously.
    "},{"location":"ejabberd-faq/#erlang-support","title":"Erlang support","text":""},{"location":"ejabberd-faq/#is-ejabberd-conforming-to-the-best-erlang-practices","title":"Is ejabberd conforming to the best Erlang practices?","text":"
    Yes. Our build system is primarily based on rebar. However, as we are multiplatform and need to run in many various environments, we rely on a toolchain that can detect required library dependencies using autotools.
     
    This gives developers and admins the best of both worlds. A very flexible and very versatile build chain, that is very adequate to make sure ejabberd can be used in most operating systems and even integrated in Linux distributions.
    "},{"location":"get-started/","title":"Getting started \ud83d\udc4b","text":""},{"location":"get-started/#meet-ejabberd-your-superpowerful-messaging-framework","title":"Meet ejabberd, your superpowerful messaging framework","text":"
    This web site is dedicated to help you use and develop for ejabberd XMPP messaging server.
     
    ejabberd has been in development since 2002 and is used all over the world to power the largest XMPP deployments. This project is so versatile that you can deploy it and customize it for very large scale, no matter what your use case is.
     
    This incredible power comes with a price. You need to learn how to leverage it. Fortunately, the goal of this website is to get you started on your path to mastery. Whether you are a sysadmin, an architect, a developer planning to extend it, or even a simple XMPP user, we have something for you here.
    "},{"location":"get-started/#overview","title":"Overview","text":"
    ejabberd is the de facto XMPP server in the world. The fact that it is used to power the largest deployments in the world should not intimidate you. ejabberd is equally suitable for small instances.
     
    ejabberd has been designed from the ground-up, since 2002 for robust, enterprise deployment. The goal has always been to shoot for the moon and this is what made it a long-lasting success.
     
    ejabberd is specifically designed for enterprise purposes: it is fault-tolerant, can utilise the resources of multiple clustered machines, and can easily scale when more capacity is required (by just adding a box/VM).
     
    Designed at a moment when clients were mostly desktops that only supported a kind of HTTP polling call BOSH, the project managed to adapt to recent changes by introducing support for WebSockets, BOSH improvements, and a solid mobile  stack.
     
    It was developed at a time when XMPP was still known as \"Jabber\", but quickly adopted an evolution process in order to support the various versions of XMPP RFCs. It now encourages innovation and experimentation by supporting most, if not all, extensions produced by the XSF.
     
    ejabberd relies on a dynamic community all over the world. To get an idea of existing contributions, you can check ejabberd main repository or the repository containing a great amount of contributed extensions.
     
    This is possible thanks to a modular architecture based on a core router and an extremely powerful plugin mechanism that is getting richer every day.
     
    Welcome to the beginning of your journey of ejabberd mastery!
    "},{"location":"get-started/#options-to-use-ejabberd","title":"Options to use ejabberd","text":"
    ejabberd can be used in different ways. The most common one is to use ejabberd Community Edition. This is the standard Open Source version that everyone loves: highly scalable and flexible.
     
    Fortunately, if you need more than just the ejabberd platform software, ProcessOne can help you with a commercial offering. Commercial offering come in two type of packaging:
     
       
    •  
      ejabberd Business Edition, including features for large companies   (enhanced geodistributed companies and mobile support to develop   own, rich clients) and world-class support, that can please even the   most demanding businesses, with 24/7 options.
       
      •  
    •  
      Fluux.io being a way to access and benefit of all the features   of ejabberd Business Edition at an attractive and scalable   price. Fluux.io allows you to keep control of your data thanks   to integration API you can implement on your backend to become a   data provider for ejabberd SaaS.
       
      •  
     
    Whatever approach you choose, you can hardly make the wrong choice with ejabberd! In every case you can easily integrate ejabberd with your existing application using:
     
       
    • REST API and ejabberdctl command-line tool
      •  
    • Mobile libraries for iOS: XMPPFramework, Jayme REST API
      •  
    • Mobile libraries for Android: Smack, Retrofit
      •  
    • Web library with WebSocket support and fallback to BOSH: Strophe
      •  
    "},{"location":"get-started/#architecture-of-an-ejabberd-service","title":"Architecture of an ejabberd service","text":"
    ejabberd brings configurability, scalability and fault-tolerance to the core feature of XMPP \u2013 routing messages.
     
    Its architecture is based on a set of pluggable modules that enable different features, including:
     
       
    • One-to-one messaging
      •  
    • Store-and-forward (offline messages)
      •  
    • Contact list (roster) and presence
      •  
    • Groupchat: MUC (Multi-User Chat)
      •  
    • Messaging archiving with Message Archive Management (MAM)
      •  
    • User presence extension: Personal Event Protocol (PEP) and typing indicator
      •  
    • Privacy settings, through privacy list and simple blocking extensions
      •  
    • User profile with vCards
      •  
    • Full feature web support, with BOSH and websockets
      •  
    • Stream management for message reliability on mobile (aka XEP-0198)
      •  
    • Message Delivery Receipts (aka XEP-184)
      •  
    • Last activity
      •  
    • Metrics and full command-line administration
      •  
    • and many many more.
      •  
     
    The full list of supported protocol and extensions is available on Protocols Supported by ejabberd page.
     
    This modular architecture allows high customisability and easy access to the required features.
     
    ejabberd enables authenticating users using external or internal databases (Mnesia, SQL), LDAP or external scripts. It also allows connecting anonymous users, when required.
     
    For storing persistent data, ejabberd uses Mnesia (the distributed internal Erlang database), but you can opt for SQL database like MySQL or PostgreSQL
     
    And of course, thanks to its API, ejabberd can be customised to work with a database chosen by the customer.
    "},{"location":"get-started/#deploying-and-managing-an-ejabberd-service","title":"Deploying and managing an ejabberd service","text":"
    ejabberd can be deployed for a number of scenarios fitting end-user / developer / customer needs. The default installation setup consists of a single ejabberd node using Mnesia, so it does not require any additional configuration. This primary system is sufficient for fast deployment and connecting XMPP clients. It should be good enough for most of the small deployments (and even medium ones).
     
    A more scalable solution would be deploying ejabberd with an external database for persistent data. As Mnesia is caching part of its data in ejabberd memory (actually in Erlang VM node), this kind of setup make your system more scalable and typically easier to integrate with your usual database. As a sysadmin, yes, you can use your standard backup process.
     
    Those larger setup can run as a cluster of ejabberd nodes. This is a clustering mode where all nodes are active, so it can be use for fault-tolerance, but also to increase the capacity of your ejabberd deployment.
     
    With such a deployment you can load balance the traffic to your cluster node using one of the following solution:
     
       
    • traditional TCP/IP load balancer (beware of the cost of your solution, typical XMPP connections are persistent).
      •  
    • DNS load balancing.
      •  
    • Custom approach that requires client cooperation.
      •  
     
    If deployed on a 16 GB RAM machine with at least 4 cores, a single ejabberd node can typically handle 200-300 K online users. This setup is suitable for systems with up to 10 nodes.
     
    Note that your mileage may vary depending on your use case, the feature your are using and how clean the architecture design and the client is developed. That's why, if you plan to reach huge volume, it is recommended to start asking advices from day 1 to an ejabberd expert. Initial mistakes in the solution design are harder to fix once the project is in production.
     
    If the service requires a cluster of more than 10 nodes, we recommend not relying on Mnesia clustering mode. Many solutions are available, the easiest and more inexpensive being to rely on ejabberd Software-as-a-Service approach.
     
    ejabberd also allows connecting different clusters as parts of larger systems. This is a standard XMPP feature call server-to-server (aka s2s in XMPP lingo). It is used in geo-localised services handling massive traffic from all over the world. Special extension are also available from ProcessOne to handle geodistribution in an even more robust way.
     
    To manage the users, rosters, messages and general settings, we provide a command-line tool, ejabberdctl. That command-line allows you to gather metrics from ejabberd to be able to monitor what is happening in your system, understand and even anticipate issues.
     
    The main benefit of ejabberd is the ability to reach a command-line to type Erlang commands. This allows you to fix and troubleshoot most of the tricky situation and even update and reload code without stopping the service. This is a life saver for your uptime.
     
    Welcome to the benefit of Erlang hot-code swapping!
    "},{"location":"get-started/#ejabberd-is-more-than-xmpp","title":"ejabberd is more than XMPP","text":"
    Thanks to the modular architecture of ejabberd, the platform is becoming a core component for messaging applications.
     
    Messaging applications require to transfer more than text messages. ejabberd has grow a full set of media related features that makes ejabberd a great choice to support voice and video applications, but also to proxy various kind of media transfer (images, audio and video files for example).
     
    As such, ejabberd support:
     
       
    • Jingle, XMPP based voice protocol
      •  
    • SIP (Session Initiation Protocol): Yes, you can pass SIP calls using ejabberd :)
      •  
    • ICE (Interactive Connectivity Establishment: A Protocol for Network Address Translator (NAT) Traversal)
      •  
    • STUN
      •  
    • TURN
      •  
    • Proxy65 media relay
      •  
     
    This makes ejabberd the best XMPP server to support SIP and WebRTC based communication tools.
    "},{"location":"get-started/#helping-us-in-the-development-process","title":"Helping us in the development process","text":"
    With thousands of more or less official forks, the core ejabberd team, supported by ProcessOne, is constantly monitoring and reviewing improvements.  We use our 15 years of experience to filter the best ideas or improvements to make sure ejabberd is always your most solid choice in term of scalability, robustness and manageability.
     
    The best way to start developing for ejabberd is to clone, watch and star the project, to get in touch on our developer chatroom (ejabberd@conference.process-one.net) or to join ejabberd community on StackOverflow.
    "},{"location":"livebooks/ejabberd-developer-livebook/","title":"The ejabberd Developer Livebook","text":"
    Info
     
    This page is designed to run interactively using Livebook. Of course, you could simply reproduce the instructions manually yourself. But, if possible, install Livebook in your machine and get the full experience clicking on the button:
     
     
    filename = \"ejabberd.yml\"\n\nif File.exists?(filename) do\n  Mix.install([\n    {:ejabberd, \"~> 24.2\"},\n    {:kino, \"~> 0.12.3\"}\n  ])\nelse\n  url = \"https://raw.githubusercontent.com/processone/ejabberd/master/ejabberd.yml.example\"\n\n  Mix.install([:req]) &&\n    File.write!(\n      filename,\n      String.replace(Req.get!(url).body, \"starttls_required: true\", \"\")\n    )\n\n  IO.puts(\"ejabberd.yml downloaded correctly, click 'Reconnect and setup' to download ejabberd.\")\nend\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#setup-ejabberd-inside-livebook","title":"Setup ejabberd inside livebook","text":"
    This Livebook will download, compile and install ejabberd:
     
       
    1.  
      If you want to use a specific ejabberd.yml configuration file, copy it to your Livebook folder.
       
      2.  
    2.  
      On top of this page, click Setup.
       
      3.  
    3.  
      If ejabberd.yml is not found, it will be downloaded from ejabberd git repository.
       
      4.  
    4.  
      Click Reconnect and setup to download ejabberd and all its dependencies. It will be compiled and started... it may take a pair of minutes.
       
      5.  
     
    Alternatively, if you already have ejabberd installed and running in your system, you can connect livebook to your ejabberd node
    "},{"location":"livebooks/ejabberd-developer-livebook/#execute-some-erlang-code","title":"Execute some Erlang code","text":"
    Now that Livebook is connected a running ejabberd node, you can run Erlang and Elixir code from this page directly in your node.
     
    For example, to run some erlang code, put your mouse over the new lines and click on Evaluate:
     
    ejabberd_admin:registered_vhosts().\n
     
    Let's define the details of an account, we will later register it. You may change those values:
     
    Username = <<\"user1\">>,\nServer = <<\"localhost\">>,\nPassword = <<\"somepass123\">>,\n{Username, Server, Password}.\n
     
    Now let's execute an Erlang function to register the account:
     
    ejabberd_auth:try_register(Username, Server, Password).\n
     
    Let's check the account was registered:
     
    ejabberd_auth:get_users(<<\"localhost\">>).\n
     
    And is the account's password the one we introduced?
     
    Password == ejabberd_auth:get_password(Username, Server).\n
     
    Ok, enough for now, let's remove the account:
     
    ejabberd_auth:remove_user(Username, Server).\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#execute-some-elixir-code","title":"Execute some Elixir code","text":"
    The same code of the previous section can be executed using Elixir:
     
    :ejabberd_admin.registered_vhosts()\n
     
    username = <<\"user1\">>\nserver = <<\"localhost\">>\npassword = <<\"somepass123\">>\n{username, server, password}\n
     
    :ejabberd_auth.try_register(username, server, password)\n
     
    :ejabberd_auth.get_users(server)\n
     
    password == :ejabberd_auth.get_password(username, server)\n
     
    :ejabberd_auth.remove_user(username, server)\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#run-api-commands","title":"Run API commands","text":"
    Let's run some ejabberd API commands using the ejabberd_ctl frontend (there is is also mod_http_api and ejabberd_xmlrpc).
     
    For example, the status API command:
     
    ejabberd_ctl:process([\"status\"]).\n
     
    How to register an account using ejabberd_ctl to call the API command
     
    command = ~c\"register\"\n:ejabberd_ctl.process([command, username, server, password])\n
     
    If you have ejabberd installed in the the system, and the ejabberdctl command-line script is available in your PATH, then you could also try to execute with:
     
    os:cmd(\"ejabberdctl status\").\n
     
    :os.cmd(~c\"ejabberdctl status\")\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#draw-process-structure","title":"Draw process structure","text":"
    Let's view the ejabberd process tree:
     
    Kino.Process.render_app_tree(:ejabberd, direction: :left_right)\n
     
    Let's view the erlang processes that handle XMPP client connections. If this graph is empty, login to ejabberd with a client and reevaluate this code:
     
    Kino.Process.render_sup_tree(:ejabberd_c2s_sup, direction: :left_right)\n
     
    And some information about the erlang process that handles the XMPP client session:
     
    [resource] = :ejabberd_sm.get_user_resources(username, server)\nElixir.Process.info(:ejabberd_sm.get_session_pid(username, server, resource))\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#connect-livebook-to-your-ejabberd-node","title":"Connect Livebook to your ejabberd node","text":"
    By default this livebook downloads, compiles and starts ejabberd by setting up ejabberd sinde livebook. If you already have ejabberd installed and would like to connect this livebook to your existing ejabberd node, follow those steps:
    "},{"location":"livebooks/ejabberd-developer-livebook/#get-erlang-node-name","title":"Get erlang node name","text":"
    To connect Livebook to your running ejabberd node, you must know its erlang node name and its cookie.
     
    The erlang node name is by default ejabberd@localhost. You can check this in many places, for example:
     
       
    • Using ejabberdctl status:
      •  
     
    $ ejabberdctl status\nThe node ejabberd@localhost is started with status: started\nejabberd 24.2.52 is running in that node\n
     
       
    • In the ejabberd.log file, which contains a line like:
      •  
     
    2024-03-26 13:18:35.019288+01:00 [info] <0.216.0>@ejabberd_app:start/2:63\nejabberd 24.2.52 is started in the node ejabberd@localhost in 0.91s\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#setup-ejabberd-node","title":"Setup ejabberd node","text":"
    A Livebook can only connect to an Erlang node that has Elixir support. So, make sure you install not only Erlang, but also Elixir.
     
    When compiling ejabberd, make sure to enable Elixir support. It should get enabled by default, but you can ensure this: either by ./configure --with-rebar=mix or by ./configure --enable-elixir.
     
    Then start ejabberd with IEx shell: ejabberdctl iexlive
    "},{"location":"livebooks/ejabberd-developer-livebook/#get-erlang-cookie","title":"Get erlang cookie","text":"
    The erlang cookie is a random string of capital letters required to connect to an existing erlang node.
     
    You can get it in a running node, simply call:
     
    :erlang.get_cookie()\n:XQFOPGGPSNEZNUWKRZJU\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#connect-this-livebook-to-your-ejabberd-node","title":"Connect this livebook to your ejabberd node","text":"
    Now that you have ejabberd running, and you know the information required to connect to it:
     
       
    1. go to Livebook
      2.  
    2. in the left side bar, click the Runtime settings icon, or press sr keyboard shortcut
      3.  
    3. click the Configure button
      4.  
    4. click the Attached node button
      5.  
    5. introduce the erlang node name (ejabberd@localhost) and cookie (XQFOPGGPSNEZNUWKRZJU) of your ejabberd node
      6.  
    6. click the Connect button (it may say Reconnect)
      7.  
    7. If it connected successfully, it will now show memory consumption of that node
      8.  
    "},{"location":"livebooks/ejabberd-developer-livebook/#test-the-connection","title":"Test the connection","text":"
    Now that Livebook is connected to your running ejabberd node, you can run Erlang and Elixir code from this page directly in your node.
     
    For example, to run some erlang code, put your mouse over the new lines and click on Evaluate:
     
    ejabberd_admin:registered_vhosts().\n
     
    The same code can be executed using Elixir:
     
    :ejabberd_admin.registered_vhosts()\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#stop-ejabberd","title":"Stop ejabberd","text":"
    Let' stop ejabberd insie livebook
     
    :ejabberd.stop()\n
    "},{"location":"roadmap/","title":"ejabberd Roadmap","text":""},{"location":"roadmap/#in-the-works","title":"In the Works","text":"
       
    •  
      Rework ejabberd Docs
       
      The ejabberd Docs site needs some reorganization, as some sections has grown quite a lot and would better be reorganized.
       
      •  
    "},{"location":"roadmap/#planned","title":"Planned","text":"
       
    •  
      Set as default automatic SQL schema update
       
      Automatic SQL schema update was included as a beta-testing feature in ejabberd 23.10 (see the feature announcement), and it will become the default. 
       
      •  
    •  
      Remove support for Rebar2
       
      ejabberd includes many tweaks to support rebar3 and rebar2. By removing support for rebar2, we could simplify rebar.config and other files a lot. But more importantly, dependencies would not need to be updated just because other dependencies are updated: Rebar2 requires exact version numbers to be provided, Rebar3 doesn't require that, and neither does Mix.
       
      •  
    "},{"location":"roadmap/#released","title":"Released","text":""},{"location":"roadmap/#2024","title":"2024","text":"
       
    • 24.02
         
      • Matrix gateway
        •  
      • RFC 9266 Channel Bindings for TLS 1.3
        •  
      • XEP-0386: Bind 2
        •  
      • XEP-0388: Extensible SASL Profile (SASL2)
        •  
      • XEP-0424: Message Retraction
        •  
      • XEP-0440: SASL Channel-Binding Type Capability
        •  
      • XEP-0474: SASL SCRAM Downgrade Protection
        •  
      • XEP-0480: SASL Upgrade Tasks
        •  
      • Automatic SQL schema creation and update
        •  
      • Commands API versioning
        •  
      • Support Elixir 1.16 and Erlang/OTP 27.0-rc1
        •  
       
      •  
    "},{"location":"roadmap/#2023","title":"2023","text":"
       
    •  
      23.10
       
         
      • Support for XEP-0402: PEP Native Bookmarks
        •  
      • Support for XEP-0421: Occupant Id
        •  
      • MySQL Performance enhancements
        •  
       
      •  
    •  
      23.04
       
         
      • mod_mam support for XEP-0425: Message Moderation
        •  
      • New mod_muc_rtbl: Real-Time Block List for MUC rooms
        •  
      • Binaries use Erlang/OTP 25.3, and changes in containers
        •  
       
      •  
    •  
      23.01
       
         
      • New mod_mqtt_bridge: MQTT bridge
        •  
       
      •  
    "},{"location":"roadmap/#2022","title":"2022","text":"
       
    •  
      22.10
       
         
      • Improved MIX support
        •  
      • Improved SQL reconnection Mechanism
        •  
      • Better burst traffix handling
        •  
       
      •  
    •  
      22.05
       
         
      • Improved MQTT, MUC and ConverseJS integration
        •  
      • New installers and container image
        •  
      • Support for Erlang/OTP 25
        •  
       
      •  
    "},{"location":"roadmap/#2021","title":"2021","text":"
       
    •  
      21.12
       
         
      • New mod_conversejs: built-in ConverseJS web client
        •  
      • Support for MUC Hats extension
        •  
      • PubSub, MucSub and Multicast improvements
        •  
       
      •  
    •  
      21.07
       
         
      • Improved database and caching for shared rosters
        •  
      • Broader multicast support for MUC
        •  
      • Improved rebar3 and Elixir support
        •  
       
      •  
    •  
      21.04
       
         
      • Full support for Erlang/OTP 24 and rebar3
        •  
      • New API commands
        •  
      • New CAPTCHA script
        •  
       
      •  
    •  
      21.01
       
         
      • Systemd watchdog support
        •  
      • STUN improvements
        •  
       
      •  
    "},{"location":"roadmap/#2020","title":"2020","text":"
       
    •  
      20.12
       
         
      • Extended SCRAM-SHA support
        •  
      • Microsoft ODBC Driver support
        •  
       
      •  
    •  
      20.07
       
         
      • Support for Unix Domain Sockets
        •  
      • Erlang/OTP 23 compatibility
        •  
       
      •  
    •  
      20.04
       
         
      • New mod_stun_disco: support XEP-0215 including Audio/Video calls
        •  
      • Improved MS SQL support
        •  
       
      •  
    •  
      20.03
       
         
      • SSL connection to MySQL
        •  
      • Improved performance of mod_shared_roster
        •  
       
      •  
    •  
      20.02
       
         
      • Improved compatibility with CockroachDB
        •  
      • Emoji storage in MSSQL
        •  
       
      •  
    •  
      20.01
       
         
      • OAuth support for ejabberd's MQTT
        •  
      • New OTP 22 event logger
        •  
      • New config parser & validator
        •  
       
      •  
    "},{"location":"roadmap/#2019","title":"2019","text":"
       
    •  
      19.09
       
         
      • Significant improvements in ACME support: ACME v2
        •  
      • Erlang/OTP 19.3 is required
        •  
       
      •  
    •  
      19.08
       
         
      • New JWT (JSON Web Token) authentication
        •  
      • New configuration validator, yconf
        •  
      • Improved MUC scalability
        •  
      • Removed Riak support
        •  
       
      •  
    •  
      19.05
       
         
      • MQTT over WebSocket
        •  
      • Improved MucSub
        •  
      • Erlang/OTP 19.1 is required
        •  
       
      •  
    •  
      19.02
       
         
      • MQTT Support
        •  
      • MIX improvements
        •  
       
      •  
    "},{"location":"roadmap/#2018","title":"2018","text":"
       
    •  
      18.12
       
         
      • XML Compression in message archive storage
        •  
      • PROXY protocol support versions 1 and 2
        •  
      • MUC Self-Ping server optimisation (XEP-0410)
        •  
      • Bookmarks Conversion (XEP-0411)
        •  
       
      •  
    •  
      18.09
       
         
      • Default configuration file simplification
        •  
      • Improved logging
        •  
      • OpenSSL 1.1.1 support
        •  
      • Modular ejabberd core
        •  
       
      •  
    •  
      18.06
       
         
      • Stop ejabberd initialization on invalid/unknown options
        •  
      • Support SASL PLAIN
        •  
      • Drop support of mod_irc
        •  
       
      •  
    •  
      18.04
       
      •  
    •  
      18.03
       
         
      • New SQL schemas with server_host
        •  
       
      •  
    •  
      18.01
       
      •  
    "},{"location":"roadmap/#2017","title":"2017","text":"
       
    •  
      17.12
       
         
      • SNI (Server Name Indication) for inbound connections
        •  
      • Rewrite ejabberd system monitor
        •  
      • Support PubSub v1.14 and OMEMO
        •  
       
      •  
    •  
      17.11
       
         
      • ACME Support
        •  
      • Introduce \u2018certfiles\u2019 global option
        •  
      • PubSub improved, and SQL storage
        •  
       
      •  
    •  
      17.09
       
         
      • New mod_avatar
        •  
      • SRV for XMPP over TLS
        •  
       
      •  
    •  
      17.08
       
         
      • XEP-0357: Push Notifications
        •  
      • Modular cluster with cluster_backend
        •  
       
      •  
    •  
      17.07
       
      •  
    •  
      17.06
       
         
      • New Caching system
        •  
      • Extended Riak support
        •  
      • Certificate manager
        •  
       
      •  
    •  
      17.04
       
      •  
    •  
      17.03
       
         
      • Modular code
        •  
      • Dynamic configuration reload
        •  
      • mod_blockstrangers for spam protection
        •  
      • S2S dialback
        •  
       
      •  
    •  
      17.01
       
         
      • PostgreSQL SSL support
        •  
       
      •  
    "},{"location":"roadmap/#2016","title":"2016","text":"
       
    •  
      16.12
       
         
      • New BOSH module
        •  
      • New Commands API permissions framework
        •  
      • XMPP packet handling using dedicated xmpp erlang library
        •  
      • New ejaberd/mix Docker container
        •  
       
      •  
    •  
      16.09
       
         
      • Support for Elixir configuration file
        •  
      • XEP-0355 Namespace Delegation
        •  
      • XEP-0356 Privileged Entity
        •  
       
      •  
    •  
      16.08
       
         
      • New MUC/Sub
        •  
      • Improved Elixir support
        •  
      • Major clean-up and improvement on OAuth ReST API
        •  
       
      •  
    •  
      16.06
       
         
      • New ACL (Access Control List) infrastructure
        •  
       
      •  
    •  
      16.04
       
      •  
    •  
      16.03
       
         
      • Experimental support for MIX (Mediated Information eXchange)
        •  
      • Erlang/OTP 17.5 required
        •  
       
      •  
    •  
      16.02
       
         
      • XEP-0013 Flexible Offline Message Retrieval
        •  
      • Improved Message Archive Management (MAM)
        •  
      • Published ejabberd on hex.pm
        •  
      • Faster and more memory efficient XML parsing and TLS encryption.
        •  
      • Stream compression after SASL
        •  
      • Migration script from Prosody
        •  
       
      •  
    •  
      16.01
       
      •  
    "},{"location":"roadmap/#2015","title":"2015","text":"
       
    •  
      15.11
       
         
      • Improved join_cluster and leave_cluster
        •  
       
      •  
    •  
      15.10
       
         
      • New mod_http_upload with support for XEP-0363 HTTP File Upload
        •  
      • Added support for Grapherl
        •  
       
      •  
    •  
      15.09
       
         
      • OAuth 2.0 delegation framework
        •  
      • Preliminary OAuth and HTTP based ejabberd API
        •  
      • X-AUTH2 authentication mechanism
        •  
       
      •  
    •  
      15.07
       
      •  
    •  
      15.06
       
         
      • New mod_mam with XEP-0313 Message Archive Management
        •  
      • Configuration checking on launch
        •  
      • Added Windows 7/8 installers, RPM and DEB packages
        •  
      • Document protocol support and version inside each module
        •  
       
      •  
    •  
      15.04
       
         
      • Added mod_admin_extra and mod_muc_admin
        •  
      • Added XEP-0033 Extended Stanza Addressing
        •  
      • Support to embed ejabberd in an Elixir app
        •  
      • Erlang/OTP R16B03-1 is required
        •  
       
      •  
    •  
      15.03
       
         
      • Added support for WebSocket
        •  
      • Customizable session backends
        •  
      • SCRAM support for SQL authentication backend
        •  
       
      •  
    •  
      15.02
       
         
      • Added Elixir support
        •  
      • New command to reload configuration withour restart
        •  
      • New documentation site published: docs.ejabberd.im/
        •  
      • Bug tracker moves from JIRA to GitHub Issues
        •  
       
      •  
    •  
      Revamped ejabberd website, new logo, new development process and bugtracking migrated from JIRA to GitHub
       
      •  
    "},{"location":"roadmap/#2014","title":"2014","text":"
       
    •  
      14.12
       
         
      • New mod_client_state with XEP-0352: Client State Indication
        •  
      • New mod_fail2ban
        •  
       
      •  
    •  
      14.07
       
         
      • SIP Outbound (RFC 5626)
        •  
       
      •  
    •  
      14.05
       
         
      • RFC-3261 SIP proxy/registrar
        •  
      • RFC-5766 TURN: Traversal Using Relays around NAT
        •  
      • XEP-0198 Stream Management
        •  
      • XEP-0321 Remote Roster Management
        •  
      • Several improvements regarding encryption
        •  
      • New Bash completion script for ejabberdctl
        •  
       
      •  
    "},{"location":"roadmap/#2013","title":"2013","text":"
       
    •  
      13.12
       
         
      • New OpenSSL ciphers option in c2s, s2s and s2s_out
        •  
      • ejabberd_xmlrpc included
        •  
       
      •  
    •  
      13.10
       
         
      • ejabberd configuration file in YAML format
        •  
      • Log files are created using Lager
        •  
      • Rebar2 is used to manage dependencies
        •  
      • Erlang/OTP R15 is required
        •  
       
      •  
    •  
      13.03-beta1 (announcement)
       
         
      • Binarize and indent code
        •  
      • New versioning scheme
        •  
       
      •  
    "},{"location":"roadmap/#2012","title":"2012","text":"
       
    • 2.1.11
         
      • Added ODBC support for several modules
        •  
       
      •  
    "},{"location":"roadmap/#2011","title":"2011","text":"
       
    •  
      2.1.10
       
      •  
    •  
      2.1.9
       
         
      • New SASL SCRAM-SHA-1 authentication mechanism
        •  
       
      •  
    "},{"location":"roadmap/#2010","title":"2010","text":"
       
    •  
      2.1.6
       
         
      • mod_register: New captcha_protected option to require CAPTCHA
        •  
      • Support PostgreSQL 9.0
        •  
       
      •  
    •  
      October: the source code repository and the bug tracker were finally moved to GitHub
       
      •  
    •  
      2.1.5
       
      •  
    •  
      2.1.4
       
         
      • Full support for XEP-0115 Entity Capabilities v1.5
        •  
       
      •  
    •  
      2.1.2
       
      •  
    "},{"location":"roadmap/#2009","title":"2009","text":"
       
    •  
      2.1.1
       
      •  
    •  
      2.1.0
       
         
      • LDAPS support
        •  
      • STUN server
        •  
      • New XEPs supported: XMPP Ping, Roster Versioning, Import/Export Format
        •  
      • Erlang/OTP R13 is supported
        •  
       
      •  
    •  
      2.0.5 (announcement)
       
      •  
    •  
      2.0.4 (announcement)
       
      •  
    •  
      2.0.3 (announcement)
       
      •  
    "},{"location":"roadmap/#2008","title":"2008","text":"
       
    •  
      2.0.2 (announcement)
       
      •  
    •  
      2.0.1 (announcement)
       
      •  
    •  
      2.0.0 (announcement)
       
         
      • New front-end and back-end cluster architecture
        •  
      • Complete rewrite of the PubSub module
        •  
      • New Proxy65 file transfer proxy
        •  
      • BOSH support
        •  
      • Many more improvements
        •  
       
      •  
    "},{"location":"roadmap/#2007","title":"2007","text":"
       
    •  
      1.1.4
       
      •  
    •  
      1.1.3
       
      •  
    "},{"location":"roadmap/#2006","title":"2006","text":"
       
    •  
      1.1.2 (announcement)
       
         
      • LDAP improvements
        •  
      • Microsoft SQL supported
        •  
      • New Windows installer
        •  
       
      •  
    •  
      1.1.1 (announcement)
       
         
      • Erlang/OTP R9C-2 required
        •  
       
      •  
    •  
      1.1.0 (announcement)
       
         
      • JEP-0050: Ad-Hoc Commands
        •  
      • JEP-0138: Stream Compression
        •  
      • JEP-0175: SASL anonymous
        •  
      • Native MySQL support
        •  
      • MUC improvement: Chatroom logging
        •  
       
      •  
    "},{"location":"roadmap/#2005","title":"2005","text":"
       
    •  
      1.0.0 (announcement)
       
         
      • S2S encryption: STARTTLS + SASL_EXTERNAL and STARTTLS + Dialback
        •  
      • Different certificates can be defined for each virtual host.
        •  
      • Support for vCard storage in ODBC
        •  
      • New tool to convert Mnesia to ODBC
        •  
      • Native PostgreSQL support
        •  
       
      •  
    •  
      0.9.8 (announcement)
       
         
      • Enhanced virtual hosting
        •  
      • Enhanced PubSub
        •  
       
      •  
    •  
      0.9.1 (announcement)
       
      •  
    •  
      0.9 (announcement)
       
         
      • Added support for virtual hosts
        •  
      • New mod_shared_roster
        •  
      • Added PostgreSQL support
        •  
       
      •  
    •  
      February: source code moved from SVN to Git, and the bug tracker from Bugzilla to JIRA
       
      •  
    •  
      Beginning of 2005, source code moved from JabberStudio CVS to ProcessOne SVN
       
      •  
    "},{"location":"roadmap/#2004","title":"2004","text":"
       
    •  
      October: website moved from JabberStudio to ejabberd.jabber.ru, and the bug tracker to Jabber.ru\u2019s Bugzilla
       
      •  
    •  
      0.7.5
       
         
      • Support for STARTTLS with C2S connections
        •  
      • Support for authentification via external script
        •  
      • Added module which implement JUD and vCard services using LDAP
        •  
      • Improvements in web-based administration interface (user creation/removal, roster and offline queue management)
        •  
      • Support for message expiration (JEP-0023)
        •  
      • Support for HTTPS in web interface
        •  
       
      •  
    •  
      0.7
       
         
      • Support for LDAP authentification
        •  
      • Support for HTTP Polling
        •  
      • Support for web-based administration interface
        •  
      • Added command-line administration utility \"ejabberdctl\"
        •  
      • Support for history management in MUC rooms
        •  
       
      •  
    "},{"location":"roadmap/#2003","title":"2003","text":"
       
    •  
      16th November, 0.5
       
         
      • First release
        •  
       
      •  
    •  
      January, initial documentation in LaTeX: Ejabberd Installation and Operation Guide
       
      •  
    "},{"location":"roadmap/#2002","title":"2002","text":"
       
    •  
      18th November, first commit to CVS
       
      •  
    •  
      16th November, first erlang modules written
       
      •  
    "},{"location":"tutorials/","title":"ejabberd and XMPP tutorials","text":"
    Learning ejabberd and XMPP through videos and hands-on tutorials.
    "},{"location":"tutorials/#text-tutorials","title":"Text tutorials","text":"
    In the ProcessOne's blog Tutorial tag you will find tutorials about:
     
       
    •  
      How to setup MariaDB, MQTT, PubSub, STUN/TURN, WebSocket.
       
      •  
    •  
      Elixir: Part 1, Part 2, Embed in Phoenix, Embed in Elixir app.
       
      •  
    •  
      Useful configuration steps
       
      •  
    •  
      Configuration for Office IM
       
      •  
    •  
      Configuration for XMPP compliance test
       
      •  
    •  
      Using a local development trusted CA on MacOS
       
      •  
     
    In the so-called ejabberd book there are also old archived ejabberd tutorials.
    "},{"location":"tutorials/#architecture","title":"Architecture","text":"
       
    •  
      Understanding ejabberd SaaS architecture
       
      Excerpt from XMPP Academy #1 starting at 1m33s.
       
      •  
    •  
      What are ejabberd backends? What backends are available in ejabberd and how do they work?
       
      Excerpt from XMPP Academy #2 starting at 2m05s.
       
      •  
    •  
      ejabberd backends architecture
       
      Excerpt from XMPP Academy #2 starting at 14m00s.
       
      •  
    •  
      What are ejabberd session backends and how to use them to scale?
       
      Excerpt from XMPP Academy #2 starting at 19m42s.
       
      •  
    "},{"location":"tutorials/#xmpp-on-mobile-devices-smartphones","title":"XMPP on mobile devices (smartphones)","text":"
       
    •  
      Mobile XMPP support on ejabberd SaaS and Business Edition: Standby, push and detached modes
       
      Excerpt from XMPP Academy #1 starting at 16m44s.
       
      •  
    •  
      How does Apple and Google Push support work on ejabberd SaaS and ejabberd Business Edition?
       
      Excerpt from XMPP Academy #3 starting at 1m20s.
       
      •  
    •  
      What is the relationship between ejabberd Push support and XEP-0357: Push Notifications?
       
      Excerpt from XMPP Academy #3 starting at 22m34s.
       
      •  
    •  
      What are message carbons and how do they work?
       
      Excerpt from XMPP Academy #2 starting at 27m30s.
       
      •  
    •  
      Demo: learning message carbons with Psi XMPP console
       
      Excerpt from XMPP Academy #2 starting at 29m51s.
       
      •  
    "},{"location":"tutorials/#xmpp-for-the-web","title":"XMPP for the Web","text":"
       
    •  
      ejabberd roadmap: announcing OAuth2 support
       
      Excerpt from XMPP Academy #1 starting at 27m43s.
       
      •  
    •  
      What is the impact of Websocket on Web chat performance?
       
      Excerpt from XMPP Academy #3 starting at 25m02s.
       
      •  
    "},{"location":"tutorials/#multi-user-chat","title":"Multi-User Chat","text":"
       
    • Why do avatars / carbons not work in MUC rooms? What is special about MUC rooms? 
      Excerpt from XMPP Academy #2 starting at 34m15s.
       
      •  
    "},{"location":"tutorials/#developer-tools-and-techniques","title":"Developer tools and techniques","text":"
       
    • What are the typical tools for quick XMPP prototyping?
      •  
    "},{"location":"tutorials/#ejabberd-and-xmpp-server-side-implementation","title":"ejabberd and XMPP server-side implementation","text":"
       
    •  
      How does ejabberd internally store messages which are not yet delivered?
       
      •  
    •  
      How are privacy lists managed in ejabberd?
       
      •  
    •  
      Why do we seem to find duplicate in Message Archive Management backend?
       
      Excerpt from XMPP Academy #3 starting at 32m20s.
       
      •  
    "},{"location":"tutorials/mix-010/","title":"Getting started with MIX","text":"
    MIX stands for Mediated Information eXchange and defined in MIX-CORE (XEP-0369), MIX-PRESENCE (XEP-0403) and MIX-PAM (XEP-0405). More concretely, ejabberd supports MIX 0.14.1.
     
    It is a work in progress extension for the XMPP protocol to build a group messaging protocol that does not rely on the presence mechanism. It is designed to overcome the limitation of Multi-User Chat (XEP-0045) , in a context where most clients are mobile clients.
     
    To do so, MIX is built on top of PubSub (XEP-0060) and use different nodes per channel to separate event types. There is five nodes to support five different types of event for each MIX channel:
     
       
    • Messages
      •  
    • Presence
      •  
    • Participant list changes
      •  
    • Subject update
      •  
    • Conversion configuration changes
      •  
     
    This is a work in progress, but this is a very important task and we are happy to provide the very first server implementation of the Mix protocol to get up to speed on that specification.
     
    Here is a short walk through what can already be done.
     
    Also note that the specification can (and will) change significantly before it becomes stable. These examples are based on XEP-0369 v0.1.
    "},{"location":"tutorials/mix-010/#configuration","title":"Configuration","text":"
    Configuration is simple:
     
       
    •  
      Install a recent ejabberd version (19.02 or newer)
       
      •  
    •  
      You need to add mod_mix and mod_mix_pam in ejabberd configuration, modules section:
       
      modules:\n  mod_mix: {}\n  mod_mix_pam: {}\n
       
      •  
    •  
      Make sure you have PubSub enabled. Default configuration is fine:
       
      modules:\n  mod_pubsub:\n    access_createnode: pubsub_createnode\n    plugins:\n      - \"flat\"\n      - \"pep\"\n
       
      •  
    •  
      The examples assume you have this virtual host:
       
      hosts:\n  - shakespeare.example\n
       
      •  
    "},{"location":"tutorials/mix-010/#usage","title":"Usage","text":"
    There is no client supporting MIX yet so here is how it works directly at XMPP stream level.
     
    Here are real-life examples from playing with our MIX implementation:
    "},{"location":"tutorials/mix-010/#creating-a-mix-channel","title":"Creating a MIX Channel","text":"
    First of all, create a new MIX channel following 7.3.2 Creating a Channel:
     
    <iq id='lx09df27'\n    to='mix.shakespeare.example'\n    type='set'>\n  <create channel='coven' xmlns='urn:xmpp:mix:core:0'/>\n</iq>\n
    "},{"location":"tutorials/mix-010/#joining-a-mix-channel","title":"Joining a MIX Channel","text":"
    Now tell your server that you want your account to join that MIX channel, using MIX-PAM: 2.7 Joining a Channel:
     
    <iq type='set'\n    to='hag66@shakespeare.example'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <client-join xmlns='urn:xmpp:mix:pam:0'\n               channel='coven@mix.shakespeare.example'>\n    <join xmlns='urn:xmpp:mix:core:0'>\n      <nick>third witch</nick>\n      <subscribe node='urn:xmpp:mix:nodes:messages'></subscribe>\n      <subscribe node='urn:xmpp:mix:nodes:presence'></subscribe>\n      <subscribe node='urn:xmpp:mix:nodes:participants'></subscribe>\n      <subscribe node='urn:xmpp:mix:nodes:subject'></subscribe>\n      <subscribe node='urn:xmpp:mix:nodes:config'></subscribe>\n    </join>\n  </client-join>\n</iq>\n
     
    You receive IQ that confirms success:
     
    <iq type=\"result\"\n    from=\"hag66@shakespeare.example\"\n    to=\"hag66@shakespeare.example/MacBook-Pro-de-Mickael\"\n    id=\"E6E10350-76CF-40C6-B91B-1EA08C332FC7\">\n  <client-join xmlns='urn:xmpp:mix:pam:0'>\n    <join xmlns=\"urn:xmpp:mix:core:0\"\n          jid='d79d011852b97adfaad6#coven@mix.shakespeare.example'>\n      <nick>third witch</nick>\n      <subscribe node=\"urn:xmpp:mix:nodes:messages\"></subscribe>\n      <subscribe node=\"urn:xmpp:mix:nodes:presence\"></subscribe>\n      <subscribe node=\"urn:xmpp:mix:nodes:participants\"></subscribe>\n      <subscribe node=\"urn:xmpp:mix:nodes:subject\"></subscribe>\n      <subscribe node=\"urn:xmpp:mix:nodes:config\"></subscribe>\n   </join>\n  </client-join>\n</iq>\n
     
    Subscribers on the participants node for that channel will also receive the new list of participants (so, including ourselves in that case):
     
    <message from=\"coven@mix.shakespeare.example\"\n         type=\"headline\"\n         to=\"hag66@shakespeare.example/MacBook-Pro-de-Mickael\">\n <event xmlns=\"http://jabber.org/protocol/pubsub#event\">\n  <items node=\"urn:xmpp:mix:nodes:participants\">\n   <item id=\"3d1766e2bd1b02167104f350f84b0668f850ef92\">\n    <participant xmlns=\"urn:xmpp:mix:core:0\" jid=\"hag66@shakespeare.example\"></participant>\n   </item>\n  </items>\n </event>\n</message>\n
    "},{"location":"tutorials/mix-010/#setting-a-nick","title":"Setting a nick","text":"
    You may want to set a nick for this channel (see 7.1.4 Setting a Nick):
     
    <iq type='set'\n    to='coven@mix.shakespeare.example'\n    id='7nve413p'>\n  <setnick xmlns='urn:xmpp:mix:core:0'>\n    <nick>thirdwitch</nick>\n  </setnick>\n</iq>\n
     
    Note: Support for MIX nickname registration is not implemented in ejabberd.
    "},{"location":"tutorials/mix-010/#sending-and-receiving-messages","title":"Sending and receiving messages","text":"
    You can now start chatting with your peers, by publishing on the message node (see 7.1.6 Sending a Message):
     
    <message to='coven@mix.shakespeare.example'\n         id='92vax143g'\n         type='groupchat'>\n  <body>Harpier cries: 'tis time, 'tis time.</body>\n</message>\n
     
    The message is received by all subscribers on the message node on that MIX channel:
     
    <message\n to='hag77@shakespeare.example'\n from='coven@mix.shakespeare.example/19be8c262ed618e078b7'\n type='groupchat'\n id='1625493702877370'>\n  <mix xmlns='urn:xmpp:mix:core:0'>\n    <nick>thirdwitch</nick>\n    <jid>hag66@shakespeare.example</jid>\n  </mix>\n  <body>Harpier cries: &apos;tis time, &apos;tis time.</body>\n</message>\n
    "},{"location":"tutorials/mix-010/#querying-participants-list","title":"Querying participants list","text":"
    A participant can always get list of participants with a PubSub query on node items for the channel (see 6.6 Determining the Participants in a Channel):
     
    <iq type='get'\n    to='coven@mix.shakespeare.example'\n    id='mix4'>\n  <pubsub xmlns='http://jabber.org/protocol/pubsub'>\n    <items node='urn:xmpp:mix:nodes:participants'></items>\n  </pubsub>\n</iq>\n
     
    The channel will reply with list of participants:
     
    <iq to='hag66@shakespeare.example/tka1'\n    from='coven@mix.shakespeare.example'\n    type='result'\n    id='kl2fax27'>\n  <pubsub xmlns='http://jabber.org/protocol/pubsub'>\n    <items node='urn:xmpp:mix:nodes:participants'>\n      <item id='19be8c262ed618e078b7'>\n        <participant nick='thirdwitch'\n jid='hag66@shakespeare.example'\n xmlns='urn:xmpp:mix:core:0'/>\n      </item>\n      <item id='6be2b26cbf4d7108f1fb'>\n        <participant jid='hag77@shakespeare.example'\n xmlns='urn:xmpp:mix:core:0'/>\n      </item>\n    </items>\n  </pubsub>\n</iq>\n
    "},{"location":"tutorials/mix-010/#caveats","title":"Caveats","text":"
    At the moment it is unclear from XEP-0369 example how you match a message you receive to a participant. We are going to improve our implementation in the following way:
     
       
    1. Add a participant id on the item tag when broadcasting new participant.
      2.  
    2. Add the participant id on the published items.
      3.  
    3. Add the participant id in participants list on the publisher
      4.  
     
    Another issue is that the current specification and implementation will have trouble scaling and offer plenty of opportunities for \"Denial of Service\" attacks. This is something that will change in the future as the specification matures. However, currently, do not deploy or rely on this implementation for large-scale production services. The work is still an experiment to progress on the specifications by offering client developers to give real life feedback on a reference implementation of the current specification.
    "},{"location":"tutorials/mix-010/#conclusion","title":"Conclusion","text":"
    We are only at the beginning of MIX. However, we are excited to have reached a point where it is already usable in some cases.
     
    It is still missing on administrative tasks, right management, user invitations, relationship with MAM archiving and probably a lot more. And we need consolidations on participants message attribution. However, we want to iterate fast with client developers to prototype implementation changes and have meaningful and real life feedback to improve XEP-0359.
     
    Send us your feedback !
    "},{"location":"tutorials/muc-vcard/","title":"Setting vCards / Avatars for MUC rooms","text":"
    ejabberd supports the ability to set vCard for MUC rooms. One of the most common use case is to be able to define an avatar for your own MUC room.
    "},{"location":"tutorials/muc-vcard/#how-does-it-work","title":"How does it work?","text":"
    To be allowed to set vCard for a given room, you need to be owner of that room.
     
    To set up vCard avatar for your MUC room, you first need to make sure you convert your avatar image to base64 encoding, so that you can pass it on XMPP stream.
     
    If you want to convert it manually from command line, you can use base64 tool. For example:
     
    base64 muc_logo.png > muc_logo.b64\n
     
    However, when coding the client, you can more likely directly do the proper image base64 encoding in your code.
    "},{"location":"tutorials/muc-vcard/#setting-up-muc-vcard","title":"Setting up MUC vCard","text":"
    To set the MUC vCard, you can send a vcard-temp set request, as defined in XEP-0054: vcard-temp, but directly addressed to your MUC room. For example, assuming my room id is test@conference.localhost:
     
    <iq id='set1'\n    type='set'\n    to='test@conference.localhost'>\n<vCard xmlns='vcard-temp'>\n    <PHOTO>\n      <TYPE>image/png</TYPE>\n      <BINVAL>\niVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAACXBIWXMAAAsTAAALEwEAmpwYAAAB1WlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNS40LjAiPgogICA8cmRmOlJERiB4bWxuczpyZGY9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkvMDIvMjItcmRmLXN5bnRheC1ucyMiPgogICAgICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIgogICAgICAgICAgICB4bWxuczp0aWZmPSJodHRwOi8vbnMuYWRvYmUuY29tL3RpZmYvMS4wLyI+CiAgICAgICAgIDx0aWZmOkNvbXByZXNzaW9uPjE8L3RpZmY6Q29tcHJlc3Npb24+CiAgICAgICAgIDx0aWZmOk9yaWVudGF0aW9uPjE8L3RpZmY6T3JpZW50YXRpb24+CiAgICAgICAgIDx0aWZmOlBob3RvbWV0cmljSW50ZXJwcmV0YXRpb24+MjwvdGlmZjpQaG90b21ldHJpY0ludGVycHJldGF0aW9uPgogICAgICA8L3JkZjpEZXNjcmlwdGlvbj4KICAgPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KAtiABQAADkVJREFUeAHtWgtwVNUZ/nY3m0022bxIyItAIBBArZRUUbCoKCgVnWJxxlataO1rlKl2amec1urUdmrp2KE6nXFgGIWpQGmlzCDaoTDUBwoMVcFCeOQFhDwhCXlsNrub3fT7z7l3H8kmm4RUWsNJ7uvcc//zf//r/OectfSxYBwX6zjGrqBfEcDltID/Be+7rBZgsVgup/yvuIBI4LJawGVX//gUQB8iY0/C56EFlWj0Szfi+7+Znow8ThAi5N84GRA1Hek3MvRY/huJkEg4Eq90GAuwtItVbypFayosCM14bIFo0LqtxTK0ZweDfvZr5WHDmAogGAwq3q3W2AwEg33weHrQ6fYgM90Fh8OuzHGgEARILKBh840E2dcXVIBMwcm1t7cbXn8LvN4L8PnOwx+4yLo2+PwNSHfNx8QJi2C1JuKSXUBrW2syErinx4uW1nY0NLbgXP0FNDS34ejJelTVd+Cplbfi9lvKIvlV96ZFuD3n0Ni8DclJ03kUIcmRB0diFhm2hyxGQGsTF01qgXt9LejoOonOrk/g7j5AsJsQCOhW0pzyx6T8LcjJukWBF6sZtQA0cA4jVvEpra229k5UVdfhyLEaHPi0BusPngM+7BR98GjEzKVzsGX1A5h7bWkUYPWga3i2INDrRlPLj9UQJcaUkHA1BXEXUlPmIS31GqQ6i2GzJYU+c3fX4nzrbrS1vw6vb5+ql+/IGr8tQV+wCn18nlp0EBMy5+meDPcbsQuYGje1HQgEUVFVi/f3H8Xf9hzFrjfq2IGXhwNZC11o9VP0B9x4ee1teORbS5DmSoliQD0YJ9OUO7sqcLK6lIIt4RsfgsFapT2JKzYCSU56FJkZy5Hhmou2jkO0lhXopablndVazO8cdC0RvIXXOvXttKL9yM66Ubmc2IRpNSMSgPi4aFsOAX74aAXefOsAfrvuCFDrAaY6YS9woCTVDpfDhkO7W4A5Tux+cQUW33qdghkgDatBw8AdupgC6Og6hZNVM9kPIViy+F5M30XmAzxqKBBt1gJY7qWdzVbKd262reNV6sQqC+j3dSgq2IGC3HtYL7HFfKduh+8CAt7U+qnKs9j4l3fxm58fFHKwLEjD5Bkp8NLJnAlW1Lt70bGrHt9/ugzPrFqOqVPyVW9CwzZIgNTsxDoTNFqJuEm9FIHYbC7e+wiogfc5vE/g/SnjY0oFoqgS+P2VyMpcrcDrl2HNG43jCyDS5Ls9Xry54z2sfGYXcLoHhYsy4aAaznl6UdsTwLSUBFTWUAuVXry++T7cf++tNFcHtaQtxxSg2flwr6JLEbTWO4UhAiHrFksGr208JMZIEZOXvopooZWwJ85FUf531BvTutRDxGnIIGiajDBeW9eEF9Zsw/rfHwZumIDS0hRUU9O9dL4JNPf0RAsqd1/A9cvz8cet92Fe2WzVjbiKTWx1BIU2pfFGfaPNN1wloC+GH3kn/Fosibzz8J4RP+9ljiDZhlBi8zCoAEzw4kv/Lq/Csic3onZPK2bekYcL1PapDr/qPD/ZhgY+t7zfgmdfXIhVjy1Dbo74rfjnyMHLdzqp4Y1WvVQNr6j2Wey3kdF/FlwperTRlhObREwBRIL/9LNTKFuxjlYWxKw7J+CEAZyiRq7DioaabnFHbH/7Ydxz5wKl7cFMXmsoPiplAbH5HbJWU25krMqjC5xATe1qTC9+Hon29EGtIKZdmIyeZLAre2i9BGHMmJGKE+0+wa00k51oRVNjD+5dXIhj//wRlt/1VQVeRXm6jI7CYX5NoYRr4tzFl9MQBEQIhWjvXIPqs6sRCHrJj1UJof9HAwQgjIrPt7R1YNXzm4EzPpQWOVFBzUvSozyRp2QbOTzhw5T8dMwunaLoKn/vF+WFnqTAZgAMSGoWp6g+4rSJ/7qZ2eMsXGx/EbX1m1RzLYRo6lECEM2bjG7Y8g/s2VyD2fPTlb9bCZhDri7E3uILIp2Jzh9+fRgHPy43OtCvhY6ANoGL4BqbWrD+T++g+YIOXCKYwcolKV9zQm37eTTBbs9A04XH0HrxU6O7OAKQVuL3Tz/xPjIXZuMsI73klP3Z7Q70IZNuIGXb2weZiQWU8OQq5i+g5ejodGPnrv248aGX8b2VHD6HUUJBcBhtYzfRc5O+vjbG0WwVS+ubXlETpP6uELIAU/tiolt3fES6QWRxeHNzGBustNIK7Del4aUXjuDY8RrVLMFmU9e2i534+56D+PaTr+KepW/gzLvtmPd1MnPp6h2MnX71phAqGZtK0NW9Aa3tH/drI9mEUczAV326Hqs3HOVY70KbT/w1NscCpIN5/gyXHRVBH3bsOoRZjAVi6h9wXvD69kPY++fTQKETVy3NRnlzDy4yYZLx+XMt5FPsV/htbdvJmeAC3ouShBGLFoAJXhg7cqwaqOpAaUkeTnXKwoER+ORlRFE4aOK1BIXr07HunXLUNa3H2v3ngH3NQEkapi/ORReHz4teCtJD11B/EUT+67da2pJKSy7m9ryEbs8qpDiLqAhtISEXEKAyhH1WfpZsyUIFL/r7IdlkDsRoy3S4uxdr15wAuvwovSMfhZOTUcn40SgNVIltSbGIjzYPiEVL1/VQkdmMU0F09wi+cFEuIDiFPQ9z/eM154G8RPQwyKnKcNuYd2JaXoYJO0eJgpvTqOg+ZTnSWFvP8IGbHaggaD6MyVXS5iSl1B5vQxRFHQMMCXi9PtS1MLNLt8HHYUwkIOehinpPjH7enKGZq0KpCOx43w5Od+RCG5yWvJFAzuSM50CvHoZFOcJhyAX4pCTkF83Tt0cVrISmwfvowYdICEtjXpidGDQ1o1oABtN2uw05LocKWHb15lJgjJ73Me1VEROA2rH0WoIoW14wVxE2Dfxq7j69KINzfb+a54sNm++k3edXxlAECoB4Okc0nh32iQYM3UeUCyQm2nHtrEls4IOdbnDZy5ixkEiNc4LE4T85eXIULG0BDAhmbj7nmmlsYEebt5dWED8IRlEb64exMARFI10tjCY7VsKZLAqWoqUbZQFSPWvGZHzju9PQfLwbeUkU2aiioVAafQnlAZdsAZwCk4YsqAY5QGWmL0eCLVn5vx4FZGwwiswCZfbmSnXi0fvmA83d6qU0vGQ+zE54HY5SQ3nAcBpH0I6+Fa6ZAqNQLY44HGXcE7jJaBImHBJA5MeLFs7Fg09cjZp9HVzp5oqrzOcjG4z03ugv3O1ICYymve7NAiczXOZ22b/i+mBOlPaFahQumb5KLEhxJuGZJ+5m1gBUM7UVVxDriGcJ8j6FNFyMHebBJUMk8hkJFgZW0/OGBqRsjp9YLFyKYgZHqjzSeCTzGE7RsctiuQq+3gruBf6U65RLjA9FMGEkUQKQFip9pd9fM3sa3tr5Te7qnIed7TPIvZpAGGRiXYS0m4LqZDJlHpIcqqyytw/8H6YLkJC05aIG0CNUeXTw4OZL3CJJHC3WMovz/3JuwC5E8aSfcG1C5jcyK4yGrFPhCKKmAKTq7jvnY8PmDjzywF+BBRORyilV1yBzBFFygOBR6yWvtDlRnkiEAqifQDOo9uAkJ006ARHqQxQyKmYrI7HF0h4SmujNahWWJbfvX+StdCirWrMJ/jhsCXmYPvk15je5McELhUG3xvRylpbmlm178eAvdyEpPUElkj7pJ6KkE317ux9fKU7FKz+7l8EmjTuzvWpFyGwWFK0QUUlxIZK4WaKsSeXjZgu5CmEL/L2d6HKf5p2SgGLeZnVwUaMSdY3LSEe0KILgcrQyZ5MhFwVWxO/LuRRWhulTtnIzdfqg4PlxeEFEHiKLMCvLW7LCc8ei6zBl3Xs4w0WNrHQ7WsWWI4pDVNUdQLrTji9z59eZzHR6iBIbvHygtWhPcHHI+tIAClbuCJ9rlOpIAQgvifyykOJr5G8ByjmS/YA7wc+RjwIDvNCNXQa4gNlMmDT38d7ZfRBnuNE5aVEW6mRxo1/xsy1Fr1ygmz+AEAHIjpEIUYnKkJcoXA2rAzQfSVBbnZ7BSb08y0p1AoczjxKRthTOWvlkQTH78FJZNYpI/sTXUJh/PxXnHFLzqjFPgwpAXEC2tCqqz2HlC7uBualq81OwGlyYFovc5AS0pYpfWkJCk28F7GiK/o5xo18JB7BU0s4jQI8CLjylpvwQhbmPI8OwnFgBrx859RhTADIUCgBZH1izdidwvAfTFmdyL5BRWUAZGpWdIRkhTvyrXdbJkTg7M9SHYRSh57G6Ud33tRM4+yQfTufD/LnLI9z7564U44SU4YKXtgMEoIOfHio2vbkXr/7uMGYsmYgKrg+qQsAFBJ7CYbGijsNSuRtPPVuGMw3t2H7kQmhOoRuP7VmA+cgG52zISHsOEzKWUuNzlLlLT/L7AbGSsKXE7z9qFBDNmxsjsqR915KNyL45U632OCW54TDm4zB4up5j83H+AmNeJrb94mtquPR6/TjFX4rIXCLFGZ1vx2dj6BZm0HR76rjB8RED8TzGmaIQUBGMlJEAN3sMCcAc9uTF3g8+we0Pb8LUEieS+IMHWR0ONHF8r5LAwyRpWT4eX1GGZUvmYfKkXJNW6GoyHKoYk5vI4KMJXgpwkyUlAJPhHvr81u3v8rc8G/k+lYe4AqVbkMJfdU3EbdcX44ayGcwSpyJ3ot4Cl29N1kw6ow1+JlNDXU3QEnDHoh8Lzb5PCLVzC2v72x9i977jmFmcw2QmlYcL+bmZPLKQk5NJv5NEI8xepMuEa/+/7iiAPgqAS9vUvp9jt/ykZahfdCiNU+sitLHQwOUWV5QL9GfGBKvqBbDR4IsA3MQaCoICtn/5IgHtj818DuUB4wGsCTryqjOeyJpxdn9FAONM4QPgXrGAASIZZxVXLGCcKXwA3CsWMEAk46ziP3wnyrgPINtbAAAAAElFTkSuQmCC\n      </BINVAL>\n    </PHOTO>\n</vCard>\n</iq>\n
     
    Please, note that you have to set the mime type of the image properly to help the client displaying it.
     
    You can of course add other fields to the vCard if needed.
     
    After that IQ set stanza, the server will reply with success:
     
    <iq from=\"test@conference.localhost\"\n    type=\"result\"\n    to=\"owner@localhost/r\"\n    id=\"set1\">\n <vCard xmlns=\"vcard-temp\"/>\n</iq>\n
     
    The MUC room also broadcasts a notification about non-privacy related configuration change to users that are currently in the room:
     
    <message from=\"test@conference.localhost\"\n         type=\"groupchat\"\n         to=\"owner@localhost/r\"\n         id=\"17095969463368094420\">\n <x xmlns=\"http://jabber.org/protocol/muc#user\">\n  <status code=\"104\"/>\n </x>\n</message>\n
    "},{"location":"tutorials/muc-vcard/#retrieving-a-muc-room-vcard","title":"Retrieving a MUC room vCard","text":"
    Any user can retrieve the MUC vCard but sending a vcard-temp get IQ to the room itself:
     
    <iq to='test@conference.localhost'\n    id='get1'\n    type='get'>\n  <vCard xmlns='vcard-temp'/>\n</iq>\n
     
    Server will reply by sending back the vCard:
     
    <iq from=\"test@conference.localhost\"\n    type=\"result\"\n    to=\"user@localhost/r\"\n    id=\"get1\">\n <vCard xmlns=\"vcard-temp\">\n    <PHOTO>\n      <TYPE>image/png</TYPE>\n      <BINVAL>\niVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAACXBIWXMAAAsTAAALEwEAmpwYAAAB1WlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNS40LjAiPgogICA8cmRmOlJERiB4bWxuczpyZGY9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkvMDIvMjItcmRmLXN5bnRheC1ucyMiPgogICAgICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIgogICAgICAgICAgICB4bWxuczp0aWZmPSJodHRwOi8vbnMuYWRvYmUuY29tL3RpZmYvMS4wLyI+CiAgICAgICAgIDx0aWZmOkNvbXByZXNzaW9uPjE8L3RpZmY6Q29tcHJlc3Npb24+CiAgICAgICAgIDx0aWZmOk9yaWVudGF0aW9uPjE8L3RpZmY6T3JpZW50YXRpb24+CiAgICAgICAgIDx0aWZmOlBob3RvbWV0cmljSW50ZXJwcmV0YXRpb24+MjwvdGlmZjpQaG90b21ldHJpY0ludGVycHJldGF0aW9uPgogICAgICA8L3JkZjpEZXNjcmlwdGlvbj4KICAgPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KAtiABQAADkVJREFUeAHtWgtwVNUZ/nY3m0022bxIyItAIBBArZRUUbCoKCgVnWJxxlataO1rlKl2amec1urUdmrp2KE6nXFgGIWpQGmlzCDaoTDUBwoMVcFCeOQFhDwhCXlsNrub3fT7z7l3H8kmm4RUWsNJ7uvcc//zf//r/OectfSxYBwX6zjGrqBfEcDltID/Be+7rBZgsVgup/yvuIBI4LJawGVX//gUQB8iY0/C56EFlWj0Szfi+7+Znow8ThAi5N84GRA1Hek3MvRY/huJkEg4Eq90GAuwtItVbypFayosCM14bIFo0LqtxTK0ZweDfvZr5WHDmAogGAwq3q3W2AwEg33weHrQ6fYgM90Fh8OuzHGgEARILKBh840E2dcXVIBMwcm1t7cbXn8LvN4L8PnOwx+4yLo2+PwNSHfNx8QJi2C1JuKSXUBrW2syErinx4uW1nY0NLbgXP0FNDS34ejJelTVd+Cplbfi9lvKIvlV96ZFuD3n0Ni8DclJ03kUIcmRB0diFhm2hyxGQGsTF01qgXt9LejoOonOrk/g7j5AsJsQCOhW0pzyx6T8LcjJukWBF6sZtQA0cA4jVvEpra229k5UVdfhyLEaHPi0BusPngM+7BR98GjEzKVzsGX1A5h7bWkUYPWga3i2INDrRlPLj9UQJcaUkHA1BXEXUlPmIS31GqQ6i2GzJYU+c3fX4nzrbrS1vw6vb5+ql+/IGr8tQV+wCn18nlp0EBMy5+meDPcbsQuYGje1HQgEUVFVi/f3H8Xf9hzFrjfq2IGXhwNZC11o9VP0B9x4ee1teORbS5DmSoliQD0YJ9OUO7sqcLK6lIIt4RsfgsFapT2JKzYCSU56FJkZy5Hhmou2jkO0lhXopablndVazO8cdC0RvIXXOvXttKL9yM66Ubmc2IRpNSMSgPi4aFsOAX74aAXefOsAfrvuCFDrAaY6YS9woCTVDpfDhkO7W4A5Tux+cQUW33qdghkgDatBw8AdupgC6Og6hZNVM9kPIViy+F5M30XmAzxqKBBt1gJY7qWdzVbKd262reNV6sQqC+j3dSgq2IGC3HtYL7HFfKduh+8CAt7U+qnKs9j4l3fxm58fFHKwLEjD5Bkp8NLJnAlW1Lt70bGrHt9/ugzPrFqOqVPyVW9CwzZIgNTsxDoTNFqJuEm9FIHYbC7e+wiogfc5vE/g/SnjY0oFoqgS+P2VyMpcrcDrl2HNG43jCyDS5Ls9Xry54z2sfGYXcLoHhYsy4aAaznl6UdsTwLSUBFTWUAuVXry++T7cf++tNFcHtaQtxxSg2flwr6JLEbTWO4UhAiHrFksGr208JMZIEZOXvopooZWwJ85FUf531BvTutRDxGnIIGiajDBeW9eEF9Zsw/rfHwZumIDS0hRUU9O9dL4JNPf0RAsqd1/A9cvz8cet92Fe2WzVjbiKTWx1BIU2pfFGfaPNN1wloC+GH3kn/Fosibzz8J4RP+9ljiDZhlBi8zCoAEzw4kv/Lq/Csic3onZPK2bekYcL1PapDr/qPD/ZhgY+t7zfgmdfXIhVjy1Dbo74rfjnyMHLdzqp4Y1WvVQNr6j2Wey3kdF/FlwperTRlhObREwBRIL/9LNTKFuxjlYWxKw7J+CEAZyiRq7DioaabnFHbH/7Ydxz5wKl7cFMXmsoPiplAbH5HbJWU25krMqjC5xATe1qTC9+Hon29EGtIKZdmIyeZLAre2i9BGHMmJGKE+0+wa00k51oRVNjD+5dXIhj//wRlt/1VQVeRXm6jI7CYX5NoYRr4tzFl9MQBEQIhWjvXIPqs6sRCHrJj1UJof9HAwQgjIrPt7R1YNXzm4EzPpQWOVFBzUvSozyRp2QbOTzhw5T8dMwunaLoKn/vF+WFnqTAZgAMSGoWp6g+4rSJ/7qZ2eMsXGx/EbX1m1RzLYRo6lECEM2bjG7Y8g/s2VyD2fPTlb9bCZhDri7E3uILIp2Jzh9+fRgHPy43OtCvhY6ANoGL4BqbWrD+T++g+YIOXCKYwcolKV9zQm37eTTBbs9A04XH0HrxU6O7OAKQVuL3Tz/xPjIXZuMsI73klP3Z7Q70IZNuIGXb2weZiQWU8OQq5i+g5ejodGPnrv248aGX8b2VHD6HUUJBcBhtYzfRc5O+vjbG0WwVS+ubXlETpP6uELIAU/tiolt3fES6QWRxeHNzGBustNIK7Del4aUXjuDY8RrVLMFmU9e2i534+56D+PaTr+KepW/gzLvtmPd1MnPp6h2MnX71phAqGZtK0NW9Aa3tH/drI9mEUczAV326Hqs3HOVY70KbT/w1NscCpIN5/gyXHRVBH3bsOoRZjAVi6h9wXvD69kPY++fTQKETVy3NRnlzDy4yYZLx+XMt5FPsV/htbdvJmeAC3ouShBGLFoAJXhg7cqwaqOpAaUkeTnXKwoER+ORlRFE4aOK1BIXr07HunXLUNa3H2v3ngH3NQEkapi/ORReHz4teCtJD11B/EUT+67da2pJKSy7m9ryEbs8qpDiLqAhtISEXEKAyhH1WfpZsyUIFL/r7IdlkDsRoy3S4uxdr15wAuvwovSMfhZOTUcn40SgNVIltSbGIjzYPiEVL1/VQkdmMU0F09wi+cFEuIDiFPQ9z/eM154G8RPQwyKnKcNuYd2JaXoYJO0eJgpvTqOg+ZTnSWFvP8IGbHaggaD6MyVXS5iSl1B5vQxRFHQMMCXi9PtS1MLNLt8HHYUwkIOehinpPjH7enKGZq0KpCOx43w5Od+RCG5yWvJFAzuSM50CvHoZFOcJhyAX4pCTkF83Tt0cVrISmwfvowYdICEtjXpidGDQ1o1oABtN2uw05LocKWHb15lJgjJ73Me1VEROA2rH0WoIoW14wVxE2Dfxq7j69KINzfb+a54sNm++k3edXxlAECoB4Okc0nh32iQYM3UeUCyQm2nHtrEls4IOdbnDZy5ixkEiNc4LE4T85eXIULG0BDAhmbj7nmmlsYEebt5dWED8IRlEb64exMARFI10tjCY7VsKZLAqWoqUbZQFSPWvGZHzju9PQfLwbeUkU2aiioVAafQnlAZdsAZwCk4YsqAY5QGWmL0eCLVn5vx4FZGwwiswCZfbmSnXi0fvmA83d6qU0vGQ+zE54HY5SQ3nAcBpH0I6+Fa6ZAqNQLY44HGXcE7jJaBImHBJA5MeLFs7Fg09cjZp9HVzp5oqrzOcjG4z03ugv3O1ICYymve7NAiczXOZ22b/i+mBOlPaFahQumb5KLEhxJuGZJ+5m1gBUM7UVVxDriGcJ8j6FNFyMHebBJUMk8hkJFgZW0/OGBqRsjp9YLFyKYgZHqjzSeCTzGE7RsctiuQq+3gruBf6U65RLjA9FMGEkUQKQFip9pd9fM3sa3tr5Te7qnIed7TPIvZpAGGRiXYS0m4LqZDJlHpIcqqyytw/8H6YLkJC05aIG0CNUeXTw4OZL3CJJHC3WMovz/3JuwC5E8aSfcG1C5jcyK4yGrFPhCKKmAKTq7jvnY8PmDjzywF+BBRORyilV1yBzBFFygOBR6yWvtDlRnkiEAqifQDOo9uAkJ006ARHqQxQyKmYrI7HF0h4SmujNahWWJbfvX+StdCirWrMJ/jhsCXmYPvk15je5McELhUG3xvRylpbmlm178eAvdyEpPUElkj7pJ6KkE317ux9fKU7FKz+7l8EmjTuzvWpFyGwWFK0QUUlxIZK4WaKsSeXjZgu5CmEL/L2d6HKf5p2SgGLeZnVwUaMSdY3LSEe0KILgcrQyZ5MhFwVWxO/LuRRWhulTtnIzdfqg4PlxeEFEHiKLMCvLW7LCc8ei6zBl3Xs4w0WNrHQ7WsWWI4pDVNUdQLrTji9z59eZzHR6iBIbvHygtWhPcHHI+tIAClbuCJ9rlOpIAQgvifyykOJr5G8ByjmS/YA7wc+RjwIDvNCNXQa4gNlMmDT38d7ZfRBnuNE5aVEW6mRxo1/xsy1Fr1ygmz+AEAHIjpEIUYnKkJcoXA2rAzQfSVBbnZ7BSb08y0p1AoczjxKRthTOWvlkQTH78FJZNYpI/sTXUJh/PxXnHFLzqjFPgwpAXEC2tCqqz2HlC7uBualq81OwGlyYFovc5AS0pYpfWkJCk28F7GiK/o5xo18JB7BU0s4jQI8CLjylpvwQhbmPI8OwnFgBrx859RhTADIUCgBZH1izdidwvAfTFmdyL5BRWUAZGpWdIRkhTvyrXdbJkTg7M9SHYRSh57G6Ud33tRM4+yQfTufD/LnLI9z7564U44SU4YKXtgMEoIOfHio2vbkXr/7uMGYsmYgKrg+qQsAFBJ7CYbGijsNSuRtPPVuGMw3t2H7kQmhOoRuP7VmA+cgG52zISHsOEzKWUuNzlLlLT/L7AbGSsKXE7z9qFBDNmxsjsqR915KNyL45U632OCW54TDm4zB4up5j83H+AmNeJrb94mtquPR6/TjFX4rIXCLFGZ1vx2dj6BZm0HR76rjB8RED8TzGmaIQUBGMlJEAN3sMCcAc9uTF3g8+we0Pb8LUEieS+IMHWR0ONHF8r5LAwyRpWT4eX1GGZUvmYfKkXJNW6GoyHKoYk5vI4KMJXgpwkyUlAJPhHvr81u3v8rc8G/k+lYe4AqVbkMJfdU3EbdcX44ayGcwSpyJ3ot4Cl29N1kw6ow1+JlNDXU3QEnDHoh8Lzb5PCLVzC2v72x9i977jmFmcw2QmlYcL+bmZPLKQk5NJv5NEI8xepMuEa/+/7iiAPgqAS9vUvp9jt/ykZahfdCiNU+sitLHQwOUWV5QL9GfGBKvqBbDR4IsA3MQaCoICtn/5IgHtj818DuUB4wGsCTryqjOeyJpxdn9FAONM4QPgXrGAASIZZxVXLGCcKXwA3CsWMEAk46ziP3wnyrgPINtbAAAAAElFTkSuQmCC\n      </BINVAL>\n    </PHOTO>\n </vCard>\n</iq>\n
    "},{"location":"tutorials/mysql/","title":"Using ejabberd with MySQL","text":"
    ejabberd is bundled with a native Erlang driver to use MySQL as a backend for persistent storage. Using MySQL as backend is thus extremely straightforward.
    "},{"location":"tutorials/mysql/#ejabberd-installation","title":"ejabberd installation","text":"
    ejabberd packages and binary installers contain all the modules needed to connect to your MySQL server. You have no extra module to install anymore.
     
    If you are building ejabberd from source, make sure that you configure ejabberd to include MySQL module. It can be done by passing option --enable-mysql to configure script. For example:
     
    cd ejabberd-source\n./configure --enable-mysql\n
    "},{"location":"tutorials/mysql/#mysql-installation","title":"MySQL installation","text":"
    You need a MySQL server that you can point your ejabberd configuration to. The database does not have to be on the same server than ejabberd.
    "},{"location":"tutorials/mysql/#requirements","title":"Requirements","text":"
    ejabberd uses FULLTEXT indexes with InnoDB. Thus, you need MySQL 5.6 or greater to use with ejabberd.
     
    Note: If you do not store message archive in database however, you can try using older 5.5 version. You may need to adapt MySQL database schema to cope with those older MySQL versions.
    "},{"location":"tutorials/mysql/#mysql-on-linux","title":"MySQL on Linux","text":"
    This documentation will not get into the details of making MySQL running on Linux for production. It is dependent on Linux distribution and system administrators preferences and habits.
     
    It is also well documented, so it should not be an issue.
    "},{"location":"tutorials/mysql/#amazon-rds-compliance","title":"Amazon RDS compliance","text":"
    ejabberd is fully compliant with MySQL on Amazon RDS.
     
    You just need to make sure to use MySQL version 5.6 or greater when you create your database.
    "},{"location":"tutorials/mysql/#mysql-on-osx-with-homebrew","title":"MySQL on OSX with Homebrew","text":"
    For testing / development, it is common to start experimenting with MySQL with Homebrew installation.
     
    Here is how to get started to help with setup up environment.
     
    With Homebrew properly installed, you can use the following command to install MySQL:
     
    brew install mysql\n
     
    You can then follow instruction to finish the installation, for example by running mysql_secure_installation.
     
    You can manually start server with:
     
    mysql.server start\n
     
    To connect to your local MySQL server using mysql command-line, assuming you kept the default set up, use:
     
    mysql -uroot\n
     
    To stop it, use:
     
    mysql.server stop\n
    "},{"location":"tutorials/mysql/#mysql-on-windows-with-bash","title":"MySQL on Windows with Bash","text":"
    On Windows you can install MySQL easily like on Linux using Ubuntu Bash:
     
    sudo apt-get install mysql-server-5.6\n
     
    After configuration, you can start MySQL with:
     
    sudo /etc/init.d/mysql start\n
     
    You can connect on the database with your created admin password:
     
    mysql -uroot -ppassword\n
    "},{"location":"tutorials/mysql/#mysql-database-creation","title":"MySQL database creation","text":""},{"location":"tutorials/mysql/#create-ejabberd-user-and-database","title":"Create ejabberd user and database","text":"
    MySQL admins should use this procedure and grant rights to a dedicated ejabberd user (replace password with your desired password):
     
    echo \"GRANT ALL ON ejabberd.* TO 'ejabberd'@'localhost' IDENTIFIED BY 'password';\" | mysql -h localhost -u root\n
     
    You can then create a dedicated ejabberd database (use password created earlier):
     
    echo \"CREATE DATABASE ejabberd;\" | mysql -h localhost -u ejabberd -p\n
     
    You should now be able to connect to ejabberd database with user ejabberd (use password defined on GRANT command):
     
    mysql -h localhost -u ejabberd -p -D ejabberd\n\nWelcome to the MySQL monitor.  Commands end with ; or \\g.\nYour MySQL connection id is 8\nServer version: 5.7.11 Homebrew\n\nCopyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.\n\nOracle is a registered trademark of Oracle Corporation and/or its\naffiliates. Other names may be trademarks of their respective\nowners.\n\nType 'help;' or '\\h' for help. Type '\\c' to clear the current input statement.\n\nmysql>\n
    "},{"location":"tutorials/mysql/#decide-which-sql-schema-to-use","title":"Decide which SQL schema to use","text":"
    Read carefully the Default and New Schemas section and decide which schema is preferable in your case: the default or the new schema.
     
    Then modify the ejabberd.yml configuration file to setup your desired option value:
     
    new_sql_schema: true\n
    "},{"location":"tutorials/mysql/#use-automatic-schema-update","title":"Use automatic schema update","text":"
    Since ejabberd 23.10, ejabberd can take care to create the tables automatically the first time it starts with an empty database, and also takes care to update the database schema when you upgrade ejabberd to a newer version.
     
    That feature works both for default and new SQL schema, for MySQL, PostgreSQL and SQLite.
     
    To enable automatic database schema creation and update, simply add in your ejabberd.yml configuration file:
     
    update_sql_schema: true\n
     
    In that case, you don't need to load the database schema manually: no need to read the next section.
    "},{"location":"tutorials/mysql/#load-database-schema-manually","title":"Load database schema manually","text":"
    MySQL default schema is defined in a file called mysql.sql, and the new schema is mysql.new.sql. Some tables of the schema are described in: ejabberd SQL database schema documentation.
     
    Those schema files can be found:
     
       
    •  
      Git repository and source code package: /sql/ directory
       
      •  
    •  
      When installed from source code or binary installer, the SQL schemas are copied to   PREFIX/lib/ejabberd-VERSION/priv/sql
       
      •  
     
    Load the schema in your ejabberd database with the command:
     
    mysql -h localhost -D ejabberd -u ejabberd -p < mysql.sql\n
     
    To make sure all looks fine, you can show the list of SQL tables:
     
    echo \"SHOW TABLES;\" | mysql -h localhost -D ejabberd -u ejabberd -p --table\n\nmysql: [Warning] Using a password on the command line interface can be insecure.\n+-------------------------+\n| Tables_in_ejabberd      |\n+-------------------------+\n| archive                 |\n| archive_prefs           |\n| caps_features           |\n| last                    |\n| motd                    |\n| muc_registered          |\n| muc_room                |\n| privacy_default_list    |\n| privacy_list            |\n| privacy_list_data       |\n| private_storage         |\n| pubsub_item             |\n| pubsub_node             |\n| pubsub_node_option      |\n| pubsub_node_owner       |\n| pubsub_state            |\n| pubsub_subscription_opt |\n| roster_version          |\n| rostergroups            |\n| rosterusers             |\n| sm                      |\n| spool                   |\n| sr_group                |\n| sr_user                 |\n| users                   |\n| vcard                   |\n| vcard_search            |\n| vcard_xupdate           |\n+-------------------------+\n
     
    Your database is now ready to connect with ejabberd.
    "},{"location":"tutorials/mysql/#ejabberd-configuration","title":"ejabberd configuration","text":""},{"location":"tutorials/mysql/#setup-mysql-connection","title":"Setup MySQL connection","text":"
    In ejabberd.yml, define your database parameters:
     
    sql_type: mysql\nsql_server: \"localhost\"\nsql_database: \"ejabberd\"\nsql_username: \"ejabberd\"\nsql_password: \"password\"\n## If you want to specify the port:\nsql_port: 3306\n
     
    Those parameters are mandatory if you want to use MySQL with ejabberd.
    "},{"location":"tutorials/mysql/#authentication-use-mysql","title":"Authentication use MySQL","text":"
    If you decide to store user password in ejabberd, you need to tell ejabberd to use MySQL instead of internal database for authentication.
     
    You thus need to change ejabberd configuration auth_method to replace internal authentication with sql:
     
    auth_method: sql\n
     
    If you restart ejabberd, it should connect to your database for authentication. In case it does not work as expected, check your config file syntax and log files (ejabberd.log, error.log, crash.log)
     
    For example, you can create a user in database with ejabberdctl:
     
    /sbin/ejabberdctl register \"testuser\" \"localhost\" \"passw0rd\"\n\nUser testuser@localhost successfully registered\n
     
    You should now be able to connect XMPP users based on MySQL user base.
    "},{"location":"tutorials/mysql/#modules-use-mysql","title":"Modules use MySQL","text":"
    At this stage, only the authentication / user base has been moved to MySQL. For data managed by modules, ejabberd still uses the Mnesia internal database by default; you can decide to use MySQL on a module-by-module basis.
     
    For each modules that support SQL backend, you can pass option db_type: sql to use your configured MySQL database. Switch can be done on a module by module basis. For example, if you want to store contact list in MySQL, you can do:
     
    modules:\n  mod_roster:\n    db_type: sql\n
     
    However, if you want to use MySQL for all modules that support MySQL, you can simply use global option default_db: sql:
     
    default_db: sql\n
     
    Note: even if you move all the persistent data you can to MySQL, Mnesia will still be started and used to manage clustering.
    "},{"location":"tutorials/mysql/#migrating-data-from-internal-to-mysql","title":"Migrating data from internal to MySQL","text":"
    To migrate your data, once you have setup your sql service, you can move most of the data to your database.
     
    You need to take precautions before you launch the migration:
     
       
    1.  
      Before you launch migration from internal database, make sure you have made a proper backup.
       
      2.  
    2.  
      Always try the migration first on an instance created from your data backup, to make sure the migration script will work fine on your dataset.
       
      3.  
    3.  
      Then, when doing final migration, make sure your instance is not accepting connections by blocking incoming connections, for example with firewall rules (block port 5222, 5269 and 5280 as default).
       
      4.  
     
    When you are ready, you can:
     
       
    1.  
      Connect to a running ejabberd:
       
      ./ejabberdctl debug\n
       
      2.  
    2.  
      Alternatively, use ejabberdctl live to launch ejabberd with an Erlang shell attached.
       
      3.  
    3.  
      Launch the migration command ejd2sql:export/2 from Erlang shell. First parameter is the XMPP domain name you want to migrate (i.e localhost). Second parameter sql tells ejabberd to export to configured MySQL database. For example:
       
      ejd2sql:export(<<\"localhost\">>, sql).\n
       
      4.  
     
    You should be set now.
    "},{"location":"tutorials/mysql/#converting-database-from-default-to-new-schema","title":"Converting database from default to new schema","text":"
    Please check the section Default and New Schemas.
    "},{"location":"tutorials/mysql/#getting-further","title":"Getting further","text":"
    To get further you can read the ejabberd Configuration section about Databases.
    "},{"location":"use-cases/","title":"ejabberd Use Cases","text":"
    ejabberd is very versatile and is a solid choice to build messaging services across a large number of industries:
    "},{"location":"use-cases/#ejabberd","title":"ejabberd","text":""},{"location":"use-cases/#mobile-messaging","title":"Mobile messaging","text":"
    ejabberd's massive scalability makes it the most solid choice as the backbone for a very large number of mobile messaging services.
     
    This includes:
     
       
    • Chaatz
      •  
    • Libon
      •  
    • Nokia OVI Chat
      •  
    • Roo Kids : Safe & fun instant messaging app for kids with minimum yet critical parental controls.
      •  
    • Swisscom IO
      •  
    • Versapp
      •  
    • Whatsapp
      •  
    "},{"location":"use-cases/#gaming","title":"Gaming","text":"
       
    • Electronic Arts
      •  
    • FACEIT
      •  
    • Kixeye
      •  
    • Machine Zone (Game of War)
      •  
    • Nokia nGage
      •  
    • Riot Games (League of Legends)
      •  
    "},{"location":"use-cases/#voice-and-video-messaging","title":"Voice and video messaging","text":"
       
    • Nimbuzz
      •  
    • ooVoo
      •  
    • Sipphone
      •  
    • WowApp
      •  
    "},{"location":"use-cases/#internet-of-things","title":"Internet of Things","text":"
       
    • AeroFS
      •  
    • IMA Teleassistance
      •  
    • Nabaztag (Violet, Mindscape, then Aldebaran Robotics)
      •  
    "},{"location":"use-cases/#telecom-hosting","title":"Telecom / Hosting","text":"
       
    • Fastmail
      •  
    • GMX
      •  
    • Mailfence
      •  
    • Orange
      •  
    • SAPO - Portugal Telecom
      •  
    "},{"location":"use-cases/#customer-chat-crm","title":"Customer chat / CRM","text":"
       
    • CoBrowser.net: Coder Interview.
      •  
    • iAdvize
      •  
    • LiveHelpercChat: Blog post: Full XMPP chat support for ejabberd
      •  
    "},{"location":"use-cases/#media","title":"Media","text":"
       
    • AFP
      •  
    • BBC
      •  
    "},{"location":"use-cases/#social-media","title":"Social media","text":"
       
    • Facebook
      •  
    • Nasza Klasa (NKTalk messenger)
      •  
    • StudiVZ
      •  
    • Sify
      •  
    • Tuenti
      •  
    "},{"location":"use-cases/#sport","title":"Sport","text":"
       
    • Major League of Baseball (MLB)
      •  
    "},{"location":"use-cases/#education","title":"Education","text":"
       
    • Apollo group
      •  
    • Laureate
      •  
    "},{"location":"use-cases/#push-alerts","title":"Push alerts","text":"
       
    • Nokia push notifications
      •  
    • Notify.me
      •  
    "},{"location":"use-cases/#dating","title":"Dating","text":"
       
    • Grindr
      •  
    • Meetic
      •  
    "},{"location":"use-cases/#community-sites","title":"Community sites","text":"
       
    • Jabber.at
      •  
    • Talkr.im
      •  
    "},{"location":"use-cases/#xmpp-use-cases","title":"XMPP Use Cases","text":"
    XMPP is a very versatile protocol designed to address many use cases of modern real-time messaging needs. However, it is also a very large protocol and it is difficult to understand at first sight all the use cases that XMPP adequately addresses.
     
    This page is gathering XMPP specifications that make XMPP a good fit for a given use case of industry.
    "},{"location":"use-cases/#realtime-web","title":"Realtime web","text":"
    XMPP was designed before the advent of realtime web. However, it managed to adapt thanks to the following specifications:
     
       
    •  
      XMPP PubSub is defined in   XEP-0060. This is a   very powerful mechanism that defines channel based communication on   top of the XMPP protocol itself. A server can handle millions of   channels, called Pubsub nodes. Users interested in specific channels   can subscribe to nodes. When data needs to be send to a given   channel, authorized publishers can send data to that node. The XMPP   server will then broadcast the content to all subscribers. This is   very adequate for realtime web as it allows you to broadcast   relevant events to web pages.
       
      •  
    •  
      WebSocket: XMPP over WebSocket is defined in   RFC 7395. It is more   efficient and more scalable than XMPP for web's previous   specifications called   BOSH. WebSocket being a   true bidirectional channel, it allows lower latency messaging and is   very reliable. Note that BOSH can still be used transparently along   with WebSocket to support old web browsers.
       
      •  
     
    Use cases: News, interactive web page, web chat, web games.
     
    Supported by ejabberd: Yes.
    "}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"CHANGELOG/","title":"ChangeLog","text":""},{"location":"CHANGELOG/#version-2402","title":"Version 24.02","text":""},{"location":"CHANGELOG/#core","title":"Core:","text":"
       
    • Added Matrix gateway in mod_matrix_gw
      •  
    • Support SASL2 and Bind2
      •  
    • Support tls-server-end-point channel binding and sasl2 codec
      •  
    • Support tls-exporter channel binding
      •  
    • Support XEP-0474: SASL SCRAM Downgrade Protection
      •  
    • Fix presenting features and returning results of inline bind2 elements
      •  
    • disable_sasl_scram_downgrade_protection: New option to disable XEP-0474
      •  
    • negotiation_timeout: Increase default value from 30s to 2m
      •  
    • mod_carboncopy: Teach how to interact with bind2 inline requests
      •  
    "},{"location":"CHANGELOG/#other","title":"Other:","text":"
       
    • ejabberdctl: Fix startup problem when having set EJABBERD_OPTS and logger options
      •  
    • ejabberdctl: Set EJABBERD_OPTS back to \"\", and use previous flags as example
      •  
    • eldap: Change logic for eldap tls_verify=soft and false
      •  
    • eldap: Don't set fail_if_no_peer_cert for eldap ssl client connections
      •  
    • Ignore hints when checking for chat states
      •  
    • mod_mam: Support XEP-0424 Message Retraction
      •  
    • mod_mam: Fix XEP-0425: Message Moderation with SQL storage
      •  
    • mod_ping: Support XEP-0198 pings when stream management is enabled
      •  
    • mod_pubsub: Normalize pubsub max_items node options on read
      •  
    • mod_pubsub: PEP nodetree: Fix reversed logic in node fixup function
      •  
    • mod_pubsub: Only care about PEP bookmarks options when creating node from scratch
      •  
    "},{"location":"CHANGELOG/#sql","title":"SQL:","text":"
       
    • MySQL: Support sha256_password auth plugin
      •  
    • ejabberd_sql_schema: Use the first unique index as a primary key
      •  
    • Update SQL schema files for MAM's XEP-0424
      •  
    • New option sql_flags: right now only useful to enable mysql_alternative_upsert
      •  
    "},{"location":"CHANGELOG/#installers-and-container","title":"Installers and Container:","text":"
       
    • Container: Add ability to ignore failures in execution of CTL_ON_* commands
      •  
    • Container: Update to Erlang/OTP 26.2, Elixir 1.16.1 and Alpine 3.19
      •  
    • Container: Update this custom ejabberdctl to match the main one
      •  
    • make-binaries: Bump OpenSSL 3.2.1, Erlang/OTP 26.2.2, Elixir 1.16.1
      •  
    • make-binaries: Bump many dependency versions
      •  
    "},{"location":"CHANGELOG/#commands-api","title":"Commands API:","text":"
       
    • print_sql_schema: New command available in ejabberdctl command-line script
      •  
    • ejabberdctl: Rework temporary node name generation
      •  
    • ejabberdctl: Print argument description, examples and note in help
      •  
    • ejabberdctl: Document exclusive ejabberdctl commands like all the others
      •  
    • Commands: Add a new muc_sub tag to all the relevant commands
      •  
    • Commands: Improve syntax of many commands documentation
      •  
    • Commands: Use list arguments in many commands that used separators
      •  
    • Commands: set_presence: switch priority argument from string to integer
      •  
    • ejabberd_commands: Add the command API version as a tag vX
      •  
    • ejabberd_ctl: Add support for list and tuple arguments
      •  
    • ejabberd_xmlrpc: Fix support for restuple error response
      •  
    • mod_http_api: When no specific API version is requested, use the latest
      •  
    "},{"location":"CHANGELOG/#compilation-with-rebar3elixirmix","title":"Compilation with Rebar3/Elixir/Mix:","text":"
       
    • Fix compilation with Erlang/OTP 27: don't use the reserved word 'maybe'
      •  
    • configure: Fix explanation of --enable-group option (#4135)
      •  
    • Add observer and runtime_tools in releases when --enable-tools
      •  
    • Update \"make translations\" to reduce build requirements
      •  
    • Use Luerl 1.0 for Erlang 20, 1.1.1 for 21-26, and temporary fork for 27
      •  
    • Makefile: Add install-rel and uninstall-rel
      •  
    • Makefile: Rename make rel to make prod
      •  
    • Makefile: Update make edoc to use ExDoc, requires mix
      •  
    • Makefile: No need to use escript to run rebar|rebar3|mix
      •  
    • configure: If --with-rebar=rebar3 but rebar3 not system-installed, use local one
      •  
    • configure: Use Mix or Rebar3 by default instead of Rebar2 to compile ejabberd
      •  
    • ejabberdctl: Detect problem running iex or etop and show explanation
      •  
    • Rebar3: Include Elixir files when making a release
      •  
    • Rebar3: Workaround to fix protocol consolidation
      •  
    • Rebar3: Add support to compile Elixir dependencies
      •  
    • Rebar3: Compile explicitly our Elixir files when --enable-elixir
      •  
    • Rebar3: Provide proper path to iex
      •  
    • Rebar/Rebar3: Update binaries to work with Erlang/OTP 24-27
      •  
    • Rebar/Rebar3: Remove Elixir as a rebar dependency
      •  
    • Rebar3/Mix: If dev profile/environment, enable tools automatically
      •  
    • Elixir: Fix compiling ejabberd as a dependency (#4128)
      •  
    • Elixir: Fix ejabberdctl start/live when installed
      •  
    • Elixir: Fix: FORMATTER ERROR: bad return value (#4087)
      •  
    • Elixir: Fix: Couldn't find file Elixir Hex API
      •  
    • Mix: Enable stun by default when vars.config not found
      •  
    • Mix: New option vars_config_path to set path to vars.config (#4128)
      •  
    • Mix: Fix ejabberdctl iexlive problem locating iex in an OTP release
      •  
    "},{"location":"CHANGELOG/#version-2310","title":"Version 23.10","text":""},{"location":"CHANGELOG/#compilation","title":"Compilation:","text":"
       
    • Erlang/OTP: Raise the requirement to Erlang/OTP 20.0 as a minimum
      •  
    • CI: Update tests to Erlang/OTP 26 and recent Elixir
      •  
    • Move Xref and Dialyzer options from workflows to rebar.config
      •  
    • Add sections to rebar.config to organize its content
      •  
    • Dialyzer dirty workarounds because re:mp() is not an exported type
      •  
    • When installing module already configured, keep config as example
      •  
    • Elixir 1.15 removed support for --app
      •  
    • Elixir: Improve support to stop external modules written in Elixir
      •  
    • Elixir: Update syntax of function calls as recommended by Elixir compiler
      •  
    • Elixir: When building OTP release with mix, keep ERLANG_NODE=ejabberd@localhost
      •  
    • ejabberdctl: Pass ERLANG_OPTS when calling erl to parse the INET_DIST_INTERFACE (#4066
      •  
    "},{"location":"CHANGELOG/#commands","title":"Commands:","text":"
       
    • create_room_with_opts: Fix typo and move examples to args_example (#4080)
      •  
    • etop: Let ejabberdctl etop work in a release (if observer application is available)
      •  
    • get_roster: Command now returns groups in a list instead of newlines (#4088)
      •  
    • halt: New command to halt ejabberd abruptly with an error status code
      •  
    • ejabberdctl: Fix calling ejabberdctl command with wrong number of arguments with Erlang 26
      •  
    • ejabberdctl: Improve printing lists in results
      •  
    • ejabberdctl: Support policy=user in the help and return proper arguments
      •  
    • ejabberdctl: Document how to stop a debug shell: control+g
      •  
    "},{"location":"CHANGELOG/#container","title":"Container:","text":"
       
    • Dockerfile: Add missing dependency for mssql databases
      •  
    • Dockerfile: Reorder stages and steps for consistency
      •  
    • Dockerfile: Use Alpine as base for METHOD=package
      •  
    • Dockerfile: Rename packages to improve compatibility
      •  
    • Dockerfile: Provide specific OTP and elixir vsn for direct compilation
      •  
    • Halt ejabberd if a command in CTL_ON_ fails during ejabberd startup
      •  
    "},{"location":"CHANGELOG/#core_1","title":"Core:","text":"
       
    • auth_external_user_exists_check: New option (#3377)
      •  
    • gen_mod: Extend gen_mod API to simplify hooks and IQ handlers registration
      •  
    • gen_mod: Add shorter forms for gen_mod hook/iq_handler API
      •  
    • gen_mod: Update modules to the new gen_mod API
      •  
    • install_contrib_modules: New option to define contrib modules to install automatically
      •  
    • unix_socket: New listener option, useful when setting unix socket files (#4059)
      •  
    • ejabberd_systemd: Add a few debug messages
      •  
    • ejabberd_systemd: Avoid using gen_server timeout (#4054)(#4058)
      •  
    • ejabberd_listener: Increase default listen queue backlog value to 128, which is the default value on both Linux and FreeBSD (#4025)
      •  
    • OAuth: Handle badpass error message
      •  
    • When sending message on behalf of user, trigger user_send_packet (#3990)
      •  
    • Web Admin: In roster page move the AddJID textbox to top (#4067)
      •  
    • Web Admin: Show a warning when visiting webadmin with non-privileged account (#4089)
      •  
    "},{"location":"CHANGELOG/#docs","title":"Docs:","text":"
       
    • Example configuration: clarify 5223 tls options; specify s2s shaper
      •  
    • Make sure that policy=user commands have host instead of server arg in docs
      •  
    • Improve syntax of many command descriptions for the Docs site
      •  
    • Move example Perl extauth script from ejabberd git to Docs site
      •  
    • Remove obsolete example files, and add link in Docs to the archived copies
      •  
    "},{"location":"CHANGELOG/#installers-make-binaries","title":"Installers (make-binaries):","text":"
       
    • Bump Erlang/OTP version to 26.1.1, and other dependencies
      •  
    • Remove outdated workaround
      •  
    • Don't build Linux-PAM examples
      •  
    • Fix check for current Expat version
      •  
    • Apply minor simplifications
      •  
    • Don't duplicate config entries
      •  
    • Don't hard-code musl version
      •  
    • Omit unnecessary glibc setting
      •  
    • Set kernel version for all builds
      •  
    • Let curl fail on HTTP errors
      •  
    "},{"location":"CHANGELOG/#modules","title":"Modules:","text":"
       
    • mod_muc_log: Add trailing backslash to URLs shown in disco info
      •  
    • mod_muc_occupantid: New module with support for XEP-0421 Occupant Id (#3397)
      •  
    • mod_muc_rtbl: Better error handling in (#4050)
      •  
    • mod_private: Add support for XEP-0402 PEP Native Bookmarks
      •  
    • mod_privilege: Don't fail to edit roster (#3942)
      •  
    • mod_pubsub: Fix usage of plugins option, which produced default_node_config ignore (#4070)
      •  
    • mod_pubsub: Add pubsub_delete_item hook
      •  
    • mod_pubsub: Report support of config-node-max in pep
      •  
    • mod_pubsub: Relay pubsub iq queries to muc members without using bare jid (#4093)
      •  
    • mod_pubsub: Allow pubsub node owner to overwrite items published by other persons
      •  
    • mod_push_keepalive: Delay wake_on_start
      •  
    • mod_push_keepalive: Don't let hook crash
      •  
    • mod_push: Add notify_on option
      •  
    • mod_push: Set last-message-sender to bare JID
      •  
    • mod_register_web: Make redirect to page that end with / (#3177)
      •  
    • mod_shared_roster_ldap: Don't crash in get_member_jid on empty output (#3614)
      •  
    "},{"location":"CHANGELOG/#muc","title":"MUC:","text":"
       
    • Add support to register nick in a room (#3455)
      •  
    • Convert allow_private_message MUC room option to allowpm (#3736)
      •  
    • Update xmpp version to send roomconfig_changesubject in disco#info (#4085)
      •  
    • Fix crash when loading room from DB older than ffa07c6, 23.04
      •  
    • Fix support to retract a MUC room message
      •  
    • Don't always store messages passed through muc_filter_message (#4083)
      •  
    • Pass also MUC room retract messages over the muc_filter_message (#3397)
      •  
    • Pass MUC room private messages over the muc_filter_message too (#3397)
      •  
    • Store the subject author JID, and run muc_filter_message when sending subject (#3397)
      •  
    • Remove existing role information for users that are kicked from room (#4035)
      •  
    • Expand rule \"mucsub subscribers are members in members only rooms\" to more places
      •  
    "},{"location":"CHANGELOG/#sql_1","title":"SQL:","text":"
       
    • Add ability to force alternative upsert implementation in mysql
      •  
    • Properly parse mysql version even if it doesn't have type tag
      •  
    • Use prepared statement with mysql
      •  
    • Add alternate version of mysql upsert
      •  
    • ejabberd_auth_sql: Reset scram fields when setting plain password
      •  
    • mod_privacy_sql: Fix return values from calculate_diff
      •  
    • mod_privacy_sql: Optimize set_list
      •  
    • mod_privacy_sql: Use more efficient way to calculate changes in set_privacy_list
      •  
    "},{"location":"CHANGELOG/#version-2304","title":"Version 23.04","text":""},{"location":"CHANGELOG/#general","title":"General:","text":"
       
    • New s2s_out_bounce_packet hook
      •  
    • Re-allow anonymous connection for connection without client certificates (#3985)
      •  
    • Stop ejabberd_system_monitor before stopping node
      •  
    • captcha_url option now accepts auto value, and it's the default
      •  
    • mod_mam: Add support for XEP-0425: Message Moderation
      •  
    • mod_mam_sql: Fix problem with results of mam queries using rsm with max and before
      •  
    • mod_muc_rtbl: New module for Real-Time Block List for MUC rooms (#4017)
      •  
    • mod_roster: Set roster name from XEP-0172, or the stored one (#1611)
      •  
    • mod_roster: Preliminary support to store extra elements in subscription request (#840)
      •  
    • mod_pubsub: Pubsub xdata fields max_item/item_expira/children_max use max not infinity
      •  
    • mod_vcard_xupdate: Invalidate vcard_xupdate cache on all nodes when vcard is updated
      •  
    "},{"location":"CHANGELOG/#admin","title":"Admin:","text":"
       
    • ext_mod: Improve support for loading *.so files from ext_mod dependencies
      •  
    • Improve output in gen_html_doc_for_commands command
      •  
    • Fix ejabberdctl output formatting (#3979)
      •  
    • Log HTTP handler exceptions
      •  
    "},{"location":"CHANGELOG/#muc_1","title":"MUC:","text":"
       
    • New command get_room_history
      •  
    • Persist none role for outcasts
      •  
    • Try to populate room history from mam when unhibernating
      •  
    • Make mod_muc_room:set_opts process persistent flag first
      •  
    • Allow passing affiliations and subscribers to create_room_with_opts command
      •  
    • Store state in db in mod_muc:create_room()
      •  
    • Make subscribers members by default
      •  
    "},{"location":"CHANGELOG/#sql-schemas","title":"SQL schemas:","text":"
       
    • Fix a long standing bug in new schema migration
      •  
    • update_sql command: Many improvements in new schema migration
      •  
    • update_sql command: Add support to migrate MySQL too
      •  
    • Change PostgreSQL SERIAL to BIGSERIAL columns
      •  
    • Fix minor SQL schema inconsistencies
      •  
    • Remove unnecessary indexes
      •  
    • New SQL schema migrate fix
      •  
    "},{"location":"CHANGELOG/#ms-sql","title":"MS SQL:","text":"
       
    • MS SQL schema fixes
      •  
    • Add new schema for MS SQL
      •  
    • Add MS SQL support for new schema migration
      •  
    • Minor MS SQL improvements
      •  
    • Fix MS SQL error caused by ORDER BY in subquery
      •  
    "},{"location":"CHANGELOG/#sql-tests","title":"SQL Tests:","text":"
       
    • Add support for running tests on MS SQL
      •  
    • Add ability to run tests on upgraded DB
      •  
    • Un-deprecate ejabberd_config:set_option/2
      •  
    • Use python3 to run extauth.py for tests
      •  
    • Correct README for creating test docker MS SQL DB
      •  
    • Fix TSQLlint warnings in MSSQL test script
      •  
    "},{"location":"CHANGELOG/#testing","title":"Testing:","text":"
       
    • Fix Shellcheck warnings in shell scripts
      •  
    • Fix Remark-lint warnings
      •  
    • Fix Prospector and Pylint warnings in test extauth.py
      •  
    • Stop testing ejabberd with Erlang/OTP 19.3, as Github Actions no longer supports ubuntu-18.04
      •  
    • Test only with oldest OTP supported (20.0), newest stable (25.3) and bleeding edge (26.0-rc2)
      •  
    • Upload Common Test logs as artifact in case of failure
      •  
    "},{"location":"CHANGELOG/#ecs-container-image","title":"ecs container image:","text":"
       
    • Update Alpine to 3.17 to get Erlang/OTP 25 and Elixir 1.14
      •  
    • Add tini as runtime init
      •  
    • Set ERLANG_NODE fixed to ejabberd@localhost
      •  
    • Upload images as artifacts to Github Actions
      •  
    • Publish tag images automatically to ghcr.io
      •  
    "},{"location":"CHANGELOG/#ejabberd-container-image","title":"ejabberd container image:","text":"
       
    • Update Alpine to 3.17 to get Erlang/OTP 25 and Elixir 1.14
      •  
    • Add METHOD to build container using packages (#3983)
      •  
    • Add tini as runtime init
      •  
    • Detect runtime dependencies automatically
      •  
    • Remove unused Mix stuff: ejabberd script and static COOKIE
      •  
    • Copy captcha scripts to /opt/ejabberd-*/lib like the installers
      •  
    • Expose only HOME volume, it contains all the required subdirs
      •  
    • ejabberdctl: Don't use .../releases/COOKIE, it's no longer included
      •  
    "},{"location":"CHANGELOG/#installers","title":"Installers:","text":"
       
    • make-binaries: Bump versions, e.g. erlang/otp to 25.3
      •  
    • make-binaries: Fix building with erlang/otp v25.x
      •  
    • make-packages: Fix for installers workflow, which didn't find lynx
      •  
    "},{"location":"CHANGELOG/#version-2301","title":"Version 23.01","text":""},{"location":"CHANGELOG/#general_1","title":"General:","text":"
       
    • Add misc:uri_parse/2 to allow declaring default ports for protocols
      •  
    • CAPTCHA: Add support to define module instead of path to script
      •  
    • Clustering: Handle mnesia_system_event mnesia_up when other node joins this (#3842)
      •  
    • ConverseJS: Don't set i18n option because Converse enforces it instead of browser lang (#3951)
      •  
    • ConverseJS: Try to redirect access to files mod_conversejs to CDN when there is no local copies
      •  
    • ext_mod: compile C files and install them in ejabberd's priv
      •  
    • ext_mod: Support to get module status from Elixir modules
      •  
    • make-binaries: reduce log output
      •  
    • make-binaries: Bump zlib version to 1.2.13
      •  
    • MUC: Don't store mucsub presence events in offline storage
      •  
    • MUC: hibernation_time is not an option worth storing in room state (#3946)
      •  
    • Multicast: Jid format when multicastc was cached (#3950)
      •  
    • mysql: Pass ssl options to mysql driver
      •  
    • pgsql: Do not set standard_conforming_strings to off (#3944)
      •  
    • OAuth: Accept jid as a HTTP URL query argument
      •  
    • OAuth: Handle when client is not identified
      •  
    • PubSub: Expose the pubsub#type field in disco#info query to the node (#3914)
      •  
    • Translations: Update German translation
      •  
    "},{"location":"CHANGELOG/#admin_1","title":"Admin:","text":"
       
    • api_permissions: Fix option crash when doesn't have who: section
      •  
    • log_modules_fully: New option to list modules that will log everything
      •  
    • outgoing_s2s_families: Changed option's default to IPv6, and fall back to IPv4
      •  
    • Fix bash completion when using Relive or other install methods
      •  
    • Fix portability issue with some shells (#3970)
      •  
    • Allow admin command to subscribe new users to members_only rooms
      •  
    • Use alternative split/2 function that works with Erlang/OTP as old as 19.3
      •  
    • Silent warning in OTP24 about not specified cacerts in SQL connections
      •  
    • Fix compilation warnings with Elixir 1.14
      •  
    "},{"location":"CHANGELOG/#doap","title":"DOAP:","text":"
       
    • Support extended -protocol erlang attribute
      •  
    • Add extended RFCs and XEP details to some protocol attributes
      •  
    • tools/generate-doap.sh: New script to generate DOAP file, add make doap (#3915)
      •  
    • ejabberd.doap: New DOAP file describing ejabberd supported protocols
      •  
    "},{"location":"CHANGELOG/#mqtt","title":"MQTT:","text":"
       
    • Add MQTT bridge module
      •  
    • Add support for certificate authentication in MQTT bridge
      •  
    • Implement reload in MQTT bridge
      •  
    • Add support for websockets to MQTT bridge
      •  
    • Recognize ws5/wss5 urls in MQTT bridge
      •  
    • mqtt_publish: New hook for MQTT publish event
      •  
    • mqtt_(un)subscribe: New hooks for MQTT subscribe & unsubscribe events
      •  
    "},{"location":"CHANGELOG/#vscode","title":"VSCode:","text":"
       
    • Improve .devcontainer to use use devcontainer image and .vscode
      •  
    • Add .vscode files to instruct VSCode how to run ejabberd
      •  
    • Add Erlang LS default configuration
      •  
    • Add Elvis default configuration
      •  
    "},{"location":"CHANGELOG/#version-2210","title":"Version 22.10","text":""},{"location":"CHANGELOG/#core_2","title":"Core:","text":"
       
    • Add log_burst_limit_* options (#3865)
      •  
    • Support ERL_DIST_PORT option to work without epmd
      •  
    • Auth JWT: Catch all errors from jose_jwt:verify and log debugging details (#3890)
      •  
    • CAPTCHA: Support @VERSION@ and @SEMVER@ in captcha_cmd option (#3835)
      •  
    • HTTP: Fix unix socket support (#3894)
      •  
    • HTTP: Handle invalid values in X-Forwarded-For header more gracefuly
      •  
    • Listeners: Let module take over socket
      •  
    • Listeners: Don't register listeners that failed to start in config reload
      •  
    • mod_admin_extra: Handle empty roster group names
      •  
    • mod_conversejs: Fix crash when mod_register not enabled (#3824)
      •  
    • mod_host_meta: Complain at start if listener is not encrypted
      •  
    • mod_ping: Fix regression on stop_ping in clustering context (#3817)
      •  
    • mod_pubsub: Don't crash on command failures
      •  
    • mod_shared_roster: Fix cache invalidation
      •  
    • mod_shared_roster_ldap: Update roster_get hook to use #roster_item{}
      •  
    • prosody2ejabberd: Fix parsing of scram password from prosody
      •  
    "},{"location":"CHANGELOG/#mix","title":"MIX:","text":"
       
    • Fix MIX's filter_nodes
      •  
    • Return user jid on join
      •  
    • mod_mix_pam: Add new MIX namespaces to disco features
      •  
    • mod_mix_pam: Add handling of IQs with newer MIX namespaces
      •  
    • mod_mix_pam: Do roster pushes on join/leave
      •  
    • mod_mix_pam: Parse sub elements of the mix join remote result
      •  
    • mod_mix_pam: Provide MIX channels as roster entries via hook
      •  
    • mod_mix_pam: Display joined channels on webadmin page
      •  
    • mod_mix_pam: Adapt to renaming of participant-id from mix_roster_channel record
      •  
    • mod_roster: Change hook type from #roster{} to #roster_item{}
      •  
    • mod_roster: Respect MIX <annotate/> setting
      •  
    • mod_roster: Adapt to change of mix_annotate type to boolean in roster_query
      •  
    • mod_shared_roster: Fix wrong hook type #roster{} (now #roster_item{})
      •  
    "},{"location":"CHANGELOG/#muc_2","title":"MUC:","text":"
       
    • Store role, and use it when joining a moderated room (#3330)
      •  
    • Don't persist none role (#3330)
      •  
    • Allow MUC service admins to bypass max_user_conferences limitation
      •  
    • Show allow_query_users room option in disco info (#3830)
      •  
    • mod_muc_room: Don't set affiliation to none if it's already none in process_item_change/3
      •  
    • Fix mucsub unsubscribe notification payload to have muc_unsubcribe in it
      •  
    • Allow muc_{un}subscribe hooks to modify sent packets
      •  
    • Pass room state to muc_{un}subscribed hook
      •  
    • The archive_msg export fun requires MUC Service for room archives
      •  
    • Export mod_muc_admin:get_room_pid/2
      •  
    • Export function for getting room diagnostics
      •  
    "},{"location":"CHANGELOG/#sql_2","title":"SQL:","text":"
       
    • Handle errors reported from begin/commit inside transaction
      •  
    • Make connection close errors bubble up from inside sql transaction
      •  
    • Make first sql reconnect wait shorter time
      •  
    • React to sql driver process exit earlier
      •  
    • Skip connection exit message when we triggered reconnection
      •  
    • Add syntax_tools to applications, required when using ejabberd_sql_pt (#3869)
      •  
    • Fix mam delete_old_messages_batch for sql backend
      •  
    • Use INSERT ... ON DUPLICATE KEY UPDATE for upsert on mysql
      •  
    • Update mysql library
      •  
    • Catch mysql connection being close earlier
      •  
    "},{"location":"CHANGELOG/#build","title":"Build:","text":"
       
    • make all: Generate start scripts here, not in make install (#3821)
      •  
    • make clean: Improve this and \"distclean\"
      •  
    • make deps: Ensure deps configuration is ran when getting deps (#3823)
      •  
    • make help: Update with recent changes
      •  
    • make install: Don't leak DESTDIR in files copied by 'make install'
      •  
    • make options: Fix error reporting on OTP24+
      •  
    • make update: configure also in this case, similarly to make deps
      •  
    • Add definition to detect OTP older than 25, used by ejabberd_auth_http
      •  
    • Configure eimp with mix to detect image convert properly (#3823)
      •  
    • Remove unused macro definitions detected by rebar3_hank
      •  
    • Remove unused header files which content is already in xmpp library
      •  
    "},{"location":"CHANGELOG/#container_1","title":"Container:","text":"
       
    • Get ejabberd-contrib sources to include them
      •  
    • Copy .ejabberd-modules directory if available
      •  
    • Do not clone repo inside container build
      •  
    • Use make deps, which performs additional steps (#3823)
      •  
    • Support ERL_DIST_PORT option to work without epmd
      •  
    • Copy ejabberd-docker-install.bat from docker-ejabberd git and rename it
      •  
    • Set a less frequent healthcheck to reduce CPU usage (#3826)
      •  
    • Fix build instructions, add more podman examples
      •  
    "},{"location":"CHANGELOG/#installers_1","title":"Installers:","text":"
       
    • make-binaries: Include CAPTCHA script with release
      •  
    • make-binaries: Edit rebar.config more carefully
      •  
    • make-binaries: Fix linking of EIMP dependencies
      •  
    • make-binaries: Fix GitHub release version checks
      •  
    • make-binaries: Adjust Mnesia spool directory path
      •  
    • make-binaries: Bump Erlang/OTP version to 24.3.4.5
      •  
    • make-binaries: Bump Expat and libpng versions
      •  
    • make-packages: Include systemd unit with RPM
      •  
    • make-packages: Fix permissions on RPM systems
      •  
    • make-installers: Support non-root installation
      •  
    • make-installers: Override code on upgrade
      •  
    • make-installers: Apply cosmetic changes
      •  
    "},{"location":"CHANGELOG/#external-modules","title":"External modules:","text":"
       
    • ext_mod: Support managing remote nodes in the cluster
      •  
    • ext_mod: Handle correctly when COMMIT.json not found
      •  
    • Don't bother with COMMIT.json user-friendly feature in automated user case
      •  
    • Handle not found COMMIT.json, for example in GH Actions
      •  
    • Add WebAdmin page for managing external modules
      •  
    "},{"location":"CHANGELOG/#workflows-actions","title":"Workflows Actions:","text":"
       
    • Update workflows to Erlang 25
      •  
    • Update workflows: Ubuntu 18 is deprecated and 22 is added
      •  
    • CI: Remove syntax_tools from applications, as fast_xml fails Dialyzer
      •  
    • Runtime: Add Xref options to be as strict as CI
      •  
    "},{"location":"CHANGELOG/#version-2205","title":"Version 22.05","text":""},{"location":"CHANGELOG/#core_3","title":"Core","text":"
       
    • C2S: Don't expect that socket will be available in c2s_terminated hook
      •  
    • Event handling process hook tracing
      •  
    • Guard against erlang:system_info(logical_processors) not always returning a number
      •  
    • domain_balancing: Allow for specifying type only, without specifying component_number
      •  
    "},{"location":"CHANGELOG/#mqtt_1","title":"MQTT","text":"
       
    • Add TLS certificate authentication for MQTT connections
      •  
    • Fix login when generating client id, keep connection record (#3593)
      •  
    • Pass property name as expected in mqtt_codec (fixes login using MQTT 5)
      •  
    • Support MQTT subscriptions spread over the cluster (#3750)
      •  
    "},{"location":"CHANGELOG/#muc_3","title":"MUC","text":"
       
    • Attach meta field with real jid to mucsub subscription events
      •  
    • Handle user removal
      •  
    • Stop empty MUC rooms 30 seconds after creation
      •  
    • default_room_options: Update options configurable
      •  
    • subscribe_room_many_max_users: New option in mod_muc_admin
      •  
    "},{"location":"CHANGELOG/#mod_conversejs","title":"mod_conversejs","text":"
       
    • Improved options to support @HOST@ and auto values
      •  
    • Set auth and register options based on ejabberd configuration
      •  
    • conversejs_options: New option
      •  
    • conversejs_resources: New option
      •  
    "},{"location":"CHANGELOG/#pubsub","title":"PubSub","text":"
       
    • mod_pubsub: Allow for limiting item_expire value
      •  
    • mod_pubsub: Unsubscribe JID on whitelist removal
      •  
    • node_pep: Add config-node and multi-items features (#3714)
      •  
    "},{"location":"CHANGELOG/#sql_3","title":"SQL","text":"
       
    • Improve compatibility with various db engine versions
      •  
    • Sync old-to-new schema script with reality (#3790)
      •  
    • Slight improvement in MSSQL testing support, but not yet complete
      •  
    "},{"location":"CHANGELOG/#other-modules","title":"Other Modules","text":"
       
    • auth_jwt: Checking if an user is active in SM for a JWT authenticated user (#3795)
      •  
    • mod_configure: Implement Get List of Registered/Online Users from XEP-0133
      •  
    • mod_host_meta: New module to serve host-meta files, see XEP-0156
      •  
    • mod_mam: Store all mucsub notifications not only message notifications
      •  
    • mod_ping: Delete ping timer if resource is gone after the ping has been sent
      •  
    • mod_ping: Don't send ping if resource is gone
      •  
    • mod_push: Fix notifications for pending sessions (XEP-0198)
      •  
    • mod_push: Keep push session ID on session resume
      •  
    • mod_shared_roster: Adjust special group cache size
      •  
    • mod_shared_roster: Normalize JID on unset_presence (#3752)
      •  
    • mod_stun_disco: Fix parsing of IPv6 listeners
      •  
    "},{"location":"CHANGELOG/#dependencies","title":"Dependencies","text":"
       
    • autoconf: Supported from 2.59 to the new 2.71
      •  
    • fast_tls: Update to 1.1.14 to support OpenSSL 3
      •  
    • jiffy: Update to 1.1.1 to support Erlang/OTP 25.0-rc1
      •  
    • luerl: Update to 1.0.0, now available in hex.pm
      •  
    • lager: This dependency is used only when Erlang is older than 22
      •  
    • rebar2: Updated binary to work from Erlang/OTP 22 to 25
      •  
    • rebar3: Updated binary to work from Erlang/OTP 22 to 25
      •  
    • make update: Fix when used with rebar 3.18
      •  
    "},{"location":"CHANGELOG/#compile","title":"Compile","text":"
       
    • mix release: Copy include/ files for ejabberd, deps and otp, in mix.exs
      •  
    • rebar3 release: Fix ERTS path in ejabberdctl
      •  
    • configure.ac: Set default ejabberd version number when not using git
      •  
    • mix.exs: Move some dependencies as optional
      •  
    • mix.exs: No need to use Distillery, Elixir has built-in support for OTP releases (#3788)
      •  
    • tools/make-binaries: New script for building Linux binaries
      •  
    • tools/make-installers: New script for building command line installers
      •  
    "},{"location":"CHANGELOG/#start","title":"Start","text":"
       
    • New make relive similar to ejabberdctl live without installing
      •  
    • ejabberdctl: Fix some warnings detected by ShellCheck
      •  
    • ejabberdctl: Mention in the help: etop, ping and started/stopped
      •  
    • make rel: Switch to paths: conf/, database/, logs/
      •  
    • mix.exs: Add -boot and -boot_var in ejabberdctl instead of adding vm.args
      •  
    • tools/captcha.sh: Fix some warnings detected by ShellCheck
      •  
    "},{"location":"CHANGELOG/#commands_1","title":"Commands","text":"
       
    • Accept more types of ejabberdctl commands arguments as JSON-encoded
      •  
    • delete_old_mam_messages_batch: New command with rate limit
      •  
    • delete_old_messages_batch: New command with rate limit
      •  
    • get_room_occupants_number: Don't request the whole MUC room state (#3684, #1964)
      •  
    • get_vcard: Add support for MUC room vCard
      •  
    • oauth_revoke_token: Add support to work with all backends
      •  
    • room_unused_*: Optimize commands in SQL by reusing created_at
      •  
    • rooms_unused_...: Let get_all_rooms handle global argument (#3726)
      •  
    • stop|restart: Terminate ejabberd_sm before everything else to ensure sessions closing (#3641)
      •  
    • subscribe_room_many: New command
      •  
    "},{"location":"CHANGELOG/#translations","title":"Translations","text":"
       
    • Updated Catalan
      •  
    • Updated French
      •  
    • Updated German
      •  
    • Updated Portuguese
      •  
    • Updated Portuguese (Brazil)
      •  
    • Updated Spanish
      •  
    "},{"location":"CHANGELOG/#workflows","title":"Workflows","text":"
       
    • CI: Publish CT logs and Cover on failure to an external GH Pages repo
      •  
    • CI: Test shell scripts using ShellCheck (#3738)
      •  
    • Container: New workflow to build and publish containers
      •  
    • Installers: Add job to create draft release
      •  
    • Installers: New workflow to build binary packages
      •  
    • Runtime: New workflow to test compilation, rel, starting and ejabberdctl
      •  
    "},{"location":"CHANGELOG/#version-2112","title":"Version 21.12","text":""},{"location":"CHANGELOG/#commands_2","title":"Commands","text":"
       
    • create_room_with_opts: Fixed when using SQL storage
      •  
    • change_room_option: Add missing fields from config inside mod_muc_admin:change_options
      •  
    • piefxis: Fixed arguments of all commands
      •  
    "},{"location":"CHANGELOG/#modules_1","title":"Modules","text":"
       
    • mod_caps: Don't forget caps on XEP-0198 resumption
      •  
    • mod_conversejs: New module to serve a simple page for Converse.js
      •  
    • mod_http_upload_quota: Avoid max_days race
      •  
    • mod_muc: Support MUC hats (XEP-0317, conversejs/prosody compatible)
      •  
    • mod_muc: Optimize MucSub processing
      •  
    • mod_muc: Fix exception in mucsub {un}subscription events multicast handler
      •  
    • mod_multicast: Improve and optimize multicast routing code
      •  
    • mod_offline: Allow storing non-composing x:events in offline
      •  
    • mod_ping: Send ping from server, not bare user JID
      •  
    • mod_push: Fix handling of MUC/Sub messages
      •  
    • mod_register: New allow_modules option to restrict registration modules
      •  
    • mod_register_web: Handle unknown host gracefully
      •  
    • mod_register_web: Use mod_register configured restrictions
      •  
    "},{"location":"CHANGELOG/#pubsub_1","title":"PubSub","text":"
       
    • Add delete_expired_pubsub_items command
      •  
    • Add delete_old_pubsub_items command
      •  
    • Optimize publishing on large nodes (SQL)
      •  
    • Support unlimited number of items
      •  
    • Support max_items=max node configuration
      •  
    • Bump default value for max_items limit from 10 to 1000
      •  
    • Use configured max_items by default
      •  
    • node_flat: Avoid catch-all clauses for RSM
      •  
    • node_flat_sql: Avoid catch-all clauses for RSM
      •  
    "},{"location":"CHANGELOG/#sql_4","title":"SQL","text":"
       
    • Use INSERT ... ON CONFLICT in SQL_UPSERT for PostgreSQL >= 9.5
      •  
    • mod_mam export: assign MUC entries to the MUC service
      •  
    • MySQL: Fix typo when creating index
      •  
    • PgSQL: Add SASL auth support, PostgreSQL 14
      •  
    • PgSQL: Add missing SQL migration for table push_session
      •  
    • PgSQL: Fix vcard_search definition in pgsql new schema
      •  
    "},{"location":"CHANGELOG/#other_1","title":"Other","text":"
       
    • captcha-ng.sh: \"sort -R\" command not POSIX, added \"shuf\" and \"cat\" as fallback
      •  
    • Make s2s connection table cleanup more robust
      •  
    • Update export/import of scram password to XEP-0227 1.1
      •  
    • Update Jose to 1.11.1 (the last in hex.pm correctly versioned)
      •  
    "},{"location":"CHANGELOG/#version-2107","title":"Version 21.07","text":""},{"location":"CHANGELOG/#compilation_1","title":"Compilation","text":"
       
    • Add rebar3 3.15.2 binary
      •  
    • Add support for mix to: ./configure --enable-rebar=mix
      •  
    • Improved make rel to work with rebar3 and mix
      •  
    • Add make dev to build a development release with rebar3 or mix
      •  
    • Hex: Add sql/ and vars.config to Hex package files
      •  
    • Hex: Update mix applications list to fix error p1_utils is listed as both...
      •  
    • There are so many targets in Makefile... add make help
      •  
    • Fix extauth.py failure in test suite with Python 3
      •  
    • Added experimental support for GitHub Codespaces
      •  
    • Switch test service from TravisCI to GitHub Actions
      •  
    "},{"location":"CHANGELOG/#commands_3","title":"Commands:","text":"
       
    • Display extended error message in ejabberdctl
      •  
    • Remove SMP option from ejabberdctl.cfg, -smp was removed in OTP 21
      •  
    • create_room: After creating room, store in DB if it's persistent
      •  
    • help: Major changes in its usage and output
      •  
    • srg_create: Update to use label parameter instead of name
      •  
    "},{"location":"CHANGELOG/#modules_2","title":"Modules:","text":"
       
    • ejabberd_listener: New send_timeout option
      •  
    • mod_mix: Improvements to update to 0.14.1
      •  
    • mod_muc_room: Don't leak owner JIDs
      •  
    • mod_multicast: Routing for more MUC packets
      •  
    • mod_multicast: Correctly strip only other bcc addresses
      •  
    • mod_mqtt: Allow shared roster group placeholder in mqtt topic
      •  
    • mod_pubsub: Several fixes when using PubSub with RSM
      •  
    • mod_push: Handle MUC/Sub events correctly
      •  
    • mod_shared_roster: Delete cache after performing change to be sure that in cache will be up to date data
      •  
    • mod_shared_roster: Improve database and caching
      •  
    • mod_shared_roster: Reconfigure cache when options change
      •  
    • mod_vcard: Fix invalid_encoding error when using extended plane characters in vcard
      •  
    • mod_vcard: Update econf:vcard() to generate correct vcard_temp record
      •  
    • WebAdmin: New simple pages to view mnesia tables information and content
      •  
    • WebSocket: Fix typos
      •  
    "},{"location":"CHANGELOG/#sql_5","title":"SQL:","text":"
       
    • MySQL Backend Patch for scram-sha512
      •  
    • SQLite: When exporting for SQLite, use its specific escape options
      •  
    • SQLite: Minor fixes for new_sql_schema support
      •  
    • mod_privacy: Cast as boolean when exporting privacy_list_data to PostgreSQL
      •  
    • mod_mqtt: Add mqtt_pub table definition for MSSQL
      •  
    • mod_shared_roster: Add missing indexes to sr_group tables in all SQL databases
      •  
    "},{"location":"CHANGELOG/#version-2104","title":"Version 21.04","text":""},{"location":"CHANGELOG/#api-commands","title":"API Commands:","text":"
       
    • add_rosteritem/...: Add argument guards to roster commands
      •  
    • get_user_subscriptions: New command for MUC/Sub
      •  
    • remove_mam_for_user_with_peer: Fix when removing room archive
      •  
    • send_message: Fix bug introduced in ejabberd 21.01
      •  
    • set_vcard: Return modules errors
      •  
    "},{"location":"CHANGELOG/#build-and-setup","title":"Build and setup:","text":"
       
    • Allow ejabberd to be compatible as a dependency for an Erlang project using rebar3
      •  
    • CAPTCHA: New question/answer-based CAPTCHA script
      •  
    • --enable-lua: new configure option for luerl instead of --enable-tools
      •  
    • Remove support for HiPE, it was experimental and Erlang/OTP 24 removes it
      •  
    • Update sql_query record to handle the Erlang/OTP 24 compiler reports
      •  
    • Updated dependencies to fix Dialyzer warnings
      •  
    "},{"location":"CHANGELOG/#miscellaneous","title":"Miscellaneous:","text":"
       
    • CAPTCHA: Update FORM_TYPE from captcha to register
      •  
    • LDAP: fix eldap certificate verification
      •  
    • MySQL: Fix for \"specified key was too long\"
      •  
    • Translations: updated the Esperanto, Greek, and Japanese translations
      •  
    • Websocket: Fix PONG responses
      •  
    "},{"location":"CHANGELOG/#modules_3","title":"Modules:","text":"
       
    • mod_block_strangers: If stanza is type error, allow it passing
      •  
    • mod_caps: Don't request roster when not needed
      •  
    • mod_caps: Skip reading roster in one more case
      •  
    • mod_mam: Remove queryid from MAM fin element
      •  
    • mod_mqtt: When deregistering XMPP account, close its MQTT sessions
      •  
    • mod_muc: Take in account subscriber's affiliation when checking access to moderated room
      •  
    • mod_muc: Use monitors to track online and hard-killed rooms
      •  
    • mod_muc: When occupant is banned, remove his subscriptions too
      •  
    • mod_privacy: Make fetching roster lazy
      •  
    • mod_pubsub: Don't fail on PEP unsubscribe
      •  
    • mod_pubsub: Fix gen_pubsub_node:get_state return value
      •  
    • mod_vcard: Obtain and provide photo type in vCard LDAP
      •  
    "},{"location":"CHANGELOG/#version-2101","title":"Version 21.01","text":""},{"location":"CHANGELOG/#miscellaneous-changes","title":"Miscellaneous changes:","text":"
       
    • log_rotate_size option: Fix handling of \u2018infinity\u2019 value
      •  
    • mod_time: Fix invalid timezone
      •  
    • Auth JWT: New check_decoded_jwt hook runs the default JWT verifier
      •  
    • MUC: Allow non-occupant non-subscribed service admin send private MUC message
      •  
    • MUC: New max_password and max_captcha_whitelist options
      •  
    • OAuth: New oauth_cache_rest_failure_life_time option
      •  
    • PEP: Skip reading pep nodes that we know won\u2019t be requested due to caps
      •  
    • SQL: Add sql script to migrate mysql from old schema to new
      •  
    • SQL: Don\u2019t use REPLACE for upsert when there are \u201c-\u201d fields.
      •  
    • Shared Rosters LDAP: Add multi-domain support (and flexibility)
      •  
    • Sqlite3: Fix dependency version
      •  
    • Stun: Block loopback addresses by default
      •  
    • Several documentation fixes and clarifications
      •  
    "},{"location":"CHANGELOG/#commands_4","title":"Commands:","text":"
       
    • decide_room: Use better fallback value for room activity time when skipping room
      •  
    • delete_old_message: Fix when using sqlite spool table
      •  
    • module_install: Make ext_mod compile module with debug_info flags
      •  
    • room_unused_*: Don\u2019t fetch subscribers list
      •  
    • send_message: Don\u2019t include empty in messages
      •  
    • set_room_affiliation: Validate affiliations
      •  
    "},{"location":"CHANGELOG/#running","title":"Running:","text":"
       
    • Docker: New Dockerfile and devcontainer.json
      •  
    • New ejabberdctl foreground-quiet
      •  
    • Systemd: Allow for listening on privileged ports
      •  
    • Systemd: Integrate nicely with systemd
      •  
    "},{"location":"CHANGELOG/#translations_1","title":"Translations:","text":"
       
    • Moved gettext PO files to a new ejabberd-po repository
      •  
    • Improved several translations: Catalan, Chinese, German, Greek, Indonesian, Norwegian, Portuguese (Brazil), Spanish.
      •  
    "},{"location":"CHANGELOG/#version-2012","title":"Version 20.12","text":"
       
    • Add support for SCRAM-SHA-{256,512}-{PLUS} authentication
      •  
    • Don't use same value in cache for user don't exist and wrong password
      •  
    • outgoing_s2s_ipv*_address: New options to set ipv4/ipv6 outbound s2s out interface
      •  
    • s2s_send_packet: this hook now filters outgoing s2s stanzas
      •  
    • start_room: new hook runs when a room process is started
      •  
    • check_decoded_jwt: new hook to check decoded JWT after success authentication
      •  
    "},{"location":"CHANGELOG/#admin_2","title":"Admin","text":"
       
    • Docker: Fix DB initialization
      •  
    • New sql_odbc_driver option: choose the mssql ODBC driver
      •  
    • Rebar3: Fully supported. Enable with ./configure --with-rebar=/path/to/rebar3
      •  
    • systemd: start ejabberd in foreground
      •  
    "},{"location":"CHANGELOG/#modules_4","title":"Modules:","text":"
       
    • MAM: Make sure that jid used as base in mam xml_compress is bare
      •  
    • MAM: Support for MAM Flipped Pages
      •  
    • MUC: Always show MucSub subscribers nicks
      •  
    • MUC: Don't forget not-persistent rooms in load_permanent_rooms
      •  
    • MUC Admin: Better error reporting
      •  
    • MUC Admin: Fix commands with hibernated rooms
      •  
    • MUC Admin: Many improvements in rooms_unused_list/destroy
      •  
    • MUC Admin: create_room_with_opts Store options only if room starts
      •  
    • Pubsub: Remove 'dag' node plugin documentation
      •  
    • Push: Fix API call return type on error
      •  
    • Push: Support cache config changes on reload
      •  
    • Register: Allow for account-removal-only setup again
      •  
    • Roster: Make roster subscriptions work better with invalid roster state in db
      •  
    • Vcard: Fix vCard search by User when using Mnesia
      •  
    • WebAdmin: Allow vhost admins to view WebAdmin menus
      •  
    • WebAdmin: Don't do double utf-8 conversion on translated strings
      •  
    • WebAdmin: Mark dangerous buttons with CSS
      •  
    • WebSocket: Make websocket send put back pressure on c2s process
      •  
    "},{"location":"CHANGELOG/#version-2007","title":"Version 20.07","text":""},{"location":"CHANGELOG/#changes-in-this-version","title":"Changes in this version","text":"
       
    • Add support for using unix sockets in listeners.
      •  
    • Make this version compatible with erlang R23
      •  
    • Make room permissions checks more strict for subscribers
      •  
    • Fix problem with muc rooms crashing when using muc logger   with some locales
      •  
    • Limit stat calls that logger module issues
      •  
    • Don't throw errors when using user_regexp acl rule and   having non-matching host
      •  
    • Fix problem with leaving old data when updating shared rosters
      •  
    • Fix edge case that caused failure of resuming old sessions with   stream management.
      •  
    • Fix crash when room that was started with logging enabled was later   changed to logging disabled
      •  
    • Increase default shaper limits (this should help with delays for   clients that are using jingle)
      •  
    • Fix couple compatibility problems which prevented working on   erlang R19
      •  
    • Fix sending presence unavailable when session terminates for   clients that only send directed presences (helps with sometimes   not leaving muc rooms on disconnect).
      •  
    • Prevent supervisor errors for sockets that were closed before   they were passed to handler modules
      •  
    • Make stun module work better with ipv6 addresses
      •  
    "},{"location":"CHANGELOG/#version-2003","title":"Version 20.03","text":""},{"location":"CHANGELOG/#changes-in-this-version_1","title":"Changes in this version","text":"
       
    • Add support of ssl connection when connection to mysql   database (configured with sql_ssl: true option)
      •  
    • Experimental support for cockroachdb when configured   with postgres connector
      •  
    • Add cache and optimize queries issued by mod_shared_roster,   this should greatly improve performance of this module when   used with sql backend
      •  
    • Fix problem with accessing webadmin
      •  
    • Make webadmin work even when url is missing trailing slash
      •  
    • When compiling external modules with ext_mod, use flags   that were detected during compilation of ejabberd
      •  
    • Make config changed to ldap options be updated when issued   reload_config command
      •  
    • Fix room_empty_destory command
      •  
    • Fix reporting errors in send_stanza command when xml   passed to it couldn't be passed correctly
      •  
    "},{"location":"CHANGELOG/#version-2002","title":"Version 20.02","text":""},{"location":"CHANGELOG/#changes-in-this-version_2","title":"Changes in this version","text":"
       
    • Fix problems when trying to use string format with unicode   values directly in xmpp nodes
      •  
    • Add missing oauth_client table declaration in lite.new.sql
      •  
    • Improve compatibility with CocroachDB
      •  
    • Fix importing of piefxis files that did use scram passwords
      •  
    • Fix importing of piefxis files that had multiple includes   in them
      •  
    • Update jiffy dependency
      •  
    • Allow storage of emojis when using mssql database (Thanks   to Christoph Scholz)
      •  
    • Make ejabberd_auth_http be able to use auth_opts
      •  
    • Make custom_headers options in http modules correctly   override built-in values
      •  
    • Fix return value of reload_config and dump_config commands
      •  
    "},{"location":"CHANGELOG/#version-2001","title":"Version 20.01","text":""},{"location":"CHANGELOG/#new-features","title":"New features","text":"
       
    • Implement OAUTH authentication in mqtt
      •  
    • Make logging infrastructure use new logger introduced   in Erlang (requires OTP22)
      •  
    • New configuration parser/validator
      •  
    • Initial work on being able to use CockroachDB as database backend
      •  
    • Add gc command
      •  
    • Add option to disable using prepared statements on Postgresql
      •  
    • Implement routine for converting password to SCRAM format   for all backends not only SQL
      •  
    • Add infrastructure for having module documentation directly   in individual module source code
      •  
    • Generate man page automatically
      •  
    • Implement copy feature in mod_carboncopy
      •  
    "},{"location":"CHANGELOG/#fixes","title":"Fixes","text":"
       
    • Make webadmin work with configurable paths
      •  
    • Fix handling of result in xmlrpc module
      •  
    • Make webadmin work even when accessed through not declared domain
      •  
    • Better error reporting in xmlrpc
      •  
    • Limit amount of results returned by disco queries to pubsub nodes
      •  
    • Improve validation of configured JWT keys
      •  
    • Fix race condition in Redis/SQL startup
      •  
    • Fix loading order of third party modules
      •  
    • Fix reloading of ACL rules
      •  
    • Make account removal requests properly route response
      •  
    • Improve handling of malformed inputs in send_message command
      •  
    • Omit push notification if storing message in offline storage   failed
      •  
    • Fix crash in stream management when timeout was not set
      •  
    "},{"location":"CHANGELOG/#version-1909","title":"Version 19.09","text":""},{"location":"CHANGELOG/#admin_3","title":"Admin","text":"
       
    • The minimum required Erlang/OTP version is now 19.3
      •  
    • Fix API call using OAuth (#2982)
      •  
    • Rename MUC command arguments from Host to Service (#2976)
      •  
    "},{"location":"CHANGELOG/#webadmin","title":"Webadmin","text":"
       
    • Don't treat 'Host' header as a virtual XMPP host (#2989)
      •  
    • Fix some links to Guide in WebAdmin and add new ones (#3003)
      •  
    • Use select fields to input host in WebAdmin Backup (#3000)
      •  
    • Check account auth provided in WebAdmin is a local host (#3000)
      •  
    "},{"location":"CHANGELOG/#acme","title":"ACME","text":"
       
    • Improve ACME implementation
      •  
    • Fix IDA support in ACME requests
      •  
    • Fix unicode formatting in ACME module
      •  
    • Log an error message on IDNA failure
      •  
    • Support IDN hostnames in ACME requests
      •  
    • Don't attempt to create ACME directory on ejabberd startup
      •  
    • Don't allow requesting certificates for localhost or IP-like domains
      •  
    • Don't auto request certificate for localhost and IP-like domains
      •  
    • Add listener for ACME challenge in example config
      •  
    "},{"location":"CHANGELOG/#authentication","title":"Authentication","text":"
       
    • JWT-only authentication for some users (#3012)
      •  
    "},{"location":"CHANGELOG/#muc_4","title":"MUC","text":"
       
    • Apply default role after revoking admin affiliation (#3023)
      •  
    • Custom exit message is not broadcast (#3004)
      •  
    • Revert \"Affiliations other than admin and owner cannot invite to members_only rooms\" (#2987)
      •  
    • When join new room with password, set pass and password_protected (#2668)
      •  
    • Improve rooms_* commands to accept 'global' as MUC service argument (#2976)
      •  
    • Rename MUC command arguments from Host to Service (#2976)
      •  
    "},{"location":"CHANGELOG/#sql_6","title":"SQL","text":"
       
    • Fix transactions for Microsoft SQL Server (#2978)
      •  
    • Spawn SQL connections on demand only
      •  
    "},{"location":"CHANGELOG/#misc","title":"Misc","text":"
       
    • Add support for XEP-0328: JID Prep
      •  
    • Added gsfonts for captcha
      •  
    • Log Mnesia table type on creation
      •  
    • Replicate Mnesia 'bosh' table when nodes are joined
      •  
    • Fix certificate selection for s2s (#3015)
      •  
    • Provide meaningful error when adding non-local users to shared roster (#3000)
      •  
    • Websocket: don't treat 'Host' header as a virtual XMPP host (#2989)
      •  
    • Fix sm ack related c2s error (#2984)
      •  
    • Don't hide the reason why c2s connection has failed
      •  
    • Unicode support
      •  
    • Correctly handle unicode in log messages
      •  
    • Fix unicode processing in ejabberd.yml
      •  
    "},{"location":"CHANGELOG/#version-1908","title":"Version 19.08","text":""},{"location":"CHANGELOG/#administration","title":"Administration","text":"
       
    • Improve ejabberd halting procedure
      •  
    • Process unexpected erlang messages uniformly: logging a warning
      •  
    • mod_configure: Remove modules management
      •  
    "},{"location":"CHANGELOG/#configuration","title":"Configuration","text":"
       
    • Use new configuration validator
      •  
    • ejabberd_http: Use correct virtual host when consulting trusted_proxies
      •  
    • Fix Elixir modules detection in the configuration file
      •  
    • Make option 'validate_stream' global
      •  
    • Allow multiple definitions of host_config and append_host_config
      •  
    • Introduce option 'captcha_url'
      •  
    • mod_stream_mgmt: Allow flexible timeout format
      •  
    • mod_mqtt: Allow flexible timeout format in session_expiry option
      •  
    "},{"location":"CHANGELOG/#misc_1","title":"Misc","text":"
       
    • Fix SQL connections leakage
      •  
    • New authentication method using JWT tokens
      •  
    • extauth: Add 'certauth' command
      •  
    • Improve SQL pool logic
      •  
    • Add and improve type specs
      •  
    • Improve extraction of translated strings
      •  
    • Improve error handling/reporting when loading language translations
      •  
    • Improve hooks validator and fix bugs related to hooks registration
      •  
    • Gracefully close inbound s2s connections
      •  
    • mod_mqtt: Fix usage of TLS
      •  
    • mod_offline: Make count_offline_messages cache work when using mam for storage
      •  
    • mod_privacy: Don't attempt to query 'undefined' active list
      •  
    • mod_privacy: Fix race condition
      •  
    "},{"location":"CHANGELOG/#muc_5","title":"MUC","text":"
       
    • Add code for hibernating inactive muc_room processes
      •  
    • Improve handling of unexpected iq in mod_muc_room
      •  
    • Attach mod_muc_room processes to a supervisor
      •  
    • Restore room when receiving message or generic iq for not started room
      •  
    • Distribute routing of MUC messages across all CPU cores
      •  
    "},{"location":"CHANGELOG/#pubsub_2","title":"PubSub","text":"
       
    • Fix pending nodes retrieval for SQL backend
      •  
    • Check access_model when publishing PEP
      •  
    • Remove deprecated pubsub plugins
      •  
    • Expose access_model and publish_model in pubsub#metadata
      •  
    "},{"location":"CHANGELOG/#version-1905","title":"Version 19.05","text":""},{"location":"CHANGELOG/#admin_4","title":"Admin","text":"
       
    • The minimum required Erlang/OTP version is now 19.1
      •  
    • Provide a suggestion when unknown command, module, option or request handler is detected
      •  
    • Deprecate some listening options: captcha, register, web_admin, http_bind and xmlrpc
      •  
    • Add commands to get Mnesia info: mnesia_info and mnesia_table_info
      •  
    • Fix Register command to respect mod_register's Access option
      •  
    • Fixes in Prosody import: privacy and rooms
      •  
    • Remove TLS options from the example config
      •  
    • Improve request_handlers validator
      •  
    • Fix syntax in example Elixir config file
      •  
    "},{"location":"CHANGELOG/#auth","title":"Auth","text":"
       
    • Correctly support cache tags in ejabberd_auth
      •  
    • Don't process failed EXTERNAL authentication by mod_fail2ban
      •  
    • Don't call to mod_register when it's not loaded
      •  
    • Make anonymous auth don't {de}register user when there are other resources
      •  
    "},{"location":"CHANGELOG/#developer","title":"Developer","text":"
       
    • Rename listening callback from start/2 to start/3
      •  
    • New hook called when room gets destroyed: room_destroyed
      •  
    • New hooks for tracking mucsub subscriptions changes: muc_subscribed, muc_unsubscribed
      •  
    • Make static hooks analyzer working again
      •  
    "},{"location":"CHANGELOG/#muc_6","title":"MUC","text":"
       
    • Service admins are allowed to recreate room even if archive is nonempty
      •  
    • New option user_mucsub_from_muc_archive
      •  
    • Avoid late arrival of get_disco_item response
      •  
    • Handle get_subscribed_rooms call from mod_muc_room pid
      •  
    • Fix room state cleanup from db on change of persistent option change
      •  
    • Make get_subscribed_rooms work even for non-persistant rooms
      •  
    • Allow non-moderator subscribers to get list of room subscribers
      •  
    "},{"location":"CHANGELOG/#offline","title":"Offline","text":"
       
    • New option bounce_groupchat: make it not bounce mucsub/groupchat messages
      •  
    • New option use_mam_for_storage: fetch data from mam instead of spool table
      •  
    • When applying limit of max msgs in spool check only spool size
      •  
    • Do not store mucsub wrapped messages with no-store hint in offline storage
      •  
    • Always store ActivityMarker messages
      •  
    • Don't issue count/message fetch queries for offline from mam when not needed
      •  
    • Properly handle infinity as max number of message in mam offline storage
      •  
    • Sort messages by stanza_id when using mam storage in mod_offline
      •  
    • Return correct value from count_offline_messages with mam storage option
      •  
    • Make mod_offline put msg ignored by mam in spool when mam storage is on
      •  
    "},{"location":"CHANGELOG/#sql_7","title":"SQL:","text":"
       
    • Add SQL schemas for MQTT tables
      •  
    • Report better errors on SQL terms decode failure
      •  
    • Fix PostgreSQL compatibility in mod_offline_sql:remove_old_messages
      •  
    • Fix handling of list arguments on pgsql
      •  
    • Preliminary support for SQL in process_rosteritems command
      •  
    "},{"location":"CHANGELOG/#tests","title":"Tests","text":"
       
    • Add tests for user mucsub mam from muc mam
      •  
    • Add tests for offline with mam storage
      •  
    • Add tests for offline use_mam_for_storage
      •  
    • Initial Docker environment to run ejabberd test suite
      •  
    • Test offline:use_mam_for_storage, mam:user_mucsub_from_muc_archive used together
      •  
    "},{"location":"CHANGELOG/#websocket","title":"Websocket","text":"
       
    • Add WebSockets support to mod_mqtt
      •  
    • Return \"Bad request\" error when origin in websocket connection doesn't match
      •  
    • Fix RFC6454 violation on websocket connection when validating Origin header
      •  
    • Origin header validation on websocket connection
      •  
    "},{"location":"CHANGELOG/#other-modules_1","title":"Other modules","text":"
       
    • mod_adhoc: Use xml:lang from stanza when it's missing in  element
      •  
    • mod_announce: Add 'sessionid' attribute when required
      •  
    • mod_bosh: Don't put duplicate polling attribute in bosh payload
      •  
    • mod_http_api: Improve argument error messages and log messages
      •  
    • mod_http_upload: Feed whole image to eimp:identify/1
      •  
    • mod_http_upload: Log nicer warning on unknown host
      •  
    • mod_http_upload: Case-insensitive host comparison
      •  
    • mod_mqtt: Support other socket modules
      •  
    • mod_push: Check for payload in encrypted messages
      •  
    "},{"location":"CHANGELOG/#version-1902","title":"Version 19.02","text":""},{"location":"CHANGELOG/#admin_5","title":"Admin","text":"
       
    • Fix in configure.ac the Erlang/OTP version: from 17.5 to 19.0
      •  
    • reload_config command: Fix crash when sql_pool_size option is used
      •  
    • reload_config command: Fix crash when SQL is not configured
      •  
    • rooms_empty_destroy command: Several fixes to behave more conservative
      •  
    • Fix serverhost->host parameter name for muc_(un)register_nick API
      •  
    "},{"location":"CHANGELOG/#configuration_1","title":"Configuration","text":"
       
    • Allow specifying tag for listener for api_permission purposes
      •  
    • Change default ciphers to intermediate
      •  
    • Define default ciphers/protocol_option in example config
      •  
    • Don't crash on malformed 'modules' section
      •  
    • mod_mam: New option clear_archive_on_room_destroy to prevent archive removal on room destroy
      •  
    • mod_mam: New option access_preferences to restrict who can modify the MAM preferences
      •  
    • mod_muc: New option access_mam to restrict who can modify that room option
      •  
    • mod_offline: New option store_groupchat to allow storing group chat messages
      •  
    "},{"location":"CHANGELOG/#core_4","title":"Core","text":"
       
    • Add MQTT protocol support
      •  
    • Fix (un)setting of priority
      •  
    • Use OTP application startup infrastructure for starting dependencies
      •  
    • Improve starting order of several dependencies
      •  
    "},{"location":"CHANGELOG/#mam","title":"MAM","text":"
       
    • mod_mam_mnesia/sql: Improve check for empty archive
      •  
    • disallow room creation if archive not empty and clear_archive_on_room_destroy is false
      •  
    • allow check if archive is empty for or user or room
      •  
    • Additional checks for database failures
      •  
    "},{"location":"CHANGELOG/#muc_7","title":"MUC","text":"
       
    • Make sure that room_destroyed is called even when some code throws in terminate
      •  
    • Update muc room state after adding extra access field to it
      •  
    • MUC/Sub: Send mucsub subscriber notification events with from set to room jid
      •  
    "},{"location":"CHANGELOG/#shared-roster","title":"Shared Roster","text":"
       
    • Don't perform roster push for non-local contacts
      •  
    • Handle versioning result when shared roster group has remote account
      •  
    • Fix SQL queries
      •  
    "},{"location":"CHANGELOG/#miscelanea","title":"Miscelanea","text":"
       
    • CAPTCHA: Add no-store hint to CAPTCHA challenge stanzas
      •  
    • HTTP: Reject http_api request with malformed Authentication header
      •  
    • mod_carboncopy: Don't lose carbons on presence change or session resumption
      •  
    • mod_mix: Fix submission-id and channel resource
      •  
    • mod_ping: Fix ping IQ reply/timeout processing (17.x regression)
      •  
    • mod_private: Hardcode item ID for PEP bookmarks
      •  
    • mod_push: Improve notification error handling
      •  
    • PIEFXIS: Fix user export when password is scrammed
      •  
    • Prosody: Improve import of roster items, rooms and attributes
      •  
    • Translations: fixed \"make translations\"
      •  
    • WebAdmin: Fix support to restart module with new options
      •  
    "},{"location":"CHANGELOG/#version-1812","title":"Version 18.12","text":"
       
    • MAM data store compression
      •  
    • Proxy protocol support
      •  
    • MUC Self-Ping optimization (XEP-0410)
      •  
    • Bookmarks conversion (XEP-0411)
      •  
    "},{"location":"CONTAINER/","title":"ejabberd Container","text":""},{"location":"CONTAINER/#ejabberd-container-image","title":"ejabberd Container Image","text":"
    ejabberd is an open-source, robust, scalable and extensible realtime platform built using Erlang/OTP, that includes XMPP Server, MQTT Broker and SIP Service.
     
    This document explains how to use the ejabberd container image available in ghcr.io/processone/ejabberd, built using the files in .github/container/. This image is based in Alpine 3.19, includes Erlang/OTP 26.2 and Elixir 1.16.1.
     
    Alternatively, there is also the ecs container image available in docker.io/ejabberd/ecs, built using the docker-ejabberd/ecs repository. Check the differences between ejabberd and ecs images.
     
    If you are using a Windows operating system, check the tutorials mentioned in ejabberd Docs > Docker Image.
    "},{"location":"CONTAINER/#start-ejabberd","title":"Start ejabberd","text":""},{"location":"CONTAINER/#with-default-configuration","title":"With default configuration","text":"
    Start ejabberd in a new container:
     
    docker run --name ejabberd -d -p 5222:5222 ghcr.io/processone/ejabberd\n
     
    That runs the container as a daemon, using ejabberd default configuration file and XMPP domain \"localhost\".
     
    Stop the running container:
     
    docker stop ejabberd\n
     
    Restart the stopped ejabberd container:
     
    docker restart ejabberd\n
    "},{"location":"CONTAINER/#start-with-erlang-console-attached","title":"Start with Erlang console attached","text":"
    Start ejabberd with an Erlang console attached using the live command:
     
    docker run --name ejabberd -it -p 5222:5222 ghcr.io/processone/ejabberd live\n
     
    That uses the default configuration file and XMPP domain \"localhost\".
    "},{"location":"CONTAINER/#start-with-your-configuration-and-database","title":"Start with your configuration and database","text":"
    Pass a configuration file as a volume and share the local directory to store database:
     
    mkdir database\nchown ejabberd database\n\ncp ejabberd.yml.example ejabberd.yml\n\ndocker run --name ejabberd -it \\\n  -v $(pwd)/ejabberd.yml:/opt/ejabberd/conf/ejabberd.yml \\\n  -v $(pwd)/database:/opt/ejabberd/database \\\n  -p 5222:5222 ghcr.io/processone/ejabberd live\n
     
    Notice that ejabberd runs in the container with an account named ejabberd, and the volumes you mount must grant proper rights to that account.
    "},{"location":"CONTAINER/#next-steps","title":"Next steps","text":""},{"location":"CONTAINER/#register-the-administrator-account","title":"Register the administrator account","text":"
    The default ejabberd configuration does not grant admin privileges to any account, you may want to register a new account in ejabberd and grant it admin rights.
     
    Register an account using the ejabberdctl script:
     
    docker exec -it ejabberd ejabberdctl register admin localhost passw0rd\n
     
    Then edit conf/ejabberd.yml and add the ACL as explained in ejabberd Docs: Administration Account
    "},{"location":"CONTAINER/#check-ejabberd-log-files","title":"Check ejabberd log files","text":"
    Check the content of the log files inside the container, even if you do not put it on a shared persistent drive:
     
    docker exec -it ejabberd tail -f logs/ejabberd.log\n
    "},{"location":"CONTAINER/#inspect-the-container-files","title":"Inspect the container files","text":"
    The container uses Alpine Linux. Start a shell inside the container:
     
    docker exec -it ejabberd sh\n
    "},{"location":"CONTAINER/#open-ejabberd-debug-console","title":"Open ejabberd debug console","text":"
    Open an interactive debug Erlang console attached to a running ejabberd in a running container:
     
    docker exec -it ejabberd ejabberdctl debug\n
    "},{"location":"CONTAINER/#captcha","title":"CAPTCHA","text":"
    ejabberd includes two example CAPTCHA scripts. If you want to use any of them, first install some additional required libraries:
     
    docker exec --user root ejabberd apk add imagemagick ghostscript-fonts bash\n
     
    Now update your ejabberd configuration file, for example: 
    docker exec -it ejabberd vi conf/ejabberd.yml\n
     
    and add this option: 
    captcha_cmd: /opt/ejabberd-22.04/lib/captcha.sh\n
     
    Finally, reload the configuration file or restart the container: 
    docker exec ejabberd ejabberdctl reload_config\n
     
    If the CAPTCHA image is not visible, there may be a problem generating it (the ejabberd log file may show some error message); or the image URL may not be correctly detected by ejabberd, in that case you can set the correct URL manually, for example: 
    captcha_url: https://localhost:5443/captcha\n
     
    For more details about CAPTCHA options, please check the CAPTCHA documentation section.
    "},{"location":"CONTAINER/#advanced-container-configuration","title":"Advanced Container Configuration","text":""},{"location":"CONTAINER/#ports","title":"Ports","text":"
    This container image exposes the ports:
     
       
    • 5222: The default port for XMPP clients.
      •  
    • 5269: For XMPP federation. Only needed if you want to communicate with users on other servers.
      •  
    • 5280: For admin interface.
      •  
    • 5443: With encryption, used for admin interface, API, CAPTCHA, OAuth, Websockets and XMPP BOSH.
      •  
    • 1883: Used for MQTT
      •  
    • 4369-4399: EPMD and Erlang connectivity, used for ejabberdctl and clustering
      •  
    • 5210: Erlang connectivity when ERL_DIST_PORT is set, alternative to EPMD
      •  
    "},{"location":"CONTAINER/#volumes","title":"Volumes","text":"
    ejabberd produces two types of data: log files and database spool files (Mnesia). This is the kind of data you probably want to store on a persistent or local drive (at least the database).
     
    The volumes you may want to map:
     
       
    • /opt/ejabberd/conf/: Directory containing configuration and certificates
      •  
    • /opt/ejabberd/database/: Directory containing Mnesia database. You should back up or export the content of the directory to persistent storage (host storage, local storage, any storage plugin)
      •  
    • /opt/ejabberd/logs/: Directory containing log files
      •  
    • /opt/ejabberd/upload/: Directory containing uploaded files. This should also be backed up.
      •  
     
    All these files are owned by ejabberd user inside the container.
     
    It's possible to install additional ejabberd modules using volumes, this comment explains how to install an additional module using docker-compose.
    "},{"location":"CONTAINER/#commands-on-start","title":"Commands on start","text":"
    The ejabberdctl script reads the CTL_ON_CREATE environment variable the first time the container is started, and reads CTL_ON_START every time the container is started. Those variables can contain one ejabberdctl command, or several commands separated with the blankspace and ; characters.
     
    By default failure of any of commands executed that way would abort start, this can be disabled by prefixing commands with !
     
    Example usage (or check the full example): 
        environment:\n      - CTL_ON_CREATE=! register admin localhost asd\n      - CTL_ON_START=stats registeredusers ;\n                     check_password admin localhost asd ;\n                     status\n
    "},{"location":"CONTAINER/#clustering","title":"Clustering","text":"
    When setting several containers to form a cluster of ejabberd nodes, each one must have a different Erlang Node Name and the same Erlang Cookie.
     
    For this you can either: - edit conf/ejabberdctl.cfg and set variables ERLANG_NODE and ERLANG_COOKIE - set the environment variables ERLANG_NODE_ARG and ERLANG_COOKIE
     
    Example to connect a local ejabberdctl to a containerized ejabberd: 1. When creating the container, export port 5210, and set ERLANG_COOKIE: 
    docker run --name ejabberd -it \\\n  -e ERLANG_COOKIE=`cat $HOME/.erlang.cookie` \\\n  -p 5210:5210 -p 5222:5222 \\\n  ghcr.io/processone/ejabberd\n
     2. Set ERL_DIST_PORT=5210 in ejabberdctl.cfg of container and local ejabberd 3. Restart the container 4. Now use ejabberdctl in your local ejabberd deployment
     
    To connect using a local ejabberd script: 
    ERL_DIST_PORT=5210 _build/dev/rel/ejabberd/bin/ejabberd ping\n
     
    Example using environment variables (see full example docker-compose.yml): 
        environment:\n      - ERLANG_NODE_ARG=ejabberd@node7\n      - ERLANG_COOKIE=dummycookie123\n
    "},{"location":"CONTAINER/#build-a-container-image","title":"Build a Container Image","text":"
    This container image includes ejabberd as a standalone OTP release built using Elixir. That OTP release is configured with:
     
       
    • mix.exs: Customize ejabberd release
      •  
    • vars.config: ejabberd compilation configuration options
      •  
    • config/runtime.exs: Customize ejabberd paths
      •  
    • ejabberd.yml.template: ejabberd default config file
      •  
    "},{"location":"CONTAINER/#direct-build","title":"Direct build","text":"
    Build ejabberd Community Server container image from ejabberd master git repository:
     
    docker buildx build \\\n    -t personal/ejabberd \\\n    -f .github/container/Dockerfile \\\n    .\n
    "},{"location":"CONTAINER/#podman-build","title":"Podman build","text":"
    It's also possible to use podman instead of docker, just notice: - EXPOSE 4369-4399 port range is not supported, remove that in Dockerfile - It mentions that healthcheck is not supported by the Open Container Initiative image format - to start with command live, you may want to add environment variable EJABBERD_BYPASS_WARNINGS=true 
    podman build \\\n    -t ejabberd \\\n    -f .github/container/Dockerfile \\\n    .\n\npodman run --name eja1 -d -p 5222:5222 localhost/ejabberd\n\npodman exec eja1 ejabberdctl status\n\npodman exec -it eja1 sh\n\npodman stop eja1\n\npodman run --name eja1 -it -e EJABBERD_BYPASS_WARNINGS=true -p 5222:5222 localhost/ejabberd live\n
    "},{"location":"CONTAINER/#package-build-for-arm64","title":"Package build for arm64","text":"
    By default, .github/container/Dockerfile builds this container by directly compiling ejabberd, it is a fast and direct method. However, a problem with QEMU prevents building the container in QEMU using Erlang/OTP 25 for the arm64 architecture.
     
    Providing --build-arg METHOD=package is an alternate method to build the container used by the Github Actions workflow that provides amd64 and arm64 container images. It first builds an ejabberd binary package, and later installs it in the image. That method avoids using QEMU, so it can build arm64 container images, but is extremely slow the first time it's used, and consequently not recommended for general use.
     
    In this case, to build the ejabberd container image for arm64 architecture:
     
    docker buildx build \\\n    --build-arg METHOD=package \\\n    --platform linux/arm64 \\\n    -t personal/ejabberd:$VERSION \\\n    -f .github/container/Dockerfile \\\n    .\n
    "},{"location":"CONTAINER/#composer-examples","title":"Composer Examples","text":""},{"location":"CONTAINER/#minimal-example","title":"Minimal Example","text":"
    This is the barely minimal file to get a usable ejabberd. Store it as docker-compose.yml:
     
    services:\n  main:\n    image: ghcr.io/processone/ejabberd\n    container_name: ejabberd\n    ports:\n      - \"5222:5222\"\n      - \"5269:5269\"\n      - \"5280:5280\"\n      - \"5443:5443\"\n
     
    Create and start the container with the command: 
    docker-compose up\n
    "},{"location":"CONTAINER/#customized-example","title":"Customized Example","text":"
    This example shows the usage of several customizations: it uses a local configuration file, stores the mnesia database in a local path, registers an account when it's created, and checks the number of registered accounts every time it's started.
     
    Download or copy the ejabberd configuration file: 
    wget https://raw.githubusercontent.com/processone/ejabberd/master/ejabberd.yml.example\nmv ejabberd.yml.example ejabberd.yml\n
     
    Create the database directory and allow the container access to it: 
    mkdir database\nsudo chown 9000:9000 database\n
     
    Now write this docker-compose.yml file: 
    version: '3.7'\n\nservices:\n\n  main:\n    image: ghcr.io/processone/ejabberd\n    container_name: ejabberd\n    environment:\n      - CTL_ON_CREATE=register admin localhost asd\n      - CTL_ON_START=registered_users localhost ;\n                     status\n    ports:\n      - \"5222:5222\"\n      - \"5269:5269\"\n      - \"5280:5280\"\n      - \"5443:5443\"\n    volumes:\n      - ./ejabberd.yml:/opt/ejabberd/conf/ejabberd.yml:ro\n      - ./database:/opt/ejabberd/database\n
    "},{"location":"CONTAINER/#clustering-example","title":"Clustering Example","text":"
    In this example, the main container is created first. Once it is fully started and healthy, a second container is created, and once ejabberd is started in it, it joins the first one.
     
    An account is registered in the first node when created (and we ignore errors that can happen when doing that - for example whenn account already exists), and it should exist in the second node after join.
     
    Notice that in this example the main container does not have access to the exterior; the replica exports the ports and can be accessed.
     
    version: '3.7'\n\nservices:\n\n  main:\n    image: ghcr.io/processone/ejabberd\n    container_name: ejabberd\n    environment:\n      - ERLANG_NODE_ARG=ejabberd@main\n      - ERLANG_COOKIE=dummycookie123\n      - CTL_ON_CREATE=! register admin localhost asd\n\n  replica:\n    image: ghcr.io/processone/ejabberd\n    container_name: replica\n    depends_on:\n      main:\n        condition: service_healthy\n    ports:\n      - \"5222:5222\"\n      - \"5269:5269\"\n      - \"5280:5280\"\n      - \"5443:5443\"\n    environment:\n      - ERLANG_NODE_ARG=ejabberd@replica\n      - ERLANG_COOKIE=dummycookie123\n      - CTL_ON_CREATE=join_cluster ejabberd@main\n      - CTL_ON_START=registered_users localhost ;\n                     status\n
    "},{"location":"COPYING/","title":"License","text":"
    As a special exception, the authors give permission to link this program with the OpenSSL library and distribute the resulting binary.
    "},{"location":"COPYING/#gnu-general-public-license","title":"GNU GENERAL PUBLIC LICENSE","text":"
    Version 2, June 1991
     
    Copyright (C) 1989, 1991 Free Software Foundation, Inc.  \n51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA\n\nEveryone is permitted to copy and distribute verbatim copies\nof this license document, but changing it is not allowed.\n
    "},{"location":"COPYING/#preamble","title":"Preamble","text":"
    The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too.
     
    When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
     
    To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
     
    For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
     
    We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
     
    Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
     
    Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
     
    The precise terms and conditions for copying, distribution and modification follow.
    "},{"location":"COPYING/#terms-and-conditions-for-copying-distribution-and-modification","title":"TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION","text":"
    0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The \"Program\", below, refers to any such program or work, and a \"work based on the Program\" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term \"modification\".) Each licensee is addressed as \"you\".
     
    Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
     
    1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.
     
    You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
     
    2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
     
    a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
     
    b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
     
    c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)
     
    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
     
    Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.
     
    In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
     
    3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
     
    a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
     
    b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
     
    c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
     
    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
     
    If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
     
    4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
     
    5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
     
    6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
     
    7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.
     
    If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.
     
    It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
     
    This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
     
    8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
     
    9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
     
    Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and \"any later version\", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
     
    10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
     
    NO WARRANTY
     
    11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM \"AS IS\" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
     
    12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
     
    END OF TERMS AND CONDITIONS
    "},{"location":"COPYING/#how-to-apply-these-terms-to-your-new-programs","title":"How to Apply These Terms to Your New Programs","text":"
    If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
     
    To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the \"copyright\" line and a pointer to where the full notice is found.
     
    one line to give the program's name and an idea of what it does.\nCopyright (C) yyyy  name of author\n\nThis program is free software; you can redistribute it and/or\nmodify it under the terms of the GNU General Public License\nas published by the Free Software Foundation; either version 2\nof the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program; if not, write to the Free Software\nFoundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.\n
     
    Also add information on how to contact you by electronic and paper mail.
     
    If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
     
    Gnomovision version 69, Copyright (C) year name of author\nGnomovision comes with ABSOLUTELY NO WARRANTY; for details\ntype `show w'.  This is free software, and you are welcome\nto redistribute it under certain conditions; type `show c' \nfor details.\n
     
    The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.
     
    You should also get your employer (if you work as a programmer) or your school, if any, to sign a \"copyright disclaimer\" for the program, if necessary. Here is a sample; alter the names:
     
    Yoyodyne, Inc., hereby disclaims all copyright\ninterest in the program `Gnomovision'\n(which makes passes at compilers) written \nby James Hacker.\n\nsignature of Ty Coon, 1 April 1989\nTy Coon, President of Vice\n
     
    This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License.
    "},{"location":"README-DOCS/","title":"ejabberd Docs Source Code","text":"
    The ejabberd Community Server has its source code available in the ejabberd git repository. Its documentation is published in the ejabberd Docs website, and its source code is available in the docs git repository.
     
    This is a community effort and you are welcome to submit issues or pull requests in order to improve the docs and benefit the ejabberd community.
     
    This documentation site is built using MkDocs and Material for MkDocs.
    "},{"location":"README-DOCS/#installation","title":"Installation","text":"
    To build the site you need Python 3.6 or later, then install the dependencies:
    "},{"location":"README-DOCS/#pip","title":"pip","text":"
    mkdir -p .venv\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n
     
    Info
     
    From now on, remember to run source .venv/bin/activate before running any mkdocs [...] command.
     
    Tip
     
    You can freeze the dependencies to a file using pip freeze > requirements.txt.
    "},{"location":"README-DOCS/#debian","title":"Debian","text":"
    You could install most dependencies using APT:
     
    apt-get install mkdocs \\\n                mkdocs-material \\\n                mkdocs-material-extensions \\\n                mkdocs-redirects \\\n                python3-bs4\n
     
    Warning
     
    Unfortunately Debian doesn't package mkdocs-with-pdf, so you should remove with-pdf plugin from mkdocs.yml.
    "},{"location":"README-DOCS/#building","title":"Building","text":"
    Now you can start a small webserver that builds the site dynamically:
     
    mkdocs serve\n
     
    or build the site into static html files in the site/ directory:
     
    mkdocs build\n
    "},{"location":"README-DOCS/#testing","title":"Testing","text":"
    To verify the internal URLs in the site:
     
    TEST=true mkdocs serve\n
     
    To verify the internal URLs and also the external links:
     
    TEST=true TEST_EXTERNAL=true mkdocs serve\n
    "},{"location":"README-DOCS/#updating-content","title":"Updating content","text":"
    Some pages in this documentation are extracted from a running ejabberd node:
     
       
    • admin/configuration/toplevel.md
      •  
    • admin/configuration/modules.md
      •  
    • developer/ejabberd-api/admin-api.md
      •  
    • developer/ejabberd-api/admin-tags.md
      •  
     
    To update those pages, install ejabberd, start it and run make all in this repository. This gets documentation from ejabberd, processes it to obtain markdown content and moves the files to this repository.
     
    Additionally, there are several other pages that are markdown files copied from ejabberd git repository and docker-ejabberd git repository. Those repositories must be available next to docs.ejabberd.im before running make all.
    "},{"location":"README-DOCS/#markdown-shorthands","title":"Markdown Shorthands","text":"
    When editing ejabberd source code to document top-level options, modules or API commands, there is some additional syntax supported to generate HTML URLs:
     
    For example, this text in the ejabberd source code:
     
    _`mod_muc_admin`_\n_`bookmarks_to_pep`_ API\n_`default_db`_\n_`basic.md#captcha|CAPTCHA`_\nhttps://xmpp.org/extensions/xep-0045.html[XEP-0045]\n
     
    gets converted into this markdown:
     
    [mod_muc_admin](../../admin/configuration/modules.md#mod_muc_admin)\n[bookmarks_to_pep](../../developer/ejabberd-api/admin-api.md#bookmarks_to_pep) API\n[default_db](toplevel.md#default_db)\n[CAPTCHA](basic.md#captcha)\n[XEP-0045](https://xmpp.org/extensions/xep-0045.html)\n
     
    There are example usage of those shorthands in ejabberd, for example in mod_muc.erl.
    "},{"location":"README-ECS/","title":"ecs Container","text":""},{"location":"README-ECS/#ecs-container-image","title":"ecs Container Image","text":"
    ejabberd is an open-source XMPP server, robust, scalable and modular, built using Erlang/OTP, and also includes MQTT Broker and SIP Service.
     
    This container image allows you to run a single node ejabberd instance in a container.
     
    There is an Alternative Image in GitHub Packages, built using a different method and some improvements.
     
    If you are using a Windows operating system, check the tutorials mentioned in ejabberd Docs > Docker Image.
    "},{"location":"README-ECS/#start-ejabberd","title":"Start ejabberd","text":""},{"location":"README-ECS/#with-default-configuration","title":"With default configuration","text":"
    You can start ejabberd in a new container with the following command:
     
    docker run --name ejabberd -d -p 5222:5222 ejabberd/ecs\n
     
    This command will run the container image as a daemon, using ejabberd default configuration file and XMPP domain \"localhost\".
     
    To stop the running container, you can run:
     
    docker stop ejabberd\n
     
    If needed, you can restart the stopped ejabberd container with:
     
    docker restart ejabberd\n
    "},{"location":"README-ECS/#start-with-erlang-console-attached","title":"Start with Erlang console attached","text":"
    If you would like to start ejabberd with an Erlang console attached you can use the live command:
     
    docker run -it -p 5222:5222 ejabberd/ecs live\n
     
    This command will use default configuration file and XMPP domain \"localhost\".
    "},{"location":"README-ECS/#start-with-your-configuration-and-database","title":"Start with your configuration and database","text":"
    This command passes the configuration file using the volume feature and shares the local directory to store database:
     
    mkdir database\ndocker run -d --name ejabberd -v $(pwd)/ejabberd.yml:/home/ejabberd/conf/ejabberd.yml -v $(pwd)/database:/home/ejabberd/database -p 5222:5222 ejabberd/ecs\n
    "},{"location":"README-ECS/#next-steps","title":"Next steps","text":""},{"location":"README-ECS/#register-the-administrator-account","title":"Register the administrator account","text":"
    The default ejabberd configuration has already granted admin privilege to an account that would be called admin@localhost, so you just need to register such an account to start using it for administrative purposes. You can register this account using the ejabberdctl script, for example:
     
    docker exec -it ejabberd bin/ejabberdctl register admin localhost passw0rd\n
    "},{"location":"README-ECS/#check-ejabberd-log-files","title":"Check ejabberd log files","text":"
    Check the ejabberd log file in the container:
     
    docker exec -it ejabberd tail -f logs/ejabberd.log\n
    "},{"location":"README-ECS/#inspect-the-container-files","title":"Inspect the container files","text":"
    The container uses Alpine Linux. You can start a shell there with:
     
    docker exec -it ejabberd sh\n
    "},{"location":"README-ECS/#open-ejabberd-debug-console","title":"Open ejabberd debug console","text":"
    You can open a live debug Erlang console attached to a running container:
     
    docker exec -it ejabberd bin/ejabberdctl debug\n
    "},{"location":"README-ECS/#captcha","title":"CAPTCHA","text":"
    ejabberd includes two example CAPTCHA scripts. If you want to use any of them, first install some additional required libraries:
     
    docker exec --user root ejabberd apk add imagemagick ghostscript-fonts bash\n
     
    Now update your ejabberd configuration file, for example: 
    docker exec -it ejabberd vi conf/ejabberd.yml\n
     
    and add this option: 
    captcha_cmd: /home/ejabberd/lib/ejabberd-21.1.0/priv/bin/captcha.sh\n
     
    Finally, reload the configuration file or restart the container: 
    docker exec ejabberd bin/ejabberdctl reload_config\n
     
    If the CAPTCHA image is not visible, there may be a problem generating it (the ejabberd log file may show some error message); or the image URL may not be correctly detected by ejabberd, in that case you can set the correct URL manually, for example: 
    captcha_url: https://localhost:5443/captcha\n
     
    For more details about CAPTCHA options, please check the CAPTCHA documentation section.
    "},{"location":"README-ECS/#use-ejabberdapi","title":"Use ejabberdapi","text":"
    When the container is running (and thus ejabberd), you can exec commands inside the container using ejabberdctl or any other of the available interfaces, see Understanding ejabberd \"commands\"
     
    Additionally, this container image includes the ejabberdapi executable. Please check the ejabberd-api homepage for configuration and usage details.
     
    For example, if you configure ejabberd like this: 
    listen:\n  -\n    port: 5282\n    module: ejabberd_http\n    request_handlers:\n      \"/api\": mod_http_api\n\nacl:\n  loopback:\n    ip:\n      - 127.0.0.0/8\n      - ::1/128\n      - ::FFFF:127.0.0.1/128\n\napi_permissions:\n  \"admin access\":\n    who:\n      access:\n        allow:\n          acl: loopback\n    what:\n      - \"register\"\n
     
    Then you could register new accounts with this query:
     
    docker exec -it ejabberd bin/ejabberdapi register --endpoint=http://127.0.0.1:5282/ --jid=admin@localhost --password=passw0rd\n
    "},{"location":"README-ECS/#advanced-container-configuration","title":"Advanced container configuration","text":""},{"location":"README-ECS/#ports","title":"Ports","text":"
    This container image exposes the ports:
     
       
    • 5222: The default port for XMPP clients.
      •  
    • 5269: For XMPP federation. Only needed if you want to communicate with users on other servers.
      •  
    • 5280: For admin interface.
      •  
    • 5443: With encryption, used for admin interface, API, CAPTCHA, OAuth, Websockets and XMPP BOSH.
      •  
    • 1883: Used for MQTT
      •  
    • 4369-4399: EPMD and Erlang connectivity, used for ejabberdctl and clustering
      •  
    "},{"location":"README-ECS/#volumes","title":"Volumes","text":"
    ejabberd produces two types of data: log files and database (Mnesia). This is the kind of data you probably want to store on a persistent or local drive (at least the database).
     
    Here are the volume you may want to map:
     
       
    • /home/ejabberd/conf/: Directory containing configuration and certificates
      •  
    • /home/ejabberd/database/: Directory containing Mnesia database. You should back up or export the content of the directory to persistent storage (host storage, local storage, any storage plugin)
      •  
    • /home/ejabberd/logs/: Directory containing log files
      •  
    • /home/ejabberd/upload/: Directory containing uploaded files. This should also be backed up.
      •  
     
    All these files are owned by ejabberd user inside the container. Corresponding UID:GID is 9000:9000. If you prefer bind mounts instead of volumes, then you need to map this to valid UID:GID on your host to get read/write access on mounted directories.
    "},{"location":"README-ECS/#commands-on-start","title":"Commands on start","text":"
    The ejabberdctl script reads the CTL_ON_CREATE environment variable the first time the container is started, and reads CTL_ON_START every time the container is started. Those variables can contain one ejabberdctl command, or several commands separated with the blankspace and ; characters.
     
    By default failure of any of commands executed that way would abort start, this can be disabled by prefixing commands with !
     
    Example usage (or check the full example): 
        environment:\n      - CTL_ON_CREATE=\\! register admin localhost asd\n      - CTL_ON_START=stats registeredusers ;\n                     check_password admin localhost asd ;\n                     status\n
    "},{"location":"README-ECS/#clustering","title":"Clustering","text":"
    When setting several containers to form a cluster of ejabberd nodes, each one must have a different Erlang Node Name and the same Erlang Cookie. For this you can either: - edit conf/ejabberdctl.cfg and set variables ERLANG_NODE and ERLANG_COOKIE - set the environment variables ERLANG_NODE_ARG and ERLANG_COOKIE
     
    Once you have the ejabberd nodes properly set and running, you can tell the secondary nodes to join the master node using the join_cluster API call.
     
    Example using environment variables (see the full docker-compose.yml clustering example): 
    environment:\n  - ERLANG_NODE_ARG=ejabberd@replica\n  - ERLANG_COOKIE=dummycookie123\n  - CTL_ON_CREATE=join_cluster ejabberd@main\n
    "},{"location":"README-ECS/#change-mnesia-node-name","title":"Change Mnesia Node Name","text":"
    To use the same Mnesia database in a container with a different hostname, it is necessary to change the old hostname stored in Mnesia.
     
    This section is equivalent to the ejabberd Documentation Change Computer Hostname, but particularized to containers that use this ecs container image from ejabberd 23.01 or older.
    "},{"location":"README-ECS/#setup-old-container","title":"Setup Old Container","text":"
    Let's assume a container running ejabberd 23.01 (or older) from this ecs container image, with the database directory binded and one registered account. This can be produced with: 
    OLDCONTAINER=ejaold\nNEWCONTAINER=ejanew\n\nmkdir database\nsudo chown 9000:9000 database\ndocker run -d --name $OLDCONTAINER -p 5222:5222 \\\n       -v $(pwd)/database:/home/ejabberd/database \\\n       ejabberd/ecs:23.01\ndocker exec -it $OLDCONTAINER bin/ejabberdctl started\ndocker exec -it $OLDCONTAINER bin/ejabberdctl register user1 localhost somepass\ndocker exec -it $OLDCONTAINER bin/ejabberdctl registered_users localhost\n
     
    Methods to know the Erlang node name: 
    ls database/ | grep ejabberd@\ndocker exec -it $OLDCONTAINER bin/ejabberdctl status\ndocker exec -it $OLDCONTAINER grep \"started in the node\" logs/ejabberd.log\n
    "},{"location":"README-ECS/#change-mnesia-node","title":"Change Mnesia Node","text":"
    First of all let's store the Erlang node names and paths in variables. In this example they would be: 
    OLDCONTAINER=ejaold\nNEWCONTAINER=ejanew\nOLDNODE=ejabberd@95145ddee27c\nNEWNODE=ejabberd@localhost\nOLDFILE=/home/ejabberd/database/old.backup\nNEWFILE=/home/ejabberd/database/new.backup\n
     
       
    1.  
      Start your old container that can still read the Mnesia database correctly. If you have the Mnesia spool files, but don't have access to the old container anymore, go to Create Temporary Container and later come back here.
       
      2.  
    2.  
      Generate a backup file and check it was created: 
      docker exec -it $OLDCONTAINER bin/ejabberdctl backup $OLDFILE\nls -l database/*.backup\n
       
      3.  
    3.  
      Stop ejabberd: 
      docker stop $OLDCONTAINER\n
       
      4.  
    4.  
      Create the new container. For example: 
      docker run \\\n       --name $NEWCONTAINER \\\n       -d \\\n       -p 5222:5222 \\\n       -v $(pwd)/database:/home/ejabberd/database \\\n       ejabberd/ecs:latest\n
       
      5.  
    5.  
      Convert the backup file to new node name: 
      docker exec -it $NEWCONTAINER bin/ejabberdctl mnesia_change_nodename $OLDNODE $NEWNODE $OLDFILE $NEWFILE\n
       
      6.  
    6.  
      Install the backup file as a fallback: 
      docker exec -it $NEWCONTAINER bin/ejabberdctl install_fallback $NEWFILE\n
       
      7.  
    7.  
      Restart the container: 
      docker restart $NEWCONTAINER\n
       
      8.  
    8.  
      Check that the information of the old database is available. In this example, it should show that the account user1 is registered: 
      docker exec -it $NEWCONTAINER bin/ejabberdctl registered_users localhost\n
       
      9.  
    9.  
      When the new container is working perfectly with the converted Mnesia database, you may want to remove the unneeded files: the old container, the old Mnesia spool files, and the backup files.
       
      10.  
    "},{"location":"README-ECS/#create-temporary-container","title":"Create Temporary Container","text":"
    In case the old container that used the Mnesia database is not available anymore, a temporary container can be created just to read the Mnesia database and make a backup of it, as explained in the previous section.
     
    This method uses --hostname command line argument for docker, and ERLANG_NODE_ARG environment variable for ejabberd. Their values must be the hostname of your old container and the Erlang node name of your old ejabberd node. To know the Erlang node name please check Setup Old Container.
     
    Command line example: 
    OLDHOST=${OLDNODE#*@}\ndocker run \\\n       -d \\\n       --name $OLDCONTAINER \\\n       --hostname $OLDHOST \\\n       -p 5222:5222 \\\n       -v $(pwd)/database:/home/ejabberd/database \\\n       -e ERLANG_NODE_ARG=$OLDNODE \\\n       ejabberd/ecs:latest\n
     
    Check the old database content is available: 
    docker exec -it $OLDCONTAINER bin/ejabberdctl registered_users localhost\n
     
    Now that you have ejabberd running with access to the Mnesia database, you can continue with step 2 of previous section Change Mnesia Node.
    "},{"location":"README-ECS/#generating-ejabberd-release","title":"Generating ejabberd release","text":""},{"location":"README-ECS/#configuration","title":"Configuration","text":"
    Image is built by embedding an ejabberd Erlang/OTP standalone release in the image.
     
    The configuration of ejabberd Erlang/OTP release is customized with:
     
       
    • rel/config.exs: Customize ejabberd release
      •  
    • rel/dev.exs: ejabberd environment configuration for development release
      •  
    • rel/prod.exs: ejabberd environment configuration for production release
      •  
    • vars.config: ejabberd compilation configuration options
      •  
    • conf/ejabberd.yml: ejabberd default config file
      •  
     
    Build ejabberd Community Server base image from ejabberd master on Github:
     
    docker build -t ejabberd/ecs .\n
     
    Build ejabberd Community Server base image for a given ejabberd version:
     
    ./build.sh 18.03\n
    "},{"location":"README-ECS/#composer-examples","title":"Composer Examples","text":""},{"location":"README-ECS/#minimal-example","title":"Minimal Example","text":"
    This is the barely minimal file to get a usable ejabberd. Store it as docker-compose.yml:
     
    services:\n  main:\n    image: ejabberd/ecs\n    container_name: ejabberd\n    ports:\n      - \"5222:5222\"\n      - \"5269:5269\"\n      - \"5280:5280\"\n      - \"5443:5443\"\n
     
    Create and start the container with the command: 
    docker-compose up\n
    "},{"location":"README-ECS/#customized-example","title":"Customized Example","text":"
    This example shows the usage of several customizations: it uses a local configuration file, stores the mnesia database in a local path, registers an account when it's created, and checks the number of registered accounts every time it's started.
     
    Download or copy the ejabberd configuration file: 
    wget https://raw.githubusercontent.com/processone/ejabberd/master/ejabberd.yml.example\nmv ejabberd.yml.example ejabberd.yml\n
     
    Create the database directory and allow the container access to it: 
    mkdir database\nsudo chown 9000:9000 database\n
     
    Now write this docker-compose.yml file: 
    version: '3.7'\n\nservices:\n\n  main:\n    image: ejabberd/ecs\n    container_name: ejabberd\n    environment:\n      - CTL_ON_CREATE=register admin localhost asd\n      - CTL_ON_START=registered_users localhost ;\n                     status\n    ports:\n      - \"5222:5222\"\n      - \"5269:5269\"\n      - \"5280:5280\"\n      - \"5443:5443\"\n    volumes:\n      - ./ejabberd.yml:/home/ejabberd/conf/ejabberd.yml:ro\n      - ./database:/home/ejabberd/database\n
    "},{"location":"README-ECS/#clustering-example","title":"Clustering Example","text":"
    In this example, the main container is created first. Once it is fully started and healthy, a second container is created, and once ejabberd is started in it, it joins the first one.
     
    An account is registered in the first node when created (and we ignore errors that can happen when doing that - for example when account already exists), and it should exist in the second node after join.
     
    Notice that in this example the main container does not have access to the exterior; the replica exports the ports and can be accessed.
     
    version: '3.7'\n\nservices:\n\n  main:\n    image: ejabberd/ecs\n    container_name: main\n    environment:\n      - ERLANG_NODE_ARG=ejabberd@main\n      - ERLANG_COOKIE=dummycookie123\n      - CTL_ON_CREATE=\\! register admin localhost asd\n    healthcheck:\n      test: netstat -nl | grep -q 5222\n      start_period: 5s\n      interval: 5s\n      timeout: 5s\n      retries: 120\n\n  replica:\n    image: ejabberd/ecs\n    container_name: replica\n    depends_on:\n      main:\n        condition: service_healthy\n    ports:\n      - \"5222:5222\"\n      - \"5269:5269\"\n      - \"5280:5280\"\n      - \"5443:5443\"\n    environment:\n      - ERLANG_NODE_ARG=ejabberd@replica\n      - ERLANG_COOKIE=dummycookie123\n      - CTL_ON_CREATE=join_cluster ejabberd@main\n      - CTL_ON_START=registered_users localhost ;\n                     status\n
    "},{"location":"README-GIT/","title":"Readme","text":"
    ejabberd is an open-source, robust, scalable and extensible realtime platform built using Erlang/OTP, that includes XMPP Server, MQTT Broker and SIP Service.
     
    Check the features in ejabberd.im, ejabberd Docs, ejabberd at ProcessOne, and the list of supported protocols in ProcessOne and XMPP.org.
    "},{"location":"README-GIT/#installation","title":"Installation","text":"
    There are several ways to install ejabberd:
     
       
    • Source code: compile yourself, see COMPILE
      •  
    • Installers: ProcessOne Download and GitHub Releases for releases, GitHub Actions for master branch (run/deb/rpm for x64 and arm64)
      •  
    • ecs container image: Docker Hub and Github Packages, see ecs README (for x64)
      •  
    • ejabberd container image: Github Packages for releases and master branch, see CONTAINER (for x64 and arm64)
      •  
    • Using your Operating System package
      •  
    • Using the Homebrew package manager
      •  
    "},{"location":"README-GIT/#documentation","title":"Documentation","text":"
    Please check the ejabberd Docs website.
     
    When compiling from source code, you can get some help with:
     
    ./configure --help\nmake help\n
     
    Once ejabberd is installed, try:
     
    ejabberdctl help\nman ejabberd.yml\n
    "},{"location":"README-GIT/#development","title":"Development","text":"
    Bug reports and features are tracked using GitHub Issues, please check CONTRIBUTING for details.
     
    Translations can be improved online using Weblate or in your local machine as explained in Localization.
     
    Documentation for developers is available in ejabberd docs: Developers.
     
    There are nightly builds of ejabberd, both for master branch and for Pull Requests: - Installers: go to GitHub Actions: Installers, open the most recent commit, on the bottom of that commit page, download the ejabberd-packages.zip artifact. - ejabberd container image: go to ejabberd Github Packages
     
    Security reports or concerns should preferably be reported privately, please send an email to the address: contact at process-one dot net or some other method from ProcessOne Contact.
     
    For commercial offering and support, including ejabberd Business Edition and Fluux (ejabberd in the Cloud), please check ProcessOne ejabberd page.
    "},{"location":"README-GIT/#community","title":"Community","text":"
    There are several places to get in touch with other ejabberd developers and administrators:
     
       
    • ejabberd XMPP chatroom: ejabberd@conference.process-one.net
      •  
    • GitHub Discussions
      •  
    • Stack Overflow
      •  
    "},{"location":"README-GIT/#license","title":"License","text":"
    ejabberd is released under the GNU General Public License v2 (see COPYING), and ejabberd translations under MIT License.
    "},{"location":"README-HUB/","title":"ejabberd Community Server Docker Image","text":""},{"location":"README-HUB/#what-is-ejabberd","title":"What is ejabberd","text":"
    ejabberd is an open-source, robust, scalable and extensible realtime platform built using Erlang/OTP, that includes XMPP Server, MQTT Broker and SIP Service.
     
    Check the features in ejabberd.im, ejabberd Docs, ejabberd at ProcessOne, and a list of supported protocols and XEPs.
    "},{"location":"README-HUB/#what-is-ejabberdecs","title":"What is ejabberd/ecs","text":"
    This ejabberd/ecs Docker image is built for stable ejabberd releases using docker-ejabberd/ecs. It's based in Alpine Linux, and is aimed at providing a simple image to setup and configure.
     
    Please report problems related to this ejabberd/ecs image packaging in docker-ejabberd Issues, and general ejabberd problems in ejabberd Issues.
    "},{"location":"README-HUB/#how-to-use-the-ejabberdecs-image","title":"How to use the ejabberd/ecs image","text":"
    Please check ejabberd/ecs README
    "},{"location":"README-HUB/#supported-architectures","title":"Supported Architectures","text":"
    This ejabberd/ecs docker image is built for the linux/amd64 architecture.
    "},{"location":"README-HUB/#alternative-image-in-github","title":"Alternative Image in GitHub","text":"
    There is another container image published in ejabberd GitHub Packages, that you can download from the GitHub Container Registry.
     
    Its usage is similar to this ejabberd/ecs image, with some benefits and changes worth noting:
     
       
    • it's available for linux/amd64 and linux/arm64 architectures
      •  
    • it's built also for master branch, in addition to the stable ejabberd releases
      •  
    • it includes less customizations to the base ejabberd compared to ejabberd/ecs
      •  
    • it stores data in /opt/ejabberd/ instead of /home/ejabberd/
      •  
     
    See its documentation in CONTAINER.
    "},{"location":"admin/","title":"ejabberd for Administrators","text":"
    This area contains information on administering your ejabberd system.
     
    Additionally, you can refer to those extra topics:
     
       
    •  
      Advanced ejabberd Administration provides guidance on how to     handle advanced ejabberd topics.
       
      •  
    •  
      Administration API Reference provides documentation   for commands available in ejabberdctl and ReST API.
       
      •  
    •  
      ejabberdctl Reference provides documentation   for ejabberd server administration command-line tool.
       
      •  
    •  
      Admin FAQ provides tips and information on Frequently   Asked Questions for ejabberd Administrators.
       
      •  
    "},{"location":"admin/introduction/","title":"Features","text":"
    ejabberd is a free and open source instant messaging server written in Erlang/OTP.
     
    ejabberd is cross-platform, distributed, fault-tolerant, and based on open standards to achieve real-time communication.
     
    ejabberd is designed to be a rock-solid and feature rich XMPP server.
     
    ejabberd is suitable for small deployments, whether they need to be scalable or not, as well as extremely large deployments.
     
    Check also the features in ejabberd.im, ejabberd at ProcessOne, and the list of supported protocols in ProcessOne and XMPP.org.
    "},{"location":"admin/introduction/#key-features","title":"Key Features","text":"
    ejabberd is:
     
       
    •  
      Cross-platform: ejabberd runs under Microsoft Windows and Unix-derived systems such as Linux, FreeBSD and NetBSD.
       
      •  
    •  
      Distributed: You can run ejabberd on a cluster of machines all serving the same Jabber domain(s). When you need more capacity you can simply add a new cheap node to your cluster. Accordingly, you do not need to buy an expensive high-end machine to support tens of thousands concurrent users.
       
      •  
    •  
      Fault-tolerant: You can deploy an ejabberd cluster so that all the information required for a properly working service will be replicated permanently on all nodes. This means that if one of the nodes crashes, the others will continue working without disruption. In addition, nodes can be added or replaced on the fly.
       
      •  
    •  
      Administrator Friendly: ejabberd is built on top of the Erlang programming language. As a result, if you wish, you can perform self-contained deployments. You are not required to install an external database, an external web server, amongst others because everything is already included, and ready to run out of the box. Other administrator benefits include:
       
         
      • Comprehensive documentation.
        •  
      • Straightforward installers for Linux, Mac OS X, and Windows.
        •  
      • Web Administration.
        •  
      • Shared Roster Groups.
        •  
      • Command line administration tool.
        •  
      • Can integrate with existing authentication mechanisms.
        •  
      • Capability to send announce messages.
        •  
       
      •  
    •  
      Internationalized: ejabberd leads in internationalization and is well suited to build services available across the world. Related features are:
       
         
      • Translated to 25 languages.
        •  
      • Support for IDNA.
        •  
       
      •  
    •  
      Open Standards: ejabberd is the first Open Source Jabber server staking a claiming to full complyiance to the XMPP standard.
       
         
      • Fully XMPP compliant.
        •  
      • XML-based protocol.
        •  
      • Many protocols supported.
        •  
       
      •  
    "},{"location":"admin/introduction/#additional-features","title":"Additional Features","text":"
    ejabberd also comes with a wide range of other state-of-the-art features:
     
       
    •  
      Modular
       
         
      • Load only the modules you want.
        •  
      • Extend ejabberd with your own custom modules.
        •  
       
      •  
    •  
      Security
       
         
      • SASL and STARTTLS for c2s and s2s connections.
        •  
      • STARTTLS and Dialback s2s connections.
        •  
      • Web Admin accessible via HTTPS secure access.
        •  
       
      •  
    •  
      Databases
       
         
      • Internal database for fast deployment (Mnesia).
        •  
      • Native MySQL support.
        •  
      • Native PostgreSQL support.
        •  
      • ODBC data storage support.
        •  
      • Microsoft SQL Server support.
        •  
      • SQLite support.
        •  
       
      •  
    •  
      Authentication
       
         
      • Internal Authentication.
        •  
      • PAM, LDAP and SQL.
        •  
      • External Authentication script.
        •  
       
      •  
    •  
      Others
       
         
      • Support for virtual hosting.
        •  
      • Compressing XML streams with Stream Compression   (XEP-0138).
        •  
      • Statistics via Statistics Gathering   (XEP-0039).
        •  
      • IPv6 support both for c2s and s2s connections.
        •  
      • Multi-User Chat module with support for clustering and HTML logging.
        •  
      • Users Directory based on users vCards.
        •  
      • Publish-Subscribe component with support for   Personal Eventing via Pubsub.
        •  
      • Support for web clients: Support for XMPP subprotocol for WebSocket and HTTP Binding (BOSH) services.
        •  
      • IRC transport.
        •  
      • SIP support.
        •  
      • Component support: interface with networks such as AIM, ICQ and MSN installing special transports.
        •  
       
      •  
    "},{"location":"admin/configuration/","title":"Configuring ejabberd","text":"
    Here are the main entry points to learn more about ejabberd configuration. ejabberd is extremely powerful and can be configured in many ways with many options.
     
    Do not let this complexity scare you. Most of you will be fine with default config file (or light changes).
     
    Tutorials for first-time users:
     
       
    • How to move to ejabberd XMPP server
      •  
    • How to set up ejabberd video & voice calling (STUN/TURN)
      •  
    • How to configure ejabberd to get 100% in XMPP compliance test
      •  
     
    Detailed documentation in sections:
     
       
    • File Format
      •  
    • Basic Configuration: hosts, acl, logging...
      •  
    • Authentication: auth_method
      •  
    • Databases
      •  
    • LDAP
      •  
    • Listen Modules: c2s, s2s, http, sip, stun...
      •  
    • Listen Options
      •  
    • Top-Level Options
      •  
    • Modules Options
      •  
     
    There's also a copy of the old configuration document which was used up to ejabberd 20.03.
    "},{"location":"admin/configuration/authentication/","title":"Authentication","text":""},{"location":"admin/configuration/authentication/#supported-methods","title":"Supported Methods","text":"
    The authentication methods supported by ejabberd are:
     
       
    •  
      internal \u2014 See section\u00a0Internal.
       
      •  
    •  
      external \u2014 See section\u00a0External Script.
       
      •  
    •  
      ldap \u2014 See section\u00a0 LDAP.
       
      •  
    •  
      sql \u2014 See section Relational Databases.
       
      •  
    •  
      anonymous \u2014 See section\u00a0Anonymous Login and SASL Anonymous.
       
      •  
    •  
      pam \u2014 See section\u00a0Pam Authentication.
       
      •  
    •  
      jwt \u2014 See section\u00a0JWT Authentication.
       
      •  
     
    The top-level option auth_method defines the authentication methods that are used for user authentication. The option syntax is:
     
    auth_method: [Method1, Method2, ...]\n
     
    When the auth_method option is omitted, ejabberd relies on the default database which is configured in default_db option. If this option is not set neither, then the default authentication method will be internal.
     
    Account creation is only supported by internal, external and sql auth methods.
    "},{"location":"admin/configuration/authentication/#general-options","title":"General Options","text":"
    The top-level option auth_password_format allows to store the passwords in SCRAM format, see the SCRAM section.
     
    Other top-level options that are relevant to the authentication configuration: disable_sasl_mechanisms, fqdn.
     
    Authentication caching is enabled by default, and can be disabled in a specific vhost with the option auth_use_cache. The global authentication cache can be configured for all the authentication methods with the global top-level options: auth_cache_missed, auth_cache_size, auth_cache_life_time. For example:
     
    auth_cache_size: 1500\nauth_cache_life_time: 10 minutes\n\nhost_config:\n  example.org:\n    auth_method: [internal]\n  example.net:\n    auth_method: [ldap]\n    auth_use_cache: false\n
    "},{"location":"admin/configuration/authentication/#internal","title":"Internal","text":"
    ejabberd uses its internal Mnesia database as the default authentication method. The value internal will enable the internal authentication method.
     
    To store the passwords in SCRAM format instead of plaintext, see the SCRAM section.
     
    Examples:
     
       
    •  
      To use internal authentication on example.org and LDAP  authentication on example.net:
       
      host_config:\n  example.org:\n    auth_method: [internal]\n  example.net:\n    auth_method: [ldap]\n
       
      •  
    •  
      To use internal authentication with hashed passwords on all virtual  hosts:
       
      auth_method: internal\nauth_password_format: scram\n
       
      •  
    "},{"location":"admin/configuration/authentication/#external-script","title":"External Script","text":"
    In the external authentication method, ejabberd uses a custom script to perform authentication tasks. The server administrator can write that external authentication script in any programming language.
     
    Please check some example scripts, and the details on the interface between ejabberd and the script in the Developers > Internals > External Authentication section.
     
    Options:
     
       
    • extauth_pool_name
      •  
    • extauth_pool_size
      •  
    • extauth_program
      •  
     
    Please note that caching interferes with the ability to maintain multiple passwords per account. So if your authentication mechanism supports application-specific passwords, caching must be disabled in the host that uses this authentication method with the option auth_use_cache.
     
    This example sets external authentication, specifies the extauth script, disables caching, and starts three instances of the script for each virtual host defined in ejabberd:
     
    auth_method: [external]\nextauth_program: /etc/ejabberd/JabberAuth.class.php\nextauth_pool_size: 3\nauth_use_cache: false\n
    "},{"location":"admin/configuration/authentication/#anonymous-login-and-sasl-anonymous","title":"Anonymous Login and SASL Anonymous","text":"
    The anonymous authentication method enables two modes for anonymous authentication:
     
    Anonymous login:   This is a standard login, that use the classical login and password  mechanisms, but where password is accepted or preconfigured for all  anonymous users. This login is compliant with SASL authentication,  password and digest non-SASL authentication, so this option will  work with almost all XMPP clients
     
    SASL Anonymous:   This is a special SASL authentication mechanism that allows to login  without providing username or password (see  XEP-0175). The main  advantage of SASL Anonymous is that the protocol was designed to  give the user a login. This is useful to avoid in some case, where  the server has many users already logged or registered and when it  is hard to find a free username. The main disavantage is that you  need a client that specifically supports the SASL Anonymous  protocol.
     
    The anonymous authentication method can be configured with the following options. Remember that you can use the host_config option to set virtual host specific options (see section\u00a0Virtual Hosting):
     
       
    • allow_multiple_connections
      •  
    • anonymous_protocol
      •  
     
    Examples:
     
       
    •  
      To enable anonymous login on all virtual hosts:
       
      auth_method: [anonymous]\nanonymous_protocol: login_anon\n
       
      •  
    •  
      Similar as previous example, but limited to public.example.org:
       
      host_config:\n  public.example.org:\n    auth_method: [anonymous]\n    anonymous_protoco: login_anon\n
       
      •  
    •  
      To enable anonymous login and internal authentication on a virtual  host:
       
      host_config:\n  public.example.org:\n    auth_method:\n      - internal\n      - anonymous\n    anonymous_protocol: login_anon\n
       
      •  
    •  
      To enable SASL Anonymous on a virtual host:
       
      host_config:\n  public.example.org:\n    auth_method: [anonymous]\n    anonymous_protocol: sasl_anon\n
       
      •  
    •  
      To enable SASL Anonymous and anonymous login on a virtual host:
       
      host_config:\n  public.example.org:\n    auth_method: [anonymous]\n    anonymous_protocol: both\n
       
      •  
    •  
      To enable SASL Anonymous, anonymous login, and internal  authentication on a virtual host:
       
      host_config:\n  public.example.org:\n    auth_method:\n      - internal\n      - anonymous\n    anonymous_protocol: both\n
       
      •  
     
    There are more configuration examples and XMPP client example stanzas in Anonymous users support.
    "},{"location":"admin/configuration/authentication/#pam-authentication","title":"PAM Authentication","text":"
    ejabberd supports authentication via Pluggable Authentication Modules (PAM). PAM is currently supported in AIX, FreeBSD, HP-UX, Linux, Mac OS X, NetBSD and Solaris. PAM authentication is disabled by default, so you have to configure and compile ejabberd with PAM support enabled:
     
    ./configure --enable-pam && make install\n
     
    Options:
     
       
    • pam_service
      •  
    • pam_userinfotype
      •  
     
    Example:
     
    auth_method: [pam]\npam_service: ejabberd\n
     
    Though it is quite easy to set up PAM support in ejabberd, PAM itself introduces some security issues:
     
       
    •  
      To perform PAM authentication ejabberd uses external C-program  called epam. By default, it is located in  /var/lib/ejabberd/priv/bin/ directory. You have to set it root on  execution in the case when your PAM module requires root privileges  (pam_unix.so for example). Also you have to grant access for  ejabberd to this file and remove all other permissions from it.  Execute with root privileges:
       
      chown root:ejabberd /var/lib/ejabberd/priv/bin/epam\nchmod 4750 /var/lib/ejabberd/priv/bin/epam\n
       
      •  
    •  
      Make sure you have the latest version of PAM installed on your  system. Some old versions of PAM modules cause memory leaks. If you  are not able to use the latest version, you can kill(1) epam  process periodically to reduce its memory consumption: ejabberd  will restart this process immediately.
       
      •  
    •  
      epam program tries to turn off delays on authentication failures.  However, some PAM modules ignore this behavior and rely on their own  configuration options. You can create a configuration file  ejabberd.pam. This example shows how to turn off delays in  pam_unix.so module:
       
      #%PAM-1.0\nauth        sufficient  pam_unix.so likeauth nullok nodelay\naccount     sufficient  pam_unix.so\n
       
      •  
     
    That is not a ready to use configuration file: you must use it as a  hint when building your own PAM configuration instead. Note that if  you want to disable delays on authentication failures in the PAM  configuration file, you have to restrict access to this file, so a  malicious user can\u2019t use your configuration to perform brute-force  attacks.
     
       
    •  
      You may want to allow login access only for certain users.  pam_listfile.so module provides such functionality.
       
      •  
    •  
      If you use pam_winbind to authorise against a Windows Active  Directory, then /etc/nsswitch.conf must be configured to use  winbind as well.
       
      •  
    "},{"location":"admin/configuration/authentication/#jwt-authentication","title":"JWT Authentication","text":"
    ejabberd supports authentication using JSON Web Token (JWT).  When enabled, clients send signed tokens instead of passwords, which are checked using a private key specified in the jwt_key option. JWT payload must look like this:
     
    {\n  \"jid\": \"test@example.org\",\n  \"exp\": 1564436511\n}\n
     
    Options:
     
       
    • jwt_key
      •  
    • jwt_auth_only_rule
      •  
    • jwt_jid_field
      •  
     
    Example:
     
    auth_method: jwt\njwt_key: /path/to/jwt/key\n
     
    In this example, admins can use both JWT and plain passwords, while the rest of users can use only JWT.
     
    # the order is important here, don't use [sql, jwt]\nauth_method: [jwt, sql]\n\naccess_rules:\n  jwt_only:\n    deny: admin\n    allow: all\n\njwt_auth_only_rule: jwt_only\n
     
    Please notice that, when using JWT authentication, mod_offline will not work. With JWT authentication the accounts do not exist in the database, and there is no way to know if a given account exists or not.
     
    For more information about JWT authentication, you can check a brief tutorial in the ejabberd 19.08 release notes.
    "},{"location":"admin/configuration/authentication/#scram","title":"SCRAM","text":"
    The top-level option auth_password_format defines in what format the users passwords are stored: SCRAM format or plaintext format.
     
    The top-level option auth_scram_hash defines the hash algorithm that will be used to scram the password.
     
    ejabberd supports channel binding to the external channel, allowing the clients to use -PLUS authentication mechanisms.
     
    In summary, depending on the configured options, ejabberd supports:
     
       
    • SCRAM_SHA-1(-PLUS)
      •  
    • SCRAM_SHA-256(-PLUS)
      •  
    • SCRAM_SHA-512(-PLUS)
      •  
     
    For details about the client-server communication when using SCRAM, refer to SASL Authentication and SCRAM.
    "},{"location":"admin/configuration/authentication/#internal-storage","title":"Internal storage","text":"
    When ejabberd starts with internal auth method and SCRAM password format configured:
     
    auth_method: internal\nauth_password_format: scram\n
     
    and detects that there are plaintext passwords stored, they are automatically converted to SCRAM format:
     
    [info] Passwords in Mnesia table 'passwd' will be SCRAM'ed\n[info] Transforming table 'passwd', this may take a while\n
    "},{"location":"admin/configuration/authentication/#sql-database","title":"SQL Database","text":"
    Please note that if you use SQL auth method and SCRAM password format, the plaintext passwords already stored in the database are not automatically converted to SCRAM format.
     
    To convert plaintext passwords to SCRAM format in your database, use the convert_to_scram command:
     
    ejabberdctl convert_to_scram example.org\n
    "},{"location":"admin/configuration/authentication/#foreign-authentication","title":"Foreign authentication","text":"
    Note on SCRAM using and foreign authentication limitations: when using the SCRAM password format, it is not possible to use foreign authentication method in ejabberd, as the real password is not known.
     
    Foreign authentication are use to authenticate through various bridges ejabberd provide. Foreign authentication includes at the moment SIP and TURN auth support and they will not be working with SCRAM.
    "},{"location":"admin/configuration/basic/","title":"Basic Configuration","text":""},{"location":"admin/configuration/basic/#xmpp-domains","title":"XMPP Domains","text":""},{"location":"admin/configuration/basic/#host-names","title":"Host Names","text":"
    ejabberd supports managing several independent XMPP domains on a single ejabberd instance, using a feature called virtual hosting.
     
    The option hosts  defines a list containing one or more domains that ejabberd will serve.
     
    Of course, the hosts list can contain just one domain if you do not want to host multiple XMPP domains on the same instance.
     
    Examples:
     
       
    •  
      Serving one domain:
       
      hosts: [example.org]\n
       
      •  
    •  
      Serving three domains:
       
      hosts:\n  - example.net\n  - example.com\n  - jabber.somesite.org\n
       
      •  
    "},{"location":"admin/configuration/basic/#virtual-hosting","title":"Virtual Hosting","text":"
    When managing several XMPP domains in a single instance, those domains are truly independent. It means they can even have different configuration parameters.
     
    Options can be defined separately for every virtual host using the host_config option.
     
    Examples:
     
       
    •  
      Domain example.net is using the internal authentication method  while domain example.com is using the LDAP server running on the  domain localhost to perform authentication:
       
      host_config:\n  example.net:\n    auth_method: internal\n  example.com:\n    auth_method: ldap\n    ldap_servers:\n      - localhost\n    ldap_uids:\n      - uid\n    ldap_rootdn: \"dc=localdomain\"\n    ldap_password: \"\"\n
       
      •  
    •  
      Domain example.net is using SQL to perform authentication while  domain example.com is using the LDAP servers running on the  domains localhost and otherhost:
       
      host_config:\n  example.net:\n    auth_method: sql\n    sql_type: odbc\n    sql_server: \"DSN=ejabberd;UID=ejabberd;PWD=ejabberd\"\n  example.com:\n    auth_method: ldap\n    ldap_servers:\n      - localhost\n      - otherhost\n    ldap_uids:\n      - uid\n    ldap_rootdn: \"dc=example,dc=com\"\n    ldap_password: \"\"\n
       
      •  
     
    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, instead of defining each option in host_config use append_host_config with the same syntax.
     
    In this example three virtual hosts have some similar modules, but there are also other different modules for some specific virtual hosts:
     
    ## This ejabberd server has three vhosts:\nhosts:\n  - one.example.org\n  - two.example.org\n  - three.example.org\n\n## Configuration of modules that are common to all vhosts\nmodules:\n  mod_roster:    {}\n  mod_configure: {}\n  mod_disco:     {}\n  mod_private:   {}\n  mod_time:      {}\n  mod_last:      {}\n  mod_version:   {}\n\nappend_host_config:\n  ## Add some modules to vhost one:\n  one.example.org:\n    modules:\n      mod_muc:\n        host: conference.one.example.org\n      mod_ping: {}\n  ## Add a module just to vhost two:\n  two.example.org:\n    modules:\n      mod_muc:\n        host: conference.two.example.org\n
    "},{"location":"admin/configuration/basic/#logging","title":"Logging","text":"
    ejabberd configuration can help a lot by having the right amount of logging set up.
     
    There are several toplevel options to configure logging:
     
       
    • loglevel: Verbosity of log files generated by ejabberd.
      •  
    • hide_sensitive_log_data:     Privacy option to disable logging of IP address or sensitive data.
      •  
    • log_modules_fully:     Modules that will log everything independently from the general loglevel option.
      •  
    • log_rotate_size
      •  
    • log_rotate_count:     Setting count to N keeps N rotated logs. Setting count to 0     does not disable rotation, it instead rotates the file and keeps no previous     versions around. Setting size to X rotate log when it reaches X bytes.
      •  
    • log_burst_limit_count
      •  
    • log_burst_limit_window_time
      •  
     
    The values in default configuration file are:
     
    log_rotate_size: 10485760\nlog_rotate_count: 1\n
     
    For example, log warning and higher messages, but all c2s messages, and hide sensitive data:
     
    loglevel: warning\nhide_sensitive_log_data: true\nlog_modules_fully: [ejabberd_c2s]\n
    "},{"location":"admin/configuration/basic/#default-language","title":"Default Language","text":"
    The language option defines the default language of server strings that can be seen by XMPP clients. If a XMPP client does not support xml:lang, ejabberd uses the language specified in this option.
     
    The option syntax is:
     
    language: Language: The default value is en. In order to take effect there must be a translation file Language.msg in ejabberd\u2019s msgs directory.
     
    For example, to set Russian as default language:
     
    language: ru\n
     
    The page Internationalization and Localization provides more details.
    "},{"location":"admin/configuration/basic/#captcha","title":"CAPTCHA","text":"
    Some ejabberd modules can be configured to require a CAPTCHA challenge on certain actions, for instance mod_block_strangers, mod_muc, mod_register, and mod_register_web. If the client does not support CAPTCHA Forms (XEP-0158), a web link is provided so the user can fill the challenge in a web browser.
     
    Example scripts are provided that generate the image using ImageMagick\u2019s Convert program and Ghostscript fonts. Remember to install those dependencies: in Debian install the imagemagick and gsfonts packages; in container images check their documentation for details.
     
    The relevant top-level options are:
     
       
    •  
      captcha_cmd: Path | Module:   Full path to a script that generates the image,   or name of a module that supports generating CAPTCHA images   (mod_ecaptcha,   mod_captcha_rust).   The default value disables the feature: undefined
       
      •  
    •  
      captcha_url: URL | auto:   An URL where CAPTCHA requests should be sent,   or auto to determine the URL automatically.   The default value is auto.
       
      •  
     
    And finally, configure request_handlers for the ejabberd_http listener with a path handled by ejabberd_captcha, where the CAPTCHA images will be served.
     
    Example configuration:
     
    hosts: [example.org]\n\ncaptcha_cmd: /lib/ejabberd/priv/bin/captcha.sh\n# captcha_cmd: /opt/ejabberd-23.01/lib/captcha.sh\n# captcha_cmd: mod_ecaptcha\n\ncaptcha_url: auto\n## captcha_url: http://example.org:5280/captcha\n## captcha_url: https://example.org:443/captcha\n## captcha_url: http://example.com/captcha\n\nlisten:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /captcha: ejabberd_captcha\n
    "},{"location":"admin/configuration/basic/#acme","title":"ACME","text":"
    ACME is used 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.
    "},{"location":"admin/configuration/basic/#setting-up-acme","title":"Setting up ACME","text":"
    In ejabberd, ACME is configured using the acme top-level option, check there the available options and example configuration.
     
    The automated mode is enabled by default. However, some configuration of ejabberd is still required, because ACME requires HTTP challenges: an ACME remote server will connect to your ejabberd server on HTTP port 80 during certificate issuance.
     
    For that reason you must have an ejabberd_http listener with TLS disabled handling an \"ACME well known\" path. For example:
     
    listen:\n  -\n    module: ejabberd_http\n    port: 5280\n    tls: false\n    request_handlers:\n      /.well-known/acme-challenge: ejabberd_acme\n
     
    Note that the ACME protocol requires challenges to be sent on port 80. Since this is a privileged port, ejabberd cannot listen on it directly without root privileges. Thus you need some mechanism to forward port 80 to the port defined by the listener (port 5280 in the example above). There are several ways to do this: using NAT, setcap (Linux only), or HTTP front-ends (e.g. sslh, nginx, haproxy and so on). Pick one that fits your installation the best, but DON'T run ejabberd as root.
     
    If you see errors in the logs with ACME server problem reports, it's highly recommended to change ca_url option in the acme top-level option to the URL pointing to some staging ACME environment, fix the problems until you obtain a certificate, and then change the URL back and retry using request-certificate ejabberdctl command (see below). This is needed because ACME servers typically have rate limits, preventing you from requesting certificates too rapidly and you can get stuck for several hours or even days. By default, ejabberd uses Let's Encrypt authority. Thus, the default value of ca_url option is https://acme-v02.api.letsencrypt.org/directory and the staging URL will be https://acme-staging-v02.api.letsencrypt.org/directory:
     
    acme:\n  ## Staging environment\n  ca_url: https://acme-staging-v02.api.letsencrypt.org/directory\n  ## Production environment (the default):\n  # ca_url: https://acme-v02.api.letsencrypt.org/directory\n
     
    The automated mode can be disabled by setting auto option to false in the acme top-level option:
     
    acme:\n  auto: false\n
     
    In this case automated renewals are still enabled, however, in order to request a new certificate, you need to run request_certificate  API command:
     
    ejabberdctl request-certificate all\n
     
    If you only want to request certificates for a subset of the domains, run:
     
    ejabberdctl request-certificate domain.tld,pubsub.domain.tld,server.com,conference.server.com,...\n
     
    You can view the certificates obtained using ACME and list_certificates:
     
    $ ejabberdctl list-certificates\ndomain.tld /path/to/cert/file1 true\nserver.com /path/to/cert/file2 false\n
     
    The output is mostly self-explained: every line contains the domain, the corresponding certificate file, and whether this certificate file is used or not. A certificate might not be used for several reasons: mostly because ejabberd detects a better certificate (i.e. not expired, or having a longer lifetime). It's recommended to revoke unused certificates if they are not yet expired (see below).
     
    At any point you can revoke a certificate using revoke_certificate: pick the certificate file from the listing above and run:
     
    ejabberdctl revoke-certificate /path/to/cert/file\n
     
    If the commands return errors, consult the log files for details.
    "},{"location":"admin/configuration/basic/#acme-implementation-details","title":"ACME implementation details","text":"
    In nutshell, certification requests are performed in two phases. Firstly, ejabberd creates an account at the ACME server. That is an EC private key. Secondly, a certificate is requested. In the case of a revocation, no account is used - only a certificate in question is needed. All information is stored under acme directory inside spool directory of ejabberd (typically /var/lib/ejabberd). An example content of the directory is the following:
     
    $ tree /var/lib/ejabberd\n/var/lib/ejabberd\n\u251c\u2500\u2500 acme\n\u2502   \u251c\u2500\u2500 account.key\n\u2502   \u2514\u2500\u2500 live\n\u2502       \u251c\u2500\u2500 251ce180d964e98a2f18b65504df2ab7c55943e2\n\u2502       \u2514\u2500\u2500 93816a8429ebbaa75574eb3f59d4a806b67d6917\n...\n
     
    Here, account.key is the EC private key used to identify the ACME account. You can inspect its content using openssl command:
     
    openssl ec -text -noout -in /var/lib/ejabberd/acme/account.key\n
     
    Obtained certificates are stored under acme/live directory. You can inspect any of the certificates using openssl command as well:
     
    openssl x509 -text -noout -in /var/lib/ejabberd/acme/live/251ce180d964e98a2f18b65504df2ab7c55943e2\n
     
    In the case of errors, you can delete the whole acme directory - ejabberd will recreate its content on next certification request. However, don't delete it too frequently - usually there is a rate limit on the number of accounts and certificates an ACME server creates. In particular, for Let's Encrypt the limits are described here.
    "},{"location":"admin/configuration/basic/#access-rights","title":"Access Rights","text":"
    This section describes new ACL syntax introduced in ejabberd 16.06. For old access rule and ACL syntax documentation, please refer to configuration document archive
    "},{"location":"admin/configuration/basic/#acl","title":"ACL","text":"
    Access control in ejabberd is performed via Access Control Lists (ACLs), using the acl option. The declarations of ACLs in the configuration file have the following syntax:
     
    acl:\n  ACLName:\n    ACLType: ACLValue\n
     
    ACLType: ACLValue can be one of the following:
     
       
    •  
      all:   Matches all JIDs. Example:
       
      acl:\n  world: all\n
       
      •  
    •  
      user: Username:   Matches the user with the name Username on any of the local virtual host.  Example:
       
      acl:\n  admin:\n    user: yozhik\n
       
      •  
    •  
      user: {Username: Server} | Jid:   Matches the user with the JID Username@Server and any resource.  Example:
       
      acl:\n  admin:\n    - user:\n        yozhik@example.org\n    - user: peter@example.org\n
       
      •  
    •  
      server: Server:   Matches any JID from server Server. Example:
       
      acl:\n  exampleorg:\n    server: example.org\n
       
      •  
    •  
      resource: Resource:   Matches any JID with a resource Resource. Example:
       
      acl:\n  mucklres:\n    resource: muckl\n
       
      •  
    •  
      shared_group: Groupname:   Matches any member of a Shared Roster Group with name Groupname in  the virtual host. Example:
       
      acl:\n  techgroupmembers:\n    shared_group: techteam\n
       
      •  
    •  
      shared_group: {Groupname: Server}:   Matches any member of a Shared Roster Group with name Groupname in  the virtual host Server. Example:
       
      acl:\n  techgroupmembers:\n    shared_group:\n      techteam: example.org\n
       
      •  
    •  
      ip: Network:   Matches any IP address from the Network. Example:
       
      acl:\n  loopback:\n    ip:\n      - 127.0.0.0/8\n      - \"::1\"\n
       
      •  
    •  
      user_regexp: Regexp:   Matches any local user with a name that matches Regexp on local  virtual hosts. Example:
       
      acl:\n  tests:\n    user_regexp: \"^test[0-9]*$\"\n
       
      •  
    •  
      user_regexp: {Regexp: Server} | JidRegexp:   Matches any user with a name that matches Regexp at server  Server. Example:
       
      acl:\n  tests:\n    user_regexp:\n      - \"^test1\": example.org\n      - \"^test2@example.org\"\n
       
      •  
    •  
      server_regexp: Regexp:   Matches any JID from the server that matches Regexp. Example:
       
      acl:\n  icq:\n    server_regexp: \"^icq\\\\.\"\n
       
      •  
    •  
      resource_regexp: Regexp:   Matches any JID with a resource that matches Regexp. Example:
       
      acl:\n  icq:\n    resource_regexp: \"^laptop\\\\.\"\n
       
      •  
    •  
      node_regexp: {UserRegexp: ServerRegexp}:   Matches any user with a name that matches UserRegexp at any server  that matches ServerRegexp. Example:
       
      acl:\n  yozhik:\n    node_regexp:\n      \"^yozhik$\": \"^example.(com|org)$\"\n
       
      •  
     
       
    •  
      user_glob: Glob:
       
      •  
    •  
      user_glob: {Glob: Server}:
       
      •  
    •  
      server_glob: Glob:
       
      •  
    •  
      resource_glob: Glob:
       
      •  
    •  
      node_glob: {UserGlob: ServerGlob}:   This is the same as above. However, it uses shell glob patterns instead of regexp. These patterns can have the following special characters:
       
         
      •  
        *:   matches any string including the null string.
         
        •  
      •  
        ?:   matches any single character.
         
        •  
      •  
        [...]:   matches any of the enclosed characters. Character ranges are  specified by a pair of characters separated by a -. If the  first character after [ is a !, any character not enclosed  is matched.
         
        •  
       
      •  
     
    The following ACLName are pre-defined:
     
       
    •  
      all:   Matches any JID.
       
      •  
    •  
      none:   Matches no JID.
       
      •  
    "},{"location":"admin/configuration/basic/#access-rules","title":"Access Rules","text":"
    The access_rules option is used to allow or deny access to different services. The syntax is:
     
    access_rules:\n  AccessName:\n    - allow|deny: ACLRule|ACLDefinition\n
     
    Each definition may contain arbitrary number of - allow or - deny sections, and each section can contain any number of acl rules (as defined in previous section, it recognizes one additional rule acl: RuleName that matches when acl rule named RuleName matches). If no rule or definition is defined, the rule all is applied.
     
    Definition's - allow and - deny sections are processed in top to bottom order, and first one for which all listed acl rules matches is returned as result of access rule. If no rule matches deny is returned.
     
    To simplify configuration two shortcut version are available: - allow: acl and - allow, example below shows equivalent definitions where short or long version are used:
     
    access_rules:\n  a_short: admin\n  a_long:\n    - acl: admin\n  b_short:\n    - deny: banned\n    - allow\n  b_long:\n    - deny:\n      - acl: banned\n    - allow:\n      - all\n
     
    If you define specific Access rights in a virtual host, remember that the globally defined Access rights have precedence over those. This means that, in case of conflict, the Access granted or denied in the global server is used and the Access of a virtual host doesn't have effect.
     
    Example:
     
    access_rules:\n  configure:\n    - allow: admin\n  something:\n    - deny: someone\n    - allow\n  s2s_banned:\n    - deny: problematic_hosts\n    - deny:\n      - acl: banned_forever\n    - deny:\n      - ip: 222.111.222.111/32\n    - deny:\n      - ip: 111.222.111.222/32\n    - allow\n  xmlrpc_access:\n    - allow:\n      - user: peter@example.com\n    - allow:\n      - user: ivone@example.com\n    - allow:\n      - user: bot@example.com\n      - ip: 10.0.0.0/24\n
     
    The following AccessName are pre-defined:
     
       
    •  
      all:   Always returns the value \u2018allow\u2019.
       
      •  
    •  
      none:   Always returns the value \u2018deny\u2019.
       
      •  
    "},{"location":"admin/configuration/basic/#shaper-rules","title":"Shaper Rules","text":"
    The shaper_rules top-level option declares shapers to use for matching user/hosts. The syntax is:
     
    shaper_rules:\n  ShaperRuleName:\n    - Number|ShaperName: ACLRule|ACLDefinition\n
     
    Semantic is similar to that described in Access Rights section, only difference is that instead using - allow or - deny, name of shaper or number should be used.
     
    Examples:
     
    shaper_rules:\n  connections_limit:\n    - 10:\n      - user: peter@example.com\n    - 100: admin\n    - 5\n  download_speed:\n    - fast: admin\n    - slow: anonymous_users\n    - normal\n  log_days: 30\n
    "},{"location":"admin/configuration/basic/#limiting-opened-sessions","title":"Limiting Opened Sessions","text":"
    The special access max_user_sessions specifies the maximum number of sessions (authenticated connections) per user. If a user tries to open more sessions by using different resources, the first opened session will be disconnected. The error session replaced will be sent to the disconnected session. The value for this option can be either a number, or infinity. The default value is infinity.
     
    The syntax is:
     
    shaper_rules:\n  max_user_sessions:\n    - Number: ACLRule|ACLDefinition\n
     
    This example limits the number of sessions per user to 5 for all users, and to 10 for admins:
     
    shaper_rules:\n  max_user_sessions:\n    - 10: admin\n    - 5\n
    "},{"location":"admin/configuration/basic/#connections-to-remote-server","title":"Connections to Remote Server","text":"
    The special access max_s2s_connections specifies how many simultaneous S2S connections can be established to a specific remote XMPP server. The default value is 1. There\u2019s also available the access max_s2s_connections_per_node.
     
    The syntax is:
     
    shaper_rules:\n  max_s2s_connections: MaxNumber\n
     
    For example, let's allow up to 3 connections with each remote server:
     
    shaper_rules:\n  max_s2s_connections: 3\n
    "},{"location":"admin/configuration/basic/#shapers","title":"Shapers","text":"
    The shaper top-level option defines limitations in the connection traffic. The basic syntax is:
     
    shaper:\n  ShaperName: Rate\n
     
    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.
     
    This example defines a shaper with name normal that limits traffic speed to 1,000bytes/second, and another shaper with name fast that limits traffic speed to 50,000bytes/second:
     
    shaper:\n  normal: 1000\n  fast: 50000\n
     
    You can use the full syntax to set the BurstSize too:
     
    shaper:\n  ShaperName:\n    rate: Rate\n    burst_size: BurstSize\n
     
    With BurstSize you can allow client to send more data, but its amount can be clamped reasonably. Each connection is allowed to send BurstSize of data before processing is delayed, and that amount is replenished by Rate each second, but never more than what BurstSize allows. This allows the client to send quite a bit of data at once, but still have limited amount of data to send on constant basis.
     
    In this example, the normal shaper has Rate set to 1000 and the BurstSize takes that same value. The not_normal shaper has the same Rate that before, and sets a higher BurstSize:
     
    shaper:\n  normal: 1000\n  not_normal:\n    rate: 1000\n    burst_size: 20000\n
    "},{"location":"admin/configuration/database/","title":"Database Configuration","text":""},{"location":"admin/configuration/database/#supported-storages","title":"Supported storages","text":"
    ejabberd uses its internal Mnesia database by default. However, it is possible to use a relational database, key-value storage or an LDAP server to store persistent, long-living data. ejabberd is very flexible: you can configure different authentication methods for different virtual hosts, you can configure different authentication mechanisms for the same virtual host (fallback), you can set different storage systems for modules, and so forth.
     
    The following databases are supported by ejabberd:
     
       
    •  
      Mnesia
       
      •  
    •  
      MySQL. Check the tutorial Using ejabberd with MySQL
       
      •  
    •  
      Any ODBC compatible database
       
      •  
    •  
      PostgreSQL
       
      •  
    •  
      MS SQL Server/SQL Azure
       
      •  
    •  
      SQLite
       
      •  
    •  
      Redis(only for transient data)
       
      •  
     
    Please check LDAP Configuration section for documentation about using LDAP.
    "},{"location":"admin/configuration/database/#database-schema","title":"Database Schema","text":"
    When using external database backend, ejabberd does not create schema and tables by itself. If you plan to use MySQL, PostgreSQL, MS SQL or SQLite, you must create the schema before you run ejabberd.
     
       
    •  
      If installing ejabberd from sources, you will find sql script for your backend   in the installation directory. By default: /usr/local/lib/ejabberd/priv/sql
       
      •  
    •  
      If installing ejabberd from Process-One installer, the init scripts are located   in the ejabberd's installation path under <base>/lib/ejabberd*/priv/sql
       
      •  
     
    If using MySQL or PostgreSQL, you can choose between the default or the new schemas.
     
    See ejabberd SQL Database Schema for details on database schemas.
    "},{"location":"admin/configuration/database/#virtual-hosting","title":"Virtual Hosting","text":"
    Important note about virtual hosting: if you define several domains in ejabberd.yml (see section Host Names), you probably want that each virtual host uses a different configuration of database, authentication and storage, so that usernames do not conflict and mix between different virtual hosts. For that purpose, the options described in the next sections must be set inside a host_config for each vhost (see section Virtual Hosting). For example:
     
    host_config:\n  public.example.org:\n    sql_type: pgsql\n    sql_server: localhost\n    sql_database: database-public-example-org\n    sql_username: ejabberd\n    sql_password: password\n    auth_method: [sql]\n
    "},{"location":"admin/configuration/database/#default-database","title":"Default database","text":"
    You can simplify the configuration by setting the default database. This can be done with the default_db top-level option:
     
    default_db: mnesia|sql:  This will define the default database for a module lacking db_type option or if auth_method option is not set.
    "},{"location":"admin/configuration/database/#relational-databases","title":"Relational Databases","text":""},{"location":"admin/configuration/database/#default-and-new-schemas","title":"Default and New Schemas","text":"
    There are two database schemas available in ejabberd: the default schema is preferable when serving one massive domain, the new schema is preferable when serving many small domains.
     
    The default schema stores only one XMPP domain in the database. The XMPP domain is not stored as this is the same for all the accounts, and this saves space in massive deployments. However, to handle several domains, you have to setup one database per domain and configure each one independently using host_config, so in that case you may prefer the new schema.
     
    The new schema stores the XMPP domain in a new column server_host in the database entries, so it allows to handle several XMPP domains in a single ejabberd database. Using this schema is preferable when serving several XMPP domains and changing domains from time to time. However, if you have only one massive domain, you may prefer to use the default schema.
     
    To use the new schema, edit the ejabberd configuration file and enable new_sql_schema top-level option:
     
    new_sql_schema: true\n
     
    Now, when creating the new database, remember to use the proper SQL schema! For example, if you are using MySQL and choose the default schema, use mysql.sql. If you are using PostgreSQL and need the new schema, use pg.new.sql.
     
    If you already have a MySQL or PostgreSQL database with the default schema and contents, you can upgrade it to the new schema:
     
       
    •  
      MySQL: Edit the file sql/mysql.old-to.new.sql which is included with ejabberd, fill DEFAULT_HOST in the first line, and import that SQL file in your database. Then enable the new_sql_schema option in the ejabberd configuration, and restart ejabberd.
       
      •  
    •  
      PostgreSQL: First enable new_sql_schema and mod_admin_update_sql in your ejabberd configuration:     
      new_sql_schema: true\nmodules:\n  mod_admin_update_sql: {}\n
       then restart ejabberd, and finally execute the update_sql command:     
      ejabberdctl update_sql\n
       
      •  
    "},{"location":"admin/configuration/database/#sql-options","title":"SQL Options","text":"
    The actual database access is defined in the options with sql_ prefix. The values are used to define if we want to use ODBC, or one of the two native interface available, PostgreSQL or MySQL.
     
    To configure SQL there are several top-level options:
     
       
    • sql_type
      •  
    • sql_server
      •  
    • sql_port
      •  
    • sql_database
      •  
    • sql_username
      •  
    • sql_password
      •  
    • sql_ssl
      •  
    • sql_ssl_verify
      •  
    • sql_ssl_cafile
      •  
    • sql_ssl_certfile
      •  
    • sql_pool_size
      •  
    • sql_keepalive_interval
      •  
    • sql_odbc_driver
      •  
    • sql_start_interval
      •  
    • sql_prepared_statements
      •  
    • update_sql_schema
      •  
     
    Example of plain ODBC connection:
     
    sql_server: \"DSN=database;UID=ejabberd;PWD=password\"\n
     
    Example of MySQL connection:
     
    sql_type: mysql\nsql_server: server.company.com\nsql_port: 3306 # the default\nsql_database: mydb\nsql_username: user1\nsql_password: \"**********\"\nsql_pool_size: 5\n
    "},{"location":"admin/configuration/database/#sql-authentication","title":"SQL Authentication","text":"
    You can authenticate users against an SQL database, see the option auth_method in the Authentication section.
     
    To store the passwords in SCRAM format instead of plaintext, see the SCRAM section.
    "},{"location":"admin/configuration/database/#sql-with-ssl-connection","title":"SQL with SSL Connection","text":"
    It's possible to setup SSL encrypted connections to PostgreSQL, MySQL and MsSQL by enabling the sql_ssl option in ejabberd's configuration file: sql_ssl: true
     
    Please notice that ejabberd verifies the certificate presented by the SQL server against the CA certificate list. For that reason, if your SQL server uses a self-signed certificate, you need to setup sql_ssl_verify and sql_ssl_cafile, for example:
     
    sql_ssl: true\nsql_ssl_verify: false\nsql_ssl_cafile: \"/path/to/sql_server_cacert.pem\"\n
     
    This tells ejabberd to ignore problems from not matching any CA certificate from default list, and instead try to verify using the specified CA certificate.
    "},{"location":"admin/configuration/database/#sql-storage","title":"SQL Storage","text":"
    Several ejabberd modules have options called db_type, and can store their tables in an SQL database instead of internal.
     
    In this sense, if you defined your database access using the SQL Options, you can configure a module to use your database by adding the option db_type: sql to that module.
     
    Alternatively, if you want all modules to use your SQL database when possible, you may prefer to set SQL as your default database.
    "},{"location":"admin/configuration/database/#redis","title":"Redis","text":"
    Redis is an advanced key-value cache and store. You can use it to store transient data, such as records for C2S (client) sessions. There are several options available:
     
       
    •  
      redis_server: String:   A hostname of the Redis server. The default is localhost.
       
      •  
    •  
      redis_port: Port:   The port where the Redis server is accepting connections. The default     is 6379.
       
      •  
    •  
      redis_password: String:   The password to the Redis server. The default is an empty string,     i.e. no password.
       
      •  
    •  
      redis_db: N:   Redis database number. The default is 0.
       
      •  
    •  
      redis_connect_timeout: N:   A number of seconds to wait for the connection to be established to the Redis     server. The default is 1 second.
       
      •  
     
    Example configuration:
     
    redis_server: redis.server.com\nredis_db: 1\n
    "},{"location":"admin/configuration/database/#microsoft-sql-server","title":"Microsoft SQL Server","text":"
    For now, MS SQL is only supported in Unix-like OS'es. You need to have unixODBC installed on your machine, and your Erlang/OTP must be compiled with ODBC support. Also, in some cases you need to add machine name to sql_username, especially when you have sql_server defined as an IP address, e.g.:
     
    sql_type: mssql\nsql_server: 1.2.3.4\nsql_username: user1@host\n
     
    By default, ejabberd will use the FreeTDS driver. You need to have the driver file libtdsodbc.so installed in your library PATH on your system.
     
    If the FreeTDS driver is not installed in a standard location, or if you want to use another ODBC driver, you can specify the path to the driver using the sql_odbc_driver option, available in ejabberd 20.12 or later. For example, if you want to use Microsoft ODBC Driver 17 for SQL Server:
     
    sql_odbc_driver: \"/opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.3.so.1.1\"\n
     
    Note that if you use a Microsoft driver, you may have to use an IP address instead of a host name for the sql_server option.
     
    If hostname (or IP address) is specified in sql_server option, ejabberd will connect using a an ODBC DSN connection string constructed with:
     
       
    • SERVER=sql_server
      •  
    • DATABASE=sql_database
      •  
    • UID=sql_username
      •  
    • PWD=sql_password
      •  
    • PORT=sql_port
      •  
    • ENCRYPTION=required (only if sql_ssl is true)
      •  
    • CLIENT_CHARSET=UTF-8
      •  
     
    Since ejabberd 23.04, t is possible to use different connection options by putting a full ODBC connection string in sql_server (e.g. DSN=database;UID=ejabberd;PWD=password). The DSN must be configured in existing system or user odbc.ini file, where it can be configured as desired, using a driver from system odbcinst.ini. The sql_odbc_driver option will have no effect in this case.
     
    If specifying an ODBC connection string, an ODBC connection string must also be specified for any other hosts using MS SQL DB, otherwise the auto-generated ODBC configuration will interfere.
    "},{"location":"admin/configuration/file-format/","title":"File format","text":""},{"location":"admin/configuration/file-format/#yaml-file-format","title":"Yaml File Format","text":"
    ejabberd loads its configuration file during startup. This configuration file is written in YAML format, and its file name MUST have \u201c.yml\u201d or \u201c.yaml\u201d extension. This helps ejabberd to differentiate between this new format and the legacy configuration file format.
     
    Please, consult ejabberd.log for configuration errors. ejabberd will report syntax related errors, as well as complains about unknown options and invalid values. Make sure you respect indentation (YAML is sensitive to this) or you will get pretty cryptic errors.
     
    Note that ejabberd never edits the configuration file. If you are changing parameters at runtime from web admin interface, you will need to apply them to configuration file manually. This is to prevent messing up with your config file comments, syntax, etc.
    "},{"location":"admin/configuration/file-format/#reload-at-runtime","title":"Reload at Runtime","text":"
    You can modify the ejabberd configuration file and reload it at runtime: the changes you made are applied immediately, no need to restart ejabberd. This applies to adding, changing or removing vhosts, listened ports, modules, ACLs or any other options.
     
    How to do this?
     
       
    1. Let's assume your ejabberd server is already running
      2.  
    2. Modify the configuration file
      3.  
    3. Run the reload_config command
      4.  
    4. ejabberd will read that file, check its YAML syntax is valid,    check the options are valid and known...
      5.  
    5. If there's any problem in the configuration file,    the reload is aborted and an error message is logged with details,    so you can fix the problem.
      6.  
    6. If the file is right, it detects the changed options,    and applies them immediately (add/remove hosts, add/remove modules, ...)
      7.  
    "},{"location":"admin/configuration/file-format/#legacy-configuration-file","title":"Legacy Configuration File","text":"
    In previous ejabberd version the configuration file should be written in Erlang terms. The format is still supported, but it is highly recommended to convert it to the new YAML format with the convert_to_yaml API command using ejabberdctl.
     
    If you want to specify some options using the old Erlang format, you can set them in an additional cfg file, and include it using the include_config_file option, see Include Additional Files for the option description and a related example in Restrict Execution with AccessCommands.
    "},{"location":"admin/configuration/file-format/#include-additional-files","title":"Include Additional Files","text":"
    The option include_config_file  in a configuration file instructs ejabberd to include other configuration files immediately.
     
    This is a basic example:
     
    include_config_file: /etc/ejabberd/additional.yml\n
     
    In this example, the included file is not allowed to contain a listen option. If such an option is present, the option will not be accepted. The file is in a subdirectory from where the main configuration file is.
     
    include_config_file:\n  ./example.org/additional_not_listen.yml:\n    disallow: [listen]\n
     
    Please notice that options already defined in the main configuration file cannot be redefined in the included configuration files. But you can use host_config and append_host_config as usual (see Virtual Hosting).
     
    In this example, ejabberd.yml defines some ACL for the whole ejabberd server, and later includes another file:
     
    acl:\n  admin:\n    user:\n      - admin@localhost\ninclude_config_file:\n  /etc/ejabberd/acl.yml\n
     
    The file acl.yml can add additional administrators to one of the virtual hosts:
     
    append_host_config:\n  localhost:\n    acl:\n      admin:\n        user:\n          - bob@localhost\n          - jan@localhost\n
    "},{"location":"admin/configuration/file-format/#macros-in-configuration-file","title":"Macros in Configuration File","text":"
    In the ejabberd configuration file, it is possible to define a macro for a value and later use this macro when defining an option.
     
    A macro is defined using the define_macro option.
     
    This example shows the basic usage of a macro:
     
    define_macro:\n  LOG_LEVEL_NUMBER: 5\nloglevel: LOG_LEVEL_NUMBER\n
     
    The resulting option interpreted by ejabberd is: loglevel: 5.
     
    This example shows that values can be any arbitrary YAML value:
     
    define_macro:\n  USERBOB:\n    user:\n      - bob@localhost\nacl:\n  admin: USERBOB\n
     
    The resulting option interpreted by ejabberd is:
     
    acl:\n  admin:\n    user:\n      - bob@localhost\n
     
    This complex example:
     
    define_macro:\n  NUMBER_PORT_C2S: 5222\n  NUMBER_PORT_HTTP: 5280\nlisten:\n  -\n    port: NUMBER_PORT_C2S\n    module: ejabberd_c2s\n  -\n    port: NUMBER_PORT_HTTP\n    module: ejabberd_http\n
     
    produces this result after being interpreted:
     
    listen:\n  -\n    port: 5222\n    module: ejabberd_c2s\n  -\n    port: 5280\n    module: ejabberd_http\n
    "},{"location":"admin/configuration/ldap/","title":"LDAP Configuration","text":""},{"location":"admin/configuration/ldap/#supported-storages","title":"Supported storages","text":"
    The following LDAP servers are tested with ejabberd:
     
       
    •  
      Active Directory (see section\u00a0Active Directory)
       
      •  
    •  
      OpenLDAP
       
      •  
    •  
      CommuniGate Pro
       
      •  
    •  
      Normally any LDAP compatible server should work; inform us about  your success with a not-listed server so that we can list it here.
       
      •  
    "},{"location":"admin/configuration/ldap/#ldap","title":"LDAP","text":"
    ejabberd has built-in LDAP support. You can authenticate users against LDAP server and use LDAP directory as vCard storage.
     
    Usually ejabberd treats LDAP as a read-only storage: it is possible to consult data, but not possible to create accounts or edit vCard that is stored in LDAP. However, it is possible to change passwords if mod_register module is enabled and LDAP server supports RFC 3062.
    "},{"location":"admin/configuration/ldap/#ldap-connection","title":"LDAP Connection","text":"
    Two connections are established to the LDAP server per vhost, one for authentication and other for regular calls.
     
    To configure the LDAP connection there are these top-level options:
     
       
    • ldap_servers
      •  
    • ldap_encrypt
      •  
    • ldap_tls_verify
      •  
    • ldap_tls_cacertfile
      •  
    • ldap_tls_depth
      •  
    • ldap_port
      •  
    • ldap_rootdn
      •  
    • ldap_password
      •  
    • ldap_deref_aliases
      •  
     
    Example:
     
    auth_method: [ldap]\nldap_servers:\n  - ldap1.example.org\nldap_port: 389\nldap_rootdn: \"cn=Manager,dc=domain,dc=org\"\nldap_password: \"**********\"\n
    "},{"location":"admin/configuration/ldap/#ldap-authentication","title":"LDAP Authentication","text":"
    You can authenticate users against an LDAP directory. Note that current LDAP implementation does not support SASL authentication.
     
    To configure LDAP authentication there are these top-level options:
     
       
    • ldap_base
      •  
    • ldap_uids
      •  
    • ldap_filter
      •  
    • ldap_dn_filter
      •  
    "},{"location":"admin/configuration/ldap/#ldap-examples","title":"LDAP Examples","text":""},{"location":"admin/configuration/ldap/#common-example","title":"Common example","text":"
    Let\u2019s say ldap.example.org is the name of our LDAP server. We have users with their passwords in ou=Users,dc=example,dc=org directory. Also we have addressbook, which contains users emails and their additional infos in ou=AddressBook,dc=example,dc=org directory. The connection to the LDAP server is encrypted using TLS, and using the custom port 6123. Corresponding authentication section should looks like this:
     
    ## Authentication method\nauth_method: [ldap]\n## DNS name of our LDAP server\nldap_servers: [ldap.example.org]\n## Bind to LDAP server as \"cn=Manager,dc=example,dc=org\" with password \"secret\"\nldap_rootdn: \"cn=Manager,dc=example,dc=org\"\nldap_password: secret\nldap_encrypt: tls\nldap_port: 6123\n## Define the user's base\nldap_base: \"ou=Users,dc=example,dc=org\"\n## We want to authorize users from 'shadowAccount' object class only\nldap_filter: \"(objectClass=shadowAccount)\"\n
     
    Now we want to use users LDAP-info as their vCards. We have four attributes defined in our LDAP schema: mail \u2014 email address, givenName \u2014 first name, sn \u2014 second name, birthDay \u2014 birthday. Also we want users to search each other. Let\u2019s see how we can set it up:
     
    modules:\n  mod_vcard:\n    db_type: ldap\n    ## We use the same server and port, but want to bind anonymously because\n    ## our LDAP server accepts anonymous requests to\n    ## \"ou=AddressBook,dc=example,dc=org\" subtree.\n    ldap_rootdn: \"\"\n    ldap_password: \"\"\n    ## define the addressbook's base\n    ldap_base: \"ou=AddressBook,dc=example,dc=org\"\n    ## uidattr: user's part of JID is located in the \"mail\" attribute\n    ## uidattr_format: common format for our emails\n    ldap_uids:\n      mail: \"%u@mail.example.org\"\n    ## We have to define empty filter here, because entries in addressbook does not\n    ## belong to shadowAccount object class\n    ldap_filter: \"\"\n    ## Now we want to define vCard pattern\n    ldap_vcard_map:\n     NICKNAME: {\"%u\": []} # just use user's part of JID as their nickname\n     GIVEN: {\"%s\": [givenName]}\n     FAMILY: {\"%s\": [sn]}\n     FN: {\"%s, %s\": [sn, givenName]} # example: \"Smith, John\"\n     EMAIL: {\"%s\": [mail]}\n     BDAY: {\"%s\": [birthDay]}\n    ## Search form\n    ldap_search_fields:\n      User: \"%u\"\n      Name: givenName\n      \"Family Name\": sn\n      Email: mail\n      Birthday: birthDay\n    ## vCard fields to be reported\n    ## Note that JID is always returned with search results\n    ldap_search_reported:\n      \"Full Name\": FN\n      Nickname: NICKNAME\n      Birthday: BDAY\n
     
    Note that mod_vcard with LDAP backend checks for the existence of the user before searching their information in LDAP.
    "},{"location":"admin/configuration/ldap/#active-directory","title":"Active Directory","text":"
    Active Directory is just an LDAP-server with predefined attributes. A sample configuration is shown below:
     
    auth_method: [ldap]\nldap_servers: [office.org]  # List of LDAP servers\nldap_base: \"DC=office,DC=org\" # Search base of LDAP directory\nldap_rootdn: \"CN=Administrator,CN=Users,DC=office,DC=org\" # LDAP manager\nldap_password: \"*******\" # Password to LDAP manager\nldap_uids: [sAMAccountName]\nldap_filter: \"(memberOf=*)\"\n\nmodules:\n  mod_vcard:\n    db_type: ldap\n    ldap_vcard_map:\n      NICKNAME: {\"%u\": []}\n      GIVEN: {\"%s\": [givenName]}\n      MIDDLE: {\"%s\": [initials]}\n      FAMILY: {\"%s\": [sn]}\n      FN: {\"%s\": [displayName]}\n      EMAIL: {\"%s\": [mail]}\n      ORGNAME: {\"%s\": [company]}\n      ORGUNIT: {\"%s\": [department]}\n      CTRY: {\"%s\": [c]}\n      LOCALITY: {\"%s\": [l]}\n      STREET: {\"%s\": [streetAddress]}\n      REGION: {\"%s\": [st]}\n      PCODE: {\"%s\": [postalCode]}\n      TITLE: {\"%s\": [title]}\n      URL: {\"%s\": [wWWHomePage]}\n      DESC: {\"%s\": [description]}\n      TEL: {\"%s\": [telephoneNumber]}\n    ldap_search_fields:\n      User: \"%u\"\n      Name: givenName\n      \"Family Name\": sn\n      Email: mail\n      Company: company\n      Department: department\n      Role: title\n      Description: description\n      Phone: telephoneNumber\n    ldap_search_reported:\n      \"Full Name\": FN\n      Nickname: NICKNAME\n      Email: EMAIL\n
    "},{"location":"admin/configuration/ldap/#shared-roster-in-ldap","title":"Shared Roster in LDAP","text":"
    Since mod_shared_roster_ldap has a few complex options, some of them are documented with more detail here:
    "},{"location":"admin/configuration/ldap/#filters","title":"Filters","text":"
    ldap_ufilter:   \u201cUser Filter\u201d \u2013 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. If  unspecified, defaults to the top-level parameter of the same name.  If that one also is unspecified, then the filter is assembled from  values of other parameters as follows ([ldap_SOMETHING] is used to  mean \u201cthe value of the configuration parameter  ldap_SOMETHING\u201d):
     
    (&(&([ldap_memberattr]=[ldap_memberattr_format])([ldap_groupattr]=%g))[ldap_filter])\n
     
    Subsequently %u and %g are replaced with a *. This means that given the defaults, the filter sent to the LDAP server would be (&(memberUid=*)(cn=*)). If however the ldap_memberattr_format is something like uid=%u,ou=People,o=org, then the filter will be (&(memberUid=uid=*,ou=People,o=org)(cn=*)).
     
    ldap_filter:   Additional filter which is AND-ed together with User  Filter and Group Filter. If unspecified,  defaults to the top-level parameter of the same name. If that one is  also unspecified, then no additional filter is merged with the other  filters.
     
    Note that you will probably need to manually define the User and Group Filter (since the auto-assembled ones will not work) if:
     
       
    •  
      your ldap_memberattr_format is anything other than a  simple %u,
       
      •  
    •  
      and the attribute specified with ldap_memberattr does not support substring matches.
       
      •  
     
    An example where it is the case is OpenLDAP and (unique)MemberName attribute from the groupOf(Unique)Names objectClass. A symptom of this problem is that you will see messages such as the following in your slapd.log:
     
    get_filter: unknown filter type=130\nfilter=\"(&(?=undefined)(?=undefined)(something=else))\"\n
    "},{"location":"admin/configuration/ldap/#control-parameters","title":"Control parameters","text":"
    These parameters control the behaviour of the module.
     
    ldap_memberattr_format_re:   A regex for extracting user ID from the value of the attribute named  by ldap_memberattr.
     
    An example value \u201cCN=(\\\\w*),(OU=.*,)*DC=company,DC=com\u201d works for user IDs such as the following:
     
       
    • CN=Romeo,OU=Montague,DC=company,DC=com
      •  
    • CN=Abram,OU=Servants,OU=Montague,DC=company,DC=com
      •  
    • CN=Juliet,OU=Capulet,DC=company,DC=com
      •  
    • CN=Peter,OU=Servants,OU=Capulet,DC=company,DC=com
      •  
     
    In case:
     
       
    • the option is unset,
      •  
    • or the re module in unavailable in the current Erlang environment,
      •  
    • or the regular expression does not compile,
      •  
     
    then instead of a regular expression, a simple format specified by ldap_memberattr_format is used. Also, in the last two cases an error message is logged during the module initialization.
     
    Also, note that in all cases ldap_memberattr_format (and *not* the regex version) is used for constructing the default \u201cUser/Group Filter\u201d \u2014 see section\u00a0Filters.
    "},{"location":"admin/configuration/ldap/#retrieving-the-roster","title":"Retrieving the roster","text":"
    When the module is called to retrieve the shared roster for a user, the following algorithm is used:
     
       
    1.  
      [step:rfilter] A list of names of groups to display is created: the Roster Filter is run against the base DN, retrieving the values of the attribute named by ldap_groupattr.
       
      2.  
    2.  
      Unless the group cache is fresh (see the ldap_group_cache_validity option), it is refreshed:
       
         
      1.  
        Information for all groups is retrieved using a single query: the Group Filter is run against the Base DN, retrieving the values of attributes named by ldap_groupattr (group ID), ldap_groupdesc (group \u201cDisplay Name\u201d) and ldap_memberattr (IDs of group members).
         
        2.  
      2.  
        group \u201cDisplay Name\u201d, read from the attribute named by ldap_groupdesc, is stored in the cache for the   given group
         
        3.  
      3.  
        the following processing takes place for each retrieved value of attribute named by ldap_memberattr:
         
           
        1.  
          the user ID part of it is extracted using ldap_memberattr_format(_re),
           
          2.  
        2.  
          then (unless ldap_auth_check is set to off) for each found user ID, the module checks (using the ejabberd authentication subsystem) whether such user exists in the given virtual host. It is skipped if the check is enabled and fails.    This step is here for historical reasons. If you have a tidy DIT and properly defined \u201cRoster Filter\u201d and \u201cGroup Filter\u201d, it is safe to disable it by setting ldap_auth_check to off \u2014 it will speed up the roster retrieval.
           
          3.  
        3.  
          the user ID is stored in the list of members in the cache for the given group.
           
          4.  
         
        4.  
       
      3.  
    3.  
      For each item (group name) in the list of groups retrieved in step\u00a0[step:rfilter]:
       
         
      1.  
        the display name of a shared roster group is retrieved from the group cache
         
        2.  
      2.  
        for each IDs of users which belong to the group, retrieved from the group cache:
         
           
        1.  
          the ID is skipped if it\u2019s the same as the one for which we are retrieving the roster. This is so that the user does not have himself in the roster.
           
          2.  
        2.  
          the display name of a shared roster user is retrieved:
           
             
          1.  
            first, unless the user name cache is fresh (see the ldap_user_cache_validity option), it is refreshed by running the User Filter, against the Base DN, retrieving the values of attributes named by ldap_useruid and ldap_userdesc.
             
            2.  
          2.  
            then, the display name for the given user ID is retrieved from the user name cache.
             
            3.  
           
          3.  
         
        3.  
       
      4.  
    "},{"location":"admin/configuration/ldap/#multi-domain","title":"Multi-Domain","text":"
    By default, the module option ldap_userjidattr is set to the empty string, in that case the JID of the user's contact is formed by compounding UID of the contact @ Host of the user owning the roster.
     
    When the option ldap_userjidattr is set to something like \"mail\", then it uses that field to determine the JID of the contact. This is useful if the ldap mail attribute contains the JID of the accounts.
     
    Basically, it allows us to define a groupOfNames (e.g. xmppRosterGroup) and list any users, anywhere in the ldap directory by specifying the attribute defining the JID of the members.
     
    This allows hosts/domains other than that of the roster owner. It is also more flexible, since the LDAP manager can specify the JID of the users without any assumptions being made. The only down side is that there must be an LDAP attribute (field) filled in for all Jabber/XMPP users.
     
    Below is a sample, a relevant LDAP entry, and ejabberd's module configuration:
     
    cn=Example Org Roster,ou=groups,o=Example Organisation,dc=acme,dc=com\nobjectClass: groupOfNames\nobjectClass: xmppRosterGroup\nobjectClass: top\nxmppRosterStatus: active\nmember:\ndescription: Roster group for Example Org\ncn: Example Org Roster\nuniqueMember: uid=john,ou=people,o=Example Organisation,dc=acme,dc=com\nuniqueMember: uid=pierre,ou=people,o=Example Organisation,dc=acme,dc=com\nuniqueMember: uid=jane,ou=people,o=Example Organisation,dc=acme,dc=com\n\nuid=john,ou=people,o=Example Organisation,dc=acme,dc=com\nobjectClass: top\nobjectClass: person\nobjectClass: organizationalPerson\nobjectClass: inetOrgPerson\nobjectClass: mailUser\nobjectClass: sipRoutingObject\nuid: john\ngivenName: John\nsn: Doe\ncn: John Doe\ndisplayName: John Doe\naccountStatus: active\nuserPassword: secretpass\nIMAPURL: imap://imap.example.net:143\nmailHost: smtp.example.net\nmail: john@example.net\nsipLocalAddress: john@example.net\n
     
    Below is the sample ejabberd.yml module configuration to match:
     
    mod_shared_roster_ldap:\n  ldap_servers:\n    - \"ldap.acme.com\"\n  ldap_encrypt: tls\n  ldap_port: 636\n  ldap_rootdn: \"cn=Manager,dc=acme,dc=com\"\n  ldap_password: \"supersecretpass\"\n  ldap_base: \"dc=acme,dc=com\"\n  ldap_filter: \"(objectClass=*)\"\n  ldap_rfilter: \"(&(objectClass=xmppRosterGroup)(xmppRosterStatus=active))\"\n  ldap_gfilter: \"(&(objectClass=xmppRosterGroup)(xmppRosterStatus=active)(cn=%g))\"\n  ldap_groupattr: \"cn\"\n  ldap_groupdesc: \"cn\"\n  ldap_memberattr: \"uniqueMember\"\n  ldap_memberattr_format_re: \"uid=([a-z.]*),(ou=.*,)*(o=.*,)*dc=acme,dc=com\"\n  ldap_useruid: \"uid\"\n  ldap_userdesc: \"cn\"\n   ldap_userjidattr: \"mail\"\n   ldap_auth_check: false\n   ldap_user_cache_validity: 86400\n   ldap_group_cache_validity: 86400\n
    "},{"location":"admin/configuration/ldap/#configuration-examples","title":"Configuration examples","text":"
    Since there are many possible DIT layouts, it will probably be easiest to understand how to configure the module by looking at an example for a given DIT (or one resembling it).
    "},{"location":"admin/configuration/ldap/#flat-dit","title":"Flat DIT","text":"
    This seems to be the kind of DIT for which this module was initially designed. Basically there are just user objects, and group membership is stored in an attribute individually for each user. For example in a layout like this, it's stored in the ou attribute:
     
     
    Such layout has a few downsides, including:
     
       
    •  
      information duplication \u2013 the group name is repeated in every member  object
       
      •  
    •  
      difficult group management \u2013 information about group members is not  centralized, but distributed between member objects
       
      •  
    •  
      inefficiency \u2013 the list of unique group names has to be computed by  iterating over all users
       
      •  
     
    This however seems to be a common DIT layout, so the module keeps supporting it. You can use the following configuration\u2026
     
    modules:\n  mod_shared_roster_ldap:\n    ldap_base: \"ou=flat,dc=nodomain\"\n    ldap_rfilter: \"(objectClass=inetOrgPerson)\"\n    ldap_groupattr: ou\n    ldap_memberattr: cn\n    ldap_filter: \"(objectClass=inetOrgPerson)\"\n    ldap_userdesc: displayName\n
     
    \u2026to be provided with a roster upon connecting as user czesio, as shown in this figure:
     
    "},{"location":"admin/configuration/ldap/#deep-dit","title":"Deep DIT","text":"
    This type of DIT contains distinctly typed objects for users and groups \u2013 see the next figure. They are shown separated into different subtrees, but it\u2019s not a requirement.
     
     
    If you use the following example module configuration with it:
     
    modules:\n  mod_shared_roster_ldap:\n    ldap_base: \"ou=deep,dc=nodomain\"\n    ldap_rfilter: \"(objectClass=groupOfUniqueNames)\"\n    ldap_filter: \"\"\n    ldap_gfilter: \"(&(objectClass=groupOfUniqueNames)(cn=%g))\"\n    ldap_groupdesc: description\n    ldap_memberattr: uniqueMember\n    ldap_memberattr_format: \"cn=%u,ou=people,ou=deep,dc=nodomain\"\n    ldap_ufilter: \"(&(objectClass=inetOrgPerson)(cn=%u))\"\n    ldap_userdesc: displayName\n
     
    \u2026and connect as user czesio, then ejabberd will provide you with the roster shown in this figure:
     
    "},{"location":"admin/configuration/ldap/#vcard-in-ldap","title":"vCard in LDAP","text":"
    Since LDAP may be complex to configure in mod_vcard, this section provides more details.
     
    ejabberd can map LDAP attributes to vCard fields. This feature is enabled when the mod_vcard module is configured with db_type: ldap. Notice that it does not depend on the authentication method (see LDAP Authentication).
     
    Usually ejabberd treats LDAP as a read-only storage: it is possible to consult data, but not possible to create accounts or edit vCard that is stored in LDAP. However, it is possible to change passwords if mod_register module is enabled and LDAP server supports RFC 3062.
     
    This feature has its own optional parameters. The first group of parameters has the same meaning as the top-level LDAP parameters to set the authentication method: ldap_servers, ldap_port, ldap_rootdn, ldap_password, ldap_base, ldap_uids, ldap_deref_aliases and ldap_filter. See section LDAP Authentication for detailed information about these options. If one of these options is not set, ejabberd will look for the top-level option with the same name.
     
    Examples:
     
       
    •  
      Let\u2019s say ldap.example.org is the name of our LDAP server. We have  users with their passwords in ou=Users,dc=example,dc=org  directory. Also we have addressbook, which contains users emails and  their additional infos in ou=AddressBook,dc=example,dc=org  directory. Corresponding authentication section should looks like  this:
       
      ## authentication method\nauth_method: ldap\n## DNS name of our LDAP server\nldap_servers:\n  - ldap.example.org\n## We want to authorize users from 'shadowAccount' object class only\nldap_filter: \"(objectClass=shadowAccount)\"\n
       
      •  
    •  
      Now we want to use users LDAP-info as their vCards. We have four attributes defined in our LDAP schema: mail \u2014 email address, givenName \u2014 first name, sn \u2014 second name, birthDay \u2014 birthday. Also we want users to search each other. Let\u2019s see how we can set it up:
       
      modules:\n  mod_vcard:\n    db_type: ldap\n    ## We use the same server and port, but want to bind anonymously because\n    ## our LDAP server accepts anonymous requests to\n    ## \"ou=AddressBook,dc=example,dc=org\" subtree.\n    ldap_rootdn: \"\"\n    ldap_password: \"\"\n    ## define the addressbook's base\n    ldap_base: \"ou=AddressBook,dc=example,dc=org\"\n    ## uidattr: user's part of JID is located in the \"mail\" attribute\n    ## uidattr_format: common format for our emails\n    ldap_uids: {\"mail\": \"%u@mail.example.org\"}\n    ## Now we want to define vCard pattern\n    ldap_vcard_map:\n      NICKNAME: {\"%u\": []} # just use user's part of JID as their nickname\n      FIRST: {\"%s\": [givenName]}\n      LAST: {\"%s\": [sn]}\n      FN: {\"%s, %s\": [sn, givenName]} # example: \"Smith, John\"\n      EMAIL: {\"%s\": [mail]}\n      BDAY: {\"%s\": [birthDay]}\n    ## Search form\n    ldap_search_fields:\n      User: \"%u\"\n      Name: givenName\n      \"Family Name\": sn\n      Email: mail\n      Birthday: birthDay\n    ## vCard fields to be reported\n    ## Note that JID is always returned with search results\n    ldap_search_reported:\n      \"Full Name\": FN\n      Nickname: NICKNAME\n      Birthday: BDAY\n
       
      Note that mod_vcard with LDAP backend checks an existence of the user before searching their info in LDAP.
       
      •  
    •  
      ldap_vcard_map example:
       
      ldap_vcard_map:\n  NICKNAME: {\"%u\": []} # just use user's part of JID as their nickname\n  FN: {\"%s\": [displayName]}\n  CTRY: {Russia: []}\n  EMAIL: {\"%u@%d\": []}\n  DESC: {\"%s\\n%s\": [title, description]}\n
       
      •  
    •  
      ldap_search_fields example:
       
      ldap_search_fields:\n  User: uid\n  \"Full Name\": displayName\n  Email: mail\n
       
      •  
    •  
      ldap_search_reported example:
       
      ldap_search_reported:\n  \"Full Name\": FN\n  Email: EMAIL\n  Birthday: BDAY\n  Nickname: NICKNAME\n
       
      •  
    "},{"location":"admin/configuration/listen-options/","title":"Listen Options","text":"
    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.
     
    This is a detailed description of each option allowed by the listening modules:
    "},{"location":"admin/configuration/listen-options/#access","title":"access","text":"
    AccessName
     
    This option defines access to the port. The default value is all.
    "},{"location":"admin/configuration/listen-options/#backlog","title":"backlog","text":"
    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.
    "},{"location":"admin/configuration/listen-options/#cafile","title":"cafile","text":"
    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 top-level option. To set a file for all server connections, you can use the s2s_cafile top-level option or the ca_file top-level option.
     
    Please note: if this option is set in ejabberd_c2s or ejabberd_s2s_in and the corresponding top-level option is also set (c2s_cafile, s2s_cafile), then the top-level option is used, not this one.
    "},{"location":"admin/configuration/listen-options/#certfile","title":"certfile","text":"
    Path
     
    Path to the certificate file. Only makes sense when the tls options is set. If this option is not set, you should set the certfiles top-level option or configure ACME.
    "},{"location":"admin/configuration/listen-options/#check_from","title":"check_from","text":"
    true | false
     
    This option can be used with ejabberd_service only.  XEP-0114 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 \u2019from\u2019 attribute. Only use  this option if you are completely sure about it. The default value  is true, to be compliant with  XEP-0114.
    "},{"location":"admin/configuration/listen-options/#ciphers","title":"ciphers","text":"
    Ciphers
     
    OpenSSL ciphers list in the same format accepted by  \u2018openssl ciphers\u2019 command.
     
    Please note: if this option is set in ejabberd_c2s or ejabberd_s2s_in and the corresponding top-level option is also set (c2s_ciphers, s2s_ciphers), then the top-level option is used, not this one.
    "},{"location":"admin/configuration/listen-options/#custom_headers","title":"custom_headers","text":"
    {Name: Value}
     
    Specify additional HTTP headers to be included in all HTTP responses. Default value is: []
    "},{"location":"admin/configuration/listen-options/#default_host","title":"default_host","text":"
    undefined | HostName
     
    If the HTTP request received by ejabberd contains the HTTP header  Host with an ambiguous virtual host that doesn\u2019t match any one  defined in ejabberd (see         Host Names),         then this configured HostName  is set as the request Host. The default value of this option is:  undefined.
    "},{"location":"admin/configuration/listen-options/#dhfile","title":"dhfile","text":"
    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 or ejabberd_s2s_in and the corresponding top-level option is also set (c2s_dhfile, s2s_dhfile), then the top-level option is used, not this one.
    "},{"location":"admin/configuration/listen-options/#global_routes","title":"global_routes","text":"
    true | false
     
    This option emulates legacy behaviour which registers all routes defined in 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.
    "},{"location":"admin/configuration/listen-options/#hosts","title":"hosts","text":"
    {Hostname: [HostOption, ...]}
     
    The external Jabber component that connects to this 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).
    "},{"location":"admin/configuration/listen-options/#max_fsm_queue","title":"max_fsm_queue","text":"
    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         and ejabberd_c2s         listeners, or also globally for         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  \u2019undefined\u2019. Default value: \u201910000\u2019.
    "},{"location":"admin/configuration/listen-options/#max_payload_size","title":"max_payload_size","text":"
    Size
     
    Specify the maximum payload size in bytes. It can be either an integer or the word infinity. The default value is infinity.
    "},{"location":"admin/configuration/listen-options/#max_stanza_size","title":"max_stanza_size","text":"
    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.
    "},{"location":"admin/configuration/listen-options/#password","title":"password","text":"
    Secret
     
    Specify the password to verify an external component that connects to the port.
    "},{"location":"admin/configuration/listen-options/#port","title":"port","text":"
    Port number, or unix domain socket path
     
     improved in 20.07
     
    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.
    "},{"location":"admin/configuration/listen-options/#protocol_options","title":"protocol_options","text":"
    ProtocolOpts
     
    List of general options relating to SSL/TLS. These map to  OpenSSL\u2019s set_options().  The default entry is: \"no_sslv3|cipher_server_preference|no_compression\"
     
    Please note: if this option is set in ejabberd_c2s or ejabberd_s2s_in and the corresponding top-level option is also set (c2s_protocol_options, s2s_protocol_options), then the top-level option is used, not this one.
    "},{"location":"admin/configuration/listen-options/#request_handlers","title":"request_handlers","text":"
    {Path: Module}
     
    To define one or several handlers that will serve HTTP requests in 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:
     
    request_handlers:\n  /a/b: mod_foo\n  /bosh: mod_bosh\n  /mqtt: mod_mqtt\n
    "},{"location":"admin/configuration/listen-options/#send_timeout","title":"send_timeout","text":"
    Integer | infinity
     
     new in 21.07
     
    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
    "},{"location":"admin/configuration/listen-options/#shaper","title":"shaper","text":"
    none | ShaperName
     
    This option defines a shaper for the port (see section Shapers).  The default value is none.
    "},{"location":"admin/configuration/listen-options/#shaper_rule","title":"shaper_rule","text":"
    none | ShaperRule
     
    This option defines a shaper rule for ejabberd_service (see section Shapers). The recommended value is fast.
    "},{"location":"admin/configuration/listen-options/#starttls","title":"starttls","text":"
    true | false
     
    This option specifies that STARTTLS encryption is available on connections to the port. You should also set the certfiles top-level option or configure ACME.
     
    This option gets implicitly enabled when enabling starttls_required or tls_verify.
    "},{"location":"admin/configuration/listen-options/#starttls_required","title":"starttls_required","text":"
    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 top-level option or configure ACME.
     
    Enabling this option implicitly enables also the starttls option.
    "},{"location":"admin/configuration/listen-options/#tag","title":"tag","text":"
    String
     
    Allow specifying a tag in a listen section and later use it to have a special api_permissions just for it.
     
    For example:
     
    listen:\n  -\n    port: 4000\n    module: ejabberd_http\n    tag: \"magic_listener\"\n\napi_permissions:\n  \"magic_access\":\n    from:\n      - tag: \"magic_listener\"\n    who: all\n    what: \"*\"\n
     
    The default value is the empty string: \"\".
    "},{"location":"admin/configuration/listen-options/#timeout","title":"timeout","text":"
    Integer
     
    Timeout of the connections, expressed in milliseconds. Default: 5000
    "},{"location":"admin/configuration/listen-options/#tls","title":"tls","text":"
    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,  which can be enabled in ejabberd with the option         starttls.
     
    If this option is set, you should also set the         certfiles top-level         option or configure ACME.
     
    The option tls can also be used in         ejabberd_http         to support HTTPS.
     
    Enabling this option implicitly disables the starttls option.
    "},{"location":"admin/configuration/listen-options/#tls_compression","title":"tls_compression","text":"
    true | false
     
    Whether to enable or disable TLS compression. The default value is  false.
     
    Please note: if this option is set in ejabberd_c2s or ejabberd_s2s_in and the corresponding top-level option is also set (c2s_tls_compression, s2s_tls_compression), then the top-level option is used, not this one.
    "},{"location":"admin/configuration/listen-options/#tls_verify","title":"tls_verify","text":"
    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. 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 option.
    "},{"location":"admin/configuration/listen-options/#use_proxy_protocol","title":"use_proxy_protocol","text":"
    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.     The default value of this option isfalse.
    "},{"location":"admin/configuration/listen-options/#zlib","title":"zlib","text":"
    true | false
     
    This option specifies that Zlib stream compression (as defined in  XEP-0138) is available  on connections to the port.
    "},{"location":"admin/configuration/listen/","title":"Listen Modules","text":"
    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.
    "},{"location":"admin/configuration/listen/#listen-options","title":"Listen Options","text":"
    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:
     
    listen:\n  -\n    port: 5222\n    ip: 127.0.0.1\n    module: ejabberd_c2s\n    starttls: true\n  -\n    port: 5269\n    transport: tcp\n    module: ejabberd_s2s_in\n
    "},{"location":"admin/configuration/listen/#ejabberd_c2s","title":"ejabberd_c2s","text":"
    Handles c2s connections.
     
    General listen options supported: access, cafile, ciphers, dhfile, max_fsm_queue, max_stanza_size, protocol_options, send_timeout, shaper, starttls, starttls_required, tls, tls_compression, tls_verify, zlib.
    "},{"location":"admin/configuration/listen/#ejabberd_s2s_in","title":"ejabberd_s2s_in","text":"
    Handles incoming s2s connections.
     
    General listen options supported: cafile, ciphers, dhfile, max_fsm_queue, max_stanza_size, protocol_options, send_timeout, shaper, tls, tls_compression.
    "},{"location":"admin/configuration/listen/#ejabberd_service","title":"ejabberd_service","text":"
    Interacts with an external component as defined in XEP-0114: Jabber Component Protocol.
     
    General listen options supported: access, cafile, certfile, check_from, ciphers, dhfile, global_routes, hosts, max_fsm_queue, max_stanza_size, password, protocol_options, send_timeout, shaper, shaper_rule, tls, tls_compression.
    "},{"location":"admin/configuration/listen/#mod_mqtt","title":"mod_mqtt","text":"
    Support for MQTT requires configuring mod_mqtt both in the listen and the modules sections. Check the mod_mqtt module options, and the MQTT Support section.
     
    General listen options supported: backlog, max_fsm_queue, max_payload_size, send_timeout, tls, tls_verify.
    "},{"location":"admin/configuration/listen/#ejabberd_stun","title":"ejabberd_stun","text":"
    ejabberd can act as a stand-alone STUN/TURN server, and this module handles STUN/TURN requests as defined in (RFC 5389/RFC 5766. In that role ejabberd helps clients with ICE (RFC 5245 or Jingle ICE (XEP-0176 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, send_timeout, shaper, 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
       
      8b12c67 (Major reorganization of the Listen page)
       
      The IPv4 address advertised by your TURN server. The address should not be NAT\u2019ed 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\u2019ed 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):
     
    listen:\n  -\n    port: 3478\n    transport: udp\n    module: ejabberd_stun\n  -\n    port: 3478\n    module: ejabberd_stun\n  -\n    port: 5349\n    module: ejabberd_stun\n    certfile: /etc/ejabberd/server.pem\n
     
    Example configuration with TURN functionality. Note that STUN is always enabled if TURN is enabled. Here, only UDP section is shown:
     
    listen:\n  -\n    port: 3478\n    transport: udp\n    use_turn: true\n    turn_ipv4_address: 10.20.30.1\n    module: ejabberd_stun\n
     
    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 of RFC 5389 and section Creating an Allocation of RFC 5766 for details.
     
    Example DNS SRV configuration for STUN only:
     
    _stun._udp   IN SRV  0 0 3478 stun.example.com.\n_stun._tcp   IN SRV  0 0 3478 stun.example.com.\n_stuns._tcp  IN SRV  0 0 5349 stun.example.com.\n
     
    And you should also add these in the case if TURN is enabled:
     
    _turn._udp   IN SRV  0 0 3478 turn.example.com.\n_turn._tcp   IN SRV  0 0 3478 turn.example.com.\n_turns._tcp  IN SRV  0 0 5349 turn.example.com.\n
    "},{"location":"admin/configuration/listen/#ejabberd_sip","title":"ejabberd_sip","text":"
    ejabberd has built-in support to handle SIP requests as defined in RFC 3261.
     
    To activate this feature, add the ejabberd_sip listen module, enable 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 section. If option tls is specified, option certfile must be specified as well, otherwise incoming TLS connections would fail.
     
    General listen options supported: certfile, send_timeout, tls.
     
    Example configuration with standard ports (as per RFC 3261):
     
    listen:\n  -\n    port: 5060\n    transport: udp\n    module: ejabberd_sip\n  -\n    port: 5060\n    module: ejabberd_sip\n  -\n    port: 5061\n    module: ejabberd_sip\n    tls: true\n    certfile: /etc/ejabberd/server.pem\n
     
    Note that there is no StartTLS support in SIP and SNI 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 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\u2019s not fatal, however, highly recommended.
     
    Example configuration of NAPTR records:
     
    example.com IN NAPTR 10  0 \"s\" \"SIPS+D2T\" \"\" _sips._tcp.example.com.\nexample.com IN NAPTR 20  0 \"s\" \"SIP+D2T\" \"\" _sip._tcp.example.com.\nexample.com IN NAPTR 30  0 \"s\" \"SIP+D2U\" \"\" _sip._udp.example.com.\n
     
    Example configuration of SRV records with standard ports (as per RFC 3261:
     
    _sip._udp   IN SRV  0 0 5060 sip.example.com.\n_sip._tcp   IN SRV  0 0 5060 sip.example.com.\n_sips._tcp  IN SRV  0 0 5061 sip.example.com.\n
     
    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.
    "},{"location":"admin/configuration/listen/#ejabberd_http","title":"ejabberd_http","text":"
    Handles incoming HTTP connections.
     
    With the proper request handlers configured, this serves HTTP services like ACME, API, BOSH, CAPTCHA, Fileserver, OAuth, RegisterWeb, Upload, WebAdmin, WebSocket, XML-RPC.
     
    Options: cafile, ciphers, custom_headers, default_host, dhfile, protocol_options, request_handlers, send_timeout, tag, tls, tls_compression, and the trusted_proxies top-level option.
    "},{"location":"admin/configuration/listen/#ejabberd_http_ws","title":"ejabberd_http_ws","text":"
    This module enables XMPP communication over WebSocket connection as described in RFC 7395.
    "},{"location":"admin/configuration/listen/#websocket-config","title":"WebSocket Config","text":"
    To enable WebSocket, simply add a handler to the request_handlers section of an ejabberd_http listener:
     
    listen:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /xmpp: ejabberd_http_ws\n
     
    This module can be configured using those top-level options:
     
       
    • websocket_origin
      •  
    • websocket_ping_interval
      •  
    • websocket_timeout
      •  
    "},{"location":"admin/configuration/listen/#websocket-discovery","title":"WebSocket Discovery","text":"
    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). One easy way to provide that file is using mod_host_meta.
    "},{"location":"admin/configuration/listen/#testing-websocket","title":"Testing WebSocket","text":"
    A test client can be found on Github: WebSocket test client
     
    There is an example configuration for WebSocket and Converse.js in the ejabberd 21.12 release notes.
    "},{"location":"admin/configuration/listen/#ejabberd_xmlrpc","title":"ejabberd_xmlrpc","text":"
    Handles XML-RPC requests to execute ejabberd commands. It is configured as a request handler in ejabberd_http.
     
    This is the minimum configuration required to enable the feature:
     
    listen:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /xmlrpc: ejabberd_xmlrpc\n\napi_permissions:\n  \"public commands\":\n    who:\n      ip: 127.0.0.1/8\n    what:\n      - connected_users_number\n
     
    Example Python3 script:
     
    import xmlrpc.client\nserver = xmlrpc.client.ServerProxy(\"http://127.0.0.1:5280/xmlrpc/\");\nprint(server.connected_users_number())\n
     
    By default there is no restriction to who can execute what commands, so it is strongly recommended that you configure restrictions using API Permissions.
     
    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):
     
    listen:\n  -\n    port: 5280\n    ip: \"::\"\n    module: ejabberd_http\n    request_handlers:\n      /xmlrpc: ejabberd_xmlrpc\n\napi_permissions:\n  \"some XMLRPC commands\":\n    from: ejabberd_xmlrpc\n    who:\n      - ip: 127.0.0.1\n      - user: user1@localhost\n    what:\n      - registered_users\n      - connected_users_number\n
     
    Example Python3 script for that restricted configuration:
     
    import xmlrpc.client\nserver = xmlrpc.client.ServerProxy(\"http://127.0.0.1:5280/xmlrpc/\");\n\nparams = {}\nparams['host'] = 'localhost'\n\nauth = {'user': 'user1',\n        'server': 'localhost',\n        'password': 'mypass11',\n        'admin': True}\n\ndef calling(command, data):\n    fn = getattr(server, command)\n    return fn(auth, data)\n\nprint(calling('registered_users', params))\n
     
    Please notice, when using the old Python2, replace the two first lines with:
     
    import xmlrpclib\nserver = xmlrpclib.Server(\"http://127.0.0.1:5280/xmlrpc/\");\n
     
    It's possible to use OAuth for authentication instead of plain password, see OAuth Support.
     
    In ejabberd 20.03 and older, it was possible to configure ejabberd_xmlrpc as a listener, see the old document for reference and example configuration: Listening Module.
     
    Just for reference, there's also the old ejabberd_xmlrpc documentation with example clients in other languages.
    "},{"location":"admin/configuration/listen/#examples","title":"Examples","text":"
    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. The socket only listens connections to the IP address 127.0.0.1.
       
      •  
     
    hosts:\n  - example.com\n  - example.org\n  - example.net\n\ncertfiles:\n  - /etc/ejabberd/server.pem\n  - /etc/ejabberd/example_com.pem\n\nlisten:\n  -\n    port: 5222\n    module: ejabberd_c2s\n    access: c2s\n    shaper: c2s_shaper\n    starttls: true\n    max_stanza_size: 65536\n  -\n    port: 5223\n    module: ejabberd_c2s\n    access: c2s\n    shaper: c2s_shaper\n    tls: true\n    max_stanza_size: 65536\n  -\n    port: 5269\n    ip: \"::\"\n    module: ejabberd_s2s_in\n    shaper: s2s_shaper\n    max_stanza_size: 131072\n  -\n    port: 3478\n    transport: udp\n    module: ejabberd_stun\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /bosh: mod_bosh\n  -\n    port: 5281\n    ip: 127.0.0.1\n    module: ejabberd_http\n    tls: true\n    request_handlers:\n      /admin: ejabberd_web_admin\n      /bosh: mod_bosh\n\ns2s_use_starttls: optional\noutgoing_s2s_families:\n  - ipv4\n  - ipv6\noutgoing_s2s_timeout: 10000\ntrusted_proxies: [127.0.0.1, 192.168.1.11]\n
     
    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 \u2018bad\u2019.
       
      •  
    •  
      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:  \u201cjabber.example.org\u201d and \u201cexample.com\u201d.
       
      •  
    •  
      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\u00a0Managing: 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 aim.example.org is connected to port 5233 on localhost IP  addresses (127.0.0.1 and ::1) with password \u2018aimsecret\u2019.
       
      •  
    •  
      The ICQ transport JIT (icq.example.org and sms.example.org) is  connected to port 5234 with password \u2018jitsecret\u2019.
       
      •  
    •  
      The MSN transport msn.example.org is connected to port 5235 with password  \u2018msnsecret\u2019.
       
      •  
    •  
      The Yahoo! transport yahoo.example.org is connected to port 5236 with password  \u2018yahoosecret\u2019.
       
      •  
    •  
      The  Gadu-Gadu transport gg.example.org is connected to port 5237 with password  \u2018ggsecret\u2019.
       
      •  
    •  
      The Jabber Mail Component jmc.example.org is connected to port 5238 with password  \u2018jmcsecret\u2019.
       
      •  
    •  
      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.
       
      •  
     
    acl:\n  blocked:\n    user: bad\n  trusted_servers:\n    server:\n      - example.com\n      - jabber.example.org\n  xmlrpc_bot:\n    user:\n      - xmlrpc-robot@example.org\nshaper:\n  normal: 1000\nshaper_rules:\n  c2s_shaper:\n    - none: admin\n    - normal\naccess_rules:\n  c2s:\n    - deny: blocked\n    - allow\n  xmlrpc_access:\n    - allow: xmlrpc_bot\n  s2s:\n    - allow: trusted_servers\ncertfiles:\n  - /path/to/ssl.pem\ns2s_access: s2s\ns2s_use_starttls: required_trusted\nlisten:\n  -\n    port: 5222\n    module: ejabberd_c2s\n    shaper: c2s_shaper\n    access: c2s\n  -\n    ip: 192.168.0.1\n    port: 5223\n    module: ejabberd_c2s\n    tls: true\n    access: c2s\n  -\n    ip: \"FDCA:8AB6:A243:75EF::1\"\n    port: 5223\n    module: ejabberd_c2s\n    tls: true\n    access: c2s\n  -\n    port: 5269\n    module: ejabberd_s2s_in\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /admin: ejabberd_web_admin\n      /bosh: mod_bosh\n      /mqtt: mod_mqtt\n  -\n    port: 4560\n    module: ejabberd_xmlrpc\n    access_commands: {}\n  -\n    ip: 127.0.0.1\n    port: 5233\n    module: ejabberd_service\n    hosts:\n      aim.example.org:\n        password: aimsecret\n  -\n    ip: \"::1\"\n    port: 5233\n    module: ejabberd_service\n    hosts:\n      aim.example.org:\n        password: aimsecret\n  -\n    port: 5234\n    module: ejabberd_service\n    hosts:\n      icq.example.org:\n        password: jitsecret\n      sms.example.org:\n        password: jitsecret\n  -\n    port: 5235\n    module: ejabberd_service\n    hosts:\n      msn.example.org:\n        password: msnsecret\n  -\n    port: 5236\n    module: ejabberd_service\n    password: yahoosecret\n  -\n    port: 5237\n    module: ejabberd_service\n    hosts:\n      gg.example.org:\n        password: ggsecret\n  -\n    port: 5238\n    module: ejabberd_service\n    hosts:\n      jmc.example.org:\n        password: jmcsecret\n  -\n    port: 5239\n    module: ejabberd_service\n    check_from: false\n    hosts:\n      custom.example.org:\n        password: customsecret\n
     
    Note, that for services based in jabberd14 or WPJabber you have to make the transports log and do XDB by themselves:
     
    <!--\n   You have to add elogger and rlogger entries here when using ejabberd.\n   In this case the transport will do the logging.\n-->\n\n<log id='logger'>\n  <host/>\n  <logtype/>\n  <format>%d: [%t] (%h): %s</format>\n  <file>/var/log/jabber/service.log</file>\n</log>\n\n<!--\n   Some XMPP server implementations do not provide\n   XDB services (for example, jabberd2 and ejabberd).\n   xdb_file.so is loaded in to handle all XDB requests.\n-->\n\n<xdb id=\"xdb\">\n  <host/>\n  <load>\n    <!-- this is a lib of wpjabber or jabberd14 -->\n    <xdb_file>/usr/lib/jabber/xdb_file.so</xdb_file>\n    </load>\n  <xdb_file xmlns=\"jabber:config:xdb_file\">\n    <spool><jabberd:cmdline flag='s'>/var/spool/jabber</jabberd:cmdline></spool>\n  </xdb_file>\n</xdb>\n
    "},{"location":"admin/configuration/modules/","title":"Modules Options","text":"
    This section describes modules options of ejabberd 24.02.  If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the Archive. The modules that changed in this version are marked with \ud83d\udfe4.
    "},{"location":"admin/configuration/modules/#mod_adhoc","title":"mod_adhoc","text":"
    This module implements XEP-0050: Ad-Hoc Commands. It\u2019s 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.
      •  
    "},{"location":"admin/configuration/modules/#mod_admin_extra","title":"mod_admin_extra","text":"
    This module provides additional administrative commands.
     
    Details for some commands:
     
       
    •  
      ban-acount: 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\u2019t 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 blankspaces, 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:
     
    acl:\n  adminextraresource:\n    - resource: \"modadminextraf8x,31ad\"\naccess_rules:\n  vcard_set:\n    - allow: adminextraresource\nmodules:\n  mod_admin_extra: {}\n  mod_vcard:\n    access_set: vcard_set\n
     
    Content of roster file for pushroster command:
     
    [{<<\"bob\">>, <<\"example.org\">>, <<\"workers\">>, <<\"Bob\">>},\n{<<\"mart\">>, <<\"example.org\">>, <<\"workers\">>, <<\"Mart\">>},\n{<<\"Rich\">>, <<\"example.org\">>, <<\"bosses\">>, <<\"Rich\">>}].\n
     
    With this call, the sessions of the local account which JID is boby@example.org will be kicked, and its password will be set to something like BANNED_ACCOUNT\u201420080425T21:45:07\u20142176635\u2014Spammed_rooms
     
    ejabberdctl vhost example.org ban-account boby \"Spammed rooms\"\n
     
    Call to srg-create using double-quotes and single-quotes:
     
    ejabberdctl srg-create g1 example.org \"'Group number 1'\" this_is_g1 g1\n
    "},{"location":"admin/configuration/modules/#mod_admin_update_sql","title":"mod_admin_update_sql","text":"
    This module can be used to update existing SQL database from the default to the new schema. Check the section 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 API.
     
    The module has no options.
    "},{"location":"admin/configuration/modules/#mod_announce","title":"mod_announce","text":"
    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 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) 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level default_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_avatar","title":"mod_avatar","text":"
    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.
     
    Also, the module supports conversion between avatar image formats on the fly.
     
    The module depends on mod_vcard, mod_vcard_xupdate and 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:
       
      convert:\n  webp: jpg\n  default: png\n
       
      •  
    •  
      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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_block_strangers","title":"mod_block_strangers","text":"
    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\u2019ll 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\u2019s 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\u2019s JID is in user\u2019s 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 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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_blocking","title":"mod_blocking","text":"
    The module implements XEP-0191: Blocking Command.
     
    This module depends on mod_privacy where all the configuration is performed.
     
    The module has no options.
    "},{"location":"admin/configuration/modules/#mod_bosh","title":"mod_bosh","text":"
    This module implements XMPP over BOSH as defined in XEP-0124 and XEP-0206. 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level 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 option, but applied to this module only.
       
      •  
    •  
      ram_db_type: mnesia | sql | redis Same as top-level default_ram_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
     
    Example:
     
    listen:\n  -\n    port: 5222\n    module: ejabberd_c2s\n  -\n    port: 5443\n    module: ejabberd_http\n    request_handlers:\n      /bosh: mod_bosh\n\nmodules:\n  mod_bosh: {}\n
    "},{"location":"admin/configuration/modules/#mod_caps","title":"mod_caps","text":"
    This module implements XEP-0115: Entity Capabilities. The main purpose of the module is to provide PEP functionality (see mod_pubsub).
     
    Available options:
     
       
    •  
      cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level default_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_carboncopy","title":"mod_carboncopy","text":"
    The module implements XEP-0280: Message Carbons. The module broadcasts messages on all connected user resources (devices).
     
    The module has no options.
    "},{"location":"admin/configuration/modules/#mod_client_state","title":"mod_client_state","text":"
    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). This can save bandwidth and resources.
     
    A stanza is dropped from the queue if it\u2019s 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\u2019t 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) 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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_configure","title":"mod_configure","text":"
    The module provides server configuration functionality via XEP-0050: Ad-Hoc Commands. Implements many commands as defined in XEP-0133: Service Administration. This module requires mod_adhoc to be loaded.
     
    The module has no options.
    "},{"location":"admin/configuration/modules/#mod_conversejs","title":"mod_conversejs","text":"
     added in 21.12 and improved in 22.05
     
    This module serves a simple page for the Converse XMPP web browser client.
     
    To use this module, in addition to adding it to the modules section, you must also enable it in listen \u2192 ejabberd_http \u2192 request_handlers.
     
    Make sure either mod_bosh or ejabberd_http_ws 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} added in 22.05  Specify additional options to be passed to Converse. See Converse configuration. Only boolean, integer and string values are supported; lists are not supported.
       
      •  
    •  
      conversejs_resources: Path added in 22.05  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:
     
    listen:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /bosh: mod_bosh\n      /websocket: ejabberd_http_ws\n      /conversejs: mod_conversejs\n\nmodules:\n  mod_bosh: {}\n  mod_conversejs:\n    websocket_url: \"ws://@HOST@:5280/websocket\"\n
     
    Host Converse locally and let auto detection of WebSocket and Converse URLs:
     
    listen:\n  -\n    port: 443\n    module: ejabberd_http\n    tls: true\n    request_handlers:\n      /websocket: ejabberd_http_ws\n      /conversejs: mod_conversejs\n\nmodules:\n  mod_conversejs:\n    conversejs_resources: \"/home/ejabberd/conversejs-9.0.0/package/dist\"\n
     
    Configure some additional options for Converse
     
    modules:\n  mod_conversejs:\n    websocket_url: auto\n    conversejs_options:\n      auto_away: 30\n      clear_cache_on_logout: true\n      i18n: \"pt\"\n      locked_domain: \"@HOST@\"\n      message_archiving: always\n      theme: dracula\n
    "},{"location":"admin/configuration/modules/#mod_delegation","title":"mod_delegation","text":"
    This module is an implementation of XEP-0355: Namespace Delegation. 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 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.
     
    access_rules:\n  external_pubsub:\n    allow: external_component\n  external_mam:\n    allow: external_component\n\nacl:\n  external_component:\n    server: sat-pubsub.example.org\n\nmodules:\n  mod_delegation:\n    namespaces:\n      urn:xmpp:mam:1:\n        access: external_mam\n      http://jabber.org/protocol/pubsub:\n        access: external_pubsub\n
    "},{"location":"admin/configuration/modules/#mod_disco","title":"mod_disco","text":"
    This module adds support for XEP-0030: Service Discovery. 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. 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:
       
      server_info:\n  -\n    modules: all\n    name: abuse-addresses\n    urls: [\"mailto:abuse@shakespeare.lit\"]\n  -\n    modules: [mod_muc]\n    name: \"Web chatroom logs\"\n    urls: [\"http://www.example.org/muc-logs\"]\n  -\n    modules: [mod_disco]\n    name: feedback-addresses\n    urls:\n      - http://shakespeare.lit/feedback.php\n      - mailto:feedback@shakespeare.lit\n      - xmpp:feedback@shakespeare.lit\n  -\n    modules:\n      - mod_disco\n      - mod_vcard\n    name: admin-addresses\n    urls:\n      - mailto:xmpp@shakespeare.lit\n      - xmpp:admins@shakespeare.lit\n
       
      •  
    "},{"location":"admin/configuration/modules/#mod_fail2ban","title":"mod_fail2ban","text":"
    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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_host_meta","title":"mod_host_meta","text":"
     added in 22.05
     
    This module serves small host-meta files as described in XEP-0156: Discovering Alternative XMPP Connection Methods.
     
    To use this module, in addition to adding it to the modules section, you must also enable it in listen \u2192 ejabberd_http \u2192 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:
     
    listen:\n  -\n    port: 443\n    module: ejabberd_http\n    tls: true\n    request_handlers:\n      /bosh: mod_bosh\n      /ws: ejabberd_http_ws\n      /.well-known/host-meta: mod_host_meta\n      /.well-known/host-meta.json: mod_host_meta\n\nmodules:\n  mod_bosh: {}\n  mod_host_meta:\n    bosh_service_url: \"https://@HOST@:5443/bosh\"\n    websocket_url: \"wss://@HOST@:5443/ws\"\n
    "},{"location":"admin/configuration/modules/#mod_http_api","title":"mod_http_api","text":"
    This module provides a ReST interface to call ejabberd API commands using JSON data.
     
    To use this module, in addition to adding it to the modules section, you must also enable it in listen \u2192 ejabberd_http \u2192 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:
     
    listen:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /api: mod_http_api\n\nmodules:\n  mod_http_api: {}\n
    "},{"location":"admin/configuration/modules/#mod_http_fileserver","title":"mod_http_fileserver","text":"
    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:
       
      content_types:\n  .css: text/css\n  .gif: image/gif\n  .html: text/html\n  .jar: application/java-archive\n  .jpeg: image/jpeg\n  .jpg: image/jpeg\n  .js: text/javascript\n  .png: image/png\n  .svg: image/svg+xml\n  .txt: text/plain\n  .xml: application/xml\n  .xpi: application/x-xpinstall\n  .xul: application/vnd.mozilla.xul+xml\n
       
      •  
    •  
      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\u2019s 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:
     
    listen:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /pub/content: mod_http_fileserver\n\nmodules:\n  mod_http_fileserver:\n    docroot: /var/www\n    accesslog: /var/log/ejabberd/access.log\n    directory_indices:\n      - index.html\n      - main.htm\n    custom_headers:\n      X-Powered-By: Erlang/OTP\n      X-Fry: \"It's a widely-believed fact!\"\n    content_types:\n      .ogg: audio/ogg\n      .png: image/png\n    default_content_type: text/html\n
    "},{"location":"admin/configuration/modules/#mod_http_upload","title":"mod_http_upload","text":"
    This module allows for requesting permissions to upload a file via HTTP as described in XEP-0363: HTTP File Upload. 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 \u2192 ejabberd_http \u2192 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\u2019s mod_http_upload_external 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 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\u2019s 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\u2019s 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:
       
      # This XML representation of vCard:\n#   <vCard xmlns='vcard-temp'>\n#     <FN>Conferences</FN>\n#     <ADR>\n#       <WORK/>\n#       <STREET>Elm Street</STREET>\n#     </ADR>\n#   </vCard>\n#\n# is translated to:\nvcard:\n  fn: Conferences\n  adr:\n    -\n      work: true\n      street: Elm Street\n
       
      •  
     
    Example:
     
    listen:\n  -\n    port: 5443\n    module: ejabberd_http\n    tls: true\n    request_handlers:\n      /upload: mod_http_upload\n\nmodules:\n  mod_http_upload:\n    docroot: /ejabberd/upload\n    put_url: \"https://@HOST@:5443/upload\"\n
    "},{"location":"admin/configuration/modules/#mod_http_upload_quota","title":"mod_http_upload_quota","text":"
    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\u2019s 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:
     
    shaper_rules:\n  soft_upload_quota:\n    1000: all # MiB\n  hard_upload_quota:\n    1100: all # MiB\n\nmodules:\n  mod_http_upload: {}\n  mod_http_upload_quota:\n    max_days: 100\n
    "},{"location":"admin/configuration/modules/#mod_jidprep","title":"mod_jidprep","text":"
    This module allows XMPP clients to ask the server to normalize a JID as per the rules specified in RFC 6122: XMPP Address Format. 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.
      •  
    "},{"location":"admin/configuration/modules/#mod_last","title":"mod_last","text":"
    This module adds support for XEP-0012: Last Activity. 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level default_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_legacy_auth","title":"mod_legacy_auth","text":"
    The module implements XEP-0078: Non-SASL Authentication.
     
    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.
    "},{"location":"admin/configuration/modules/#mod_mam","title":"mod_mam","text":"
    This module implements XEP-0313: Message Archive Management and XEP-0441: Message Archive Management Preferences. 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\u2019s stream management code (see 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\u2019s 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level 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) 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 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\u2019s 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\u2019s messages are archived as usual. The default value is false.
       
      •  
    •  
      use_cache: true | false Same as top-level 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 separa 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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_matrix_gw","title":"mod_matrix_gw \ud83d\udfe4","text":"
     added in 24.02
     
    Matrix 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%matrixdomain.tld@matrix.myxmppdomain.tld, where matrix.myxmppdomain.tld is the JID of the gateway service as set by the host option. The default is false.
       
      •  
     
    Example:
     
    listen:\n  -\n    port: 8448\n    module: ejabberd_http\n    tls: true\n    request_handlers:\n      \"/_matrix\": mod_matrix_gw\n\nmodules:\n  mod_matrix_gw:\n    key_name: \"key1\"\n    key: \"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n    matrix_id_as_jid: true\n
    "},{"location":"admin/configuration/modules/#mod_metrics","title":"mod_metrics","text":"
    This module sends events to external backend (by now only 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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_mix","title":"mod_mix","text":"
     added in 16.03 and improved in 19.02
     
    This module is an experimental implementation of XEP-0369: Mediated Information eXchange (MIX). It\u2019s asserted that the MIX protocol is going to replace the MUC protocol in the future (see mod_muc).
     
    To learn more about how to use that feature, you can refer to our tutorial: Getting started with MIX
     
    The module depends on 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 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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_mix_pam","title":"mod_mix_pam","text":"
    This module implements XEP-0405: Mediated Information eXchange (MIX): Participant Server Requirements. 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level default_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_mqtt","title":"mod_mqtt","text":"
    This module adds support for the MQTT 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level 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 option, but applied to this module only.
       
      •  
    •  
      ram_db_type: mnesia Same as top-level 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 option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_mqtt_bridge","title":"mod_mqtt_bridge","text":"
    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.
     
    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:
     
    modules:\n  mod_mqtt_bridge:\n    servers:\n      \"mqtt://server.com\":\n        publish:\n          \"localA\": \"remoteA\" # local changes to 'localA' will be replicated on remote server as 'remoteA'\n          \"topicB\": \"topicB\"\n        subscribe:\n          \"remoteB\": \"localB\" # changes to 'remoteB' on remote server will be stored as 'localB' on local server\n        authentication:\n          certfile: \"/etc/ejabberd/mqtt_server.pem\"\n    replication_user: \"mqtt@xmpp.server.com\"\n
    "},{"location":"admin/configuration/modules/#mod_muc","title":"mod_muc","text":"
    This module provides support for XEP-0045: Multi-User Chat. 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 improved in 23.10  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 added in 22.05  Remove affiliations for non-existing local users on startup. The default value is false.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level 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. 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\u2019t 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 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. 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:
         
        presence_broadcast:\n  - moderator\n  - participant\n  - visitor\n
         
        •  
      •  
        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\u2019re 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 added in 21.01  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 added in 21.01  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 overcrowed, 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. 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 option, but applied to this module only.
       
      •  
    •  
      ram_db_type: mnesia | sql Same as top-level 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:
       
      # This XML representation of vCard:\n#   <vCard xmlns='vcard-temp'>\n#     <FN>Conferences</FN>\n#     <ADR>\n#       <WORK/>\n#       <STREET>Elm Street</STREET>\n#     </ADR>\n#   </vCard>\n#\n# is translated to:\nvcard:\n  fn: Conferences\n  adr:\n    -\n      work: true\n      street: Elm Street\n
       
      •  
    "},{"location":"admin/configuration/modules/#mod_muc_admin","title":"mod_muc_admin","text":"
    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.
     
    Available options:
     
       
    • subscribe_room_many_max_users: Number added in 22.05  How many users can be subscribed to a room at once using the subscribe_room_many command. The default value is 50.
      •  
    "},{"location":"admin/configuration/modules/#mod_muc_log","title":"mod_muc_log","text":"
    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.
     
    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:
       
      file_permissions:\n  mode: 644\n  group: 33\n
       
      •  
    •  
      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:
       
      top_link:\n  /: Home\n
       
      •  
    •  
      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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_muc_occupantid","title":"mod_muc_occupantid","text":"
     added in 23.10
     
    This module implements XEP-0421: Anonymous unique occupant identifiers for MUCs.
     
    When the module is enabled, the feature is enabled in all semi-anonymous rooms.
     
    The module has no options.
    "},{"location":"admin/configuration/modules/#mod_muc_rtbl","title":"mod_muc_rtbl","text":"
     added in 23.04
     
    This module implement Real-time blocklists for MUC rooms.
     
    It works by observing remote pubsub node conforming with specification described in https://xmppbl.org/.
     
    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
       
      •  
    "},{"location":"admin/configuration/modules/#mod_multicast","title":"mod_multicast","text":"
    This module implements a service for XEP-0033: Extended Stanza Addressing.
     
    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:
         
        # Default values:\nlocal:\n  message: 100\n  presence: 100\nremote:\n  message: 20\n  presence: 20\n
         
        •  
       
      •  
    •  
      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:
     
    # Only admins can send packets to multicast service\naccess_rules:\n  multicast:\n    - allow: admin\n\n# If you want to allow all your users:\naccess_rules:\n  multicast:\n    - allow\n\n# This allows both admins and remote users to send packets,\n# but does not allow local users\nacl:\n  allservers:\n    server_glob: \"*\"\naccess_rules:\n  multicast:\n    - allow: admin\n    - deny: local\n    - allow: allservers\n\nmodules:\n  mod_multicast:\n     host: multicast.example.org\n     access: multicast\n     limits:\n       local:\n         message: 40\n         presence: infinite\n       remote:\n         message: 150\n
    "},{"location":"admin/configuration/modules/#mod_offline","title":"mod_offline","text":"
    This module implements XEP-0160: Best Practices for Handling Offline Messages and XEP-0013: Flexible Offline Message Retrieval. 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 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 optimisation 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 optimisation is enabled.
       
      •  
    •  
      cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level 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.
       
      •  
    •  
      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 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\u2019t 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:
     
    acl:\n  admin:\n    user:\n      - admin1@localhost\n      - admin2@example.org\n  poweruser:\n    user:\n      - bob@example.org\n      - jane@example.org\n\nshaper_rules:\n  max_user_offline_messages:\n    - 5000: poweruser\n    - 2000: admin\n    - 100\n\nmodules:\n  ...\n  mod_offline:\n    access_max_user_messages: max_user_offline_messages\n  ...\n
    "},{"location":"admin/configuration/modules/#mod_ping","title":"mod_ping","text":"
    This module implements support for XEP-0199: XMPP Ping 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 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 is loaded and stream management is enabled by a client, killing the client connection doesn\u2019t 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:
     
    modules:\n  mod_ping:\n    send_pings: true\n    ping_interval: 4 min\n    timeout_action: kill\n
    "},{"location":"admin/configuration/modules/#mod_pres_counter","title":"mod_pres_counter","text":"
    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:
     
    modules:\n  mod_pres_counter:\n    count: 5\n    interval: 30 secs\n
    "},{"location":"admin/configuration/modules/#mod_privacy","title":"mod_privacy","text":"
    This module implements XEP-0016: Privacy Lists.
     
    Note
     
    Nowadays modern XMPP clients rely on XEP-0191: Blocking Command which is implemented by mod_blocking module. However, you still need mod_privacy loaded in order for mod_blocking to work.
     
    Available options:
     
       
    •  
      cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level default_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_private","title":"mod_private","text":"
    This module adds support for XEP-0049: Private XML Storage.
     
    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\u2019s conferences (XEP-0048: Bookmarks).
     
    It also implements the bookmark conversion described in XEP-0402: PEP Native Bookmarks, see the command bookmarks_to_pep API.
     
    Available options:
     
       
    •  
      cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level default_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_privilege","title":"mod_privilege","text":"
    This module is an implementation of XEP-0356: Privileged Entity. 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 or MAM 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, 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\u2019s roster. The default value is none.
         
        •  
      •  
        get: AccessName    Sets read access to a user\u2019s roster. The default value is none.
         
        •  
      •  
        set: AccessName    Sets write access to a user\u2019s roster. The default value is none.
         
        •  
       
      •  
     
    Example:
     
    modules:\n  mod_privilege:\n    roster:\n      get: all\n    presence:\n      managed_entity: all\n    message:\n      outgoing: all\n
    "},{"location":"admin/configuration/modules/#mod_proxy65","title":"mod_proxy65","text":"
    This module implements XEP-0065: SOCKS5 Bytestreams. 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\u2019s 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. 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 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:
     
    acl:\n  admin:\n    user: admin@example.org\n  proxy_users:\n    server: example.org\n\naccess_rules:\n  proxy65_access:\n    allow: proxy_users\n\nshaper_rules:\n  proxy65_shaper:\n    none: admin\n  proxyrate: proxy_users\n\nshaper:\n  proxyrate: 10240\n\nmodules:\n  mod_proxy65:\n    host: proxy1.example.org\n    name: \"File Transfer Proxy\"\n    ip: 200.150.100.1\n    port: 7778\n    max_connections: 5\n    access: proxy65_access\n    shaper: proxy65_shaper\n    recbuf: 10240\n    sndbuf: 10240\n
    "},{"location":"admin/configuration/modules/#mod_pubsub","title":"mod_pubsub","text":"
    This module offers a service for XEP-0060: Publish-Subscribe. The functionality in mod_pubsub can be extended using plugins. The plugin that implements PEP (XEP-0163: Personal Eventing via Pubsub) is enabled in the default ejabberd configuration file, and it requires 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 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:
       
      force_node_config:\n  ## Avoid buggy clients to make their bookmarks public\n  storage:bookmarks:\n    access_model: whitelist\n
       
      •  
    •  
      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 added in 21.12  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. 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:
       
      modules:\n  ...\n  mod_pubsub:\n    pep_mapping:\n      http://jabber.org/protocol/tune: tune\n  ...\n
       
      •  
    •  
      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:
       
      # This XML representation of vCard:\n#   <vCard xmlns='vcard-temp'>\n#     <FN>Conferences</FN>\n#     <ADR>\n#       <WORK/>\n#       <STREET>Elm Street</STREET>\n#     </ADR>\n#   </vCard>\n#\n# is translated to:\nvcard:\n  fn: Conferences\n  adr:\n    -\n      work: true\n      street: Elm Street\n
       
      •  
     
    Examples:
     
    Example of configuration that uses flat nodes as default, and allows use of flat, hometree and pep nodes:
     
    modules:\n  mod_pubsub:\n    access_createnode: pubsub_createnode\n    max_subscriptions_node: 100\n    default_node_config:\n      notification_type: normal\n      notify_retract: false\n      max_items: 4\n    plugins:\n      - flat\n      - pep\n
     
    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:
     
    modules:\n  mod_pubsub:\n    db_type: sql\n    access_createnode: pubsub_createnode\n    ignore_pep_from_offline: true\n    last_item_cache: false\n    plugins:\n      - flat\n      - pep\n
    "},{"location":"admin/configuration/modules/#mod_push","title":"mod_push","text":"
    This module implements the XMPP server\u2019s part of the push notification solution specified in XEP-0357: Push Notifications. It does not generate, for example, APNS or FCM notifications directly. Instead, it\u2019s 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\u2019s mobile device using platform-dependant backend services such as FCM or APNS.
     
    Available options:
     
       
    •  
      cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level 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\u2019s JID is included with push notifications generated for incoming messages with a body. The default value is false.
       
      •  
    •  
      notify_on: messages | all added in 23.10  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\u2019s set to all, any kind of XMPP stanza will trigger a notification. If unsure, it\u2019s strongly recommended to stick to all, which is the default value.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_push_keepalive","title":"mod_push_keepalive","text":"
    This module tries to keep the stream management session (see 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\u2019t respond to push notifications.
     
    The module depends on 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 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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_register","title":"mod_register","text":"
    This module adds support for XEP-0077: In-Band Registration. 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 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\u2019t 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, ...] added in 21.12  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. 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 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.
       
      •  
    •  
      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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_register_web","title":"mod_register_web","text":"
    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 to register a new account. To enable this feature, configure the top-level captcha_cmd and top-level 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 \u2192 ejabberd_http \u2192 request_handlers, no need to enable in modules. The module depends on mod_register where all the configuration is performed.
     
    The module has no options.
     
    Example:
     
    listen:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /register: mod_register_web\n\nmodules:\n  mod_register: {}\n
    "},{"location":"admin/configuration/modules/#mod_roster","title":"mod_roster","text":"
    This module implements roster management as defined in RFC6121 Section 2. The module also adds support for XEP-0237: Roster Versioning.
     
    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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level 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 or mod_shared_roster_ldap, you must set the value of the option to false.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    •  
      versioning: true | false Enables/disables Roster Versioning. The default value is false.
       
      •  
     
    Example:
     
    modules:\n  mod_roster:\n    versioning: true\n    store_current_id: false\n
    "},{"location":"admin/configuration/modules/#mod_s2s_dialback","title":"mod_s2s_dialback","text":"
    The module adds support for XEP-0220: Server Dialback to provide server identity verification based on DNS.
     
    Warning
     
    DNS-based verification is vulnerable to DNS cache poisoning, 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\u2019s compromised).
     
    Available options:
     
       
    • access: AccessName An access rule that can be used to restrict dialback for some servers. The default value is all.
      •  
     
    Example:
     
    modules:\n  mod_s2s_dialback:\n    access:\n      allow:\n        server: legacy.domain.tld\n        server: invalid-cert.example.org\n      deny: all\n
    "},{"location":"admin/configuration/modules/#mod_service_log","title":"mod_service_log","text":"
    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.
     
    Available options:
     
       
    • loggers: [Domain, ...] A list of servers or connected components to which stanzas will be forwarded.
      •  
     
    Example:
     
    modules:\n  mod_service_log:\n    loggers:\n      - xmpp-server.tld\n      - component.domain.tld\n
    "},{"location":"admin/configuration/modules/#mod_shared_roster","title":"mod_shared_roster","text":"
    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\u2019s members. A group of other vhost can be identified with     groupid@vhost.
       
      •  
     
    This module depends on mod_roster. If not enabled, roster queries will return 503 errors.
     
    Available options:
     
       
    •  
      cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql Same as top-level default_db option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level 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:
     
    Name: club_members\nLabel: Club Members\nDescription: Members from the computer club\nMembers: member1@example.org, member2@example.org, member3@example.org\nDisplayed Groups: club_members\n
     
    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:
     
    First list:\nName: management\nLabel: Management\nDescription: Management\nMembers: manager1@example.org, manager2@example.org\nDisplayed: management, marketing, sales\n\nSecond list:\nName: marketing\nLabel: Marketing\nDescription: Marketing\nMembers: marketeer1@example.org, marketeer2@example.org, marketeer3@example.org\nDisplayed: management, marketing\n\nThird list:\nName: sales\nLabel: Sales\nDescription: Sales\nMembers: salesman1@example.org, salesman2@example.org, salesman3@example.org\nDisplayed: management, sales\n
    "},{"location":"admin/configuration/modules/#mod_shared_roster_ldap","title":"mod_shared_roster_ldap","text":"
    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 section for more     information about them.
       
      •  
     
    Check also the Configuration 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size Same as top-level 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 option, but applied to this module only.
       
      •  
    •  
      ldap_base Same as top-level ldap_base option, but applied to this module only.
       
      •  
    •  
      ldap_deref_aliases Same as top-level ldap_deref_aliases option, but applied to this module only.
       
      •  
    •  
      ldap_encrypt Same as top-level 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 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 \u2192 memberUid; groupOfNames \u2192 member; groupOfUniqueNames \u2192 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 section.
       
      •  
    •  
      ldap_password Same as top-level ldap_password option, but applied to this module only.
       
      •  
    •  
      ldap_port Same as top-level 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 option, but applied to this module only.
       
      •  
    •  
      ldap_servers Same as top-level ldap_servers option, but applied to this module only.
       
      •  
    •  
      ldap_tls_cacertfile Same as top-level ldap_tls_cacertfile option, but applied to this module only.
       
      •  
    •  
      ldap_tls_certfile Same as top-level ldap_tls_certfile option, but applied to this module only.
       
      •  
    •  
      ldap_tls_depth Same as top-level ldap_tls_depth option, but applied to this module only.
       
      •  
    •  
      ldap_tls_verify Same as top-level 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 section.
       
      •  
    •  
      ldap_uids Same as top-level 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 option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_sic","title":"mod_sic","text":"
    This module adds support for XEP-0279: Server IP Check. 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.
    "},{"location":"admin/configuration/modules/#mod_sip","title":"mod_sip","text":"
    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 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 TCP connections. The default value is 2 minutes.
       
      •  
    •  
      flow_timeout_udp: timeout() The options sets a keep-alive timer for SIP outbound 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 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\u2019re 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:
     
    modules:\n  mod_sip:\n    always_record_route: false\n    record_route: \"sip:example.com;lr\"\n    routes:\n      - \"sip:example.com;lr\"\n      - \"sip:sip.example.com;lr\"\n    flow_timeout_udp: 30 sec\n    flow_timeout_tcp: 1 min\n    via:\n      - tls://sip-tls.example.com:5061\n      - tcp://sip-tcp.example.com:5060\n      - udp://sip-udp.example.com:5060\n
    "},{"location":"admin/configuration/modules/#mod_stats","title":"mod_stats","text":"
    This module adds support for XEP-0039: Statistics Gathering. 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.
    "},{"location":"admin/configuration/modules/#mod_stream_mgmt","title":"mod_stream_mgmt","text":"
    This module adds support for XEP-0198: Stream Management. This protocol allows active management of an XML stream between two XMPP entities, including features for stanza acknowledgements and stream resumption.
     
    Available options:
     
       
    •  
      ack_timeout: timeout() A time to wait for stanza acknowledgements. 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 option, but applied to this module only. The default value is 48 hours.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level 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 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\u2019t 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.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_stun_disco","title":"mod_stun_disco","text":"
     added in 20.04
     
    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.
     
    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\u2019s 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\u2019t 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\u2019s 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\u2019s built-in STUN/TURN server and with external servers that support the same REST API For Access To TURN Services. 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\u2019s 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:
       
      services:\n  -\n    host: 203.0.113.3\n    port: 3478\n    type: stun\n    transport: udp\n    restricted: false\n  -\n    host: 203.0.113.3\n    port: 3478\n    type: turn\n    transport: udp\n    restricted: true\n  -\n    host: 2001:db8::3\n    port: 3478\n    type: stun\n    transport: udp\n    restricted: false\n  -\n    host: 2001:db8::3\n    port: 3478\n    type: turn\n    transport: udp\n    restricted: true\n  -\n    host: server.example.com\n    port: 5349\n    type: turns\n    transport: tcp\n    restricted: true\n
       
      •  
    "},{"location":"admin/configuration/modules/#mod_time","title":"mod_time","text":"
    This module adds support for XEP-0202: Entity Time. In other words, the module reports server\u2019s system time.
     
    The module has no options.
    "},{"location":"admin/configuration/modules/#mod_vcard","title":"mod_vcard","text":"
    This module allows end users to store and retrieve their vCard, and to retrieve other users vCards, as defined in XEP-0054: vcard-temp. 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 option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      db_type: mnesia | sql | ldap Same as top-level 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\u2019s 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. 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 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:
       
      # This XML representation of vCard:\n#\n#   <vCard xmlns='vcard-temp'>\n#     <FN>Conferences</FN>\n#     <ADR>\n#       <WORK/>\n#       <STREET>Elm Street</STREET>\n#     </ADR>\n#   </vCard>\n#\n# is translated to:\n#\nvcard:\n  fn: Conferences\n  adr:\n    -\n      work: true\n      street: Elm Street\n
       
      •  
     
    Available options for ldap backend:
     
       
    •  
      ldap_backups Same as top-level ldap_backups option, but applied to this module only.
       
      •  
    •  
      ldap_base Same as top-level ldap_base option, but applied to this module only.
       
      •  
    •  
      ldap_deref_aliases Same as top-level ldap_deref_aliases option, but applied to this module only.
       
      •  
    •  
      ldap_encrypt Same as top-level ldap_encrypt option, but applied to this module only.
       
      •  
    •  
      ldap_filter Same as top-level ldap_filter option, but applied to this module only.
       
      •  
    •  
      ldap_password Same as top-level ldap_password option, but applied to this module only.
       
      •  
    •  
      ldap_port Same as top-level ldap_port option, but applied to this module only.
       
      •  
    •  
      ldap_rootdn Same as top-level 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:
       
      User: \"%u\"\n\"Full Name\": displayName\n\"Given Name\": givenName\n\"Middle Name\": initials\n\"Family Name\": sn\nNickname: \"%u\"\nBirthday: birthDay\nCountry: c\nCity: l\nEmail: mail\n\"Organization Name\": o\n\"Organization Unit\": ou\n
       
      •  
    •  
      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:
       
      \"Full Name\": FN\n\"Given Name\": FIRST\n\"Middle Name\": MIDDLE\n\"Family Name\": LAST\n\"Nickname\": NICKNAME\n\"Birthday\": BDAY\n\"Country\": CTRY\n\"City\": LOCALITY\n\"Email\": EMAIL\n\"Organization Name\": ORGNAME\n\"Organization Unit\": ORGUNIT\n
       
      •  
    •  
      ldap_servers Same as top-level ldap_servers option, but applied to this module only.
       
      •  
    •  
      ldap_tls_cacertfile Same as top-level ldap_tls_cacertfile option, but applied to this module only.
       
      •  
    •  
      ldap_tls_certfile Same as top-level ldap_tls_certfile option, but applied to this module only.
       
      •  
    •  
      ldap_tls_depth Same as top-level ldap_tls_depth option, but applied to this module only.
       
      •  
    •  
      ldap_tls_verify Same as top-level ldap_tls_verify option, but applied to this module only.
       
      •  
    •  
      ldap_uids Same as top-level 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. 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:
       
      NICKNAME: {\"%u\": []}\nFN: {\"%s\": [displayName]}\nLAST: {\"%s\": [sn]}\nFIRST: {\"%s\": [givenName]}\nMIDDLE: {\"%s\": [initials]}\nORGNAME: {\"%s\": [o]}\nORGUNIT: {\"%s\": [ou]}\nCTRY: {\"%s\": [c]}\nLOCALITY: {\"%s\": [l]}\nSTREET: {\"%s\": [street]}\nREGION: {\"%s\": [st]}\nPCODE: {\"%s\": [postalCode]}\nTITLE: {\"%s\": [title]}\nURL: {\"%s\": [labeleduri]}\nDESC: {\"%s\": [description]}\nTEL: {\"%s\": [telephoneNumber]}\nEMAIL: {\"%s\": [mail]}\nBDAY: {\"%s\": [birthDay]}\nROLE: {\"%s\": [employeeType]}\nPHOTO: {\"%s\": [jpegPhoto]}\n
       
      •  
     
    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.
      •  
    "},{"location":"admin/configuration/modules/#mod_vcard_xupdate","title":"mod_vcard_xupdate","text":"
    The user\u2019s client can store an avatar in the user vCard. The vCard-Based Avatars protocol (XEP-0153) 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 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\u2019t want to set use_cache to false.
     
    The module depends on mod_vcard.
     
    Note
     
    Nowadays XEP-0153 is used mostly as \"read-only\", i.e. modern clients don\u2019t publish their avatars inside vCards. Thus in the majority of cases the module is only used along with mod_avatar for providing backward compatibility.
     
    Available options:
     
       
    •  
      cache_life_time: timeout() Same as top-level cache_life_time option, but applied to this module only.
       
      •  
    •  
      cache_missed: true | false Same as top-level cache_missed option, but applied to this module only.
       
      •  
    •  
      cache_size: pos_integer() | infinity Same as top-level cache_size option, but applied to this module only.
       
      •  
    •  
      use_cache: true | false Same as top-level use_cache option, but applied to this module only.
       
      •  
    "},{"location":"admin/configuration/modules/#mod_version","title":"mod_version","text":"
    This module implements XEP-0092: Software Version. Consequently, it answers ejabberd\u2019s version when queried.
     
    Available options:
     
       
    • show_os: true | false Should the operating system be revealed or not. The default value is true.
      •  
    "},{"location":"admin/configuration/toplevel/","title":"Top-Level Options","text":"
    This section describes top level options of ejabberd 24.02.  If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the Archive. The options that changed in this version are marked with \ud83d\udfe4.
    "},{"location":"admin/configuration/toplevel/#access_rules","title":"access_rules","text":"
    {AccessName: {allow|deny: ACLRules|ACLName}} 
     
    This option defines 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 option). There are no access rules defined by default.
     
    Example:
     
    access_rules:\n  configure:\n    allow: admin\n  something:\n    deny: someone\n    allow: all\n  s2s_banned:\n    deny: problematic_hosts\n    deny: banned_forever\n    deny:\n      ip: 222.111.222.111/32\n    deny:\n      ip: 111.222.111.222/32\n    allow: all\n  xmlrpc_access:\n    allow:\n      user: peter@example.com\n    allow:\n      user: ivone@example.com\n    allow:\n      user: bot@example.com\n      ip: 10.0.0.0/24\n
    "},{"location":"admin/configuration/toplevel/#acl","title":"acl","text":"
    {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 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.
       
      •  
    "},{"location":"admin/configuration/toplevel/#acme","title":"acme","text":"
    Options 
     
    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     https://acme-v02.api.letsencrypt.org/directory - the directory URL     of Let\u2019s 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\u2019s 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:
     
    acme:\n  ca_url: https://acme-v02.api.letsencrypt.org/directory\n  contact:\n    - mailto:admin@domain.tld\n    - mailto:bot@domain.tld\n  auto: true\n  cert_type: rsa\n
    "},{"location":"admin/configuration/toplevel/#allow_contrib_modules","title":"allow_contrib_modules","text":"
    true | false 
     
    Whether to allow installation of third-party modules or not. See ejabberd-contrib documentation section. The default value is true.
    "},{"location":"admin/configuration/toplevel/#allow_multiple_connections","title":"allow_multiple_connections","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#anonymous_protocol","title":"anonymous_protocol","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#api_permissions","title":"api_permissions","text":"
    [Permission, ...] 
     
    Define the permissions for API access. Please consult the ejabberd Docs web \u2192 For Developers \u2192 ejabberd ReST API \u2192 API Permissions.
    "},{"location":"admin/configuration/toplevel/#append_host_config","title":"append_host_config","text":"
    {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.
    "},{"location":"admin/configuration/toplevel/#auth_cache_life_time","title":"auth_cache_life_time","text":"
    timeout() 
     
    Same as cache_life_time, but applied to authentication cache only. If not set, the value from cache_life_time will be used.
    "},{"location":"admin/configuration/toplevel/#auth_cache_missed","title":"auth_cache_missed","text":"
    true | false 
     
    Same as cache_missed, but applied to authentication cache only. If not set, the value from cache_missed will be used.
    "},{"location":"admin/configuration/toplevel/#auth_cache_size","title":"auth_cache_size","text":"
    pos_integer() | infinity 
     
    Same as cache_size, but applied to authentication cache only. If not set, the value from cache_size will be used.
    "},{"location":"admin/configuration/toplevel/#auth_external_user_exists_check","title":"auth_external_user_exists_check","text":"
    true | false 
     
     added in 23.10
     
    Supplement check for user existence based on mod_last data, for authentication methods that don\u2019t 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.
    "},{"location":"admin/configuration/toplevel/#auth_method","title":"auth_method","text":"
    [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].
    "},{"location":"admin/configuration/toplevel/#auth_opts","title":"auth_opts","text":"
    [Option, ...] 
     
    This is used by the contributed module ejabberd_auth_http that can be installed from the ejabberd-contrib Git repository. Please refer to that module\u2019s README file for details.
    "},{"location":"admin/configuration/toplevel/#auth_password_format","title":"auth_password_format","text":"
    plain | scram 
     
     improved in 20.01
     
    The option defines in what format the users passwords are stored, plain text or in 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 option.
       
      •  
     
    The default value is plain.
    "},{"location":"admin/configuration/toplevel/#auth_scram_hash","title":"auth_scram_hash","text":"
    sha | sha256 | sha512 
     
    Hash algorithm that should be used to store password in SCRAM format. You shouldn\u2019t 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.
    "},{"location":"admin/configuration/toplevel/#auth_use_cache","title":"auth_use_cache","text":"
    true | false 
     
    Same as use_cache, but applied to authentication cache only. If not set, the value from use_cache will be used.
    "},{"location":"admin/configuration/toplevel/#c2s_cafile","title":"c2s_cafile","text":"
    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 to specify this option per-vhost.
     
    To set a specific file per listener, use the listener\u2019s cafile option. Please notice that c2s_cafile overrides the listener\u2019s cafile option.
    "},{"location":"admin/configuration/toplevel/#c2s_ciphers","title":"c2s_ciphers","text":"
    [Cipher, ...] 
     
    A list of OpenSSL ciphers to use for c2s connections. The default value is shown in the example below:
     
    Example:
     
    c2s_ciphers:\n  - HIGH\n  - \"!aNULL\"\n  - \"!eNULL\"\n  - \"!3DES\"\n  - \"@STRENGTH\"\n
    "},{"location":"admin/configuration/toplevel/#c2s_dhfile","title":"c2s_dhfile","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#c2s_protocol_options","title":"c2s_protocol_options","text":"
    [Option, ...] 
     
    List of general SSL options to use for c2s connections. These map to OpenSSL\u2019s set_options(). The default value is shown in the example below:
     
    Example:
     
    c2s_protocol_options:\n  - no_sslv3\n  - cipher_server_preference\n  - no_compression\n
    "},{"location":"admin/configuration/toplevel/#c2s_tls_compression","title":"c2s_tls_compression","text":"
    true | false 
     
    Whether to enable or disable TLS compression for c2s connections. The default value is false.
    "},{"location":"admin/configuration/toplevel/#ca_file","title":"ca_file","text":"
    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 option.
    "},{"location":"admin/configuration/toplevel/#cache_life_time","title":"cache_life_time","text":"
    timeout() 
     
    The time of a cached item to keep in cache. Once it\u2019s 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, oauth_cache_life_time, router_cache_life_time, and sm_cache_life_time.
    "},{"location":"admin/configuration/toplevel/#cache_missed","title":"cache_missed","text":"
    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). Usually you don\u2019t 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, oauth_cache_missed, router_cache_missed, and sm_cache_missed.
    "},{"location":"admin/configuration/toplevel/#cache_size","title":"cache_size","text":"
    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\u2019s 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, oauth_cache_size, router_cache_size, and sm_cache_size.
    "},{"location":"admin/configuration/toplevel/#captcha_cmd","title":"captcha_cmd","text":"
    Path | ModuleName 
     
     improved in 23.01
     
    Full path to a script that generates 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\u2019s 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:
     
    captcha_cmd: /opt/ejabberd-@VERSION@/lib/ejabberd-@SEMVER@/priv/bin/captcha.sh\n
    "},{"location":"admin/configuration/toplevel/#captcha_host","title":"captcha_host","text":"
    String 
     
    Deprecated. Use captcha_url instead.
    "},{"location":"admin/configuration/toplevel/#captcha_limit","title":"captcha_limit","text":"
    pos_integer() | infinity 
     
    Maximum number of 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.
    "},{"location":"admin/configuration/toplevel/#captcha_url","title":"captcha_url","text":"
    URL | auto | undefined 
     
     improved in 23.04
     
    An URL where 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. The default value is auto.
    "},{"location":"admin/configuration/toplevel/#certfiles","title":"certfiles","text":"
    [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\u2019s Encrypt certificates for your domain \"domain.tld\", the configuration will look like this:
     
    certfiles:\n  - /etc/letsencrypt/live/domain.tld/fullchain.pem\n  - /etc/letsencrypt/live/domain.tld/privkey.pem\n
    "},{"location":"admin/configuration/toplevel/#cluster_backend","title":"cluster_backend","text":"
    Backend 
     
    A database backend to use for storing information about cluster. The only available value so far is mnesia.
    "},{"location":"admin/configuration/toplevel/#cluster_nodes","title":"cluster_nodes","text":"
    [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.
    "},{"location":"admin/configuration/toplevel/#default_db","title":"default_db","text":"
    mnesia | sql 
     
    Default persistent storage for ejabberd. Modules and other components (e.g. authentication) may have its own value. The default value is mnesia.
    "},{"location":"admin/configuration/toplevel/#default_ram_db","title":"default_ram_db","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#define_macro","title":"define_macro","text":"
    {MacroName: MacroValue} 
     
    Defines a macro. The value can be any valid arbitrary YAML value. For convenience, it\u2019s 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:
     
    define_macro:\n  DEBUG: debug\n  LOG_LEVEL: DEBUG\n  USERBOB:\n    user: bob@localhost\n\nloglevel: LOG_LEVEL\n\nacl:\n  admin: USERBOB\n
    "},{"location":"admin/configuration/toplevel/#disable_sasl_mechanisms","title":"disable_sasl_mechanisms","text":"
    [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.
    "},{"location":"admin/configuration/toplevel/#disable_sasl_scram_downgrade_protection","title":"disable_sasl_scram_downgrade_protection","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#domain_balancing","title":"domain_balancing","text":"
    {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\u2019s to attribute;     source - by the full JID of the packet\u2019s from attribute;     bare_destination - by the bare JID (without resource) of the     packet\u2019s to attribute; bare_source - by the bare JID (without     resource) of the packet\u2019s from attribute is used. The default     value is random.
       
      •  
     
    Example:
     
    domain_balancing:\n  component.domain.tld:\n    type: destination\n    component_number: 5\n  transport.example.org:\n    type: bare_source\n
    "},{"location":"admin/configuration/toplevel/#ext_api_headers","title":"ext_api_headers","text":"
    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: \"\".
    "},{"location":"admin/configuration/toplevel/#ext_api_http_pool_size","title":"ext_api_http_pool_size","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#ext_api_path_oauth","title":"ext_api_path_oauth","text":"
    Path 
     
    Define the base URI path when performing OAUTH ReST requests. The default value is: \"/oauth\".
    "},{"location":"admin/configuration/toplevel/#ext_api_url","title":"ext_api_url","text":"
    URL 
     
    Define the base URI when performing ReST requests. The default value is: \"http://localhost/api\".
    "},{"location":"admin/configuration/toplevel/#extauth_pool_name","title":"extauth_pool_name","text":"
    Name 
     
    Define the pool name appendix, so the full pool name will be extauth_pool_Name. The default value is the hostname.
    "},{"location":"admin/configuration/toplevel/#extauth_pool_size","title":"extauth_pool_size","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#extauth_program","title":"extauth_program","text":"
    Path 
     
    Indicate in this option the full path to the external authentication script. The script must be executable by ejabberd.
    "},{"location":"admin/configuration/toplevel/#fqdn","title":"fqdn","text":"
    Domain 
     
    A fully qualified domain name that will be used in SASL DIGEST-MD5 authentication. The default is detected automatically.
    "},{"location":"admin/configuration/toplevel/#hide_sensitive_log_data","title":"hide_sensitive_log_data","text":"
    true | false 
     
    A privacy option to not log sensitive data (mostly IP addresses). The default value is false for backward compatibility.
    "},{"location":"admin/configuration/toplevel/#host_config","title":"host_config","text":"
    {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:
     
    hosts:\n  - domain.tld\n  - example.org\n\nauth_method:\n  - sql\n\nhost_config:\n  domain.tld:\n    auth_method:\n      - ldap\n
    "},{"location":"admin/configuration/toplevel/#hosts","title":"hosts","text":"
    [Domain1, Domain2, ...] 
     
    The option defines a list containing one or more domains that ejabberd will serve. This is a mandatory option.
    "},{"location":"admin/configuration/toplevel/#include_config_file","title":"include_config_file","text":"
    [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.
       
      •  
    "},{"location":"admin/configuration/toplevel/#install_contrib_modules","title":"install_contrib_modules","text":"
    [Module, ...] 
     
     added in 23.10
     
    Modules to install from ejabberd-contrib at start time. The default value is an empty list of modules: [].
    "},{"location":"admin/configuration/toplevel/#jwt_auth_only_rule","title":"jwt_auth_only_rule","text":"
    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, \u2026), users that match this rule can only use JWT. The default value is none.
    "},{"location":"admin/configuration/toplevel/#jwt_jid_field","title":"jwt_jid_field","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#jwt_key","title":"jwt_key","text":"
    FilePath 
     
    Path to the file that contains the JWK Key. The default value is undefined.
    "},{"location":"admin/configuration/toplevel/#language","title":"language","text":"
    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\".
    "},{"location":"admin/configuration/toplevel/#ldap_backups","title":"ldap_backups","text":"
    [Host, ...] 
     
    A list of IP addresses or DNS names of LDAP backup servers. When no servers listed in 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\u2019t 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.
    "},{"location":"admin/configuration/toplevel/#ldap_base","title":"ldap_base","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#ldap_deref_aliases","title":"ldap_deref_aliases","text":"
    never | always | finding | searching 
     
    Whether to dereference aliases or not. The default value is never.
    "},{"location":"admin/configuration/toplevel/#ldap_dn_filter","title":"ldap_dn_filter","text":"
    {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\u2019s 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 option if possible.
     
    Example:
     
    ldap_dn_filter:\n  \"(&(name=%s)(owner=%D)(user=%u@%d))\": [sn]\n
    "},{"location":"admin/configuration/toplevel/#ldap_encrypt","title":"ldap_encrypt","text":"
    tls | none 
     
    Whether to encrypt LDAP connection using TLS or not. The default value is none. NOTE: STARTTLS encryption is not supported.
    "},{"location":"admin/configuration/toplevel/#ldap_filter","title":"ldap_filter","text":"
    Filter 
     
    An LDAP filter as defined in RFC4515. There is no default value. Example: \"(&(objectClass=shadowAccount)(memberOf=XMPP Users))\". NOTE: don\u2019t forget to close brackets and don\u2019t use superfluous whitespaces. Also you must not use \"uid\" attribute in the filter because this attribute will be appended to the filter automatically.
    "},{"location":"admin/configuration/toplevel/#ldap_password","title":"ldap_password","text":"
    Password 
     
    Bind password. The default value is an empty string.
    "},{"location":"admin/configuration/toplevel/#ldap_port","title":"ldap_port","text":"
    1..65535 
     
    Port to connect to your LDAP server. The default port is 389 if encryption is disabled and 636 if encryption is enabled.
    "},{"location":"admin/configuration/toplevel/#ldap_rootdn","title":"ldap_rootdn","text":"
    RootDN 
     
    Bind Distinguished Name. The default value is an empty string, which means \"anonymous connection\".
    "},{"location":"admin/configuration/toplevel/#ldap_servers","title":"ldap_servers","text":"
    [Host, ...] 
     
    A list of IP addresses or DNS names of your LDAP servers. The default value is [localhost].
    "},{"location":"admin/configuration/toplevel/#ldap_tls_cacertfile","title":"ldap_tls_cacertfile","text":"
    Path 
     
    A path to a file containing PEM encoded CA certificates. This option is required when TLS verification is enabled.
    "},{"location":"admin/configuration/toplevel/#ldap_tls_certfile","title":"ldap_tls_certfile","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#ldap_tls_depth","title":"ldap_tls_depth","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#ldap_tls_verify","title":"ldap_tls_verify","text":"
    false | soft | hard 
     
    This option specifies whether to verify LDAP server certificate or not when TLS is enabled. When hard is set, ejabberd doesn\u2019t 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.
    "},{"location":"admin/configuration/toplevel/#ldap_uids","title":"ldap_uids","text":"
    [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\u2019s part of the JID and AttrFormat must contain one and only one pattern variable \"%u\" which will be replaced by the user\u2019s part of the JID. For example, \"%u@example.org\". If the value is in the form of [Attr] then AttrFormat is assumed to be \"%u\".
    "},{"location":"admin/configuration/toplevel/#listen","title":"listen","text":"
    [Options, ...] 
     
    The option for listeners configuration. See the Listen Modules section for details.
    "},{"location":"admin/configuration/toplevel/#log_burst_limit_count","title":"log_burst_limit_count","text":"
    Number 
     
     added in 22.10
     
    The number of messages to accept in log_burst_limit_window_time period before starting to drop them. Default 500
    "},{"location":"admin/configuration/toplevel/#log_burst_limit_window_time","title":"log_burst_limit_window_time","text":"
    Number 
     
     added in 22.10
     
    The time period to rate-limit log messages by. Defaults to 1 second.
    "},{"location":"admin/configuration/toplevel/#log_modules_fully","title":"log_modules_fully","text":"
    [Module, ...] 
     
     added in 23.01
     
    List of modules that will log everything independently from the general loglevel option.
    "},{"location":"admin/configuration/toplevel/#log_rotate_count","title":"log_rotate_count","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#log_rotate_size","title":"log_rotate_size","text":"
    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).
    "},{"location":"admin/configuration/toplevel/#loglevel","title":"loglevel","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#max_fsm_queue","title":"max_fsm_queue","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#modules","title":"modules","text":"
    {Module: Options} 
     
    The option for modules configuration. See Modules section for details.
    "},{"location":"admin/configuration/toplevel/#negotiation_timeout","title":"negotiation_timeout","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#net_ticktime","title":"net_ticktime","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#new_sql_schema","title":"new_sql_schema","text":"
    true | false 
     
    Whether to use new SQL schema. All schemas are located at https://github.com/processone/ejabberd/tree/24.02/sql. 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.
    "},{"location":"admin/configuration/toplevel/#oauth_access","title":"oauth_access","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#oauth_cache_life_time","title":"oauth_cache_life_time","text":"
    timeout() 
     
    Same as cache_life_time, but applied to OAuth cache only. If not set, the value from cache_life_time will be used.
    "},{"location":"admin/configuration/toplevel/#oauth_cache_missed","title":"oauth_cache_missed","text":"
    true | false 
     
    Same as cache_missed, but applied to OAuth cache only. If not set, the value from cache_missed will be used.
    "},{"location":"admin/configuration/toplevel/#oauth_cache_rest_failure_life_time","title":"oauth_cache_rest_failure_life_time","text":"
    timeout() 
     
     added in 21.01
     
    The time that a failure in OAuth ReST is cached. The default value is infinity.
    "},{"location":"admin/configuration/toplevel/#oauth_cache_size","title":"oauth_cache_size","text":"
    pos_integer() | infinity 
     
    Same as cache_size, but applied to OAuth cache only. If not set, the value from cache_size will be used.
    "},{"location":"admin/configuration/toplevel/#oauth_client_id_check","title":"oauth_client_id_check","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#oauth_db_type","title":"oauth_db_type","text":"
    mnesia | sql 
     
    Database backend to use for OAuth authentication. The default value is picked from default_db option, or if it\u2019s not set, mnesia will be used.
    "},{"location":"admin/configuration/toplevel/#oauth_expire","title":"oauth_expire","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#oauth_use_cache","title":"oauth_use_cache","text":"
    true | false 
     
    Same as use_cache, but applied to OAuth cache only. If not set, the value from use_cache will be used.
    "},{"location":"admin/configuration/toplevel/#oom_killer","title":"oom_killer","text":"
    true | false 
     
    Enable or disable OOM (out-of-memory) killer. When system memory raises above the limit defined in 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.
    "},{"location":"admin/configuration/toplevel/#oom_queue","title":"oom_queue","text":"
    Size 
     
    Trigger OOM killer when some of the running Erlang processes have messages queue above this Size. Note that such processes won\u2019t be killed if oom_killer option is set to false or if oom_watermark is not reached yet.
    "},{"location":"admin/configuration/toplevel/#oom_watermark","title":"oom_watermark","text":"
    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 option). Later, when memory drops below this Percent, OOM killer is deactivated. The default value is 80 percents.
    "},{"location":"admin/configuration/toplevel/#outgoing_s2s_families","title":"outgoing_s2s_families","text":"
    [ipv6 | ipv4, ...] 
     
     changed in 23.01
     
    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 and Erlang/OTP 22, or newer versions of them.
    "},{"location":"admin/configuration/toplevel/#outgoing_s2s_ipv4_address","title":"outgoing_s2s_ipv4_address","text":"
    Address 
     
     added in 20.12
     
    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.
    "},{"location":"admin/configuration/toplevel/#outgoing_s2s_ipv6_address","title":"outgoing_s2s_ipv6_address","text":"
    Address 
     
     added in 20.12
     
    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.
    "},{"location":"admin/configuration/toplevel/#outgoing_s2s_port","title":"outgoing_s2s_port","text":"
    1..65535 
     
    A port number to use for outgoing s2s connections when the target server doesn\u2019t have an SRV record. The default value is 5269.
    "},{"location":"admin/configuration/toplevel/#outgoing_s2s_timeout","title":"outgoing_s2s_timeout","text":"
    timeout() 
     
    The timeout in seconds for outgoing S2S connection attempts. The default value is 10 seconds.
    "},{"location":"admin/configuration/toplevel/#pam_service","title":"pam_service","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#pam_userinfotype","title":"pam_userinfotype","text":"
    username | jid 
     
    This option defines what type of information about the user ejabberd provides to the PAM service: only the username, or the user\u2019s JID. Default is username.
    "},{"location":"admin/configuration/toplevel/#pgsql_users_number_estimate","title":"pgsql_users_number_estimate","text":"
    true | false 
     
    Whether to use PostgreSQL estimation when counting registered users. The default value is false.
    "},{"location":"admin/configuration/toplevel/#queue_dir","title":"queue_dir","text":"
    Directory 
     
    If queue_type option is set to file, use this Directory to store file queues. The default is to keep queues inside Mnesia directory.
    "},{"location":"admin/configuration/toplevel/#queue_type","title":"queue_type","text":"
    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 option where file queues will be placed. The default value is ram.
    "},{"location":"admin/configuration/toplevel/#redis_connect_timeout","title":"redis_connect_timeout","text":"
    timeout() 
     
    A timeout to wait for the connection to be re-established to the Redis server. The default is 1 second.
    "},{"location":"admin/configuration/toplevel/#redis_db","title":"redis_db","text":"
    Number 
     
    Redis database number. The default is 0.
    "},{"location":"admin/configuration/toplevel/#redis_password","title":"redis_password","text":"
    Password 
     
    The password to the Redis server. The default is an empty string, i.e. no password.
    "},{"location":"admin/configuration/toplevel/#redis_pool_size","title":"redis_pool_size","text":"
    Number 
     
    The number of simultaneous connections to the Redis server. The default value is 10.
    "},{"location":"admin/configuration/toplevel/#redis_port","title":"redis_port","text":"
    1..65535 
     
    The port where the Redis server is accepting connections. The default is 6379.
    "},{"location":"admin/configuration/toplevel/#redis_queue_type","title":"redis_queue_type","text":"
    ram | file 
     
    The type of request queue for the Redis server. See description of queue_type option for the explanation. The default value is the value defined in queue_type or ram if the latter is not set.
    "},{"location":"admin/configuration/toplevel/#redis_server","title":"redis_server","text":"
    Hostname 
     
    A hostname or an IP address of the Redis server. The default is localhost.
    "},{"location":"admin/configuration/toplevel/#registration_timeout","title":"registration_timeout","text":"
    timeout() 
     
    This is a global option for module 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.
    "},{"location":"admin/configuration/toplevel/#resource_conflict","title":"resource_conflict","text":"
    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. 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.
    "},{"location":"admin/configuration/toplevel/#router_cache_life_time","title":"router_cache_life_time","text":"
    timeout() 
     
    Same as cache_life_time, but applied to routing table cache only. If not set, the value from cache_life_time will be used.
    "},{"location":"admin/configuration/toplevel/#router_cache_missed","title":"router_cache_missed","text":"
    true | false 
     
    Same as cache_missed, but applied to routing table cache only. If not set, the value from cache_missed will be used.
    "},{"location":"admin/configuration/toplevel/#router_cache_size","title":"router_cache_size","text":"
    pos_integer() | infinity 
     
    Same as cache_size, but applied to routing table cache only. If not set, the value from cache_size will be used.
    "},{"location":"admin/configuration/toplevel/#router_db_type","title":"router_db_type","text":"
    mnesia | redis | sql 
     
    Database backend to use for routing information. The default value is picked from default_ram_db option, or if it\u2019s not set, mnesia will be used.
    "},{"location":"admin/configuration/toplevel/#router_use_cache","title":"router_use_cache","text":"
    true | false 
     
    Same as use_cache, but applied to routing table cache only. If not set, the value from use_cache will be used.
    "},{"location":"admin/configuration/toplevel/#rpc_timeout","title":"rpc_timeout","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#s2s_access","title":"s2s_access","text":"
    Access 
     
    This Access Rule 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.
    "},{"location":"admin/configuration/toplevel/#s2s_cafile","title":"s2s_cafile","text":"
    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 will be used.
     
    You can use host_config to specify this option per-vhost.
    "},{"location":"admin/configuration/toplevel/#s2s_ciphers","title":"s2s_ciphers","text":"
    [Cipher, ...] 
     
    A list of OpenSSL ciphers to use for s2s connections. The default value is shown in the example below:
     
    Example:
     
    s2s_ciphers:\n  - HIGH\n  - \"!aNULL\"\n  - \"!eNULL\"\n  - \"!3DES\"\n  - \"@STRENGTH\"\n
    "},{"location":"admin/configuration/toplevel/#s2s_dhfile","title":"s2s_dhfile","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#s2s_dns_retries","title":"s2s_dns_retries","text":"
    Number 
     
    DNS resolving retries. The default value is 2.
    "},{"location":"admin/configuration/toplevel/#s2s_dns_timeout","title":"s2s_dns_timeout","text":"
    timeout() 
     
    The timeout for DNS resolving. The default value is 10 seconds.
    "},{"location":"admin/configuration/toplevel/#s2s_max_retry_delay","title":"s2s_max_retry_delay","text":"
    timeout() 
     
    The maximum allowed delay for s2s connection retry to connect after a failed connection attempt. The default value is 300 seconds (5 minutes).
    "},{"location":"admin/configuration/toplevel/#s2s_protocol_options","title":"s2s_protocol_options","text":"
    [Option, ...] 
     
    List of general SSL options to use for s2s connections. These map to OpenSSL\u2019s set_options(). The default value is shown in the example below:
     
    Example:
     
    s2s_protocol_options:\n  - no_sslv3\n  - cipher_server_preference\n  - no_compression\n
    "},{"location":"admin/configuration/toplevel/#s2s_queue_type","title":"s2s_queue_type","text":"
    ram | file 
     
    The type of a queue for s2s packets. See description of queue_type option for the explanation. The default value is the value defined in queue_type or ram if the latter is not set.
    "},{"location":"admin/configuration/toplevel/#s2s_timeout","title":"s2s_timeout","text":"
    timeout() 
     
    A time to wait before closing an idle s2s connection. The default value is 1 hour.
    "},{"location":"admin/configuration/toplevel/#s2s_tls_compression","title":"s2s_tls_compression","text":"
    true | false 
     
    Whether to enable or disable TLS compression for s2s connections. The default value is false.
    "},{"location":"admin/configuration/toplevel/#s2s_use_starttls","title":"s2s_use_starttls","text":"
    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).
    "},{"location":"admin/configuration/toplevel/#s2s_zlib","title":"s2s_zlib","text":"
    true | false 
     
    Whether to use zlib compression (as defined in XEP-0138) or not. The default value is false. WARNING: this type of compression is nowadays considered insecure.
    "},{"location":"admin/configuration/toplevel/#shaper","title":"shaper","text":"
    {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 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:
     
    shaper:\n  normal: 1000\n  fast: 50000\n
    "},{"location":"admin/configuration/toplevel/#shaper_rules","title":"shaper_rules","text":"
    {ShaperRuleName: {Number|ShaperName: ACLRule|ACLName}} 
     
    An entry allowing to declaring shaper to use for matching user/hosts. Semantics is similar to access_rules option, the only difference is that instead using allow or deny, a name of a shaper (defined in shaper option) or a positive number should be used.
     
    Example:
     
    shaper_rules:\n  connections_limit:\n    10:\n      user: peter@example.com\n    100: admin\n    5: all\n  download_speed:\n    fast: admin\n    slow: anonymous_users\n    normal: all\n  log_days: 30\n
    "},{"location":"admin/configuration/toplevel/#sm_cache_life_time","title":"sm_cache_life_time","text":"
    timeout() 
     
    Same as cache_life_time, but applied to client sessions table cache only. If not set, the value from cache_life_time will be used.
    "},{"location":"admin/configuration/toplevel/#sm_cache_missed","title":"sm_cache_missed","text":"
    true | false 
     
    Same as cache_missed, but applied to client sessions table cache only. If not set, the value from cache_missed will be used.
    "},{"location":"admin/configuration/toplevel/#sm_cache_size","title":"sm_cache_size","text":"
    pos_integer() | infinity 
     
    Same as cache_size, but applied to client sessions table cache only. If not set, the value from cache_size will be used.
    "},{"location":"admin/configuration/toplevel/#sm_db_type","title":"sm_db_type","text":"
    mnesia | redis | sql 
     
    Database backend to use for client sessions information. The default value is picked from default_ram_db option, or if it\u2019s not set, mnesia will be used.
    "},{"location":"admin/configuration/toplevel/#sm_use_cache","title":"sm_use_cache","text":"
    true | false 
     
    Same as use_cache, but applied to client sessions table cache only. If not set, the value from use_cache will be used.
    "},{"location":"admin/configuration/toplevel/#sql_connect_timeout","title":"sql_connect_timeout","text":"
    timeout() 
     
    A time to wait for connection to an SQL server to be established. The default value is 5 seconds.
    "},{"location":"admin/configuration/toplevel/#sql_database","title":"sql_database","text":"
    Database 
     
    An SQL database name. For SQLite this must be a full path to a database file. The default value is ejabberd.
    "},{"location":"admin/configuration/toplevel/#sql_flags","title":"sql_flags \ud83d\udfe4","text":"
    [mysql_alternative_upsert] 
     
     added in 24.02
     
    This option accepts a list of SQL flags, and is empty by default. mysql_alternative_upsert forces the alternative upsert implementation in MySQL.
    "},{"location":"admin/configuration/toplevel/#sql_keepalive_interval","title":"sql_keepalive_interval","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#sql_odbc_driver","title":"sql_odbc_driver","text":"
    Path 
     
     added in 20.12
     
    Path to the ODBC driver to use to connect to a Microsoft SQL Server database. This option only applies if the sql_type option is set to mssql and sql_server is not an ODBC connection string. The default value is: libtdsodbc.so
    "},{"location":"admin/configuration/toplevel/#sql_password","title":"sql_password","text":"
    Password 
     
    The password for SQL authentication. The default is empty string.
    "},{"location":"admin/configuration/toplevel/#sql_pool_size","title":"sql_pool_size","text":"
    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\u2019s not recommended to change it due to potential race conditions.
    "},{"location":"admin/configuration/toplevel/#sql_port","title":"sql_port","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#sql_prepared_statements","title":"sql_prepared_statements","text":"
    true | false 
     
     added in 20.01
     
    This option is true by default, and is useful to disable prepared statements. The option is valid for PostgreSQL and MySQL.
    "},{"location":"admin/configuration/toplevel/#sql_query_timeout","title":"sql_query_timeout","text":"
    timeout() 
     
    A time to wait for an SQL query response. The default value is 60 seconds.
    "},{"location":"admin/configuration/toplevel/#sql_queue_type","title":"sql_queue_type","text":"
    ram | file 
     
    The type of a request queue for the SQL server. See description of queue_type option for the explanation. The default value is the value defined in queue_type or ram if the latter is not set.
    "},{"location":"admin/configuration/toplevel/#sql_server","title":"sql_server","text":"
    Host 
     
     improved in 23.04
     
    The hostname or IP address of the SQL server. For sql_type mssql or odbc this can also be an ODBC connection string. The default value is localhost.
    "},{"location":"admin/configuration/toplevel/#sql_ssl","title":"sql_ssl","text":"
    true | false 
     
     improved in 20.03
     
    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.
    "},{"location":"admin/configuration/toplevel/#sql_ssl_cafile","title":"sql_ssl_cafile","text":"
    Path 
     
    A path to a file with CA root certificates that will be used to verify SQL connections. Implies sql_ssl and 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.
    "},{"location":"admin/configuration/toplevel/#sql_ssl_certfile","title":"sql_ssl_certfile","text":"
    Path 
     
    A path to a certificate file that will be used for SSL connections to the SQL server. Implies sql_ssl option is set to true. There is no default which means ejabberd won\u2019t provide a client certificate to the SQL server. This option has no effect for MS SQL.
    "},{"location":"admin/configuration/toplevel/#sql_ssl_verify","title":"sql_ssl_verify","text":"
    true | false 
     
    Whether to verify SSL connection to the SQL server against CA root certificates defined in sql_ssl_cafile option. Implies sql_ssl option is set to true. This option has no effect for MS SQL. The default value is false.
    "},{"location":"admin/configuration/toplevel/#sql_start_interval","title":"sql_start_interval","text":"
    timeout() 
     
    A time to wait before retrying to restore failed SQL connection. The default value is 30 seconds.
    "},{"location":"admin/configuration/toplevel/#sql_type","title":"sql_type","text":"
    mssql | mysql | odbc | pgsql | sqlite 
     
    The type of an SQL connection. The default is odbc.
    "},{"location":"admin/configuration/toplevel/#sql_username","title":"sql_username","text":"
    Username 
     
    A user name for SQL authentication. The default value is ejabberd.
    "},{"location":"admin/configuration/toplevel/#trusted_proxies","title":"trusted_proxies","text":"
    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.
    "},{"location":"admin/configuration/toplevel/#update_sql_schema","title":"update_sql_schema","text":"
    true | false 
     
     added in 23.10
     
    Allow ejabberd to update SQL schema. The default value is false.
    "},{"location":"admin/configuration/toplevel/#use_cache","title":"use_cache","text":"
    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, oauth_use_cache, router_use_cache, and sm_use_cache.
    "},{"location":"admin/configuration/toplevel/#validate_stream","title":"validate_stream","text":"
    true | false 
     
    Whether to validate any incoming XML packet according to the schemas of supported XMPP extensions. WARNING: the validation is only intended for the use by client developers - don\u2019t enable it in production environment. The default value is false.
    "},{"location":"admin/configuration/toplevel/#version","title":"version","text":"
    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 module. The default value is obtained at compile time from the underlying version control system.
    "},{"location":"admin/configuration/toplevel/#websocket_origin","title":"websocket_origin","text":"
    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\".
    "},{"location":"admin/configuration/toplevel/#websocket_ping_interval","title":"websocket_ping_interval","text":"
    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\u2019t 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.
    "},{"location":"admin/configuration/toplevel/#websocket_timeout","title":"websocket_timeout","text":"
    timeout() 
     
    Amount of time without any communication after which the connection would be closed. The default value is 300 seconds.
    "},{"location":"admin/contrib/","title":"External authentication","text":"
    There are examples of external authentication scripts in many different languages in the page: https://ejabberd.im/extauth
    "},{"location":"admin/contrib/#main-contribution-repository","title":"Main contribution repository","text":"
    Check also the contributions hosted in the ejabberd-contrib Github repository.
    "},{"location":"admin/contrib/#ejabberd-api-libraries","title":"ejabberd API libraries","text":"
    Here is a ejabberd API implementations allowing to ease ejabberd integration with your own backends:
     
       
    • Pyejabberd:   Client library for ejabberd XMLRPC API, in Python, by Dirkmoors, MIT license.     See https://pypi.python.org/pypi/pyejabberd     and https://github.com/dirkmoors/pyejabberd
      •  
    "},{"location":"admin/contrib/#old-obsolete-contributions","title":"Old / obsolete contributions","text":"
    Finally, there is an old list of contributions that were developed for ejabberd 2.x in: https://ejabberd.im/contributions
    "},{"location":"admin/ejabberdctl/","title":"ejabberctl Reference","text":"
    Here are main features covered by ejabberdctl command-line tool:
     
       
    • ejabberdctl overview
      •  
    • Administration Commands API
      •  
    • Multi User Chat Administration Commands
      •  
    "},{"location":"admin/ejabberdctl/muc-admin/","title":"Multi User Chat Administration Commands","text":""},{"location":"admin/ejabberdctl/muc-admin/#prerequisite","title":"Prerequisite","text":"
    Most of the command to manage MUC service depends on the activation of mod_muc_admin module in ejabberd.
     
    mod_muc_admin is included in ejabberd main code base since ejabberd 15.04.
     
    To enable mod_muc_admin-dependant ejabberdctl commands, you just need to add mod_muc_admin in modules section of ejabberd config file.
     
    For example, in ejabberd.yml format:
     
    modules:\n  mod_muc_admin: {}\n
    "},{"location":"admin/ejabberdctl/muc-admin/#commands","title":"Commands","text":"
    The most updated and detailed list of commands for managing a MUC service and MUC rooms is available in the muc API tag and the muc_room API tag.
    "},{"location":"admin/ejabberdctl/muc-admin/#online-rooms","title":"Online Rooms","text":"
    List existing rooms ('global' to get all vhosts).
     
    ejabberdctl muc_online_rooms [global]\n
    "},{"location":"admin/ejabberdctl/muc-admin/#unregister-nickname","title":"Unregister nickname","text":"
    Unregister the nick in the MUC service.
     
    ejabberdctl muc_unregister_nick nickname\n
    "},{"location":"admin/ejabberdctl/muc-admin/#create-muc-room","title":"Create MUC room","text":"
    Create a MUC room name@service in host.
     
    ejabberdctl create_room room_name muc_service xmpp_domain\n
    "},{"location":"admin/ejabberdctl/muc-admin/#destroy-muc-room","title":"Destroy MUC room","text":"
    Destroy a MUC chat room.
     
    ejabberdctl destroy_room room_name muc_service\n
    "},{"location":"admin/ejabberdctl/muc-admin/#create-multiple-rooms-from-file","title":"Create multiple rooms from file","text":"
    Create the rooms listed in a local file.
     
    ejabberdctl create_rooms_file filename\n
     
    TODO: Describe the file format.
    "},{"location":"admin/ejabberdctl/muc-admin/#destroy-multiple-rooms-from-file","title":"Destroy multiple rooms from file","text":"
    Destroy the rooms indicated in a local file.
     
    ejabberdctl destroy_rooms_file filename\n
    "},{"location":"admin/ejabberdctl/muc-admin/#list-unused-muc-rooms","title":"List unused MUC rooms","text":"
    List rooms that have not been used in several days on an XMPP domain.
     
    ejabberdctl rooms_unused_list xmpp_domain number_of_days\n
    "},{"location":"admin/ejabberdctl/muc-admin/#destroy-unused-muc-rooms","title":"Destroy unused MUC rooms","text":"
    Destroy rooms that have not been used in several days on an XMPP domain.
     
    ejabberdctl rooms_unused_destroy xmpp_domain number_of_days\n
    "},{"location":"admin/ejabberdctl/muc-admin/#list-rooms-joined-by-a-given-user","title":"List rooms joined by a given user","text":"
    Get the list of rooms where a user is occupant.
     
    ejabberdctl get_user_rooms user_real_jid xmpp_domain\n
    "},{"location":"admin/ejabberdctl/muc-admin/#list-the-occupants-of-a-muc-room","title":"List the occupants of a MUC room","text":"
    Get the list of occupants of a MUC room.
     
    ejabberdctl get_room_occupants room_name muc_service\n
    "},{"location":"admin/ejabberdctl/muc-admin/#retrieve-number-of-occupants-in-a-muc-room","title":"Retrieve number of occupants in a MUC room","text":"
    Get the number of occupants of a MUC room.
     
    ejabberdctl get_room_occupants_number room_name muc_service\n
    "},{"location":"admin/ejabberdctl/muc-admin/#invite-several-users-to-a-muc-room","title":"Invite several users to a MUC room","text":"
    Send a direct invitation to several JIDs. Password and Message can also be: none. Users JIDs are separated with ':'.
     
    ejabberdctl send_direct_invitation room_name muc_service password reason jid1[:jid2]\n
    "},{"location":"admin/ejabberdctl/muc-admin/#change-option-for-a-muc-room","title":"Change option for a MUC room","text":"
    Change an option in a MUC room.
     
    ejabberdctl change_room_option room_name muc_service option value\n
    "},{"location":"admin/ejabberdctl/muc-admin/#get-options-from-a-muc-room","title":"Get options from a MUC room","text":"
    Get options from a MUC room.
     
    ejabberdctl get_room_options room_name muc_service\n
    "},{"location":"admin/ejabberdctl/muc-admin/#change-affiliation-for-a-user-in-a-muc-room","title":"Change affiliation for a user in a MUC room","text":"
    Change an affiliation in a MUC room. Affiliation can be one of: owner, admin, member, outcast, none.
     
    ejabberdctl set_room_affiliation room_name muc_service user_jid affiliation\n
    "},{"location":"admin/ejabberdctl/muc-admin/#get-affiliations-for-a-muc-room","title":"Get affiliations for a MUC room","text":"
    Get the list of affiliations of a MUC room.
     
    ejabberdctl get_room_affiliations room_name muc_service\n
    "},{"location":"admin/guide/","title":"Advanced ejabberd Administration","text":"
       
    • Clustering ejabberd
      •  
    • Managing an ejabberd server
      •  
    • MQTT Support
      •  
    • Securing ejabberd
      •  
    • Troubleshooting ejabberd
      •  
    • Unattended installation
      •  
    • XMPP Extensions, and how to support them
      •  
    "},{"location":"admin/guide/clustering/","title":"Clustering","text":""},{"location":"admin/guide/clustering/#purpose","title":"Purpose","text":"
    The purpose of ejabberd clustering is to be able to use several servers for a single or small group of large domains, for fault-tolerance and scalability.
     
    Note that you do not necessarily need clustering if you want to run two large domains independently. You may simply want to run two different independent servers.
     
    However, to build reliable service and support large user base, clustering is a must have feature.
    "},{"location":"admin/guide/clustering/#how-it-works","title":"How it Works","text":"
    A XMPP domain is served by one or more ejabberd nodes. These nodes can be run on different machines that are connected via a network. They all must have the ability to connect to port 4369 of all another nodes, and must have the same magic cookie (see Erlang/OTP documentation, in other words the file ~ejabberd/.erlang.cookie must be the same on all nodes). This is needed because all nodes exchange information about connected users, s2s connections, registered services, etc\u2026
     
    Each ejabberd node has the following modules:
     
       
    • router
      •  
    • local router
      •  
    • session manager
      •  
    • s2s manager
      •  
    "},{"location":"admin/guide/clustering/#router","title":"Router","text":"
    This module is the main router of XMPP packets on each node. It routes them based on their destination\u2019s domains. It uses a global routing table. The domain of the packet\u2019s destination is searched in the routing table, and if it is found, the packet is routed to the appropriate process. If not, it is sent to the s2s manager.
    "},{"location":"admin/guide/clustering/#local-router","title":"Local Router","text":"
    This module routes packets which have a destination domain equal to one of this server\u2019s host names. If the destination JID has a non-empty user part, it is routed to the session manager, otherwise it is processed depending on its content.
    "},{"location":"admin/guide/clustering/#session-manager","title":"Session Manager","text":"
    This module routes packets to local users. It looks up to which user resource a packet must be sent via a presence table. Then the packet is either routed to the appropriate c2s process, or stored in offline storage, or bounced back.
    "},{"location":"admin/guide/clustering/#s2s-manager","title":"s2s Manager","text":"
    This module routes packets to other XMPP servers. First, it checks if an opened s2s connection from the domain of the packet\u2019s source to the domain of the packet\u2019s destination exists. If that is the case, the s2s manager routes the packet to the process serving this connection, otherwise a new connection is opened.
    "},{"location":"admin/guide/clustering/#before-you-get-started","title":"Before you get started","text":"
    Before you start implementing clustering, there are a few things you need to take into account:
     
       
    • Cluster should be set up in a single data center: The clustering in   ejabberd Community Edition relies on low latency networking. While it may   work across regions, it is recommended that you run an ejabberd   cluster in a single Amazon region.
      •  
    • Clustering relies on Erlang features and Mnesia shared schemas. Before   getting started, it is best to get familiar with the Erlang environment   as this guide will heavily reference Erlang terms.
      •  
    "},{"location":"admin/guide/clustering/#clustering-setup","title":"Clustering Setup","text":""},{"location":"admin/guide/clustering/#adding-a-node-to-a-cluster","title":"Adding a node to a cluster","text":"
    Suppose you have already configured ejabberd on one node named ejabberd01. Let's create an additional node (ejabberd02) and connect them together.
     
       
    1. Copy the /home/ejabberd/.erlang.cookie file from ejabberd01 to    ejabberd02.
      2.  
     
    Alternatively you could pass the -setcookie <value>    option to all erl commands below.
     
       
    1.  
      Make sure your new ejabberd node is properly configured. Usually,    you want to have the same ejabberd.yml config file on the new node that on the    other cluster nodes.
       
      2.  
    2.  
      Adding a node to the cluster is done by starting a new ejabberd node within the same network, and running join_cluster from a cluster node. On the ejabberd02 node for example, as ejabberd is already started, run the following command as the ejabberd daemon user, using the ejabberdctl script:
       
      3.  
     
    ejabberdctl --no-timeout join_cluster 'ejabberd@ejabberd01'\n
     
    This enables ejabberd's internal replications to be launched across all nodes so new nodes can start receiving messages from other nodes and be registered in the routing tables.
    "},{"location":"admin/guide/clustering/#removing-a-node-from-the-cluster","title":"Removing a node from the cluster","text":"
    To remove a node from the cluster, it just needs to be shut down. There is no specific delay for the cluster to figure out that the node is gone, the node is immediately removed from other router entries. All clients directly connected to the stopped node are disconnected, and should reconnect to other nodes.
     
    If the cluster is used behind a load balancer and the node has been removed from the load balancer, no new clients should be connecting to that node but established connections should be kept, thus allowing to remove a node smoothly, by stopping it after most clients disconnected by themselves. If the node is started again, it's immediately attached back to the cluster until it has been explicitly removed permanently from the cluster.
     
    To permanently remove a running node from the cluster, the leave_cluster command must be run as the ejabberd daemon user, from one node of the cluster:
     
    ejabberdctl leave_cluster 'ejabberd@ejabberd02'\n
     
    The removed node must be running while calling leave_cluster to make it permanently removed. It's then immediately stopped.
    "},{"location":"admin/guide/clustering/#restarting-cluster-nodes","title":"Restarting cluster nodes","text":"
    Ejabberd Community Server uses mnesia internal database to manage cluster and internode synchronisation. As a result, you may restart ejabberd nodes as long as there is at least one running node. If you stop the last running node of a cluster, you MUST restart that node first in order to get a running service back.
    "},{"location":"admin/guide/clustering/#service-load-balancing","title":"Service Load-Balancing","text":""},{"location":"admin/guide/clustering/#domain-load-balancing-algorithm","title":"Domain Load-Balancing Algorithm","text":"
    ejabberd includes 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 cluster and that the traffic will be automatically distributed.
     
    The default distribution algorithm attempts to deliver to a local instance of a component. If several local instances are available, one instance is chosen at random. If no instance is available locally, one instance is randomly chosen among the remote component instances.
     
    If you need a different behaviour, you can change the load balancing behaviour with the domain_balancing option.
    "},{"location":"admin/guide/clustering/#load-balancing-buckets","title":"Load-Balancing Buckets","text":"
    When there is a risk of failure for a given component, domain balancing can cause service trouble. If one component is failing the service will not work correctly unless the sessions are rebalanced.
     
    In this case, it is best to limit the problem to the sessions handled by the failing component. This is what the component_number option does, making the load balancing algorithm not dynamic, but sticky on a fix number of component instances. Check domain_balancing top-level option documentation for details.
    "},{"location":"admin/guide/managing/","title":"Managing an ejabberd server","text":""},{"location":"admin/guide/managing/#ejabberdctl","title":"ejabberdctl","text":"
    With the ejabberdctl command line administration script you can execute ejabberdctl commands (described in the next section, ejabberdctl Commands) and also many general ejabberd commands (described in section ejabberd Commands). This means you can start, stop and perform many other administrative tasks in a local or remote ejabberd server (by providing the argument \u2013node NODENAME).
     
    The ejabberdctl script can be configured in the file ejabberdctl.cfg. This file includes detailed information about each configurable option. See section Erlang Runtime System.
     
    The ejabberdctl script returns a numerical status code. Success is represented by 0, error is represented by 1, and other codes may be used for specific results. This can be used by other scripts to determine automatically if a command succeeded or failed, for example using: echo $?
     
    To restrict what commands can be executed; see API Permissions.
    "},{"location":"admin/guide/managing/#bash-completion","title":"Bash Completion","text":"
    If you use Bash, you can get Bash completion for ejabberdctl commands names.
     
    Some methods to enable that feature:
     
       
    •  
      Copy the file tools/ejabberdctl.bc to the directory /etc/bash_completion.d/ (in Debian, Ubuntu, Fedora and maybe others)
       
      •  
    •  
      Or add to your $HOME/.bashrc a line similar to:
       
      source /path/to/ejabberd/tools/ejabberdctl.bc\n
       
      •  
     
    When ejabberd is running in the machine, type ejabberdctl in a console and press the TAB key.
     
    The first time this is used, the list of commands is extracted from ejabberd and stored in a file in /tmp/. The next time, that file is reused for faster responses.
    "},{"location":"admin/guide/managing/#ejabberdctl-commands","title":"ejabberdctl Commands","text":"
    When ejabberdctl is executed without any parameter, it displays the available options. If there isn't an ejabberd server running, the available parameters are:
     
       
    •  
      start:   Start ejabberd in background mode. This is the default method.
       
      •  
    •  
      debug:   Attach an Erlang shell to an already existing ejabberd server.  This allows to execute commands interactively in the ejabberd  server.
       
      •  
    •  
      live:   Start ejabberd in live mode: the shell keeps attached to the  started server, showing log messages and allowing to execute  interactive commands.
       
      •  
     
    If there is an ejabberd server running in the system, ejabberdctl shows the ejabberdctl commands described below and all the ejabberd commands available in that server (see List of ejabberd Commands).
     
    The ejabberdctl commands are:
     
       
    •  
      help:   Get help about ejabberdctl or any available command. Try  ejabberdctl help help.
       
      •  
    •  
      status:   Check the status of the ejabberd server.
       
      •  
    •  
      stop:   Stop the ejabberd server.
       
      •  
    •  
      restart:   Restart the ejabberd server.
       
      •  
    •  
      mnesia:   Get information about the Mnesia database.
       
      •  
    "},{"location":"admin/guide/managing/#ejabberd-commands","title":"ejabberd Commands","text":"
    Please go to the API section.
    "},{"location":"admin/guide/managing/#erlang-runtime-system","title":"Erlang Runtime System","text":"
    ejabberd is an Erlang/OTP application that runs inside an Erlang runtime system. This system is configured using environment variables and command line parameters. The ejabberdctl administration script uses many of those possibilities. You can configure some of them with the file ejabberdctl.cfg, which includes detailed description about them. This section describes for reference purposes all the environment variables and command line parameters.
     
    The environment variables:
     
    EJABBERD_CONFIG_PATH:   Path to the ejabberd configuration file.
     
    EJABBERD_MSGS_PATH:   Path to the directory with translated strings.
     
    EJABBERD_LOG_PATH:   Path to the ejabberd service log file.
     
    EJABBERD_SO_PATH:   Path to the directory with binary system libraries.
     
    EJABBERD_DOC_PATH:   Path to the directory with ejabberd documentation.
     
    EJABBERD_PID_PATH:   Path to the PID file that ejabberd can create when started.
     
    HOME:   Path to the directory that is considered ejabberd\u2019s home. This  path is used to read the file .erlang.cookie.
     
    ERL_CRASH_DUMP:   Path to the file where crash reports will be dumped.
     
    ERL_EPMD_ADDRESS:   IP address where epmd listens for connections (see epmd).
     
    ERL_INETRC:   Indicates which IP name resolution to use. If using -sname,  specify either this option or -kernel inetrc filepath.
     
    ERL_MAX_PORTS:   Maximum number of simultaneously open Erlang ports.
     
    ERL_MAX_ETS_TABLES:   Maximum number of ETS and Mnesia tables.
     
    The command line parameters:
     
    -sname ejabberd:   The Erlang node will be identified using only the first part of the  host name, i.e. other Erlang nodes outside this domain cannot  contact this node. This is the preferable option in most cases.
     
    -name ejabberd:   The Erlang node will be fully identified. This is only useful if you  plan to setup an ejabberd cluster with nodes in different  networks.
     
    -kernel inetrc \u2019/etc/ejabberd/inetrc\u2019:   Indicates which IP name resolution to use. If using -sname,  specify either this option or ERL_INETRC.
     
    -kernel inet_dist_listen_min 4200 inet_dist_listen_min 4210:   Define the first and last ports that epmd can listen to  (see epmd).
     
    -kernel inet_dist_use_interface { 127,0,0,1 }:   Define the IP address where this Erlang node listens for other nodes  connections (see epmd).
     
    -detached:   Starts the Erlang system detached from the system console. Useful  for running daemons and background processes.
     
    -noinput:   Ensures that the Erlang system never tries to read any input. Useful  for running daemons and background processes.
     
    -pa /var/lib/ejabberd/ebin:   Specify the directory where Erlang binary files (*.beam) are  located.
     
    -s ejabberd:   Tell Erlang runtime system to start the ejabberd application.
     
    -mnesia dir \u2019/var/lib/ejabberd/\u2019:   Specify the Mnesia database directory.
     
    -sasl sasl_error_logger {file, /var/log/ejabberd/erlang.log}:   Path to the Erlang/OTP system log file. SASL here means \u201cSystem  Architecture Support Libraries\u201d not \u201cSimple Authentication and  Security Layer\u201d.
     
    +K [true|false]:   Kernel polling.
     
    -smp [auto|enable|disable]:   SMP support.
     
    +P 250000:   Maximum number of Erlang processes.
     
    -remsh ejabberd@localhost:   Open an Erlang shell in a remote Erlang node.
     
    -hidden:   The connections to other nodes are hidden (not published). The  result is that this node is not considered part of the cluster. This  is important when starting a temporary ctl or debug node.
     
    Note that some characters need to be escaped when used in shell scripts, for instance \" and {}. You can find other options in the Erlang manual page (erl -man erl).
    "},{"location":"admin/guide/managing/#web-admin","title":"Web Admin","text":"
    The ejabberd Web Admin allows to administer some parts of ejabberd using a web browser: accounts, Shared Roster Groups, manage the Mnesia database, create and restore backups, view server statistics, \u2026
    "},{"location":"admin/guide/managing/#basic-setup","title":"Basic Setup","text":"
       
    1.  
      If not done already, register an account and grant administration rights to it    (see Administration Account):
       
      acl:\n  admin:\n    user: admin1@example.org\naccess_rules:\n  configure:\n    allow: admin\n
       
      2.  
    2.  
      Make sure ejabberd_web_admin is available in    request_handlers    of a ejabberd_http listener.    If you want to use HTTPS, enable tls.    For example:
       
      listen:\n   -\n     port: 5443\n     ip: \"::\"\n     module: ejabberd_http\n     tls: true\n     request_handlers:\n       /admin: ejabberd_web_admin\n
       
      3.  
    3.  
      Open the Web Admin page in your favourite web browser. The exact address depends on your configuration; in this example the address is: https://example.net:5443/admin/
       
      4.  
    4.  
      In the login window provide the full Jabber ID: admin1@example.org and password.    If the web address hostname is the same that the account JID,    you can provide simply the username instead of the full JID: admin1.
       
      5.  
    5.  
      You're good! You can now use the Web Admin.
       
      6.  
    "},{"location":"admin/guide/managing/#advanced-configuration","title":"Advanced Configuration","text":"
    There are two access rules supported:
     
       
    • configure determines what accounts can access the Web Admin and make changes.
      •  
    • webadmin_view grants only view access:    those accounts can browse the Web Admin with read-only access.
      •  
     
    Example configurations:
     
       
    •  
      You can serve the Web Admin on the same port as the HTTP Polling   interface. In this example you should point your web browser to   http://example.org:5280/admin/ to administer all virtual hosts or   to http://example.org:5280/admin/server/example.com/ to administer   only the virtual host example.com. Before you get access to the   Web Admin you need to enter as username, the JID and password from a   registered user that is allowed to configure ejabberd. In this   example you can enter as username admin@example.net to   administer all virtual hosts (first URL). If you log in with   admin@example.com on   http://example.org:5280/admin/server/example.com/ you can only   administer the virtual host example.com. The account   reviewer@example.com can browse that vhost in read-only mode.
       
      acl:\n  admin:\n    user:\n      - admin: example.net\n\nhost_config:\n  example.com:\n    acl:\n      admin:\n        user:\n          - admin: example.com\n      viewers:\n        user:\n          - reviewer: example.com\n\naccess:\n  configure:\n    admin: allow\n  webadmin_view:\n    viewers: allow\n\nhosts:\n  - example.org\n\nlisten:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /admin: ejabberd_web_admin\n
       
      •  
    •  
      For security reasons, you can serve the Web Admin on a secured connection, on a port differing from the HTTP Polling interface, and bind it to the internal LAN IP. The Web Admin will be accessible by pointing your web browser to https://192.168.1.1:5282/admin/:
       
      hosts:\n  - example.org\nlisten:\n  -\n    port: 5280\n    module: ejabberd_http\n  -\n    ip: \"192.168.1.1\"\n    port: 5282\n    module: ejabberd_http\n    certfile: \"/usr/local/etc/server.pem\"\n    tls: true\n    request_handlers:\n      /admin: ejabberd_web_admin\n
       
      •  
     
    Certain pages in the ejabberd Web Admin contain a link to a related section in the ejabberd Installation and Operation Guide. In order to view such links, a copy in HTML format of the Guide must be installed in the system. The file is searched by default in /share/doc/ejabberd/guide.html. The directory of the documentation can be specified in the environment variable EJABBERD_DOC_PATH. See section Erlang Runtime System.
    "},{"location":"admin/guide/managing/#ad-hoc-commands","title":"Ad-hoc Commands","text":"
    If you enable mod_configure and mod_adhoc, you can perform several administrative tasks in ejabberd with an XMPP client. The client must support Ad-Hoc Commands (XEP-0050), and you must login in the XMPP server with an account with proper privileges.
    "},{"location":"admin/guide/managing/#change-computer-hostname","title":"Change Computer Hostname","text":"
    ejabberd uses the distributed Mnesia database. Being distributed, Mnesia enforces consistency of its file, so it stores the name of the Erlang node in it (see section Erlang Node Name). The name of an Erlang node includes the hostname of the computer. So, the name of the Erlang node changes if you change the name of the machine in which ejabberd runs, or when you move ejabberd to a different machine.
     
    You have two ways to use the old Mnesia database in an ejabberd with new node name: put the old node name in ejabberdctl.cfg, or convert the database to the new node name.
     
    Those example steps will backup, convert and load the Mnesia database. You need to have either the old Mnesia spool dir or a backup of Mnesia. If you already have a backup file of the old database, you can go directly to step 5. You also need to know the old node name and the new node name. If you don\u2019t know them, look for them by executing ejabberdctl or in the ejabberd log files.
     
    Before starting, setup some variables:
     
    OLDNODE=ejabberd@oldmachine\nNEWNODE=ejabberd@newmachine\nOLDFILE=/tmp/old.backup\nNEWFILE=/tmp/new.backup\n
     
       
    1.  
      Start ejabberd enforcing the old node name:
       
      ejabberdctl --node $OLDNODE start\n
       
      2.  
    2.  
      Generate a backup file:
       
      ejabberdctl --node $OLDNODE backup $OLDFILE\n
       
      3.  
    3.  
      Stop the old node:
       
      ejabberdctl --node $OLDNODE stop\n
       
      4.  
    4.  
      Make sure there aren't files in the Mnesia spool dir. For example:
       
      mkdir /var/lib/ejabberd/oldfiles\nmv /var/lib/ejabberd/*.* /var/lib/ejabberd/oldfiles/\n
       
      5.  
    5.  
      Start ejabberd. There isn't any need to specify the node name  anymore:
       
      ejabberdctl start\n
       
      6.  
    6.  
      Convert the backup to new node name using     mnesia_change_nodename:
       
      ejabberdctl mnesia_change_nodename $OLDNODE $NEWNODE $OLDFILE $NEWFILE\n
       
      7.  
    7.  
      Install the backup file as a fallback using     install_fallback:
       
      ejabberdctl install_fallback $NEWFILE\n
       
      8.  
    8.  
      Stop ejabberd:
       
      ejabberdctl stop\n
       
      You may see an error message in the log files, it\u2019s normal, so don\u2019t worry:
       
      Mnesia(ejabberd@newmachine):\n** ERROR ** (ignoring core)\n** FATAL ** A fallback is installed and Mnesia must be restarted.\n  Forcing shutdown after mnesia_down from ejabberd@newmachine...\n
       
      9.  
    9.  
      Now you can finally start ejabberd:
       
      ejabberdctl start\n
       
      10.  
    10.  
      Check that the information of the old database is available:  accounts, rosters... After you finish, remember to delete the  temporary backup files from public directories.
       
      11.  
    "},{"location":"admin/guide/security/","title":"Securing ejabberd","text":""},{"location":"admin/guide/security/#firewall-settings","title":"Firewall Settings","text":"
    You need to take the following ports in mind when configuring your firewall. The ports may change depending on your ejabberd configuration. Most of them are TCP ports, except the explicitely mentioned ones:
     Port Description 5222 Jabber/XMPP client connections, plain or STARTTLS 5223 Jabber client connections using the old SSL method 5269 Jabber/XMPP incoming server connections 5280/5443 HTTP/HTTPS for Web Admin and many more (ejabberd_http) 1883/8883 MQTT/MQTTS service (mod_mqtt) 3478/5349 STUN+TURN/STUNS+TURNS service (ejabberd_stun) 3478 UDP ' ' 49152-65535 range UDP STUN+TURN service (ejabberd_stun), configure with turn_min_port and turn_max_port 5060/5061 SIP service (ejabberd_sip) 7777 SOCKS5 file transfer proxy (mod_proxy65) 4369 EPMD (see epmd) listens for Erlang node name requests random port range Used by epmd for connections between Erlang nodes, configure with inet_dist_listen_min and inet_dist_listen_max 5210 Erlang connectivity when ERL_DIST_PORT is set, alternative to EPMD"},{"location":"admin/guide/security/#epmd","title":"epmd","text":"
    epmd (Erlang Port Mapper Daemon) is a small name server included in Erlang/OTP and used by Erlang programs when establishing distributed Erlang communications. ejabberd needs epmd to use ejabberdctl and also when clustering ejabberd nodes. This small program is automatically started by Erlang, and is never stopped. If ejabberd is stopped, and there aren't any other Erlang programs running in the system, you can safely stop epmd if you want.
     
    ejabberd runs inside an Erlang node. To communicate with ejabberd, the script ejabberdctl starts a new Erlang node and connects to the Erlang node that holds ejabberd. In order for this communication to work, epmd must be running and listening for name requests in the port 4369. You should block the port 4369 in the firewall in such a way that only the programs in your machine can access it, or configure the option ERL_EPMD_ADDRESS in the file ejabberdctl.cfg.
     
    If you build a cluster of several ejabberd instances, each ejabberd instance is called an ejabberd node. Those ejabberd nodes use a special Erlang communication method to build the cluster, and EPMD is again needed listening in the port 4369. So, if you plan to build a cluster of ejabberd nodes you must open the port 4369 for the machines involved in the cluster. Remember to block the port so Internet doesn't have access to it.
     
    Once an Erlang node solved the node name of another Erlang node using EPMD and port 4369, the nodes communicate directly. The ports used in this case by default are random, but can be configured in the file ejabberdctl.cfg. The Erlang command-line parameter used internally is, for example:
     
    erl ... -kernel inet_dist_listen_min 4370 inet_dist_listen_max 4375\n
     
    It is also possible to configure in ejabberdctl.cfg the network interface where the Erlang node will listen and accept connections. The Erlang command-line parameter used internally is, for example:
     
    erl ... -kernel inet_dist_use_interface \"{127,0,0,1}\"\n
    "},{"location":"admin/guide/security/#erlang-cookie","title":"Erlang Cookie","text":"
    The Erlang cookie is a string with numbers and letters. An Erlang node reads the cookie at startup from the command-line parameter -setcookie. If not indicated, the cookie is read from the file $HOME/.erlang.cookie.
     
    If this file does not exist, it is created immediately with a random cookie in the user $HOME path. This means the user running ejabberd must have a $HOME, and have write access to that path. So, when you create a new account in your system for running ejabberd, either allow it to have a $HOME, or set as $HOME a path where ejabberd will have write access. Depending on your setup, examples could be:
     
    adduser --home /usr/local/var/lib/ejabberd ejabberd\n
     
    or
     
    adduser --home /var/lib/ejabberd ejabberd\n
     
    Two Erlang nodes communicate only if they have the same cookie. Setting a cookie on the Erlang node allows you to structure your Erlang network and define which nodes are allowed to connect to which.
     
    Thanks to Erlang cookies, you can prevent access to the Erlang node by mistake, for example when there are several Erlang nodes running different programs in the same machine.
     
    Setting a secret cookie is a simple method to difficult unauthorized access to your Erlang node. However, the cookie system is not ultimately effective to prevent unauthorized access or intrusion to an Erlang node. The communication between Erlang nodes are not encrypted, so the cookie could be read sniffing the traffic on the network. The recommended way to secure the Erlang node is to block the port 4369.
    "},{"location":"admin/guide/security/#erlang-node-name","title":"Erlang Node Name","text":"
    An Erlang node may have a node name. The name can be short (if indicated with the command-line parameter -sname) or long (if indicated with the parameter -name). Starting an Erlang node with -sname limits the communication between Erlang nodes to the LAN.
     
    Using the option -sname instead of -name is a simple method to difficult unauthorized access to your Erlang node. However, it is not ultimately effective to prevent access to the Erlang node, because it may be possible to fake the fact that you are on another network using a modified version of Erlang epmd. The recommended way to secure the Erlang node is to block the port 4369.
    "},{"location":"admin/guide/security/#securing-sensitive-files","title":"Securing Sensitive Files","text":"
    ejabberd stores sensitive data in the file system either in plain text or binary files. The file system permissions should be set to only allow the proper user to read, write and execute those files and directories.
     
    ejabberd configuration file: /etc/ejabberd/ejabberd.yml:   Contains the JID of administrators and passwords of external  components. The backup files probably contain also this information,  so it is preferable to secure the whole /etc/ejabberd/ directory.
     
    ejabberd service log: /var/log/ejabberd/ejabberd.log:   Contains IP addresses of clients. If the loglevel is set to 5, it  contains whole conversations and passwords. If a logrotate system is  used, there may be several log files with similar information, so it  is preferable to secure the whole /var/log/ejabberd/ directory.
     
    Mnesia database spool files in /var/lib/ejabberd/:   The files store binary data, but some parts are still readable. The  files are generated by Mnesia and their permissions cannot be set  directly, so it is preferable to secure the whole  /var/lib/ejabberd/ directory.
     
    Erlang cookie file: /var/lib/ejabberd/.erlang.cookie:   See section Erlang Cookie.
    "},{"location":"admin/guide/troubleshooting/","title":"Troubleshooting ejabberd","text":""},{"location":"admin/guide/troubleshooting/#log-files","title":"Log Files","text":"
    An ejabberd node writes three log files:
     
       
    •  
      ejabberd.log:   is the ejabberd service log, with the messages reported by ejabberd code
       
      •  
    •  
      error.log:   is the file accumulating error messages from ejabberd.log
       
      •  
    •  
      crash.log:   is the Erlang/OTP log, with the crash messages reported by Erlang/OTP using SASL (System Architecture Support Libraries)
       
      •  
     
    The option loglevel modifies the verbosity of the file ejabberd.log. The syntax:
     
    loglevel: Level: The standard form to set a global log level.
     
    The possible Level are:
     
       
    •  
      0:   No ejabberd log at all (not recommended)
       
      •  
    •  
      1:   Critical
       
      •  
    •  
      2:   Error
       
      •  
    •  
      3:   Warning
       
      •  
    •  
      4:   Info
       
      •  
    •  
      5:   Debug
       
      •  
     
    For example, the default configuration is:
     
    loglevel: 4
     
    By default ejabberd rotates the log files when they get grown above a certain size. The exact value is controlled by the log_rotate_size top-level option.
     
    However, you can rotate the log files manually. You can either use an external tool for log rotation and the reopen_log API command to reopen the log files, or the rotate_log API command to perform both steps (please refer to section ejabberd Commands).
     
    The log_rotate_count toplevel option defines the number of rotated files to keep by the reopen_log API command. Every such file has a numeric suffix.
    "},{"location":"admin/guide/troubleshooting/#debug-console","title":"Debug Console","text":"
    The Debug Console is an Erlang shell attached to an already running ejabberd server. With this Erlang shell, an experienced administrator can perform complex tasks.
     
    This shell gives complete control over the ejabberd server, so it is important to use it with extremely care. There are some simple and safe examples in the article Interconnecting Erlang Nodes
     
    To exit the shell, close the window or press the keys: control+c control+c.
    "},{"location":"admin/guide/troubleshooting/#too-many-db-tables","title":"Too many db tables","text":"
    When running ejabberd, the log shows this error:
     
    ** Too many db tables **\n
     
    The number of concurrent ETS and Mnesia tables is limited. If this error occurs, it means that you have reached this limit.
     
    For a solution, please read the section about ERL_MAX_ETS_TABLES on the Performance Tuning page.
    "},{"location":"admin/guide/unattended/","title":"Unattended Installation","text":"
    Bitrock framework allow unattended installation. With this mode, the installer will not prompt the user for any information and will instead use the default settings configured for each of the parameters. That way, no input is required from the user during the installation. It's also possible to define the values through command line or using a configuration file
     
    ./sample-installer.bin --mode unattended --param1 value1 --param2 value2 ....\n./sample-installer.bin --mode unattended --optionfile optionfile\n
     
    Where optionfile should contain a list of pairs key=value. For instance:
     
    param1=value1\nparam2=value2\n
    "},{"location":"admin/guide/unattended/#available-parameters-for-ejabberd-installer","title":"Available parameters for ejabberd installer","text":"
    Installer recognizes those options:
     
    --admin <username>:  sets user name used that should have admin access
     
    --adminpw <password>:  password used by admin user
     
    --ejabberddomain <domain>:  domain that should be used XMPP server
     
    --installdir <path>:  installation directory
     
    --cluster <0|1>:  setting this to 1 would setup this installation as a part of    cluster (by default it's value is assumed 0)
     
    --hostname <name>:  node id used by ejabberd to use as part of erlang node id (has    only be set when using clustered environment
    "},{"location":"admin/guide/mqtt/","title":"MQTT Support","text":""},{"location":"admin/guide/mqtt/#benefits","title":"Benefits","text":"
    ejabberd is a multiprotocol server that supports MQTT out of the box since ejabberd Business Edition 4.0 and ejabberd Community Server 19.02
     
    There are major benefits in using MQTT service embedded in ejabberd:
     
       
    1. MQTT service relies on ejabberd infrastructure code, that has been battle tested since 15+ years, like the clustering engine. ejabberd MQTT service has been tested on large scale and can support millions of concurrent connections highly efficiently. ejabberd MQTT is rock-solid and highly scalable.
      2.  
    2. The ejabberd APIs and modules can be reused in MQTT. Authentication, virtual hosting, database backends, ... They both work with XMPP and MQTT. You can also share your security policy, as defined in the configuration file between the two protocols.
      3.  
    3. You can leverage existing skills and plugins you have written for ejabberd, like for example custom authentication.
      4.  
    4. You can deploy services that take advantage of both protocols and have them interoperate with each other, on a single platform, with a single tool.
      5.  
    5. ejabberd supports MQTT 5: it is a state of the art, modern MQTT server. And it also supports MQTT 3.1.1 in case you want to use previous clients.
      6.  
     
    In summary:
     
       
    • You can switch between XMPP and MQTT as you wish, even use both protocols on the same infrastructure.
      •  
    • You will save on infrastructure, given the high-performance of the platform.
      •  
    • You get support on solution design for real-time infrastructure and can get help choosing between XMPP and MQTT, from a vendor that has no interest in selling one protocol more than another.
      •  
     
    ejabberd Business Edition offers a different clustering than eCS. Using MQTT with ejabberd Business Edition means you can leverage:
     
       
    • The clustering engine of eBE will be used for the MQTT service. It means that you have a more scalable cluster, that supports geoclustering. With geoclustering, you can deploy a single MQTT service across different datacenters, spread in different regions. You can deploy a truly global service.
      •  
    • The backend integration that are supported in ejabberd Business Edition will be available in MQTT. You have no need to develop support for new API.
      •  
    "},{"location":"admin/guide/mqtt/#basic-setup","title":"Basic Setup","text":"
    Maybe you already have MQTT enabled in your ejabberd server, as it comes enabled by default in many distributions.
     
    MQTT support in ejabberd is enabled by adding mod_mqtt to the list of listen and the list of modules like this:
     
    listen:\n  -\n    port: 1883\n    module: mod_mqtt\n    backlog: 1000\n\nmodules:\n  mod_mqtt: {}\n
     
    The listener on port 1883 is MQTT over cleartext TCP/IP connection; you can later setup encryption, WebSocket, and encrypted WebSocket.
     
    For available options you can consult the mod_mqtt listener and the mod_mqtt module.
    "},{"location":"admin/guide/mqtt/#test-setup","title":"Test Setup","text":"
    Start ejabberd server and you can connect to ejabberd MQTT service with your preferred MQTT client.
     
    Let's use the clients included with mosquitto, available in Debian, Brew and many others (see mosquitto downloads).
     
    First of all register several accounts and subscribe one to the topic test/1 with:
     
    ejabberdctl register author localhost Pass\nejabberdctl register user1 localhost Pass\n\nmosquitto_sub -u user1@localhost -P Pass -t \"test/1\" -d -v\n\nClient (null) sending CONNECT\nClient (null) received CONNACK (0)\nClient (null) sending SUBSCRIBE (Mid: 1, Topic: test/1, QoS: 0, Options: 0x00)\nClient (null) received SUBACK\nSubscribed (mid: 1): 0\n
     
    Then go to another terminal or window and publish something on that topic:
     
    mosquitto_pub -u author@localhost -P Pass -t \"test/1\" -d -m \"ABC\"\n\nClient (null) sending CONNECT\nClient (null) received CONNACK (0)\nClient (null) sending PUBLISH (d0, q0, r0, m1, 'test/1', ... (3 bytes))\nClient (null) sending DISCONNECT\n
     
    You will see the message received and displayed in the mosquitto_sub window:
     
    Client (null) received PUBLISH (d0, q0, r0, m0, 'test/1', ... (3 bytes))\ntest/1 ABC\n
    "},{"location":"admin/guide/mqtt/#access-control","title":"Access Control","text":"
    The mod_mqtt module provides two options for access control:
     
       
    • access_subscribe to restrict access for subscribers,
      •  
    • and access_publish to restrict access for publishers.
      •  
     
    Both options accept mapping filter: rule where filter is an MQTT topic filter and rule is the standard ejabberd Access Rule.
     
    As an example, let's say only author@localhost is allowed to publish to topic \"/test/1/\" and its subtopics, while only user1@localhost is allowed to subscribe to this topic and its subtopics, and nobody else can publish or subscribe to anything else. The configuration will look something like this:
     
    acl:\n  publisher:\n    user: author@localhost\n  subscriber:\n    user: user1@localhost\n\nmodules:\n  mod_mqtt:\n    access_publish:\n      \"test/1/#\":\n        - allow: publisher\n        - deny\n      \"#\":\n        - deny\n    access_subscribe:\n      \"test/1/#\":\n        - allow: subscriber\n        - deny\n      \"#\":\n        - deny\n
    "},{"location":"admin/guide/mqtt/#encryption","title":"Encryption","text":""},{"location":"admin/guide/mqtt/#self-signed-certificate","title":"Self-Signed Certificate","text":"
    If you have already setup encryption in ejabberd, you can bypass this step.
     
    If you want to use TLS, you may want to create a self-signed certificate (at least to get started). The following page is a nice guide: Mosquitto SSL Configuration -MQTT TLS Security.
     
    Here is a summary of the steps, adapted for ejabberd MQTT:
     
    openssl genrsa -des3 -out ca.key 4096\nopenssl req -new -x509 -days 1826 -key ca.key -out ca.crt\nopenssl genrsa -out server.key 4096\nopenssl req -new -out server.csr -key server.key\nopenssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 360\ncat server.crt server.key > mqtt.pem\n
     
    Now copy mqtt.pem to the path with ejabberd configuration files, and configure accordingly:
     
    certfiles:\n  - \"/etc/ejabberd/mqtt.pem\"\n
    "},{"location":"admin/guide/mqtt/#configure-encryption","title":"Configure Encryption","text":"
    Add a new listener with tls option in the port number 8883 (the standard for encrypted MQTT):
     
    listen:\n  -\n    port: 1883\n    module: mod_mqtt\n    backlog: 1000\n  -\n    port: 8883\n    module: mod_mqtt\n    backlog: 1000\n    tls: true\n
     
    The listener on port 1883 is MQTT over cleartext TCP/IP connection. The listener on port 8883 is MQTT over TLS. You can enable both or only one of them depending on your needs.
    "},{"location":"admin/guide/mqtt/#test-encryption","title":"Test Encryption","text":"
    You can repeat the commands from previous test, appending -p 8883 to use the encrypted port. If you are using a self-signed certificate as explained previously, you will also have to append --cafile server.crt. For example:
     
    mosquitto_sub -u user1@localhost -P Pass -t \"test/1\" -d -v -p 8883 --cafile server.crt\n
    "},{"location":"admin/guide/mqtt/#websocket","title":"WebSocket","text":""},{"location":"admin/guide/mqtt/#setup-ws","title":"Setup WS","text":"
    Add mod_mqtt as a request_handler on the ejabberd_http listener:
     
    listen:\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /mqtt: mod_mqtt\n
     
    This configuration maps the path /mqtt to the MQTT WebSocket handler on the main ejabberd HTTP listener.
     
    You can enable listeners independently, for example enable only the WebSocket listener and not the TCP/IP ones.
    "},{"location":"admin/guide/mqtt/#test-ws","title":"Test WS","text":"
    Our beloved mosquitto client does not support MQTT over WebSocket, so you may have to find some capable MQTT client. For example, in MQTTX, setup in the login window:
     
       
    • Host: ws:// localhost
      •  
    • Port: 5280
      •  
    • Path:/mqtt
      •  
     
    If you need an example on how to use MQTTJS library, you can check our small example project: mqttjs-demo
    "},{"location":"admin/guide/mqtt/#encrypted-ws","title":"Encrypted WS","text":"
    To enable encryption on WebSocket, enable tls like this:
     
    listen:\n  -\n    port: 5281\n    ip: \"::\"\n    module: ejabberd_http\n    tls: true\n    request_handlers:\n      /mqtt: mod_mqtt\n
     
    For testing this in the MQTTX client:
     
       
    • Host: wss:// localhost
      •  
    • Port: 5281
      •  
    • Path: /mqtt
      •  
    • SSL/TLS: true
      •  
    • Certificate: CA signed server
      •  
    • If you used a self-signed certificate, you will have to disable SSL Secure
      •  
    "},{"location":"admin/guide/xep/","title":"Supporting and configuring specific XMPP Extensions in ejabberd","text":"
    XMPP extensions support can be implemented in different ways in ejabberd. We have several cases:
     
       
    1. The extension must be implemented as a core feature of ejabberd. In    that case, it may be supported as default and / or have    configuration options in ejabberd config files.
      2.  
    2. The extension can be optional and implemented as a module.
      3.  
    3. The extension may additionally need to be enabled on the client    stream to use it (For example MAM or stream management).
      4.  
     
    This section is here to help you understand how they are implemented XEP by XEP in ejabberd. We intend to explain what you can do in case you want to support a given XEP or if you want to make sure a specific Extension is disabled.
    "},{"location":"admin/guide/xep/#xep-0004-data-forms","title":"XEP-0004: Data Forms","text":""},{"location":"admin/guide/xep/#specification","title":"Specification","text":"
    XEP-0004: Data Forms
    "},{"location":"admin/guide/xep/#implementation","title":"Implementation","text":"
    ejabberd core
    "},{"location":"admin/guide/xep/#comment","title":"Comment","text":"
    This extension is a general design principle for forms in XMPP. The principles are applied by all services, components and modules inside ejabberd.
    "},{"location":"admin/guide/xep/#enabling-disabling","title":"Enabling / Disabling","text":"
    As it is a general specification, it is used as default and cannot be disabled.
    "},{"location":"admin/guide/xep/#xep-0012-last-activity","title":"XEP-0012: Last Activity","text":""},{"location":"admin/guide/xep/#specification_1","title":"Specification","text":"
    XEP-0012: Last Activity
    "},{"location":"admin/guide/xep/#implementation_1","title":"Implementation","text":"
    Main ejabberd module: mod_last.erl
    "},{"location":"admin/guide/xep/#comment_1","title":"Comment","text":"
    This extension is optional. It allows the server to send back information about when the user disconnected their last session.
     
    It also allows to query the uptime of an ejabberd server.
    "},{"location":"admin/guide/xep/#enabling","title":"Enabling","text":"
    Add mod_last configuration in modules section of the configuration file.
     
    It is enabled by default in ejabberd configuration template.
    "},{"location":"admin/guide/xep/#disabling","title":"Disabling","text":"
    Make sure mod_last is not defined or is commented out in ejabberd config modules section.
     
    No side effect.
    "},{"location":"admin/guide/xep/#module-documentation","title":"Module documentation","text":"
       
    • mod_last
      •  
    "},{"location":"admin/guide/xep/#xep-0013-flexible-offline-message-retrieval","title":"XEP-0013: Flexible Offline Message Retrieval","text":""},{"location":"admin/guide/xep/#specification_2","title":"Specification","text":"
    XEP-0013: Flexible Offline Message Retrieval
    "},{"location":"admin/guide/xep/#implementation_2","title":"Implementation","text":"
    Main ejabberd module: mod_offline.erl
    "},{"location":"admin/guide/xep/#comment_2","title":"Comment","text":"
    This extension is active on server if mod_offline module is enabled on ejabberd.
     
    However, it is not used by client automatically. Flexible offline message retrieval is enabled in the following cases:
     
       
    • client send request to retrieve number of messages prior to sending   its initial presence:   Requesting Number of Messages
      •  
    • client send request to retrieve messages headers prior to sending   its initial presence:   Requesting Message Headers
      •  
    • client send all messages retrieval request prior to sending its   initial presence:   Retrieving All Messages
      •  
    "},{"location":"admin/guide/xep/#enabling_1","title":"Enabling","text":"
    Add mod_offline configuration in modules section of the configuration file.
     
    It is enabled and can be used by client if mod_offline is enabled. This is a module enabled by default in default ejabberd configuration file template.
    "},{"location":"admin/guide/xep/#disabling_1","title":"Disabling","text":"
    Make sure mod_offline is not defined or is commented out in    ejabberd config modules section.
     
    Side effect: It will disable all offline messages storage.
    "},{"location":"admin/guide/xep/#module-documentation_1","title":"Module documentation","text":"
       
    • mod_offline
      •  
    "},{"location":"admin/install/","title":"Installation","text":"
    There are several ways to install ejabberd Community Server, depending on your needs and your infrastructure.
    "},{"location":"admin/install/#self-hosted","title":"Self-hosted","text":""},{"location":"admin/install/#container-images","title":"Container Images","text":"
       
    • ejabberd and ecs Container Images \u2013 Ideal for Windows, macOS, Linux, ...
      •  
    "},{"location":"admin/install/#binary-installers","title":"Binary Installers","text":"
       
    • Linux RUN Installer \u2013 Suitable for various Linux distributions
      •  
    • Linux DEB and RPM Installers \u2013 Specifically for DEB and RPM based Linux
      •  
    "},{"location":"admin/install/#linux-and-bsd","title":"Linux and *BSD","text":"
       
    • Operating System Package \u2013 Tailored for System Operators
      •  
    "},{"location":"admin/install/#macos","title":"MacOS","text":"
       
    • Homebrew \u2013 Optimized for MacOS
      •  
    "},{"location":"admin/install/#source-code","title":"Source Code","text":"
       
    • Source Code \u2013 Geared towards developers and advanced administrators
      •  
    "},{"location":"admin/install/#on-premise-ebe","title":"On-Premise (eBE)","text":"
       
    • ejabberd Business Edition \u2013 Explore professional support and managed services on your infrastructure
      •  
    "},{"location":"admin/install/#cloud-hosting-fluux","title":"Cloud Hosting (Fluux)","text":"
       
    • Fluux.io \u2013 Opt for ejabberd hosting with a user-friendly web dashboard
      •  
    "},{"location":"admin/install/binary-installer/","title":"Binary Installers","text":""},{"location":"admin/install/binary-installer/#linux-run-installer","title":"Linux RUN Installer","text":"
    The *.run binary installer will deploy and configure a full featured ejabberd server and does not require any extra dependencies. It includes a stripped down version of Erlang. As such, when using ejabberd installer, you do not need to install Erlang separately.
     
    Those instructions assume installation on localhost for development purposes. In this document, when mentioning ejabberd-YY.MM, we assume YY.MM is the release number, for example 18.01.
     
    Installation using the *.run binary installer:
     
       
    1.  
      Go to ejabberd GitHub Releases.
       
      2.  
    2.  
      Download the run package for your architecture
       
      3.  
    3.  
      Right-click on the downloaded file and select \"Properties\", click on the \"Permissions\" tab and tick the box that says \"Allow executing file as program\".    Alternatively, you can set the installer as executable using the command line:
       
      chmod +x ejabberd-YY.MM-1-linux-x64.run\n
       
      4.  
    4.  
      If the installer runs as superuser (by root or using sudo),    it installs ejabberd binaries in /opt/ejabberd-XX.YY/;    installs your configuration, Mnesia database and logs in /opt/ejabberd/,    and setups an ejabberd service unit in systemd:
       
      sudo ./ejabberd-YY.MM-1-linux-x64.run\n
       
      5.  
    5.  
      If the installer runs as a regular user,    it asks the base path where ejabberd should be installed.    In that case, the ejabberd service unit is not set in systemd,    and systemctl cannot be used to start ejabberd; start it manually.
       
      6.  
    6.  
      After successful installation by root, ejabberd is automatically started.    Check its status with
       
      systemctl status ejabberd\n
       
      7.  
    7.  
      Now that ejabberd is installed and running with the default configuration,    it's time to do some basic setup: edit /opt/ejabberd/conf/ejabberd.yml    and setup in the hosts option the domain that you want ejabberd to serve.    By default it's set to the name of your computer on the local network.
       
      8.  
    8.  
      Restart ejabberd completely using systemctl, or using ejabberdctl,    or simply tell it to reload the configuration file:
       
      sudo systemctl restart ejabberd\nsudo /opt/ejabberd-22.05/bin/ejabberdctl restart\nsudo /opt/ejabberd-22.05/bin/ejabberdctl reload_config\n
       
      9.  
    9.  
      Quite probably you will want to register an account and grant it admin rights,    please check Next Steps: Administration Account.
       
      10.  
    10.  
      Now you can go to the web dashboard at http://localhost:5280/admin/    and fill the username field with the full account JID,    for example admin@domain (or admin@localhost as above).    Then fill the password field with that account's password.    The next step is to get to know how to configure ejabberd.
       
      11.  
    11.  
      If something goes wrong during the installation    and you would like to start from scratch,    you will find the steps to uninstall in the file    /opt/ejabberd-22.05/uninstall.txt.
       
      12.  
    "},{"location":"admin/install/binary-installer/#linux-deb-and-rpm-installers","title":"Linux DEB and RPM Installers","text":"
    ProcessOne provides DEB and RPM all-in-one binary installers with the same content that the *.run binary installer mentioned in the previous section.
     
    Those are self-sufficient packages that contain a minimal Erlang distribution, this ensures that it does not interfere with your existing Erlang version and is also a good way to make sure ejabberd will run with the latest Erlang version.
     
    Those packages install ejabberd in /opt/ejabberd-XX.YY/. Your configuration, Mnesia database and logs are available in /opt/ejabberd/.
     
    You can download directly the DEB and RPM packages from ejabberd GitHub Releases.
     
    If you prefer, you can also get those packages from our official ejabberd packages repository.
    "},{"location":"admin/install/homebrew/","title":"Install ejabberd on macOS","text":""},{"location":"admin/install/homebrew/#homebrew","title":"Homebrew","text":"
    Homebrew is a package manager for macOS that aims to port the many Unix & Linux software that is not easily available or compatible. Homebrew installation is simple and the instruction is available on its website.
     
    Check also the guide for Installing ejabberd development environment on OSX
     
    The ejabberd configuration included in Homebrew's ejabberd has as default domain localhost, and has already granted administrative privileges to the account admin@localhost.
     
       
    1.  
      Once you have Homebrew installed, open Terminal. Run
       
      brew install ejabberd\n
       
      This should install the latest or at most the one-before-latest version of ejabberd. The installation directory should be reported at the end of this process, but usually the main executable is stored at /usr/local/sbin/ejabberdctl.
       
      2.  
    2.  
      Start ejabberd in interactive mode, which prints useful messages in the Terminal.
       
      /usr/local/sbin/ejabberdctl live\n
       
      3.  
    3.  
      Create the account admin@localhost with password set as password:
       
      /usr/local/sbin/ejabberdctl register admin localhost password\n
       
      4.  
    4.  
      Now you can go to the web dashboard at http://localhost:5280/admin/ and fill the username field with the full account JID, for example admin@localhost, then fill the password field with that account's password.
       
      5.  
    5.  
      Without configuration there's not much to see here, therefore the next step is to get to know how to configure ejabberd.
       
      6.  
    "},{"location":"admin/install/next-steps/","title":"Next Steps","text":""},{"location":"admin/install/next-steps/#starting-ejabberd","title":"Starting ejabberd","text":"
    Depending on how you installed ejabberd, it may be started automatically by the operating system at system boot time.
     
    You can use the ejabberdctl command line administration script to start and stop ejabberd, check its status and many other administrative tasks.
     
    If you provided the configure option --enable-user=USER (see compilation options, you can execute ejabberdctl with either that system account or root.
     
    Usage example:
     
    prompt> ejabberdctl start\n\nprompt> ejabberdctl status\nThe node ejabberd@localhost is started with status: started\nejabberd is running in that node\n\nprompt> ejabberdctl stop\n
     
    If ejabberd doesn't start correctly and a crash dump file is generated, there was a severe problem. You can try to start ejabberd in interactive mode with the command bin/ejabberdctl live to see the error messages provided by Erlang and identify the exact the problem.
     
    The ejabberdctl administration script is included in the bin directory in the Linux Installers and Docker image.
     
    Please refer to the section ejabberdctl for details about ejabberdctl, and configurable options to fine tune the Erlang runtime system.
    "},{"location":"admin/install/next-steps/#autostart-on-linux","title":"Autostart on Linux","text":"
    If you compiled ejabberd from source code or some other method that doesn't setup autostarting ejabberd, you can try this method.
     
    On a *nix system, create a system user called 'ejabberd', give it write access to the directories database/ and logs/, and set that as home.
     
    If you want ejabberd to be started as daemon at boot time with that user, copy ejabberd.init from the bin directory to something like /etc/init.d/ejabberd. Then you can call /etc/inid.d/ejabberd start to start the server.
     
    Or if you have a systemd distribution:
     
       
    1. copy ejabberd.service to /etc/systemd/system/
      2.  
    2. run systemctl daemon-reload
      3.  
    3. run systemctl enable ejabberd.service
      4.  
    4. To start the server, you can run systemctl start ejabberd
      5.  
     
    When ejabberd is started, the processes that are started in the system are beam or beam.smp, and also epmd. For more information regarding epmd consult the section relating to epmd.
    "},{"location":"admin/install/next-steps/#administration-account","title":"Administration Account","text":"
    Some ejabberd installation methods ask you details for the first account, and take care to register that account and grant it administrative rights; in that case you can skip this section.
     
    After installing ejabberd from source code or other methods, you may want to register the first XMPP account and grant it administrative rights:
     
       
    1.  
      Register an XMPP account on your ejabberd server.     For example, if example.org is configured in the     hosts     section in your ejabberd configuration file,     then you may want to register an account with JID admin1@example.org.
       
      There are two ways to register an XMPP account in ejabberd:
       
         
      •  
        Using an XMPP client and In-Band Registration.
         
        •  
      •  
        Using ejabberdctl:
         
        ejabberdctl register admin1 example.org password\n
         
        •  
       
      2.  
    2.  
      Edit the ejabberd configuration file to give administration     rights to the XMPP account you registered:
       
      acl:\n  admin:\n    user: admin1@example.org\n\naccess_rules:\n  configure:\n    allow: admin\n
       
      You can grant administrative privileges to many XMPP accounts, and also to accounts in other XMPP servers.
       
      3.  
    3.  
      Restart ejabberd to load the new configuration, or run the     reload_config command.
       
      4.  
    4.  
      Open the Web Admin page in your favourite browser.     The exact address depends on your ejabberd configuration,     and may be     http://localhost:5280/admin/,     https://localhost:5443/admin/,     https://localhost:5280/admin/ ...
       
      5.  
    5.  
      Your web browser shows a login window. Introduce the full JID,     in this example admin1@example.org, and the account password.     If the web address hostname is the same that the account JID,     you can provide simply the username instead of the full JID: admin1.     See Web Admin for details.
       
      6.  
    "},{"location":"admin/install/next-steps/#configuring-ejabberd","title":"Configuring ejabberd","text":"
    Now that you got ejabberd installed and running, it's time to configure it to your needs. You can follow on the Configuration section and take also a look at the Tutorials.
    "},{"location":"admin/install/os-package/","title":"Operating System Packages","text":"
    Many operating systems provide specific ejabberd packages adapted to the system architecture and libraries. They usually also check dependencies and perform basic configuration tasks like creating the initial administrator account.
     
    List of known ejabberd packages:
     
       
    • Alpine Linux
      •  
    • Arch Linux
      •  
    • Debian
      •  
    • Fedora
      •  
    • FreeBSD
      •  
    • Gentoo
      •  
    • OpenSUSE
      •  
    • NetBSD
      •  
    • Ubuntu
      •  
     
    Consult the resources provided by your Operating System for more information.
     
    There's also an ejabberd snap to install ejabberd on several operating systems using Snap package manager.
    "},{"location":"admin/install/source/","title":"Install ejabberd from Source Code","text":"
    The canonical form for distribution of ejabberd stable releases is the source code package. Compiling ejabberd from source code is quite easy in *nix systems, as long as your system have all the dependencies.
    "},{"location":"admin/install/source/#requirements","title":"Requirements","text":"
    To compile ejabberd you need:
     
       
    • GNU Make
      •  
    • GCC
      •  
    • Libexpat \u2265 1.95
      •  
    • Libyaml \u2265 0.1.4
      •  
    • Erlang/OTP \u2265 20.0. We recommend using Erlang OTP 25.3, which is the version used in the binary installers and container images.
      •  
    • OpenSSL \u2265 1.0.0
      •  
     
    Other optional libraries are:
     
       
    • Zlib \u2265 1.2.3, For Zlib Stream Compression
      •  
    • PAM library, for PAM Authentication
      •  
    • ImageMagick\u2019s Convert program and Ghostscript fonts, for CAPTCHA challenges.
      •  
    • Elixir \u2265 1.10.3, for Elixir Development. It is recommended Elixir 1.13.4 or higher and Erlang/OTP 23.0 or higher.
      •  
     
    If your system splits packages in libraries and development headers, install the development packages too.
     
    For example, in Debian:
     
    apt-get install libexpat1-dev libgd-dev libpam0g-dev \\\n                libsqlite3-dev libwebp-dev libyaml-dev \\\n                autoconf automake erlang elixir rebar3\n
    "},{"location":"admin/install/source/#download","title":"Download","text":"
    There are several ways to obtain the ejabberd source code:
     
       
    • Source code archive from ProcessOne Downloads
      •  
    • Source code package from ejabberd GitHub Releases
      •  
    • Latest development code from ejabberd Git repository
      •  
     
    The latest development source code can be retrieved from the Git repository using the commands:
     
    git clone git://github.com/processone/ejabberd.git\ncd ejabberd\n
    "},{"location":"admin/install/source/#compile","title":"Compile","text":"
    The general instructions to compile ejabberd are:
     
    ./autogen.sh\n./configure\nmake\n
     
    In this example, ./configure prepares the installed program to run with a user called ejabberd that should exist in the system (it isn't recommended to run ejabberd with root user):
     
    ./autogen.sh\n./configure --enable-user=ejabberd --enable-mysql\nmake\n
     
    make gets the dependencies and compiles everything.
     
    Note: To build ejabberd, you will need Internet access, as dependencies will be downloaded depending on the selected options.
    "},{"location":"admin/install/source/#configure","title":"./configure","text":"
    The build configuration script supports many options. Get the full list:
     
    ./configure --help\n
     
    Options details:
     
       
    •  
      --bindir=/: Specify the path to the user executables (where epmd and iex are available).
       
      •  
    •  
      --prefix=/: Specify the path prefix where the files will be copied when running the make install command.
       
      •  
    •  
      --with-rebar=/: Specify the path to rebar, rebar3 or   mix
       
       added in 20.12 and improved in 24.02
       
      •  
    •  
      --enable-user[=USER]: Allow this normal system user to execute the ejabberdctl script (see section ejabberdctl), read the configuration files, read and write in the spool directory, read and  write in the log directory. The account user and group must exist in  the machine before running make install. This account needs a HOME directory, because the Erlang cookie file will be created and read there.
       
      •  
    •  
      --enable-group[=GROUP]: Use this option additionally to --enable-user   when that account is in a group that doesn't coincide with its username.
       
      •  
    •  
      --enable-all: Enable many of the database and dependencies     options described here, this is useful for Dialyzer checks:     --enable-debug --enable-elixir --enable-mysql --enable-odbc     --enable-pam --enable-pgsql --enable-redis --enable-sip     --enable-sqlite --enable-stun --enable-tools --enable-zlib
       
      •  
    •  
      --disable-debug: Compile without +debug_info.
       
      •  
    •  
      --enable-elixir: Build ejabberd with Elixir extension support.     Works only with rebar3, not rebar2. Requires to have Elixir installed.     If interested in Elixir development, you may prefer to use --with-rebar=mix
       
       improved in 24.02
       
      •  
    •  
      --disable-erlang-version-check: Don't check Erlang/OTP version.
       
      •  
    •  
      --enable-full-xml: Use XML features in XMPP stream (ex: CDATA). This requires XML compliant clients).
       
      •  
    •  
      --enable-hipe: Compile natively with HiPE. This is an experimental feature, and not recommended.
       
      •  
    •  
      --enable-lager: Use lager Erlang logging tool instead of standard error logger.
       
      •  
    •  
      --enable-latest-deps: Makes rebar use latest versions of   dependencies developed alongside ejabberd instead of version   specified in rebar.config. Should be only used when developing   ejabberd.
       
      •  
    •  
      --enable-lua: Enable Lua support, to import from Prosody.
       
       added in 21.04
       
      •  
    •  
      --enable-mssql: Enable Microsoft SQL Server support, this     option requires --enable-odbc (see [Supported storages][18]).
       
      •  
    •  
      --enable-mysql: Enable MySQL support (see [Supported storages][18]).
       
      •  
    •  
      --enable-new-sql-schema: Use new SQL schema.
       
      •  
    •  
      --enable-odbc: Enable pure ODBC support.
       
      •  
    •  
      --enable-pam: Enable the PAM authentication method (see PAM Authentication section).
       
      •  
    •  
      --enable-pgsql: Enable PostgreSQL support (see [Supported storages][18]).
       
      •  
    •  
      --enable-redis: Enable Redis support to use for external session storage.
       
      •  
    •  
      --enable-roster-gateway-workaround: Turn on workaround for processing gateway subscriptions.
       
      •  
    •  
      --enable-sip: Enable SIP support.
       
      •  
    •  
      --enable-sqlite: Enable SQLite support (see [Supported storages][18]).
       
      •  
    •  
      --disable-stun: Disable STUN/TURN support.
       
      •  
    •  
      --enable-system-deps: Makes rebar use locally installed     dependencies instead of downloading them.
       
      •  
    •  
      --enable-tools: Enable the use of development tools.
       
       changed in 21.04
       
      •  
    •  
      --disable-zlib: Disable Stream Compression (XEP-0138) using zlib.
       
      •  
    "},{"location":"admin/install/source/#make","title":"make","text":"
    This tool is used to compile ejabberd and perform other tasks:
     
       
    • Get, update, compile dependencies; clean files
      •  
    • System install, uninstall
      •  
    • Build OTP production / development releases
      •  
    • Development: edoc, options, translations, tags
      •  
    • Testing: dialyzer, hooks, test, xref
      •  
     
    Get the full list and details:
     
    make help\n
    "},{"location":"admin/install/source/#install","title":"Install","text":"
    There are several ways to install and run the ejabberd compiled from source code: system install, building a production release, or building a development release.
    "},{"location":"admin/install/source/#system-install","title":"System Install","text":"
    To install ejabberd in the destination directories, run the command make install.
     
    Note that you probably need administrative privileges in the system to install ejabberd.
     
    The created files and directories depend on the options provided to ./configure, by default they are:
     
       
    •  
      /etc/ejabberd/:  Configuration directory:
       
         
      • ejabberd.yml:  ejabberd configuration file (see File Format)
        •  
      • ejabberdctl.cfg: Configuration file of the administration script (see Erlang Runtime System)
        •  
      • inetrc: Network DNS configuration file for Erlang
        •  
       
      •  
    •  
      /lib/ejabberd/:
       
         
      • ebin/: Erlang binary files (*.beam)
        •  
      • include/: Erlang header files (*.hrl)
        •  
      • priv/: Additional files required at runtime
        •  
      • bin/: Executable programs
        •  
      • lib/: Binary system libraries (*.so)
        •  
      • msgs/: Translation files (*.msgs) (see Default Language)
        •  
       
      •  
    •  
      /sbin/ejabberdctl: Administration script (see ejabberdctl)
       
      •  
    •  
      /share/doc/ejabberd/: Documentation of ejabberd
       
      •  
    •  
      /var/lib/ejabberd/: Spool directory:
       
         
      • .erlang.cookie: The Erlang cookie file
        •  
      • acl.DCD, ...: Mnesia database spool files (*.DCD, *.DCL, *.DAT)
        •  
       
      •  
    •  
      /var/log/ejabberd/: Log directory (see Logging):
       
         
      • ejabberd.log:   ejabberd service log
        •  
      • erlang.log:   Erlang/OTP system log
        •  
       
      •  
    "},{"location":"admin/install/source/#production-release","title":"Production Release","text":"
     improved in 21.07
     
    You can build an OTP release that includes ejabberd, Erlang/OTP and all the required erlang dependencies in a single tar.gz file. Then you can copy that file to another machine that has the same machine architecture, and run ejabberd without installing anything else.
     
    To build that production release, run:
     
    make prod\n
     
    If you provided to ./configure the option  --with-rebar to use rebar3 or mix, this will directly produce a tar.gz that you can copy.
     
    This example uses rebar3 to manage the compilation, builds an OTP production release, copies the resulting package to a temporary path, and starts ejabberd there:
     
    ./autogen.sh\n./configure --with-rebar=rebar3\nmake\nmake prod\nmkdir $HOME/eja-release\ntar -xzvf _build/prod/ejabberd-*.tar.gz -C $HOME/eja-release\n$HOME/eja-release/bin/ejabberdctl live\n
    "},{"location":"admin/install/source/#development-release","title":"Development Release","text":"
     new in 21.07
     
    If you provided to ./configure the option  --with-rebar to use rebar3 or mix, you can build an OTP development release.
     
    This is designed to run ejabberd in the local machine for development, manual testing... without installing in the system.
     
    This development release has some customizations: uses a dummy certificate file, if you register the account admin@localhost it has admin rights...
     
    This example uses Elixir's mix to manage the compilation, builds an OTP development release, and starts ejabberd there:
     
    ./autogen.sh\n./configure --with-rebar=mix\nmake\nmake dev\n_build/dev/rel/ejabberd/bin/ejabberdctl live\n
    "},{"location":"admin/install/source/#specific-notes","title":"Specific notes","text":""},{"location":"admin/install/source/#asdf","title":"asdf","text":"
    When Erlang/OTP (and/or Elixir) is installed using asdf (multiple runtime version manager), it is available only for your account, in $HOME/.asdf/shims/erl. In that case, you cannot install ejabberd globally in the system, and you cannot use the root account to start it, because that account doesn't have access to erlang.
     
    In that scenario, there are several ways to run/install ejabberd:
     
       
    •  
      Run a development release locally without installing
       
      •  
    •  
      Copy a production release locally
       
      •  
    •  
      Use system install, but install it locally:
       
      •  
     
    ./autogen.sh\n./configure --prefix=$HOME/eja-install --enable-user\nmake\nmake install\n$HOME/eja-install/sbin/ejabberdctl live\n
    "},{"location":"admin/install/source/#bsd","title":"BSD","text":"
    The command to compile ejabberd in BSD systems is gmake.
     
    You may want to check pkgsrc.se for ejabberd.
     
    Up to ejabberd 23.04, some old scripts where included in ejabberd source for NetBSD compilation, and you can take a look to those files for reference in ejabberd 23.04/examples/mtr/ path.
    "},{"location":"admin/install/source/#macos","title":"macOS","text":"
    If compiling from sources on Mac OS X, you must configure ejabberd to use custom OpenSSL, Yaml, iconv. The best approach is to use Homebrew to install your dependencies, then exports your custom path to let configure and make be aware of them.
     
    brew install git erlang elixir openssl expat libyaml libiconv libgd sqlite rebar rebar3 automake autoconf\nexport LDFLAGS=\"-L/usr/local/opt/openssl/lib -L/usr/local/lib -L/usr/local/opt/expat/lib\"\nexport CFLAGS=\"-I/usr/local/opt/openssl/include -I/usr/local/include -I/usr/local/opt/expat/include\"\nexport CPPFLAGS=\"-I/usr/local/opt/openssl/include/ -I/usr/local/include -I/usr/local/opt/expat/include\"\n./configure\nmake\n
     
    Check also the guide for Installing ejabberd development environment on OSX
    "},{"location":"admin/install/source/#start","title":"Start","text":"
    You can use the ejabberdctl command line administration script to start and stop ejabberd. Some examples, depending on your installation method:
     
       
    •  
      When installed in the system: 
      ejabberdctl start\n/sbin/ejabberdctl start\n
       
      •  
    •  
      When built an OTP production release: 
      _build/prod/rel/ejabberd/bin/ejabberdctl start\n_build/prod/rel/ejabberd/bin/ejabberdctl live\n
       
      •  
    •  
      Start interactively without installing or building OTP release: 
      make relive\n
       
      •  
    "},{"location":"admin/install/container/","title":"Install ejabberd using a Container Image","text":"
    There are two official container images of ejabberd that you can install using docker (or podman):
    "},{"location":"admin/install/container/#ejabberd-container-image","title":"ejabberd Container Image","text":"
    The \"ejabberd\" container image is available in the GitHub Container Registry. It is available for x64 and arm64, both for stable ejabberd releases and the master branch. Check the \"ejabberd\" container documentation.
     
    For example, download the latest stable ejabberd release:
     
    docker pull ghcr.io/processone/ejabberd\n
     
    If you use Microsoft Windows 7, 10, or similar operating systems, check those tutorials:
     
       
    • Install ejabberd on Windows 10 using Docker Desktop
      •  
    • Install ejabberd on Windows 7 using Docker Toolbox
      •  
     
    For bug reports and improvement suggestions, if you use the \"ecs\" container image please go to the docker-ejabberd GitHub Issues, if using the \"ejabberd\" container image from github please go to the ejabberd GitHub Issues
    "},{"location":"admin/install/container/#ecs-container-image","title":"ecs Container Image","text":"
    The \"ecs\" container image allows to get ejabberd stable releases in x64 machines. Check the \"ecs\" container documentation.
     
    Download ejabberd with:
     
    docker pull docker.io/ejabberd/ecs\n
    "},{"location":"admin/upgrade/","title":"Upgrade Procedure for ejabberd","text":"
    This document contains administration procedure for each version upgrade. Only upgrade from version N to N+1 is documented and supported. If you upgrade from an older version than previous one, you have to review all upgrade notes and apply each steps one by one for the possible database changes. You also have to stop your old ejabberd server, and start the new one.
     
    Until release note explicitly state you must restart the server for upgrade, you should be able to run soft upgrade using a cluster.  If you don't have cluster, upgrade from older release than previous one, or have explicit note soft upgrade does not work, then you have to fallback to standalone upgrade process.
    "},{"location":"admin/upgrade/#generic-upgrade-process","title":"Generic upgrade process","text":"
    This is the simplest process, and require service restart.
     
       
    • read the corresponding upgrade notes
      •  
    • apply the required changes in database from the upgrade note.
      •  
    • stop old node
      •  
    • archive content of mnesia database directory (database, i.e. /opt/ejabberd-XX.YY/database, /usr/local/var/lib/ejabberd, ...)
      •  
    • install new version
      •  
    • extract database archive in new path
      •  
    •  
      if systemctl is used to manage ejabberd, copy the new service file and reload systemctl: 
      cp ejabberd-21.12/bin/ejabberd.service /etc/systemd/system/\nsystemctl daemon-reload\n
       
      •  
    •  
      start new node
       
      •  
    "},{"location":"admin/upgrade/#soft-upgrade-process","title":"Soft upgrade process","text":"
    This process needs you to run in cluster, with at least two nodes. In this case, we assume you run node A and B with version N, and will upgrade to version N+1.
     
       
    • read the corresponding upgrade notes, make sure it does not explicitly states \"soft upgrade is not supported\".
      •  
    • apply the required changes in database from the upgrade note.
      •  
    • make sure node A is running
      •  
    • run leave_cluster on node B
      •  
    • stop old node B
      •  
    • install new version on B's host
      •  
    • start new node B
      •  
    • run join_cluster on node B, passing node A as parameter
      •  
    • make sure both nodes are running and working as expected
      •  
    • run leave_cluster on node A
      •  
    • stop old node A
      •  
    • install new version on A's host
      •  
    • start new node A
      •  
    • run join_cluster on node A, passing node B as parameter
      •  
    "},{"location":"admin/upgrade/#module-update-process","title":"Module update process","text":"
    Instead of upgrading all ejabberd to a brand new version, maybe you just want to update a few modules with bugfixes... in that case you can update only specific modules.
     
    This process is only recommended for bugfixes that involve functional changes, and do not involve structural or memory changes (those ones are usually detected and applied at server start only).
     
    How to do this?
     
       
    1. Apply the fixes to your source code, compile and reinstall ejabberd,    so the new *.beam files replace the old ones
      2.  
    2. In the ejabberd Web Admin go to Nodes -> your node -> Update
      3.  
    3. This will detect what *.beam files have changed in the installation
      4.  
    4. Select which modules you want to update now, and click Update
      5.  
    5. This will load into memory the corresponding *.beam files
      6.  
     
    If you prefer to use commands, check update_list + update.
     
    Notice this does not restart modules or any other tasks. If the fix you plan to apply requires a module restart, you can use this alternative: restart_module.
    "},{"location":"admin/upgrade/#note-on-database-schema-upgrade","title":"Note on database schema upgrade","text":"
    ejabberd automatically updates the Mnesia table definitions at startup when needed. If you also use an external database (like MySQL, ...) for storage of some modules, check in the corresponding upgrade notes of the new ejabberd version if you need to update those tables yourself manually.
    "},{"location":"admin/upgrade/#specific-version-upgrade-notes","title":"Specific version upgrade notes","text":"
    The corresponsing ugprade notes are available in the release notes of each release, and also available in the Archive section:
     
       
    • Upgrading from ejabberd 23.10 to 24.02
      •  
    • Upgrading from ejabberd 23.04 to 23.10
      •  
    • Upgrading from ejabberd 23.01 to 23.04
      •  
    • Upgrading from ejabberd 22.10 to 23.01
      •  
    • Upgrading from ejabberd 22.05 to 22.10
      •  
    • Upgrading from ejabberd 21.12 to 22.05
      •  
    • Upgrading from ejabberd 21.07 to 21.12
      •  
    • Upgrading from ejabberd 21.04 to 21.07
      •  
    • Upgrading from ejabberd 21.01 to 21.04
      •  
    • Upgrading from ejabberd 19.08 to 20.01
      •  
    • Upgrading from ejabberd 19.05 to 19.08
      •  
    • Upgrading from ejabberd 19.02 to 19.05
      •  
    • Upgrading from ejabberd 18.12 to 19.02
      •  
    • Upgrading from ejabberd 18.09 to 18.12
      •  
    • Upgrading from ejabberd 18.06 to 18.09
      •  
    • Upgrading from ejabberd 18.04 to 18.06
      •  
    • Upgrading from ejabberd 18.03 to 18.04
      •  
    • Upgrading from ejabberd 18.01 to 18.03
      •  
    • Upgrading from ejabberd 17.11 to 18.01
      •  
    • Upgrading from ejabberd 17.09 to 17.11
      •  
    • Upgrading from ejabberd \u226517.06 and \u226417.08 to 17.09
      •  
    • Upgrading from ejabberd 17.03 or 17.04 to 17.06
      •  
    • Upgrading from ejabberd \u226516.08 and \u226417.01 to 17.03
      •  
    • Upgrading from ejabberd 16.06 to 16.08
      •  
    • Upgrading from ejabberd 16.04 to 16.06
      •  
    • Upgrading from ejabberd 16.03 to 16.04
      •  
    • Upgrading from ejabberd 16.02 to 16.03
      •  
    • Upgrading from ejabberd 15.11 to 16.02
      •  
    • Upgrading from ejabberd 2.1.1x to 16.02
      •  
    "},{"location":"archive/","title":"Archived Documentation","text":"
    This section contains archived documentation of previous ejabberd releases. Please notice that it only contains the pages that most probably change between releases.
     
       
    • 24.02
      •  
    • 23.10
      •  
    • 23.04
      •  
    • 23.01
      •  
    • 22.10
      •  
    • 22.05
      •  
    • 21.12
      •  
    • 21.07
      •  
    • 21.04
      •  
    • 21.01
      •  
    • 20.12
      •  
    • 20.07
      •  
    • 20.04
      •  
    • 20.03
      •  
    • 20.02
      •  
    • 20.01
      •  
    "},{"location":"archive/20.01/","title":"Archived Documentation for 20.01","text":"
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • ejabberd 20.01 release announcement
      •  
    • ejabberd Github Compare from 19.09.1
      •  
    "},{"location":"archive/20.01/upgrade/","title":"Upgrade to ejabberd 20.01","text":""},{"location":"archive/20.01/upgrade/#database-changes","title":"Database changes","text":"
    To migrate from 19.08 (or 19.09) to 20.01, you have to use the following commands on your existing database, after you\u2019ve made a backup of it:
    "},{"location":"archive/20.01/upgrade/#mysql","title":"MySQL","text":"
    If you are using the legacy mysql.sql schema:
     
    ALTER TABLE  oauth_client CHANGE `client` `client_id` text PRIMARY KEY;\nALTER TABLE  oauth_client CHANGE `secret` `client_name` text NOT NULL;\n
     
    If you are using the newer mysql.new.sql schema:
     
    CREATE TABLE oauth_client (\n   client_id varchar(191) NOT NULL PRIMARY KEY,\n   client_name text NOT NULL,\n   grant_type text NOT NULL,\n   options text NOT NULL\n) ENGINE=InnoDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n
    "},{"location":"archive/20.01/upgrade/#postgresql","title":"PostgreSQL","text":"
    CREATE TABLE oauth_client (\n    client_id text PRIMARY KEY,\n    client_name text NOT NULL,\n    grant_type text NOT NULL,\n    options text NOT NULL\n);\nALTER TABLE oauth_client RENAME COLUMN client TO client_id;\nALTER TABLE oauth_client RENAME COLUMN secret TO client_name;\n
    "},{"location":"archive/20.02/","title":"Archived Documentation for 20.02","text":"
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • ejabberd 20.02 release announcement
      •  
    • ejabberd Github Compare from 20.01
      •  
    "},{"location":"archive/20.03/","title":"Archived Documentation for 20.03","text":"
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • ejabberd 20.03 release announcement
      •  
    • ejabberd Github Compare from 20.02
      •  
    "},{"location":"archive/20.04/","title":"Archived Documentation for 20.04","text":"
    This section contains some archived sections for ejabberd 20.04.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 20.04 release announcement
      •  
    • Docs Github Compare from 20.03
      •  
    • ejabberd Github Compare from 20.03
      •  
    "},{"location":"archive/20.07/","title":"Archived Documentation for 20.07","text":"
    This section contains some archived sections for ejabberd 20.07.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 20.07 release announcement
      •  
    • Docs Github Compare from 20.04
      •  
    • ejabberd Github Compare from 20.04
      •  
    "},{"location":"archive/20.12/","title":"Archived Documentation for 20.12","text":"
    This section contains some archived sections for ejabberd 20.12.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 20.12 release announcement
      •  
    • Docs Github Compare from 20.07
      •  
    • ejabberd Github Compare from 20.07
      •  
    "},{"location":"archive/21.01/","title":"Archived Documentation for 21.01","text":"
    This section contains some archived sections for ejabberd 21.01.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 21.01 release announcement
      •  
    • Docs Github Compare from 20.12
      •  
    • ejabberd Github Compare from 20.12
      •  
    "},{"location":"archive/21.04/","title":"Archived Documentation for 21.04","text":"
    This section contains some archived sections for ejabberd 21.04.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 21.04 release announcement
      •  
    • Docs Github Compare from 21.01
      •  
    • ejabberd Github Compare from 21.01
      •  
    "},{"location":"archive/21.04/upgrade/","title":"Upgrade to ejabberd 21.04","text":""},{"location":"archive/21.04/upgrade/#database-changes","title":"Database changes","text":""},{"location":"archive/21.04/upgrade/#mysql","title":"MySQL","text":"
    When migrating from any recent version to 21.04, you may want to apply this MySQL database definition improvement.
     
    We updated the database definition to fix the specified key was too long warnings. By default, the new character set and collation (utf8mb4 and utf8mb4_unicode_ci) will only be used with newly created databases. The existing installations don\u2019t need to convert anything.
     
    However, if you feel like it, after you upgrade to ejabberd 21.04, you can apply the following SQL command to convert your existing MySQL database character set to the latest definition:
     
    alter table push_session convert to character set utf8mb4 collate utf8mb4_unicode_ci;\nalter table mqtt_pub convert to character set utf8mb4 collate utf8mb4_unicode_ci;\n
    "},{"location":"archive/21.07/","title":"Archived Documentation for 21.07","text":"
    This section contains some archived sections for ejabberd 21.07.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 21.07 release announcement
      •  
    • Docs Github Compare from 21.04
      •  
    • ejabberd Github Compare from 21.04
      •  
    "},{"location":"archive/21.12/","title":"Archived Documentation for 21.12","text":"
    This section contains some archived sections for ejabberd 21.12.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 21.12 release announcement
      •  
    • Docs Github Compare from 21.07
      •  
    • ejabberd Github Compare from 21.07
      •  
    "},{"location":"archive/21.12/upgrade/","title":"Upgrade to ejabberd 21.12","text":""},{"location":"archive/21.12/upgrade/#postgresql-new-schema","title":"PostgreSQL new schema","text":"
    If you migrated your PostgreSQL database from old to new schema using previous ejabberd versions, your database may be missing the migration steps for the push_session table. You can update it now with: 
    ALTER TABLE push_session ADD COLUMN server_host text NOT NULL DEFAULT '<HOST>';\nDROP INDEX i_push_usn;\nDROP INDEX i_push_ut;\nALTER TABLE push_session ADD PRIMARY KEY (server_host, username, timestamp);\nCREATE UNIQUE INDEX i_push_session_susn ON push_session USING btree (server_host, username, service, node);\n
     
    In the PostgreSQL new schema, the primary key for the vcard_search table was wrong. How to update an existing database:
     
    ALTER TABLE vcard_search DROP CONSTRAINT vcard_search_pkey;\nALTER TABLE vcard_search ADD PRIMARY KEY (server_host, lusername);\n
    "},{"location":"archive/21.12/upgrade/#mod_register_web-restrictions","title":"mod_register_web restrictions","text":"
    mod_register_web is now affected by the restrictions that you configure in mod_register.
    "},{"location":"archive/22.05/","title":"Archived Documentation for 22.05","text":"
    This section contains some archived sections for ejabberd 22.05.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 22.05 release announcement
      •  
    • Docs Github Compare from 21.12
      •  
    • ejabberd Github Compare from 21.12
      •  
    "},{"location":"archive/22.05/upgrade/","title":"Upgrade to ejabberd 22.05","text":""},{"location":"archive/22.05/upgrade/#new-indexes-in-sql-for-muc","title":"New Indexes in SQL for MUC","text":"
    Two new indexes were added to optimize MUC. Those indexes can be added in the database before upgrading to 22.05, that will not affect older versions.
     
    To update an existing database, depending on the schema used to create it:
     
       
    •  
      MySQL (mysql.sql or mysql.new.sql): 
      CREATE INDEX i_muc_room_host_created_at ON muc_room(host(75), created_at);\nCREATE INDEX i_muc_room_subscribers_jid USING BTREE ON muc_room_subscribers(jid);\n
       
      •  
    •  
      PostgreSQL (pg.sql or pg.new.sql): 
      CREATE INDEX i_muc_room_host_created_at ON muc_room USING btree (host, created_at);\nCREATE INDEX i_muc_room_subscribers_jid ON muc_room_subscribers USING btree (jid);\n
       
      •  
    •  
      SQLite (lite.sql or lite.new.sql): 
      CREATE INDEX i_muc_room_host_created_at ON muc_room (host, created_at);\nCREATE INDEX i_muc_room_subscribers_jid ON muc_room_subscribers(jid);\n
       
      •  
    •  
      MS SQL (mssql.sql): 
      CREATE INDEX [muc_room_host_created_at] ON [muc_registered] (host, nick)\n    WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\nCREATE INDEX [muc_room_subscribers_jid] ON [muc_room_subscribers] (jid);\n
       
      •  
    "},{"location":"archive/22.05/upgrade/#fixes-in-postgresql-new-schema","title":"Fixes in PostgreSQL New Schema","text":"
    If you moved your PostgreSQL database from old to new schema using mod_admin_update_sql or the update_sql API command, be aware that those methods forgot to perform some updates.
     
    To fix an existing PostgreSQL database schema, apply those changes manually:
     
    ALTER TABLE archive DROP CONSTRAINT i_archive_sh_peer;\nALTER TABLE archive DROP CONSTRAINT i_archive_sh_bare_peer;\nCREATE INDEX i_archive_sh_username_peer ON archive USING btree (server_host, username, peer);\nCREATE INDEX i_archive_sh_username_bare_peer ON archive USING btree (server_host, username, bare_peer);\n\nDROP TABLE carboncopy;\n\nALTER TABLE push_session DROP CONSTRAINT i_push_session_susn;\nCREATE UNIQUE INDEX i_push_session_susn ON push_session USING btree (server_host, username, service, node);\n\nALTER TABLE mix_pam DROP CONSTRAINT i_mix_pam;\nALTER TABLE mix_pam DROP CONSTRAINT i_mix_pam_us;\nCREATE UNIQUE INDEX i_mix_pam ON mix_pam (username, server_host, channel, service);\nCREATE INDEX i_mix_pam_us ON mix_pam (username, server_host);\n\nALTER TABLE route DROP CONSTRAINT i_route;\nCREATE UNIQUE INDEX i_route ON route USING btree (domain, server_host, node, pid);\n\nALTER TABLE mqtt_pub DROP CONSTRAINT i_mqtt_topic;\nCREATE UNIQUE INDEX i_mqtt_topic_server ON mqtt_pub (topic, server_host);\n
    "},{"location":"archive/22.05/upgrade/#api-changes","title":"API Changes","text":"
    The oauth_revoke_token API command has changed its returned result. Check oauth_revoke_token documentation.
    "},{"location":"archive/22.10/","title":"Archived Documentation for 22.10","text":"
    This section contains some archived sections for ejabberd 22.10.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 22.10 release announcement
      •  
    • Docs Github Compare from 22.05
      •  
    • ejabberd Github Compare from 22.05
      •  
    "},{"location":"archive/22.10/upgrade/","title":"Upgrade to ejabberd 22.10","text":"
    There are no breaking changes in SQL schemas, configuration, or commands API. If you develop an ejabberd module, notice two hooks have changed: muc_subscribed and muc_unsubscribed.
    "},{"location":"archive/22.10/upgrade/#hook-changes","title":"Hook Changes","text":"
    Two hooks have changed: muc_subscribed and muc_unsubscribed. Now they get the packet and room state, and can modify the sent packets. If you write source code that adds functions to those hooks, please notice that previously they were ran like:
     
    ejabberd_hooks:run(muc_subscribed, ServerHost, [ServerHost, Room, Host, BareJID]);\n
     
    and now they are ran like this: 
    {Packet2a, Packet2b} = ejabberd_hooks:run_fold(muc_subscribed, ServerHost, {Packet1a, Packet1b},\n[ServerHost, Room, Host, BareJID, StateData]),\n
     being Packet1b a copy of Packet1a without the jid attribute in the muc_subscribe element.
    "},{"location":"archive/23.01/","title":"Archived Documentation for 23.01","text":"
    This section contains some archived sections for ejabberd 23.01.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 23.01 release announcement
      •  
    • Docs Github Compare from 22.10
      •  
    • ejabberd Github Compare from 22.10
      •  
    "},{"location":"archive/23.01/upgrade/","title":"Upgrade to ejabberd 23.01","text":"
    There is a new module, new hooks, new options, and some option accepts additional values, but there are no breaking changes in SQL schemas, configuration, or commands API.
     
    Please check the ejabberd 23.01 release announcement for details about the improvements.
    "},{"location":"archive/23.01/upgrade/#changes-in-option-outgoing_s2s_families","title":"Changes in option outgoing_s2s_families","text":"
    The outgoing_s2s_families top-level option specifies which address families to try, in what order.
     
    The default value has now been changed to try IPv6 first, as servers are within data centers where IPv6 is more commonly enabled (contrary to clients). And if it\u2019s not present, then it\u2019ll just fall back to IPv4.
     
    By the way, this option is obsolete and irrelevant when using ejabberd 23.01 and Erlang/OTP 22, or newer versions of them.
    "},{"location":"archive/23.04/","title":"Archived Documentation for 23.04","text":"
    This section contains some archived sections for ejabberd 23.04.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 23.04 release announcement
      •  
    • Docs Github Compare from 23.01
      •  
    • ejabberd Github Compare from 23.01
      •  
    "},{"location":"archive/23.04/upgrade/","title":"Upgrade to ejabberd 23.04","text":"
    There is a new module, new hooks, new options, and some option accepts additional values, and more importantly, there are many improvements in the SQL schemas, and a change in the ecs container image.
     
    Please check the ejabberd 23.04 release announcement for details about the improvements.
    "},{"location":"archive/23.04/upgrade/#many-improvements-in-sql-databases","title":"Many improvements in SQL databases","text":"
    There are many improvements in the SQL databases field (see #3980 and #3982):
     
       
    • Added support to migrate MySQL and MS SQL to new schema, fixed a long standing bug, and many other improvements.
      •  
    • Regarding MS SQL, there are schema fixes, added support to new schema, and the corresponding schema migration, along other minor improvements and bugfixes.
      •  
    • The automated ejabberd testing now also runs tests on upgraded schema databases, and supports for running tests on MS SQL
      •  
    • And also fixed other minor SQL schema inconsistencies, removed unnecessary indexes and changed PostgreSQL SERIAL to BIGSERIAL columns.
      •  
     
    Please upgrade your existing SQL database, check the notes later in this document!
    "},{"location":"archive/23.04/upgrade/#erlang-node-name-in-ecs-container-image","title":"Erlang node name in ecs container image","text":"
    The ecs container image is built using the files from docker-ejabberd/ecs, and published in docker.io/ejabberd/ecs. This image in general gets only minimal fixes, no major or breaking changes, but in this release it got a change that will require the administrator intervention.
     
    The Erlang node name is now by default fixed to ejabberd@localhost, instead of being variably set by the container host name. If you previously allowed ejabberd to decide its node name (which was random), then it will now create a new mnesia database instead of using the previous one: 
    $ docker exec -it ejabberd ls /home/ejabberd/database/\nejabberd@1ca968a0301a\nejabberd@localhost\n...\n
     
    A simple solution is to create the container providing ERLANG_NODE_ARG with the old erlang node name, for example: 
    docker run ... -e ERLANG_NODE_ARG=ejabberd@1ca968a0301a\n
     or in docker-compose.yml 
    version: '3.7'\nservices:\n  main:\n    image: ejabberd/ecs\n    environment:\n      - ERLANG_NODE_ARG=ejabberd@1ca968a0301a\n
     
    Another solution is to change the mnesia node name in the mnesia spool files.
    "},{"location":"archive/23.04/upgrade/#sql-databases-update","title":"SQL databases update","text":"
    Those notes allow to apply the improvements in the SQL database schemas from this ejabberd release to your existing SQL database. Please take into account what database you use, and whether it is the default or the new schema.
    "},{"location":"archive/23.04/upgrade/#postgresql-new-schema","title":"PostgreSQL new schema","text":"
    Fix a long standing bug in new schema on PostgreSQL. The fix for any existing impacted installations is the same: 
    ALTER TABLE vcard_search DROP CONSTRAINT vcard_search_pkey;\nALTER TABLE vcard_search ADD PRIMARY KEY (server_host, lusername);\n
    "},{"location":"archive/23.04/upgrade/#postgresql-defaultnew-schema","title":"PostgreSQL default/new schema","text":"
    To convert columns to allow up to 2 billion rows in these tables. This conversion will require full table rebuilds, and will take a long time if tables already have lots of rows. Optional: this is not necessary if the tables are never likely to grow large.
     
    ALTER TABLE archive ALTER COLUMN id TYPE BIGINT;\nALTER TABLE privacy_list ALTER COLUMN id TYPE BIGINT;\nALTER TABLE pubsub_node ALTER COLUMN nodeid TYPE BIGINT;\nALTER TABLE pubsub_state ALTER COLUMN stateid TYPE BIGINT;\nALTER TABLE spool ALTER COLUMN seq TYPE BIGINT;\n
    "},{"location":"archive/23.04/upgrade/#postgresqlsqlite-default-schema","title":"PostgreSQL/SQLite default schema","text":"
    DROP INDEX i_rosteru_username;\nDROP INDEX i_sr_user_jid;\nDROP INDEX i_privacy_list_username;\nDROP INDEX i_private_storage_username;\nDROP INDEX i_muc_online_users_us;\nDROP INDEX i_route_domain;\nDROP INDEX i_mix_participant_chan_serv;\nDROP INDEX i_mix_subscription_chan_serv_ud;\nDROP INDEX i_mix_subscription_chan_serv;\nDROP INDEX i_mix_pam_us;\n
    "},{"location":"archive/23.04/upgrade/#postgresqlsqlite-new-schema","title":"PostgreSQL/SQLite new schema","text":"
    DROP INDEX i_rosteru_sh_username;\nDROP INDEX i_sr_user_sh_jid;\nDROP INDEX i_privacy_list_sh_username;\nDROP INDEX i_private_storage_sh_username;\nDROP INDEX i_muc_online_users_us;\nDROP INDEX i_route_domain;\nDROP INDEX i_mix_participant_chan_serv;\nDROP INDEX i_mix_subscription_chan_serv_ud;\nDROP INDEX i_mix_subscription_chan_serv;\nDROP INDEX i_mix_pam_us;\n
     
    And now add index that might be missing
     
    In PostgreSQL: 
    CREATE INDEX i_push_session_sh_username_timestamp ON push_session USING btree (server_host, username, timestamp);\n
     
    In SQLite: 
    CREATE INDEX i_push_session_sh_username_timestamp ON push_session (server_host, username, timestamp);\n
    "},{"location":"archive/23.04/upgrade/#mysql-default-schema","title":"MySQL default schema","text":"
    ALTER TABLE rosterusers DROP INDEX i_rosteru_username;\nALTER TABLE sr_user DROP INDEX i_sr_user_jid;\nALTER TABLE privacy_list DROP INDEX i_privacy_list_username;\nALTER TABLE private_storage DROP INDEX i_private_storage_username;\nALTER TABLE muc_online_users DROP INDEX i_muc_online_users_us;\nALTER TABLE route DROP INDEX i_route_domain;\nALTER TABLE mix_participant DROP INDEX i_mix_participant_chan_serv;\nALTER TABLE mix_subscription DROP INDEX i_mix_subscription_chan_serv_ud;\nALTER TABLE mix_subscription DROP INDEX i_mix_subscription_chan_serv;\nALTER TABLE mix_pam DROP INDEX i_mix_pam_u;\n
    "},{"location":"archive/23.04/upgrade/#mysql-new-schema","title":"MySQL new schema","text":"
    ALTER TABLE rosterusers DROP INDEX i_rosteru_sh_username;\nALTER TABLE sr_user DROP INDEX i_sr_user_sh_jid;\nALTER TABLE privacy_list DROP INDEX i_privacy_list_sh_username;\nALTER TABLE private_storage DROP INDEX i_private_storage_sh_username;\nALTER TABLE muc_online_users DROP INDEX i_muc_online_users_us;\nALTER TABLE route DROP INDEX i_route_domain;\nALTER TABLE mix_participant DROP INDEX i_mix_participant_chan_serv;\nALTER TABLE mix_subscription DROP INDEX i_mix_subscription_chan_serv_ud;\nALTER TABLE mix_subscription DROP INDEX i_mix_subscription_chan_serv;\nALTER TABLE mix_pam DROP INDEX i_mix_pam_us;\n
     Add index that might be missing: 
    CREATE INDEX i_push_session_sh_username_timestamp ON push_session (server_host, username(191), timestamp);\n
    "},{"location":"archive/23.04/upgrade/#ms-sql","title":"MS SQL","text":"
    DROP INDEX [rosterusers_username] ON [rosterusers];\nDROP INDEX [sr_user_jid] ON [sr_user];\nDROP INDEX [privacy_list_username] ON [privacy_list];\nDROP INDEX [private_storage_username] ON [private_storage];\nDROP INDEX [muc_online_users_us] ON [muc_online_users];\nDROP INDEX [route_domain] ON [route];\ngo\n
     
    MS SQL schema was missing some tables added in earlier versions of ejabberd:
     
    CREATE TABLE [dbo].[mix_channel] (\n    [channel] [varchar] (250) NOT NULL,\n    [service] [varchar] (250) NOT NULL,\n    [username] [varchar] (250) NOT NULL,\n    [domain] [varchar] (250) NOT NULL,\n    [jid] [varchar] (250) NOT NULL,\n    [hidden] [smallint] NOT NULL,\n    [hmac_key] [text] NOT NULL,\n    [created_at] [datetime] NOT NULL DEFAULT GETDATE()\n) TEXTIMAGE_ON [PRIMARY];\n\nCREATE UNIQUE CLUSTERED INDEX [mix_channel] ON [mix_channel] (channel, service)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE INDEX [mix_channel_serv] ON [mix_channel] (service)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE TABLE [dbo].[mix_participant] (\n    [channel] [varchar] (250) NOT NULL,\n    [service] [varchar] (250) NOT NULL,\n    [username] [varchar] (250) NOT NULL,\n    [domain] [varchar] (250) NOT NULL,\n    [jid] [varchar] (250) NOT NULL,\n    [id] [text] NOT NULL,\n    [nick] [text] NOT NULL,\n    [created_at] [datetime] NOT NULL DEFAULT GETDATE()\n) TEXTIMAGE_ON [PRIMARY];\n\nCREATE UNIQUE INDEX [mix_participant] ON [mix_participant] (channel, service, username, domain)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE INDEX [mix_participant_chan_serv] ON [mix_participant] (channel, service)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE TABLE [dbo].[mix_subscription] (\n    [channel] [varchar] (250) NOT NULL,\n    [service] [varchar] (250) NOT NULL,\n    [username] [varchar] (250) NOT NULL,\n    [domain] [varchar] (250) NOT NULL,\n    [node] [varchar] (250) NOT NULL,\n    [jid] [varchar] (250) NOT NULL\n);\n\nCREATE UNIQUE INDEX [mix_subscription] ON [mix_subscription] (channel, service, username, domain, node)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE INDEX [mix_subscription_chan_serv_ud] ON [mix_subscription] (channel, service, username, domain)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE INDEX [mix_subscription_chan_serv_node] ON [mix_subscription] (channel, service, node)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE INDEX [mix_subscription_chan_serv] ON [mix_subscription] (channel, service)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE TABLE [dbo].[mix_pam] (\n    [username] [varchar] (250) NOT NULL,\n    [channel] [varchar] (250) NOT NULL,\n    [service] [varchar] (250) NOT NULL,\n    [id] [text] NOT NULL,\n    [created_at] [datetime] NOT NULL DEFAULT GETDATE()\n) TEXTIMAGE_ON [PRIMARY];\n\nCREATE UNIQUE CLUSTERED INDEX [mix_pam] ON [mix_pam] (username, channel, service)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\ngo\n
     
    MS SQL also had some incompatible column types:
     
    ALTER TABLE [dbo].[muc_online_room] ALTER COLUMN [node] VARCHAR (250);\nALTER TABLE [dbo].[muc_online_room] ALTER COLUMN [pid] VARCHAR (100);\nALTER TABLE [dbo].[muc_online_users] ALTER COLUMN [node] VARCHAR (250);\nALTER TABLE [dbo].[pubsub_node_option] ALTER COLUMN [name] VARCHAR (250);\nALTER TABLE [dbo].[pubsub_node_option] ALTER COLUMN [val] VARCHAR (250);\nALTER TABLE [dbo].[pubsub_node] ALTER COLUMN [plugin] VARCHAR (32);\ngo\n
     
    ... and mqtt_pub table was incorrectly defined in old schema:
     
    ALTER TABLE [dbo].[mqtt_pub] DROP CONSTRAINT [i_mqtt_topic_server];\nALTER TABLE [dbo].[mqtt_pub] DROP COLUMN [server_host];\nALTER TABLE [dbo].[mqtt_pub] ALTER COLUMN [resource] VARCHAR (250);\nALTER TABLE [dbo].[mqtt_pub] ALTER COLUMN [topic] VARCHAR (250);\nALTER TABLE [dbo].[mqtt_pub] ALTER COLUMN [username] VARCHAR (250);\nCREATE UNIQUE CLUSTERED INDEX [dbo].[mqtt_topic] ON [mqtt_pub] (topic)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\ngo\n
     
    ... and sr_group index/PK was inconsistent with other DBs:
     
    ALTER TABLE [dbo].[sr_group] DROP CONSTRAINT [sr_group_PRIMARY];\nCREATE UNIQUE CLUSTERED INDEX [sr_group_name] ON [sr_group] ([name])\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\ngo\n
    "},{"location":"archive/23.10/","title":"Archived Documentation for 23.10","text":"
    This section contains some archived sections for ejabberd 23.10.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 23.10 release announcement
      •  
    • Docs Github Compare from 23.04
      •  
    • ejabberd Github Compare from 23.04
      •  
    "},{"location":"archive/23.10/upgrade/","title":"Upgrade to ejabberd 23.10","text":"
    There is a new module, several new options, an API command has changed, but there are no breaking changes in the configuration, SQL schema.
     
    The get_roster API command has a different output, please check the release announcement for details.
     
    The MUC room option allow_private_messages is converted to allowpm. This conversion is automatic, you don't need to perform any task. However, once you update to ejabberd 23.10, the stored rooms options will be converted, and you should not attempt to use that content with ejabberd versions older than 23.10.
     
    gen_mod API is simplified. If you write your own ejabberd modules, you can optionally use that new API.
     
    In summary, you can update from previous ejabberd version to this one without performing any upgrade tasks.
     
    Please check the ejabberd 23.10 release announcement for details about the improvements.
    "},{"location":"archive/24.02/","title":"Archived Documentation for 24.02","text":"
    This section contains some archived sections for ejabberd 24.02.
     
    If you are upgrading ejabberd from a previous release, you can check:
     
       
    • Specific version upgrade notes
      •  
    • ejabberd 24.02 release announcement
      •  
    • Docs Github Compare from 24.02
      •  
    • ejabberd Github Compare from 24.02
      •  
    "},{"location":"archive/24.02/upgrade/","title":"Upgrade to ejabberd 24.02","text":"
    If you upgrade ejabberd from a previous release to 24.02, please review those changes:
     
       
    • Update the SQL schema
      •  
    • Update API commands as explained below, or use API versioning
      •  
    • Mix or Rebar3 used by default instead of Rebar to compile ejabberd
      •  
    • Authentication workaround for Converse.js and Strophe.js
      •  
    "},{"location":"archive/24.02/upgrade/#update-the-sql-schema","title":"Update the SQL schema","text":"
    The table archive has a text column named origin_id (see commit 975681). You have two methods to update the SQL schema of your existing database:
     
    If using MySQL or PosgreSQL, you can enable the option update_sql_schema and ejabberd will take care to update the SQL schema when needed: add in your ejabberd configuration file the line update_sql_schema: true
     
    If you are using other database, or prefer to update manually the SQL schema:
     
       
    •  
      MySQL default schema: 
      ALTER TABLE archive ADD COLUMN origin_id text NOT NULL DEFAULT '';\nALTER TABLE archive ALTER COLUMN origin_id DROP DEFAULT;\nCREATE INDEX i_archive_username_origin_id USING BTREE ON archive(username(191), origin_id(191));\n
       
      •  
    •  
      MySQL new schema: 
      ALTER TABLE archive ADD COLUMN origin_id text NOT NULL DEFAULT '';\nALTER TABLE archive ALTER COLUMN origin_id DROP DEFAULT;\nCREATE INDEX i_archive_sh_username_origin_id USING BTREE ON archive(server_host(191), username(191), origin_id(191));\n
       
      •  
    •  
      PostgreSQL default schema: 
      ALTER TABLE archive ADD COLUMN origin_id text NOT NULL DEFAULT '';\nALTER TABLE archive ALTER COLUMN origin_id DROP DEFAULT;\nCREATE INDEX i_archive_username_origin_id ON archive USING btree (username, origin_id);\n
       
      •  
    •  
      PostgreSQL new schema: 
      ALTER TABLE archive ADD COLUMN origin_id text NOT NULL DEFAULT '';\nALTER TABLE archive ALTER COLUMN origin_id DROP DEFAULT;\nCREATE INDEX i_archive_sh_username_origin_id ON archive USING btree (server_host, username, origin_id);\n
       
      •  
    •  
      MSSQL default schema: 
      ALTER TABLE [dbo].[archive] ADD [origin_id] VARCHAR (250) NOT NULL;\nCREATE INDEX [archive_username_origin_id] ON [archive] (username, origin_id)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n
       
      •  
    •  
      MSSQL new schema: 
      ALTER TABLE [dbo].[archive] ADD [origin_id] VARCHAR (250) NOT NULL;\nCREATE INDEX [archive_sh_username_origin_id] ON [archive] (server_host, username, origin_id)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n
       
      •  
    •  
      SQLite default schema: 
      ALTER TABLE archive ADD COLUMN origin_id text NOT NULL DEFAULT '';\nCREATE INDEX i_archive_username_origin_id ON archive (username, origin_id);\n
       
      •  
    •  
      SQLite new schema: 
      ALTER TABLE archive ADD COLUMN origin_id text NOT NULL DEFAULT '';\nCREATE INDEX i_archive_sh_username_origin_id ON archive (server_host, username, origin_id);\n
       
      •  
    "},{"location":"archive/24.02/upgrade/#support-for-api-versioning","title":"Support for API versioning","text":"
    Until now, when a new ejabberd release changed some API command (an argument renamed, a result in a different format...), then you had to update your API client to the new API at the same time that you updated ejabberd.
     
    Now the ejabberd API commands can have different versions, by default the most recent one is used, and the API client can specify the API version it supports.
     
    In fact, this feature was implemented seven years ago, included in ejabberd 16.04, documented in ejabberd Docs: API Versioning... but it was never actually used!
     
    This ejabberd release includes many fixes to get API versioning up to date, and it starts being used by several commands.
     
    Let's say that ejabberd 23.10 implemented API version 0, and this ejabberd 24.02 adds API version 1. You may want to update your API client to use the new API version 1... or you can continue using API version 0 and delay API update a few weeks or months.
     
    To continue using API version 0: - if using ejabberdctl, use the switch --version 0. For example: ejabberdctl --version 0 get_roster admin localhost - if using mod_http_api, in ejabberd configuration file add v0 to the request_handlers path. For example: /api/v0: mod_http_api
     
    Check the ejabberd 24.02 full release notes for more details about the changed commands.
     
    Check the full documentation in ejabberd Docs: API Versioning.
    "},{"location":"archive/24.02/upgrade/#use-mix-or-rebar3-by-default-instead-of-rebar-to-compile-ejabberd","title":"Use Mix or Rebar3 by default instead of Rebar to compile ejabberd","text":"
    ejabberd uses Rebar to manage dependencies and compilation since ejabberd 13.10 4d8f770. However, that tool is obsolete and unmaintained since years ago, because there is a complete replacement:
     
    Rebar3 is supported by ejabberd since 20.12 0fc1aea. Among other benefits, this allows to download dependencies from hex.pm and cache them in your system instead of downloading them from git every time, and allows to compile Elixir files and Elixir dependencies.
     
    In fact, ejabberd can be compiled using mix (a tool included with the Elixir programming language) since ejabberd 15.04 ea8db99 (with improvements in ejabberd 21.07 4c5641a)
     
    For those reasons, the tool selection performed by ./configure will now be:
     
       
    • If --with-rebar=rebar3 but Rebar3 not found installed in the system, use the rebar3 binary included with ejabberd
      •  
    • Use the program specified in option: --with-rebar=/path/to/bin
      •  
    • If none is specified, use the system mix
      •  
    • If Elixir not found, use the system rebar3
      •  
    • If Rebar3 not found, use the rebar3 binary included with ejabberd
      •  
    "},{"location":"archive/24.02/upgrade/#authentication-workaround-for-conversejs-and-strophejs","title":"Authentication workaround for Converse.js and Strophe.js","text":"
    This ejabberd release includes support for XEP-0474: SASL SCRAM Downgrade Protection, and some clients may not support it correctly yet.
     
    If you are using Converse.js 10.1.6 or older, Movim 0.23 Kojima or older, or any other client based in Strophe.js v1.6.2 or older, you may notice that they cannot authenticate correctly to ejabberd.
     
    To solve that problem, either update to newer versions of those programs (if they exist), or you can enable temporarily the option disable_sasl_scram_downgrade_protection in the ejabberd configuration file ejabberd.yml like this: 
    disable_sasl_scram_downgrade_protection: true\n
    "},{"location":"archive/older-releases/from_15.11_to_16.02/","title":"Upgrade to ejabberd 16.02","text":"
    The MySQL schema changed to UTF-8 encoding. If you are using MySQL backend you must upgrade the schema before starting ejabberd 16.02.
    "},{"location":"archive/older-releases/from_15.11_to_16.02/#sql-database-upgrade","title":"SQL database upgrade","text":"
    Example for MySQL: 
    mysql -h host -u user database -p << EOF\nALTER DATABASE ejabberd CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nALTER TABLE users CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE users MODIFY username varchar(191);\n\nALTER TABLE last CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE last MODIFY username varchar(191);\n\nALTER TABLE rosterusers CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE rosterusers MODIFY username varchar(191);\nALTER TABLE rosterusers MODIFY jid varchar(191);\n\nALTER TABLE rostergroups CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE rostergroups MODIFY username varchar(191);\nALTER TABLE rostergroups MODIFY jid varchar(191);\n\nALTER TABLE sr_group CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE sr_group MODIFY username varchar(191);\n\nALTER TABLE spool CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE spool MODIFY username varchar(191);\nALTER TABLE spool MODIFY xml BLOB NOT NULL;\n\nALTER TABLE archive CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE archive MODIFY username varchar(191);\nALTER TABLE archive MODIFY peer varchar(191);\nALTER TABLE archive MODIFY bare_peer varchar(191);\nALTER TABLE archive MODIFY nick varchar(191);\n\nALTER TABLE archive_prefs CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE archive_prefs MODIFY username varchar(191);\n\nALTER TABLE vcard CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE vcard MODIFY username varchar(191);\n\nALTER TABLE vcard_xupdate CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE vcard_xupdate MODIFY username varchar(191);\n\nALTER TABLE vcard_search CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE vcard_search MODIFY username varchar(191);\nALTER TABLE vcard_search MODIFY lusername varchar(191);\nALTER TABLE vcard_search MODIFY lfn varchar(191);\nALTER TABLE vcard_search MODIFY lfamily varchar(191);\nALTER TABLE vcard_search MODIFY lgiven varchar(191);\nALTER TABLE vcard_search MODIFY lmiddle varchar(191);\nALTER TABLE vcard_search MODIFY lnickname varchar(191);\nALTER TABLE vcard_search MODIFY lbday varchar(191);\nALTER TABLE vcard_search MODIFY lctry varchar(191);\nALTER TABLE vcard_search MODIFY llocality varchar(191);\nALTER TABLE vcard_search MODIFY lemail varchar(191);\nALTER TABLE vcard_search MODIFY lorgname varchar(191);\nALTER TABLE vcard_search MODIFY lorgunit varchar(191);\n\nALTER TABLE privacy_default_list CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE privacy_default_list MODIFY username varchar(191);\nALTER TABLE privacy_default_list MODIFY name varchar(191);\n\nALTER TABLE privacy_list CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE privacy_list MODIFY username varchar(191);\nALTER TABLE privacy_list MODIFY name varchar(191);\n\nALTER TABLE privacy_list_data CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nALTER TABLE private_storage CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE private_storage MODIFY username varchar(191);\nALTER TABLE private_storage MODIFY namespace varchar(191);\n\nALTER TABLE roster_version CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE roster_version MODIFY username varchar(191);\n\nALTER TABLE pubsub_node CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE pubsub_node_option CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE pubsub_node_state CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE pubsub_node_item CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE pubsub_subscription_opt CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nALTER TABLE muc_room CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE muc_registered CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nALTER TABLE irc_custom CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nALTER TABLE motd CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE motd MODIFY username varchar(191);\n\nALTER TABLE caps_features CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE caps_features MODIFY node varchar(191);\nALTER TABLE caps_features MODIFY subnode varchar(191);\n\nALTER TABLE sm CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE sm MODIFY username varchar(191);\nALTER TABLE sm MODIFY resource varchar(191);\n\nALTER TABLE  CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nALTER TABLE  MODIFY username varchar(191);\nEOF\n
    "},{"location":"archive/older-releases/from_16.02_to_16.03/","title":"Upgrade to ejabberd 16.03","text":"
    If you are using an sql backend for authentication, you must upgrade your schema before starting ejabberd 16.03. This can be safely done while a previous version of ejabberd is actually running.
    "},{"location":"archive/older-releases/from_16.02_to_16.03/#sql-database-upgrade","title":"SQL database upgrade","text":"
    Example for MySQL: 
    mysql -h host -u user database -p << EOF\nALTER TABLE users ADD COLUMN serverkey text NOT NULL DEFAULT '';\nALTER TABLE users ADD COLUMN salt text NOT NULL DEFAULT '';\nALTER TABLE users ADD COLUMN iterationcount integer NOT NULL DEFAULT 0;\nEOF\n
    "},{"location":"archive/older-releases/from_16.03_to_16.04/","title":"Upgrade to ejabberd 16.04","text":"
    Two data type must be changed on the users table. This can be done at any time while ejabberd 16.03 is running. If you run an older version of ejabberd you must follow database upgrade process for 16.03 first.
     
    Note: this applies only to MySQL. Other backend does not need upgrade.
    "},{"location":"archive/older-releases/from_16.03_to_16.04/#mysql-database-upgrade","title":"MySQL database upgrade","text":"
    mysql -h host -u user database -p << EOF\nALTER TABLE users MODIFY serverkey varchar(64) NOT NULL DEFAULT '';\nALTER TABLE users MODIFY salt varchar(64) NOT NULL DEFAULT '';\nEOF\n
    "},{"location":"archive/older-releases/from_16.04_to_16.06/","title":"Upgrade to ejabberd 16.06","text":"
    One data type must be changed on the users table. This can be done at any time while ejabberd 16.04 is running. If you run an older version of ejabberd you must follow database upgrade process for 16.03 and 16.04 first.
     
    Note: this applies only to MySQL. Other backend does not need upgrade.
    "},{"location":"archive/older-releases/from_16.04_to_16.06/#mysql-database-upgrade","title":"MySQL database upgrade","text":"
    mysql -h host -u user database -p << EOF\nALTER TABLE muc_room MODIFY opts mediumtext NOT NULL;\nEOF\n
    "},{"location":"archive/older-releases/from_16.06_to_16.08/","title":"Upgrade to ejabberd 16.08","text":"
    You need to create a new table to support the new OAuth feature before starting ejabberd 16.08.
    "},{"location":"archive/older-releases/from_16.06_to_16.08/#sql-database-upgrade","title":"SQL database upgrade","text":"
    Example for MySQL: 
    mysql -h host -u user database -p << EOF\nCREATE TABLE oauth_token (\n  token varchar(191) NOT NULL PRIMARY KEY,\n  jid text NOT NULL,\n  scope text NOT NULL,\n  expire bigint NOT NULL\n) ENGINE=InnoDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\nEOF\n
    "},{"location":"archive/older-releases/from_16.08_to_17.03/","title":"Upgrade to ejabberd 17.03","text":"
    If you are upgrading from ejabberd 16.08, 16.09, 16.12 or 17.01, and are using an SQL backend, you need to alter tables for better PubSub support before starting ejabberd 17.03.
    "},{"location":"archive/older-releases/from_16.08_to_17.03/#mysql-database-upgrade","title":"MySQL database upgrade","text":"
    If you're running MySQL, this change in not mandatory but highly recommended
     
    mysql -h host -u user database -p << EOF\nALTER TABLE rosterusers MODIFY subscribe text NOT NULL;\n\nUPDATE pubsub_node SET parent='' WHERE parent=NULL;\n\nALTER TABLE pubsub_node\n MODIFY host TEXT NOT NULL,\n MODIFY node TEXT NOT NULL,\n MODIFY parent VARCHAR(191) NOT NULL DEFAULT '',\n MODIFY type TEXT NOT NULL;\n\nALTER TABLE pubsub_node_option \n MODIFY name text NOT NULL,\n MODIFY val text NOT NULL;\n\nALTER TABLE pubsub_node_owner\n MODIFY owner text NOT NULL;\n\nUPDATE pubsub_state SET subscriptions='' WHERE subscriptions=NULL;\n\nALTER TABLE pubsub_state\n MODIFY jid text NOT NULL,\n MODIFY subscriptions VARCHAR(191) NOT NULL DEFAULT '';\n\nALTER TABLE pubsub_item\n MODIFY itemid text NOT NULL,\n MODIFY publisher text NOT NULL,\n MODIFY creation text NOT NULL,\n MODIFY modification text NOT NULL,\n MODIFY payload text NOT NULL;\n\nALTER TABLE pubsub_subscription_opt\n MODIFY subid text NOT NULL,\n MODIFY opt_value text NOT NULL;\nEOF\n
    "},{"location":"archive/older-releases/from_16.08_to_17.03/#postgresql-database-upgrade","title":"PostgreSQL database upgrade","text":"
    If you're running PostgreSQL, this change is mandatory.
     
    psql -W -h host database user << EOF\nALTER TABLE rosterusers ALTER COLUMN subscribe SET NOT NULL;\n\nUPDATE pubsub_node SET parent='' WHERE parent=NULL;\n\nALTER TABLE pubsub_node\nALTER COLUMN host SET NOT NULL,\nALTER COLUMN node SET NOT NULL,\nALTER COLUMN parent SET NOT NULL,\nALTER COLUMN parent SET DEFAULT '',\nALTER COLUMN type SET NOT NULL;\n\nALTER TABLE pubsub_node_option \nALTER COLUMN name SET NOT NULL,\nALTER COLUMN val SET NOT NULL;\n\nALTER TABLE pubsub_node_owner\nALTER COLUMN  owner SET NOT NULL;\n\nUPDATE pubsub_state SET subscriptions='' WHERE subscriptions=NULL;\n\nALTER TABLE pubsub_state\nALTER COLUMN jid SET NOT NULL,\nALTER COLUMN subscriptions SET NOT NULL,\nALTER COLUMN subscriptions SET DEFAULT '';\n\nALTER TABLE pubsub_item\nALTER COLUMN itemid SET NOT NULL,\nALTER COLUMN publisher SET NOT NULL,\nALTER COLUMN creation SET NOT NULL,\nALTER COLUMN modification SET NOT NULL,\nALTER COLUMN payload SET NOT NULL;\n\nALTER TABLE pubsub_subscription_opt\nALTER COLUMN subid SET NOT NULL,\nALTER COLUMN opt_value SET NOT NULL;\nEOF\n
    "},{"location":"archive/older-releases/from_16.08_to_17.03/#sqlite-database-upgrade","title":"SQLite database upgrade","text":"
    If you're running SQLite, you have to create a new database with schema file provided in ejabberd 17.03 sources. Then you have to export all data from your current database and import into the newly created database.
    "},{"location":"archive/older-releases/from_16.08_to_17.03/#mssql-database-upgrade","title":"MsSQL database upgrade","text":"
    We do not provide tested upgrade procedure on MsSQL Server. The upgrade may not be mandatory (this was not tested) but highly recommended. You have to create a new database with schema file provided in ejabberd 17.03 sources. Then you have to export all data from your current database and import into the newly created database.
    "},{"location":"archive/older-releases/from_17.03_to_17.06/","title":"Upgrade to ejabberd 17.06","text":"
    You may have to apply few changes if you are upgrading from ejabberd 17.03 or 17.04. While this is not mandatory, it's recommended to follow this procedure.
    "},{"location":"archive/older-releases/from_17.03_to_17.06/#ejabberdctl-script","title":"ejabberdctl script","text":"
    Due to a major refactor of the ejabberdctl script, which also remove all bashisms, you should check your packaging and your system's version of ejabberdctl script. While old script still works, you are encouraged to use the new one. This may depends on media you install ejabberd from.
    "},{"location":"archive/older-releases/from_17.03_to_17.06/#database","title":"Database","text":"
    There are no changes on database schema since 17.03 which requires migration procedure. However, we removed the vcard_xupdate table. If you want to cleanup your database, you can remove that table, as it is no longer used by the module.
    "},{"location":"archive/older-releases/from_17.06_to_17.09/","title":"Upgrade to ejabberd 17.09","text":"
    You should follow this procedure if you are upgrading from ejabberd 17.06, 17.07 or 17.08.
    "},{"location":"archive/older-releases/from_17.06_to_17.09/#ejabberdctl-script","title":"ejabberdctl script","text":"
    Due to a major refactor of the ejabberdctl script, you should check your packaging and your system's version of ejabberdctl script. While old script still works, you are encouraged to use the new one. This may depends on media you install ejabberd from.
    "},{"location":"archive/older-releases/from_17.09_to_17.11/","title":"Upgrade to ejabberd 17.11","text":"
    You should follow this procedure if you are upgrading from ejabberd 17.09 and running an SQL backend for archives (mod_mam) and/or PubSub (mod_pubsub) and/or MucSub (mod_muc) and/or push (mod_push).
    "},{"location":"archive/older-releases/from_17.09_to_17.11/#system","title":"System","text":"
    For best experience with new ACME features, it's recommended to install inotify-tools package on Linux. This allows automatic certificates reload. Other systems should be fine without adding extra dependency.
    "},{"location":"archive/older-releases/from_17.09_to_17.11/#database","title":"Database","text":"
    There is a minor change on indexes of archive table on SQL backend. This change gives speed improvements on archive requests. You have to open a client connected to your ejabberd database, and run the following commands. Note: if your archive table is big, this action may take a while to complete.
     
    There is a column rename in pubsub_node table, to avoid using reserved words and need extra quoting which may not be supported on all backends. You MUST apply this upgrade procedure if you're using PubSub with an SQL backend.
     
    There are two new tables, one which allows optimization on mucsub subscriptions, and another one needed by mod_push.
    "},{"location":"archive/older-releases/from_17.09_to_17.11/#mysql","title":"MySQL","text":"
    DROP INDEX i_username ON archive;\nCREATE INDEX i_username_timestamp USING BTREE ON archive(username,timestamp);\n\nALTER TABLE pubsub_node CHANGE type plugin text NOT NULL;\n\nCREATE TABLE muc_room_subscribers (\n   room varchar(191) NOT NULL,\n   host varchar(191) NOT NULL,\n   jid varchar(191) NOT NULL,\n   nick text NOT NULL,\n   nodes text NOT NULL,\n   created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,\n  UNIQUE KEY i_muc_room_subscribers_host_room_jid (host, room, jid)\n) ENGINE=InnoDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nCREATE INDEX i_muc_room_subscribers_host_jid USING BTREE ON muc_room_subscribers(host, jid);\n\nCREATE TABLE push_session (\n    username text NOT NULL,\n    timestamp bigint NOT NULL,\n    service text NOT NULL,\n    node text NOT NULL,\n    xml text NOT NULL\n);\n\nCREATE UNIQUE INDEX i_push_usn ON push_session (username(191), service(191), node(191));\nCREATE UNIQUE INDEX i_push_ut ON push_session (username(191), timestamp);\n
    "},{"location":"archive/older-releases/from_17.09_to_17.11/#postgresql","title":"PostgreSQL","text":"
    DROP INDEX i_username;\nCREATE INDEX i_username_timestamp ON archive USING btree (username, timestamp);\n\nALTER TABLE pubsub_node RENAME COLUMN type TO plugin;\n\nCREATE TABLE muc_room_subscribers (\n   room text NOT NULL,\n   host text NOT NULL,\n   jid text NOT NULL,\n   nick text NOT NULL,\n   nodes text NOT NULL,\n   created_at TIMESTAMP NOT NULL DEFAULT now()\n);\n\nCREATE INDEX i_muc_room_subscribers_host_jid ON muc_room_subscribers USING btree (host, jid);\nCREATE UNIQUE INDEX i_muc_room_subscribers_host_room_jid ON muc_room_subscribers USING btree (host, room, jid);\n\nCREATE TABLE push_session (\n    username text NOT NULL,\n    timestamp bigint NOT NULL,\n    service text NOT NULL,\n    node text NOT NULL,\n    xml text NOT NULL\n);\n\nCREATE UNIQUE INDEX i_push_usn ON push_session USING btree (username, service, node);\nCREATE UNIQUE INDEX i_push_ut ON push_session USING btree (username, timestamp);\n
    "},{"location":"archive/older-releases/from_17.09_to_17.11/#sqlite","title":"SQLite","text":"
    DROP INDEX i_username ON archive;\nCREATE INDEX i_username_timestamp ON archive(username, timestamp);\n\nALTER TABLE pubsub_node ADD plugin text NOT NULL;\nUPDATE pubsub_node SET plugin = type;\nALTER TABLE pubsub_node DROP COLUMN type;\n\nCREATE TABLE muc_room_subscribers (\n   room text NOT NULL,\n   host text NOT NULL,\n   jid text NOT NULL,\n   nick text NOT NULL,\n   nodes text NOT NULL,\n   created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE INDEX i_muc_room_subscribers_host_jid ON muc_room_subscribers(host, jid);\nCREATE UNIQUE INDEX i_muc_room_subscribers_host_room_jid ON muc_room_subscribers(host, room, jid);\n\nCREATE TABLE push_session (\n    username text NOT NULL,\n    timestamp bigint NOT NULL,\n    service text NOT NULL,\n    node text NOT NULL,\n    xml text NOT NULL\n);\n\nCREATE UNIQUE INDEX i_push_usn ON push_session (username, service, node);\nCREATE UNIQUE INDEX i_push_ut ON push_session (username, timestamp);\n
    "},{"location":"archive/older-releases/from_17.09_to_17.11/#mssql","title":"MsSQL","text":"
    DROP INDEX [archive_username] ON [archive];\nCREATE INDEX [archive_username_timestamp] ON [archive] (username, timestamp)\n WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nEXEC sp_rename '[dbo].[pubsub_node].[type]', 'plugin';\n\nCREATE TABLE [dbo].[muc_room_subscribers] (\n        [room] [varchar] (191) NOT NULL,\n        [host] [varchar] (191) NOT NULL,\n        [jid] [varchar] (191) NOT NULL,\n        [nick] [text] NOT NULL,\n        [nodes] [text] NOT NULL,\n        [created_at] [datetime] NOT NULL DEFAULT GETDATE()\n);\n\nCREATE UNIQUE CLUSTERED INDEX [muc_room_subscribers_host_room_jid] ON [muc_room_subscribers] (host, room, jid);\nCREATE INDEX [muc_room_subscribers_host_jid] ON [muc_room_subscribers] (host, jid);\n\nCREATE TABLE [dbo].[push_session] (\n    [username] [varchar] (255) NOT NULL,\n    [timestamp] [bigint] NOT NULL,\n    [service] [varchar] (255) NOT NULL,\n    [node] [varchar] (255) NOT NULL,\n    [xml] [varchar] (255) NOT NULL\n);\n\nCREATE UNIQUE CLUSTERED INDEX [i_push_usn] ON [push_session] (username, service, node)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n\nCREATE UNIQUE CLUSTERED INDEX [i_push_ut] ON [push_session] (username, timestamp)\nWITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n
    "},{"location":"archive/older-releases/from_17.11_to_18.01/","title":"Upgrade to ejabberd 18.01","text":"
    There is no significant change in code and database since 17.11. There is no specific upgrade procedure. Anyway, due to TLS improvements and ACME support, you need to check your configuration to keep it up-to-date with latest patterns.
    "},{"location":"archive/older-releases/from_17.11_to_18.01/#ejabberd-configuration","title":"ejabberd configuration","text":"
    While your old ejabberd.yml is still supported, you may prefer to simplify it thanks to latest TLS driver which enables good defaults by itself. You may also need to use the new ACME feature, which requires minor changes in ejabberd configuration file. See ejabberd.yml.example in ejabberd sources for reference.
    "},{"location":"archive/older-releases/from_18.01_to_18.03/","title":"Upgrade to ejabberd 18.03","text":"
    You should follow this procedure if you are upgrading from ejabberd 18.01 and running an SQL backend for archives (mod_mam). You should also have a look at all new configuration options.
    "},{"location":"archive/older-releases/from_18.01_to_18.03/#database","title":"Database","text":"
    There is a change on indexes of archive table on SQL backend. Peer is now indexed and old indexes must be updated to reflect this change. You must open an sql client connected to your ejabberd database, and run the following commands. Note: if your archive table is big, this action may take a while to complete.
    "},{"location":"archive/older-releases/from_18.01_to_18.03/#mysql","title":"MySQL","text":"
    DROP INDEX i_username_timestamp ON archive;\nDROP INDEX i_peer ON archive;\nDROP INDEX i_bare_peer ON archive;\nCREATE INDEX i_username_timestamp USING BTREE ON archive(username(191), timestamp);\nCREATE INDEX i_username_peer USING BTREE ON archive(username(191), peer(191));\nCREATE INDEX i_username_bare_peer USING BTREE ON archive(username(191), bare_peer(191));\n
    "},{"location":"archive/older-releases/from_18.01_to_18.03/#postgresql","title":"PostgreSQL","text":"
    DROP INDEX i_peer ON archive;\nDROP INDEX i_bare_peer ON archive;\nCREATE INDEX i_username_peer ON archive USING btree (username, peer);\nCREATE INDEX i_username_bare_peer ON archive USING btree (username, bare_peer);\n
    "},{"location":"archive/older-releases/from_18.01_to_18.03/#sqlite","title":"Sqlite","text":"
    DROP INDEX i_peer ON archive;\nDROP INDEX i_bare_peer ON archive;\nCREATE INDEX i_archive_username_peer ON archive (username, peer);\nCREATE INDEX i_archive_username_bare_peer ON archive (username, bare_peer);\n
    "},{"location":"archive/older-releases/from_18.01_to_18.03/#mssql","title":"MsSql","text":"
    DROP INDEX [archive_username_timestamp] ON [archive];\nDROP INDEX [archive_peer] ON [archive];\nDROP INDEX [archive_bare_peer] ON [archive];\nCREATE INDEX [archive_username_peer] ON [archive] (username, peer)\n WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\nCREATE INDEX [archive_username_bare_peer] ON [archive] (username, bare_peer)\n WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\nCREATE INDEX [archive_timestamp] ON [archive] (timestamp)\n WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON);\n
    "},{"location":"archive/older-releases/from_18.01_to_18.03/#ejabberd-configuration","title":"ejabberd configuration","text":"
    There are many new configuration option. We highly recommend to read details on release blogpost for good understanding of changes that may impact your configuration.
    "},{"location":"archive/older-releases/from_18.03_to_18.04/","title":"Upgrade to ejabberd 18.04","text":"
    You may follow this procedure if you are upgrading from ejabberd 18.03 or older, and running an SQL backend for PubSub.
    "},{"location":"archive/older-releases/from_18.03_to_18.04/#database","title":"Database","text":"
    There is a change on pubsub_item table on SQL backend. The type of creation and modification changed from 'text' to 'varchar(32)'. This change will speedup requests reading and sorting items. Note: if you're happy with performances, you don't need to apply this change.
    "},{"location":"archive/older-releases/from_18.03_to_18.04/#mysql","title":"MySQL","text":"
    ALTER TABLE pubsub_item\n MODIFY creation varchar(32) NOT NULL,\n MODIFY modification varchar(32) NOT NULL;\n
    "},{"location":"archive/older-releases/from_18.03_to_18.04/#postgresql","title":"PostgreSQL","text":"
    ALTER TABLE pubsub_item\n ALTER COLUMN creation TYPE varchar(32),\n ALTER COLUMN creation SET NOT NULL,\n ALTER COLUMN modification TYPE varchar(32),\n ALTER COLUMN modification SET NOT NULL;\n
    "},{"location":"archive/older-releases/from_18.03_to_18.04/#sqlite","title":"Sqlite","text":"
    ALTER TABLE pubsub_item\n MODIFY creation varchar(32) NOT NULL,\n MODIFY modification varchar(32) NOT NULL;\n
    "},{"location":"archive/older-releases/from_18.03_to_18.04/#mssql","title":"MsSql","text":"
    Note: We do not provide tested upgrade procedure on MsSQL Server. Following query should to the conversion. If you have problems with it please create an issue on ejabberd's github page. 
    ALTER TABLE [pubsub_item]\n ALTER COLUMN creation varchar(32) NOT NULL,\n ALTER COLUMN modification varchar(32) NOT NULL;\n
    "},{"location":"archive/older-releases/from_18.04_to_18.06/","title":"Upgrade to ejabberd 18.06","text":"
    There are few option changes in this version. Please check the blogpost: https://www.process-one.net/blog/ejabberd-18-06/
     
    Note: Starting with ejabberd 18.06, ejabberd will not ignore unknown options and doesn't allow to have options with malformed values. The rationale for this is to avoid unexpected behaviour during runtime, i.e. to conform to \u201cfail early\u201d approach. FOR PACKAGE BUILDERS: You must ensure your configuration is valid.
     
    You may cleanup SQL database if you are upgrading from ejabberd 18.04 or older, and running an SQL backend for mod_irc.
    "},{"location":"archive/older-releases/from_18.04_to_18.06/#database","title":"Database","text":"
    mod_irc had been obsoleted, the module is still available in ejabberd-contrib and can be installed as external module anyway. If you're not using that module or stop using it, you can safely remove the irc_custom SQL table.
    "},{"location":"archive/older-releases/from_18.06_to_18.09/","title":"Upgrade to ejabberd 18.09","text":"
    You need to update your database schema if you're using MySQL. Else there is no special upgrade process for this version.
    "},{"location":"archive/older-releases/from_18.06_to_18.09/#database","title":"Database","text":""},{"location":"archive/older-releases/from_18.06_to_18.09/#mysql","title":"MySQL","text":"
    When using stanza larger than 64 KiB, payload were silently trunced by MySQL. This raised errors when ejabberd was trying to read the content of the database.
     
    You need to alter your MySQL schema if you're using big stanzas and archive on offline table. Else you can simply dismiss this change. Note: this operation can take a long time with large archives.
     
    mysql -h host -u user database -p << EOF\nALTER TABLE spool MODIFY xml mediumtext NOT NULL;\nALTER TABLE archive MODIFY xml mediumtext NOT NULL;\nALTER TABLE archive MODIFY txt mediumtext;\nALTER TABLE pubsub_item MODIFY payload mediumtext NOT NULL;\nEOF\n
    "},{"location":"archive/older-releases/from_18.09_to_18.12/","title":"Upgrade to ejabberd 18.12","text":"
    You may need to update your database schema if you're using MySQL. A minor change on pubsub_item table was added right after 18.09 release and your schema may not have been updated already.
     
    If your users are using bookmarks, you also must migrate them to PEP before starting the service.
     
    If you're using ProcessOne installers, you must be aware API and all web ports can use TLS, and served on port 5443 instead of 5280 in this case. Using TLS requires you to generate a valid certificate. If you're a packager, we recommend to apply this change when possible.
    "},{"location":"archive/older-releases/from_18.09_to_18.12/#bookmarks-and-xep-0411","title":"Bookmarks and XEP-0411","text":"
    As ejabberd now supports XEP-0411, you must perform some actions before starting the service. If your users are NOT USING bookmarks, you can dismiss this. 
    $ for host in $(ejabberdctl registered-vhosts); do\n      ejabberdctl registered-users \"$host\" | while read user; do\n          ejabberdctl bookmarks-to-pep \"$user\" \"$host\"\n      done\n  done\n
     This might take a while if the number of users is large. Also note that this will overwrite any preexisting PEP bookmarks. However, if this is not performed, users might end up with empty bookmark lists after upgrading to the new ejabberd version, as clients might rely on PEP bookmarks once they detect that ejabberd's XEP-0411 support.  
    "},{"location":"archive/older-releases/from_18.09_to_18.12/#database","title":"Database","text":""},{"location":"archive/older-releases/from_18.09_to_18.12/#mysql","title":"MySQL","text":"
    When using stanza larger than 64 KiB, payload were silently trunced by MySQL. This raised errors when ejabberd was trying to read the content of the database.
     
    You not done yet, you need to alter your MySQL schema if you're using big stanzas on for pubsub items. Else you can simply dismiss this change.
     
    mysql -h host -u user database -p << EOF\nALTER TABLE pubsub_item MODIFY payload mediumtext NOT NULL;\nEOF\n
    "},{"location":"archive/older-releases/from_18.12_to_19.02/","title":"Upgrade to ejabberd 19.02","text":"
    19.02 adds support of latest MIX specification and MQTT protocol. You may improve your current configuration or SQL schema depending on your needs.
    "},{"location":"archive/older-releases/from_18.12_to_19.02/#configuration","title":"Configuration","text":"
    To enable MQTT, you need to add a new listener and enable mod_mqtt. Here is example of configuration:
     
    listen:\n  -\n    port: 1883\n    ip: \"::\"\n    module: mod_mqtt\n    backlog: 1000\n\nmodules:\n  mod_mqtt: {}\n
    "},{"location":"archive/older-releases/from_18.12_to_19.02/#database","title":"Database","text":"
    If you want to use latest MIX (XEP-0369) with an SQL backend then you have to create new tables.
     
    If you have issues using PEP and MySQL, you should update your schema.
    "},{"location":"archive/older-releases/from_18.12_to_19.02/#mysql","title":"MySQL","text":"
    When using PEP with MySQL, due to limitation in size of indexes, some long JIDs could have broken support. Index size on pubsub_node was modified to fix use of PEP. This change is optional and required only if you have issues when using PEP.
     
    mysql -h host -u user database -p << EOF\nDROP INDEX i_pubsub_node_tuple ON pubsub_node;\nCREATE UNIQUE INDEX i_pubsub_node_tuple ON pubsub_node(host(71), node(120));\nEOF\n
     
    If you want to use new MIX implementation, you must create some tables.
     
    CREATE TABLE mix_channel (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    jid text NOT NULL,\n    hidden boolean NOT NULL,\n    hmac_key text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n) ENGINE=InnoDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nCREATE UNIQUE INDEX i_mix_channel ON mix_channel (channel(191), service(191));\nCREATE INDEX i_mix_channel_serv ON mix_channel (service(191));\n\nCREATE TABLE mix_participant (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    jid text NOT NULL,\n    id text NOT NULL,\n    nick text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n) ENGINE=InnoDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nCREATE UNIQUE INDEX i_mix_participant ON mix_participant (channel(191), service(191), username(191), domain(191));\nCREATE INDEX i_mix_participant_chan_serv ON mix_participant (channel(191), service(191));\n\nCREATE TABLE mix_subscription (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    node text NOT NULL,\n    jid text NOT NULL\n) ENGINE=InnoDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nCREATE UNIQUE INDEX i_mix_subscription ON mix_subscription (channel(153), service(153), username(153), domain(153), node(153));\nCREATE INDEX i_mix_subscription_chan_serv_ud ON mix_subscription (channel(191), service(191), username(191), domain(191));\nCREATE INDEX i_mix_subscription_chan_serv_node ON mix_subscription (channel(191), service(191), node(191));\nCREATE INDEX i_mix_subscription_chan_serv ON mix_subscription (channel(191), service(191));\n\nCREATE TABLE mix_pam (\n    username text NOT NULL,\n    channel text NOT NULL,\n    service text NOT NULL,\n    id text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n) ENGINE=InnoDB CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n\nCREATE UNIQUE INDEX i_mix_pam ON mix_pam (username(191), channel(191), service(191));\nCREATE INDEX i_mix_pam_u ON mix_pam (username(191));\n
     
    If you want to use new MQTT feature, you need to create a table.
     
    If you're using the new schema (new_sql_schema):
     
    CREATE TABLE mqtt_pub (\n    username varchar(191) NOT NULL,\n    server_host varchar(191) NOT NULL,\n    resource varchar(191) NOT NULL,\n    topic text NOT NULL,\n    qos tinyint NOT NULL,\n    payload blob NOT NULL,\n    payload_format tinyint NOT NULL,\n    content_type text NOT NULL,\n    response_topic text NOT NULL,\n    correlation_data blob NOT NULL,\n    user_properties blob NOT NULL,\n    expiry int unsigned NOT NULL,\n    UNIQUE KEY i_mqtt_topic_server (topic(191))\n);\n
     
    If you're using the old schema:
     
    CREATE TABLE mqtt_pub (\n    username varchar(191) NOT NULL,\n    resource varchar(191) NOT NULL,\n    topic text NOT NULL,\n    qos tinyint NOT NULL,\n    payload blob NOT NULL,\n    payload_format tinyint NOT NULL,\n    content_type text NOT NULL,\n    response_topic text NOT NULL,\n    correlation_data blob NOT NULL,\n    user_properties blob NOT NULL,\n    expiry int unsigned NOT NULL,\n    UNIQUE KEY i_mqtt_topic (topic(191))\n);\n
    "},{"location":"archive/older-releases/from_18.12_to_19.02/#postgresql","title":"PostgreSQL","text":"
    If you want to use new MIX implementation, you must create some tables.
     
    CREATE TABLE mix_channel (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    jid text NOT NULL,\n    hidden boolean NOT NULL,\n    hmac_key text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE UNIQUE INDEX i_mix_channel ON mix_channel (channel, service);\nCREATE INDEX i_mix_channel_serv ON mix_channel (service);\n\nCREATE TABLE mix_participant (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    jid text NOT NULL,\n    id text NOT NULL,\n    nick text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE UNIQUE INDEX i_mix_participant ON mix_participant (channel, service, username, domain);\nCREATE INDEX i_mix_participant_chan_serv ON mix_participant (channel, service);\n\nCREATE TABLE mix_subscription (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    node text NOT NULL,\n    jid text NOT NULL\n);\n\nCREATE UNIQUE INDEX i_mix_subscription ON mix_subscription (channel, service, username, domain, node);\nCREATE INDEX i_mix_subscription_chan_serv_ud ON mix_subscription (channel, service, username, domain);\nCREATE INDEX i_mix_subscription_chan_serv_node ON mix_subscription (channel, service, node);\nCREATE INDEX i_mix_subscription_chan_serv ON mix_subscription (channel, service);\n\nCREATE TABLE mix_pam (\n    username text NOT NULL,\n    channel text NOT NULL,\n    service text NOT NULL,\n    id text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE UNIQUE INDEX i_mix_pam ON mix_pam (username, channel, service);\nCREATE INDEX i_mix_pam_us ON mix_pam (username);\n
     
    If you want to use new MQTT feature, you need to create a table.
     
    If you're using the new schema (new_sql_schema):
     
    CREATE TABLE mqtt_pub (\n    username text NOT NULL,\n    server_host text NOT NULL,\n    resource text NOT NULL,\n    topic text NOT NULL,\n    qos smallint NOT NULL,\n    payload bytea NOT NULL,\n    payload_format smallint NOT NULL,\n    content_type text NOT NULL,\n    response_topic text NOT NULL,\n    correlation_data bytea NOT NULL,\n    user_properties bytea NOT NULL,\n    expiry bigint NOT NULL\n);\n\nCREATE UNIQUE INDEX i_mqtt_topic_server ON mqtt_pub (topic, server_host);\n
     
    If you're using the old schema:
     
    CREATE TABLE mqtt_pub (\n    username text NOT NULL,\n    resource text NOT NULL,\n    topic text NOT NULL,\n    qos smallint NOT NULL,\n    payload bytea NOT NULL,\n    payload_format smallint NOT NULL,\n    content_type text NOT NULL,\n    response_topic text NOT NULL,\n    correlation_data bytea NOT NULL,\n    user_properties bytea NOT NULL,\n    expiry bigint NOT NULL\n);\n\nCREATE UNIQUE INDEX i_mqtt_topic ON mqtt_pub (topic, server_host);\n
    "},{"location":"archive/older-releases/from_18.12_to_19.02/#sqlite","title":"SQLite","text":"
    If you want to use new MIX implementation, you must create some tables.
     
    CREATE TABLE mix_channel (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    jid text NOT NULL,\n    hidden boolean NOT NULL,\n    hmac_key text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE UNIQUE INDEX i_mix_channel ON mix_channel (channel, service);\nCREATE INDEX i_mix_channel_serv ON mix_channel (service);\n\nCREATE TABLE mix_participant (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    jid text NOT NULL,\n    id text NOT NULL,\n    nick text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE UNIQUE INDEX i_mix_participant ON mix_participant (channel, service, username, domain);\nCREATE INDEX i_mix_participant_chan_serv ON mix_participant (channel, service);\n\nCREATE TABLE mix_subscription (\n    channel text NOT NULL,\n    service text NOT NULL,\n    username text NOT NULL,\n    domain text NOT NULL,\n    node text NOT NULL,\n    jid text NOT NULL\n);\n\nCREATE UNIQUE INDEX i_mix_subscription ON mix_subscription (channel, service, username, domain, node);\nCREATE INDEX i_mix_subscription_chan_serv_ud ON mix_subscription (channel, service, username, domain);\nCREATE INDEX i_mix_subscription_chan_serv_node ON mix_subscription (channel, service, node);\nCREATE INDEX i_mix_subscription_chan_serv ON mix_subscription (channel, service);\n\nCREATE TABLE mix_pam (\n    username text NOT NULL,\n    channel text NOT NULL,\n    service text NOT NULL,\n    id text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE UNIQUE INDEX i_mix_pam ON mix_pam (username, channel, service);\nCREATE INDEX i_mix_pam_us ON mix_pam (username);\n
     
    If you want to use new MQTT feature, you need to create a table.
     
    If you're using the new schema (new_sql_schema):
     
    CREATE TABLE mqtt_pub (\n    username text NOT NULL,\n    server_host text NOT NULL,\n    resource text NOT NULL,\n    topic text NOT NULL,\n    qos smallint NOT NULL,\n    payload blob NOT NULL,\n    payload_format smallint NOT NULL,\n    content_type text NOT NULL,\n    response_topic text NOT NULL,\n    correlation_data blob NOT NULL,\n    user_properties blob NOT NULL,\n    expiry bigint NOT NULL\n);\n\nCREATE UNIQUE INDEX i_mqtt_topic_server ON mqtt_pub (topic);\n
     
    If you're using the old schema:
     
    CREATE TABLE mqtt_pub (\n    username text NOT NULL,\n    resource text NOT NULL,\n    topic text NOT NULL,\n    qos smallint NOT NULL,\n    payload blob NOT NULL,\n    payload_format smallint NOT NULL,\n    content_type text NOT NULL,\n    response_topic text NOT NULL,\n    correlation_data blob NOT NULL,\n    user_properties blob NOT NULL,\n    expiry bigint NOT NULL\n);\n\nCREATE UNIQUE INDEX i_mqtt_topic ON mqtt_pub (topic);\n
    "},{"location":"archive/older-releases/from_19.02_to_19.05/","title":"Upgrade to ejabberd 19.05","text":"
    19.05 don't add changes on data or configuration. You may alter your configuration if you want to use new feature to store offline messages in archives anyway. See more details on blogpost.
    "},{"location":"archive/older-releases/from_19.02_to_19.05/#database","title":"Database","text":"
    Schema for MQTT tables was added after 19.02 release despite full support was already available. If you're using MQTT and need SQL backend, in case you dismissed the change, please report to ejabberd 19.02 upgrade note
    "},{"location":"archive/older-releases/from_19.05_to_19.08/","title":"Upgrade to ejabberd 19.08","text":""},{"location":"archive/older-releases/from_19.05_to_19.08/#database","title":"Database","text":"
    Riak support has been removed in this version, so don't upgrade to 19.08 if you store data in Riak.
     
    The only SQL schema that changed since 19.05 is mysql.new.sql.
    "},{"location":"archive/older-releases/from_19.05_to_19.08/#mysql","title":"MySQL","text":"
    mysql.new.sql from 19.05 schema can work 19.08, so the migration to 19.08 schema is optional, as it's just a type change from TEXT to VARCHAR for performances reason, but it will improve index utilization.
     
    ALTER TABLE users MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE last MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE rosterusers MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE rostergroups MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE sr_group MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE sr_user MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE spool MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE archive MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE archive_prefs MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE vcard MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE vcard_search MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE privacy_default_list MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE privacy_list MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE private_storage MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE roster_version MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE muc_room MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE muc_registered MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE muc_online_room MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE muc_online_users MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE motd MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE sm MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE route MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE push_session MODIFY server_host varchar(191) NOT NULL;\nALTER TABLE mix_pam MODIFY server_host varchar(191) NOT NULL;\n
    "},{"location":"archive/older-releases/from_19.05_to_19.08/#api-changes","title":"API changes","text":""},{"location":"archive/older-releases/from_19.05_to_19.08/#renamed-arguments-from-server-to-host","title":"Renamed arguments from Server to Host","text":"
    Several ejabberd commands still used as argument name Server, instead of the more common Host. Such arguments have been renamed, and backward support allows old calls to work correctly.
     
    The eight commands affected are: \u2013 add_rosteritem \u2013 bookmarks_to_pep \u2013 delete_rosteritem \u2013 get_offline_count \u2013 get_presence \u2013 get_roster \u2013 remove_mam_for_user \u2013 remove_mam_for_user_with_peer
     
    If you are using this calls, please start updating your parameter names to Host when moving to ejabberd 19.08. You will thus use a more consistent API and be future proof.
    "},{"location":"archive/older-releases/from_2.1.1x_to_16.02/","title":"Upgrade from 2.1.1x to 16.02","text":""},{"location":"archive/older-releases/from_2.1.1x_to_16.02/#compilation","title":"Compilation","text":"
    Compilation requires Erlang/OTP R17 or higher. Requires OpenSSL 1.0.0 or higher. exmpp is not required anymore. The mysql and pgsql erlang libraries are now included in ejabberd source code.
     
    The source code structure has improved: - The compilation scripts are moved from src/ to /, including configure and Makefile. - Source code of complex modules is moved from src/*/*.erl to src/*.erl - The SQL example files are moved from src/odbc/*.sql to sql/*.sql
     
    The configuration file now uses YAML syntax, not the Erlang syntax. For that reason, the file is now named ejabberd.yml, not ejabberd.cfg You have three options: - You can use and adapt the new file ejabberd.yml.example - You can still use your old ejabberd.cfg - You can convert your old config file to YAML with the command: ejabberdctl convert_to_yaml
    "},{"location":"archive/older-releases/from_2.1.1x_to_16.02/#ejabberd-upgrade-process","title":"Ejabberd upgrade process","text":"
    If you are using an sql backend for authentication, you need to upgrade your schema before starting ejabberd 16.02. This can be safely done while a previous version of ejabberd is actually running.
    "},{"location":"archive/older-releases/from_2.1.1x_to_16.02/#mysql-database-upgrade","title":"MySQL database upgrade","text":"
    mysql -h host -u user database -p << EOF\n\n-- Table for mod_caps: Entity Capabilities (XEP-0115)\nCREATE TABLE caps_features (\n    node varchar(250) NOT NULL,\n    subnode varchar(250) NOT NULL,\n    feature text,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n) CHARACTER SET utf8;\nCREATE INDEX i_caps_features_node_subnode ON caps_features(node(75), subnode(75));\n\n-- Make it possible to use SQL as an SM backend:\nCREATE TABLE sm (\n    usec bigint NOT NULL,\n    pid text NOT NULL,\n    node text NOT NULL,\n    username varchar(250) NOT NULL,\n    resource varchar(250) NOT NULL,\n    priority text NOT NULL,\n    info text NOT NULL\n) ENGINE=InnoDB CHARACTER SET utf8;\nCREATE UNIQUE INDEX i_sid ON sm(usec, pid(75));\nCREATE INDEX i_node ON sm(node(75));\nCREATE INDEX i_username ON sm(username);\n\n-- Support delete_old_messages (offline) command:\nCREATE INDEX i_spool_created_at USING BTREE ON spool(created_at);\n\n-- Add a missed SQL index on privacy_list_data table\nCREATE INDEX i_privacy_list_data_id ON privacy_list_data(id);\n\n-- Add SCRAM support to ejabberd_auth_odbc\nALTER TABLE users ADD COLUMN serverkey text NOT NULL;\nALTER TABLE users ADD COLUMN salt text NOT NULL;\nALTER TABLE users ADD COLUMN iterationcount integer NOT NULL DEFAULT 0;\n\n-- mod_mam (XEP-0313) support\nCREATE TABLE archive (\n    username varchar(250) NOT NULL,\n    timestamp BIGINT UNSIGNED NOT NULL,\n    peer varchar(250) NOT NULL,\n    bare_peer varchar(250) NOT NULL,\n    xml text NOT NULL,\n    txt text,\n    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT UNIQUE,\n    kind varchar(10),\n    nick varchar(250),\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n) ENGINE=InnoDB CHARACTER SET utf8;\nCREATE FULLTEXT INDEX i_text ON archive(txt);\nCREATE INDEX i_username USING BTREE ON archive(username);\nCREATE INDEX i_timestamp USING BTREE ON archive(timestamp);\nCREATE INDEX i_peer USING BTREE ON archive(peer);\nCREATE INDEX i_bare_peer USING BTREE ON archive(bare_peer);\nCREATE TABLE archive_prefs (\n    username varchar(250) NOT NULL PRIMARY KEY,\n    def text NOT NULL,\n    always text NOT NULL,\n    never text NOT NULL,\n    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP\n) ENGINE=InnoDB CHARACTER SET utf8;\n\n-- In Offline storage use BLOB instead of TEXT\nALTER TABLE spool MODIFY xml BLOB NOT NULL;\n\n-- Use UTF8MB4 character set in MySQL tables\n--\n-- TODO\n-- Commit: Use UTF8MB4 character set in MySQL tables\n--         7d1c75d0e817db0e04fe1133e06ba35cd367d76e\n--\nEOF\n
    "},{"location":"archive/older-releases/from_2.1.1x_to_16.02/#pgsql-database-upgrade","title":"PgSQL database upgrade","text":"
    psql -W -h host database user << EOF\n\n-- Table for mod_caps: Entity Capabilities (XEP-0115)\nCREATE TABLE caps_features (\n    node text NOT NULL,\n    subnode text NOT NULL,\n    feature text,\n    created_at TIMESTAMP NOT NULL DEFAULT now()\n);\nCREATE INDEX i_caps_features_node_subnode ON caps_features USING btree (node, subnode);\n\n-- Make it possible to use SQL as an SM backend:\nCREATE TABLE sm (\n    usec bigint NOT NULL,\n    pid text NOT NULL,\n    node text NOT NULL,\n    username text NOT NULL,\n    resource text NOT NULL,\n    priority text NOT NULL,\n    info text NOT NULL\n);\nCREATE UNIQUE INDEX i_sm_sid ON sm USING btree (usec, pid);\nCREATE INDEX i_sm_node ON sm USING btree (node);\nCREATE INDEX i_sm_username ON sm USING btree (username);\n\n-- Add a missed SQL index on privacy_list_data table\nCREATE INDEX i_privacy_list_data_id ON privacy_list_data USING btree (id);\n\n-- Add SCRAM support to ejabberd_auth_odbc\nALTER TABLE users ADD COLUMN serverkey text NOT NULL DEFAULT '';\nALTER TABLE users ADD COLUMN salt text NOT NULL DEFAULT '';\nALTER TABLE users ADD COLUMN iterationcount integer NOT NULL DEFAULT 0;\n\n-- mod_mam (XEP-0313) support\nCREATE TABLE archive (\n    username text NOT NULL,\n    timestamp BIGINT NOT NULL,\n    peer text NOT NULL,\n    bare_peer text NOT NULL,\n    xml text NOT NULL,\n    txt text,\n    id SERIAL,\n    kind text,\n    nick text,\n    created_at TIMESTAMP NOT NULL DEFAULT now()\n);\nCREATE INDEX i_username ON archive USING btree (username);\nCREATE INDEX i_timestamp ON archive USING btree (timestamp);\nCREATE INDEX i_peer ON archive USING btree (peer);\nCREATE INDEX i_bare_peer ON archive USING btree (bare_peer);\nCREATE TABLE archive_prefs (\n    username text NOT NULL PRIMARY KEY,\n    def text NOT NULL,\n    always text NOT NULL,\n    never text NOT NULL,\n    created_at TIMESTAMP NOT NULL DEFAULT now()\n);\nEOF\n
    "},{"location":"archive/older-releases/from_2.1.1x_to_16.02/#pubsub-database-upgrade","title":"PubSub database upgrade","text":"
    If you were using PubSub with sql backend and need to keep your pubsub data, you must alter the content of pubsub_node tables, changing type 'pep' instead of 'pep_odbc', 'flat' instead of 'flat_odbc', and 'hometree' instead of 'hometree_odbc'.
     
    UPDATE pubsub_node SET type='pep' WHERE type='pep_odbc';\nUPDATE pubsub_node SET type='flat' WHERE type='flat_odbc';\nUPDATE pubsub_node SET type='hometree' WHERE type='hometree_odbc';\n
    "},{"location":"contributing/","title":"Contributing to ejabberd","text":"
    We'd love for you to contribute to our source code and to make ejabberd even better than it is today! Here are the guidelines we'd like you to follow:
     
       
    • Code of Conduct
      •  
    • Questions and Problems
      •  
    • Issues and Bugs
      •  
    • Feature Requests
      •  
    • Issue Submission Guidelines
      •  
    • Pull Request Submission Guidelines
      •  
    • Signing the CLA
      •  
    "},{"location":"contributing/#code-of-conduct","title":"Code of Conduct","text":"
    Help us keep ejabberd community open-minded and inclusive. Please read and follow our Code of Conduct.
    "},{"location":"contributing/#questions-bugs-features","title":"Questions, Bugs, Features","text":""},{"location":"contributing/#got-a-question-or-problem","title":"Got a Question or Problem?","text":"
    Do not open issues for general support questions as we want to keep GitHub issues for bug reports and feature requests. You've got much better chances of getting your question answered on dedicated support platforms, the best being Stack Overflow.
     
    Stack Overflow is a much better place to ask questions since:
     
       
    • there are thousands of people willing to help on Stack Overflow
      •  
    • questions and answers stay available for public viewing so your question / answer might help   someone else
      •  
    • Stack Overflow's voting system assures that the best answers are prominently visible.
      •  
     
    To save your and our time, we will systematically close all issues that are requests for general support and redirect people to the section you are reading right now.
     
    Other channels for support are: - ejabberd XMPP room: ejabberd@conference.process-one.net - ejabberd XMPP room logs - ejabberd Mailing List
    "},{"location":"contributing/#found-an-issue-or-bug","title":"Found an Issue or Bug?","text":"
    If you find a bug in the source code, you can help us by submitting an issue to our GitHub Repository. Even better, you can submit a Pull Request with a fix.
    "},{"location":"contributing/#missing-a-feature","title":"Missing a Feature?","text":"
    You can request a new feature by submitting an issue to our GitHub Repository.
     
    If you would like to implement a new feature then consider what kind of change it is:
     
       
    • Major Changes that you wish to contribute to the project should be discussed first in an   GitHub issue that clearly outlines the changes and benefits of the feature.
      •  
    • Small Changes can directly be crafted and submitted to the GitHub Repository   as a Pull Request. See the section about Pull Request Submission Guidelines.
      •  
    "},{"location":"contributing/#issue-submission-guidelines","title":"Issue Submission Guidelines","text":"
    Before you submit your issue search the archive, maybe your question was already answered.
     
    If your issue appears to be a bug, and hasn't been reported, open a new issue. Help us to maximize the effort we can spend fixing issues and adding new features, by not reporting duplicate issues.
     
    The \"new issue\" form contains a number of prompts that you should fill out to make it easier to understand and categorize the issue.
    "},{"location":"contributing/#pull-request-submission-guidelines","title":"Pull Request Submission Guidelines","text":"
    By submitting a pull request for a code or doc contribution, you need to have the right to grant your contribution's copyright license to ProcessOne. Please check ProcessOne CLA for details.
     
    Before you submit your pull request consider the following guidelines:
     
       
    • Search GitHub for an open or closed Pull Request   that relates to your submission. You don't want to duplicate effort.
      •  
    • Create the development environment
      •  
    •  
      Make your changes in a new git branch:
       
      git checkout -b my-fix-branch master\n
       * Test your changes and, if relevant, expand the automated test suite. * Create your patch commit, including appropriate test cases. * If the changes affect public APIs, change or add relevant documentation. * Commit your changes using a descriptive commit message.
       
      git commit -a\n
         Note: the optional commit -a command line option will automatically \"add\" and \"rm\" edited files.
       
      •  
    •  
      Push your branch to GitHub:
       
      git push origin my-fix-branch\n
       
      •  
    •  
      In GitHub, send a pull request to ejabberd:master. This will trigger the automated testing. We will also notify you if you have not yet signed the contribution agreement.
       
      •  
    •  
      If you find that the tests have failed, look into the logs to find out if your changes caused test failures, the commit message was malformed etc. If you find that the tests failed or times out for unrelated reasons, you can ping a team member so that the build can be restarted.
       
      •  
    •  
      If we suggest changes, then:
       
      •  
    •  
      Make the required updates.
       
      •  
    • Test your changes and test cases.
      •  
    • Commit your changes to your branch (e.g. my-fix-branch).
      •  
    •  
      Push the changes to your GitHub repository (this will update your Pull Request).
       
      You can also amend the initial commits and force push them to the branch.
       
      git rebase master -i\ngit push origin my-fix-branch -f\n
       
      This is generally easier to follow, but separate commits are useful if the Pull Request contains iterations that might be interesting to see side-by-side.
       
      •  
     
    That's it! Thank you for your contribution!
    "},{"location":"contributing/#signing-the-contributor-license-agreement-cla","title":"Signing the Contributor License Agreement (CLA)","text":"
    Upon submitting a Pull Request, we will ask you to sign our CLA if you haven't done so before. It's a quick process, we promise, and you will be able to do it all online
     
    You can read ProcessOne Contribution License Agreement in PDF.
     
    This is part of the legal framework of the open-source ecosystem that adds some red tape, but protects both the contributor and the company / foundation behind the project. It also gives us the option to relicense the code with a more permissive license in the future.
    "},{"location":"contributing/CODE_OF_CONDUCT/","title":"Contributor Covenant Code of Conduct","text":""},{"location":"contributing/CODE_OF_CONDUCT/#our-pledge","title":"Our Pledge","text":"
    In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
    "},{"location":"contributing/CODE_OF_CONDUCT/#our-standards","title":"Our Standards","text":"
    Examples of behavior that contributes to creating a positive environment include:
     
       
    • Using welcoming and inclusive language
      •  
    • Being respectful of differing viewpoints and experiences
      •  
    • Gracefully accepting constructive criticism
      •  
    • Focusing on what is best for the community
      •  
    • Showing empathy towards other community members
      •  
     
    Examples of unacceptable behavior by participants include:
     
       
    • The use of sexualized language or imagery and unwelcome sexual attention or advances
      •  
    • Trolling, insulting/derogatory comments, and personal or political attacks
      •  
    • Public or private harassment
      •  
    • Publishing others' private information, such as a physical or electronic address, without explicit permission
      •  
    • Other conduct which could reasonably be considered inappropriate in a professional setting
      •  
    "},{"location":"contributing/CODE_OF_CONDUCT/#our-responsibilities","title":"Our Responsibilities","text":"
    Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
     
    Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
    "},{"location":"contributing/CODE_OF_CONDUCT/#scope","title":"Scope","text":"
    This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
    "},{"location":"contributing/CODE_OF_CONDUCT/#enforcement","title":"Enforcement","text":"
    Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at the email address: conduct AT process-one.net. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
     
    Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
    "},{"location":"contributing/CODE_OF_CONDUCT/#attribution","title":"Attribution","text":"
    This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at http://contributor-covenant.org/version/1/4
    "},{"location":"contributing/CONTRIBUTORS/","title":"Contributors","text":"
    We would like to thanks official ejabberd source code contributors:
     
       
    • Sergey Abramyan
      •  
    • Badlop
      •  
    • Ludovic Bocquet
      •  
    • Emilio Bustos
      •  
    • Thiago Camargo
      •  
    • Juan Pablo Carlino
      •  
    • Pawe\u0142 Chmielowski
      •  
    • Gabriel Gatu
      •  
    • Tsukasa Hamano
      •  
    • Konstantinos Kallas
      •  
    • Evgeny Khramtsov
      •  
    • Ben Langfeld
      •  
    • Peter Lemenkov
      •  
    • Anna Mukharram
      •  
    • Johan Oudinet
      •  
    • Pablo Polvorin
      •  
    • Micka\u00ebl R\u00e9mond
      •  
    • Matthias Rieber
      •  
    • Rafael Roemhild
      •  
    • Christophe Romain
      •  
    • J\u00e9r\u00f4me Sautret
      •  
    • Sonny Scroggin
      •  
    • Alexey Shchepin
      •  
    • Shelley Shyan
      •  
    • Radoslaw Szymczyszyn
      •  
    • Stu Tomlinson
      •  
    • Christian Ulrich
      •  
    • Holger Wei\u00df
      •  
     
    Please, if you think we are missing your contribution, do not hesitate to contact us at ProcessOne. In case you do not want to appear in this list, please, let us know as well.
     
    Thanks !
    "},{"location":"developer/","title":"ejabberd for Developers","text":"
    As a developer, you can customize ejabberd to design almost every type of XMPP related type of solutions.
     
    As a starting point, we recommend that you get extremely familiar with both the core XMPP protocol itself and its extensions.
     
    From that, once you understand well XMPP, you can tame ejabberd to build your dream messaging system.
    "},{"location":"developer/#getting-started","title":"Getting started","text":""},{"location":"developer/#source-code","title":"Source code","text":"
    ejabberd source is available on Github: ejabberd
     
    You will need to get familiar with it to start learning about ejabberd module writing. The first place to start? You should read the time module. This is one of the simplest possible module for ejabberd.
     
    Another great source of inspiration and knowledge is to read the source code of the many contributed ejabberd modules. Many of them are available from ejabberd-contribs repository.
     
    For a complete overview of ejabberd source code and its dependencies, please refer to ejabberd and related repositories
    "},{"location":"developer/#development-environment","title":"Development Environment","text":"
    The first step to develop for ejabberd is to install and configure your development environment:
     
       
    • Check the Source Code Installation section
      •  
    • If using Emacs, install erlang-mode in your operating system
      •  
    • If using OSX, check the OSX development environment section
      •  
    • For Visual Studio Code and alternatives, check the Developing ejabberd with VSCode section
      •  
    "},{"location":"developer/#customizing-ejabberd","title":"Customizing ejabberd","text":"
       
    • ejabberd development guide
      •  
    • ejabberd modules development
      •  
    "},{"location":"developer/guide/","title":"ejabberd developer guide","text":""},{"location":"developer/guide/#introduction","title":"Introduction","text":"
    ejabberd is a free and open source instant messaging server written in Erlang/OTP.
     
    ejabberd is cross-platform, distributed, fault-tolerant, and based on open standards to achieve real-time communication.
     
    ejabberd is designed to be a rock-solid and feature rich XMPP server.
     
    ejabberd is suitable for small deployments, whether they need to be scalable or not, as well as extremely big deployments.
    "},{"location":"developer/guide/#goals","title":"Goals","text":"
    This guide is a brief explanation of ejabberd internals. It is not intended to be a comprehensive ejabberd's internal API documentation. You still need to read and understand ejabberd's source code. However, the guide is believed to help you understanding ejabberd's code faster: it provides entry points from where to start reading relevant parts of the code and ignore irrelevant ones. Note that there is absolutely no need to know every line of code of ejabberd, but some parts are crucial to understand.
    "},{"location":"developer/guide/#requirements","title":"Requirements","text":"
    In order to read and understand the guide you must be pretty fluent with Erlang programming language and understand basics of the XMPP protocol: there is no detailed explanation of Erlang syntax and/or features and it's assumed that you're familiar with such terms as xml stream, stanza, c2s, s2s and so on. If you see these words for the first time in your life you're unlikely to understand the guide.
    "},{"location":"developer/guide/#version","title":"Version","text":"
    The guide describes ejabberd 17.03. Previous and next versions can differ drastically from the one described herein.
    "},{"location":"developer/guide/#coding-style-convention","title":"Coding style convention","text":"
    NOTE: this section is only relevant for ejabberd contributors. If you're hacking ejabberd for internal needs, you are free to choose whatever coding style you like.
     
    ejabberd follows Erlang Coding Standards & Guidelines or at least tries to do so: there is still a lot of poorly written legacy code (which is being leisurely rewritten), but the new code should be written with keeping these rules in mind. In some cases the rules can be bypassed, but the reason doing so should be really weighty. The rules shouldn't be ignored just because a contributor doesn't like them.
     
    The typical coding style rules found violated in contributors' code are:
     
       
    • 100 column per line: in fact we have defined 80 columns as a soft and 100 columns as a hard limit, which means most of your lines should be no longer than 80 characters and the rest must never be longer than 100 characters.
      •  
    • no deep nesting
      •  
    • no boolean parameters in case control
      •  
    • only CamelCase variables name
      •  
    • no macros
      •  
    • no case-catch
      •  
     
    It's worth noting that the code itself should be indented using Emacs indentation style (that is the standard indentation style for Erlang programs). If you're not using Emacs for ejabberd development, indent the code using it first before making a PR/commit.
    "},{"location":"developer/guide/#start-up-procedure","title":"Start-up procedure","text":"
    ejabberd is written as a standard OTP application, so the startup module can be found in src/ejabberd.app.src or, if ejabberd is compiled, in ebin/ejabberd.app file: that is, ejabberd_app.erl module from where start/2 function is called by Erlang application controller. This function makes some initialization (such as logger, mnesia, configuration file, etc.) and ends up by starting the main ejabberd supervisor - ejabberd_sup. Thus, for further startup order refer to ejabberd_sup.erl module (this is a simple list-like module with supervisor childspecs).
     
    WARNING: only \"core stuff\" should be attached to ejabberd_sup. For attaching modules use gen_mod's supervisor (via gen_mod:start_child/3,4 functions), for attaching database backend modules use ejabberd_backend_sup supervisor, etc.
     
    Once ejabberd_sup is started, ejabberd application is considered to be started.
    "},{"location":"developer/guide/#core","title":"Core","text":"
    The ejabberd core is not well-defined. Moreover, the described core layers are pure abstraction grouping several modules together by some criteria for better understanding of ejabberd internal processing rules.
    "},{"location":"developer/guide/#network-layer","title":"Network Layer","text":"
    Once ejabberd is started, some external events should obviously make it doing something. Besides explicit administrative commands, the most relevant such events are incoming connections. Incoming connections are handled inside Network Layer. The layer implemented by ejabberd_listener.erl, ejabberd_receiver.erl and ejabberd_socket.erl modules.
     
    NOTE: ejabberd_listner.erl is able to handle raw TCP and UDP connections, however only XMPP connections are described here.
     
    Once a connection is accepted by ejabberd_listener.erl, an instance (a process) of ejabberd_receiver.erl is started and it becomes the socket owner, where it performs the following operations:
     
       
    • Throttles a connection using shapers from shaper.erl module
      •  
    • Performs TLS decoding using fast_tls library
      •  
    • Performs stream decompression using ezlib library
      •  
    • Parses incoming raw XML data into #xmlel{} packets using fast_xml library
      •  
     
    ejabberd_socket.erl does the same but in a reverse order, i.e. it performs stream compression and/or TLS encoding, serializes #xmlel{} packets into raw XML data and puts them into a socket (note that shapers do not apply for outgoing data).
     
    Once xmlel{} packet is constructed by ejabberd_receiver.erl it's passed to XMPP Stream Layer.
    "},{"location":"developer/guide/#xmpp-stream-layer","title":"XMPP Stream Layer","text":"
    XMPP Stream Layer is represented by xmpp_stream_in.erl and xmpp_stream_out.erl modules. An instance (i.e. a process) of xmpp_stream_in.erl is started along with an instance of ejabberd_receiver.erl and all incoming #xmlel{} packets are passed from the latter to the former. xmpp_stream_in.erl module does the following:
     
       
    • Encodes/decodes #xmlel{} packets using xmpp library from/to internal structures (records) defined in xmpp_codec.hrl.
      •  
    • Performs negotiation of inbound XMPP streams
      •  
    • Performs STARTTLS negotiation (if needed)
      •  
    • Performs compression negotiation (if needed)
      •  
    • Performs SASL authentication
      •  
     
    NOTE: XMPP Stream Layer was only introduced in ejabberd 17.03. Prior to this XMPP stream negotiation was handled inside ejabberd_c2s.erl, ejabberd_s2s_in.erl, ejabberd_service.erl and ejabberd_s2s_out.erl. This has lead to unmaintainable monolithic spaghetti code with a lot of code duplication between these modules. It's believed introducing xmpp_stream_in.erl and xmpp_stream_out.erl modules now solves this problem.
     
    During these procedures xmpp_stream_in.erl calls functions from its callback modules, i.e. the modules of xmpp_stream_in behaviour: ejabberd_c2s.erl, ejabberd_s2s_in.erl or ejabberd_service.erl, depending on the stream namespace.
     
    xmpp_stream_out.erl does the same but for outbound XMPP streams. The only its callback module is ejabberd_s2s_out.erl.
     
    NOTE: xmpp_stream_in.erl shares the same process and state with its callback modules, i.e. functions from xmpp_stream_in.erl and functions from ejabberd_c2s/s2s_in/service.erl modules are evaluated inside the same process. This is also true for xmpp_stream_out.erl and ejabberd_s2s_out.erl. The state is represented by a map() in both cases.
    "},{"location":"developer/guide/#ejabberd_c2s-ejabberd_s2s_in-and-ejabberd_service","title":"ejabberd_c2s, ejabberd_s2s_in and ejabberd_service","text":"
    These are modules of xmpp_stream_in behaviour. The only purpose of these modules is to provide callback functions for xmpp_stream_in.erl module. Examples of such callback functions are:
     
       
    • tls_enabled/1: tells whether or not TLS is enabled in the configuration
      •  
    • check_password_fun/1: provides a function for SASL authentication
      •  
    • handle_authenticated_packet/2: what to do with packets after authentication is completed
      •  
     
    Roughly, they represent an intermediate (or \"glue\") code between XMPP Stream Layer and Routing Layer for inbound XMPP streams.
     
    ejabberd_s2s_out.erl is described elsewhere
    "},{"location":"developer/guide/#routing-layer","title":"Routing Layer","text":""},{"location":"developer/guide/#ejabberd_router","title":"ejabberd_router","text":"
    ejabberd_router.erl module is the main dispatcher of XMPP stanzas.
     
    It's pretty small and straightforward module whose the only task is to find the \"route\" for a stanza. ejabberd_router.erl only operates with #message{}, #presence{} and #iq{} packets (defined in xmpp_codec.hrl), so please note, that it is not possible to route arbitrary #xmlel{} packets or any other Erlang terms through ejabberd_router.
     
    The only valid routes are:
     
       
    • local route: stanzas of this route type are destined to the local server itself, i.e. stanzas with to attribute in the form of domain.com or domain.com/resource, where domain.com is a virtual host serviced by ejabberd. ejabberd_router passes such stanzas to ejabberd_local.erl module via ejabberd_local:route/1 function call.
      •  
    • session manager route: stanzas of this route type are destined to local users, i.e. stanzas with to attribute in the form of user@domain.com or user@domain.com/resource where domain.com is a virtual host serviced by ejabberd. ejabberd_router passes such stanzas to ejabberd_sm.erl module via ejabberd_sm:route/1 function call.
      •  
    • registered route: if a stanza is not destined to local virtual host, ejabberd first checks if there is a \"registered\" route for the stanza, i.e. a domain registered via ejabberd_router:register_route/2 function. For doing this it looks up the routing table and if there is a process Pid registered on this domain, ejabberd routes the stanza as Pid ! {route, Stanza}. The routing table is backend-dependent and is implemented in the corresponding backend module such as ejabberd_router_mnesia.erl.
      •  
    • s2s route: if a stanza is neither destined to local virtual host nor to registered route, ejabberd_router passes it to ejabberd_s2s.erl module via ejabberd_s2s:route/1 function call.
      •  
     
    Mentioned modules are explained in more details in the following sections. You're encouraged to inspect exported functions of ejabberd_router.erl, because most likely you will use some of them.
    "},{"location":"developer/guide/#ejabberd_local","title":"ejabberd_local","text":"
    ejabberd_local.erl handles stanzas destined to the local server itself. For #message{} and #presence{} it only calls hooks, while for #iq{} it finds the corresponding \"IQ handler\" by looking up its internal table to find a correspondence between a namespace of IQ's child element and the handler. Once the handler (an erlang function) is found, it passes further IQ processing to gen_iq_handler.erl via gen_iq_handler:handle/5 call.
     
    ejabberd_local.erl is also able to send IQ requests and to process responses for them. This is implemented in ejabberd_local:route_iq/2,3 functions. This is also the most notable function of the module. Calling to other functions is not recommended.
    "},{"location":"developer/guide/#ejabberd_sm","title":"ejabberd_sm","text":"
    ejabberd_sm.erl handles stanzas destined to local users. For #message{}, #presence{} and full-JID #iq{} it looks up its internal table (aka session table) for the corresponding ejabberd_c2s process and, if the process is found, it routes the stanza to this process via ejabberd_c2s:route/2 call.
     
    Bare-JID #iq{} stanzas are processed in a similar way as in ejabberd_local.erl. The internal session table is backend-dependent and is implemented in the corresponding backend module: ejabberd_sm_mnesia.erl, ejabberd_sm_redis.erl and so on.
     
    The most notable functions of the module are:
     
       
    • get_user_resources/2
      •  
    • dirty_get_sessions_list/0
      •  
    • dirty_get_my_sessions_list/0
      •  
    • get_vh_session_list/1
      •  
    • get_vh_session_number/1
      •  
    • get_vh_by_backend/1
      •  
    • get_session_pid/3
      •  
    • get_user_info/2
      •  
    • get_user_info/3
      •  
    • get_user_ip/3
      •  
    • is_existing_resource/3
      •  
    "},{"location":"developer/guide/#route-registered-processes","title":"route-registered processes","text":"
    Any process can register a route to itself. It's done by calling to ejabberd_router:route/2 function. Note that a route should be unregistered via ejabberd_router:unregister_route/1 function if the registering process terminates or the route is no longer needed. Once a route is registered to a process, this process will receive Erlang messages in the form of {route, Stanza}.
     
    NOTE: from and to fields are always set in the Stanza, so it's safe to assume that xmpp:get_from(Stanza) and xmpp:get_to(Stanza) always return #jid{} and never undefined.
     
    Refer to the code of mod_muc.erl or ejabberd_service.erl for an example of a route-registered process.
    "},{"location":"developer/guide/#ejabberd_s2s-and-ejabberd_s2s_out","title":"ejabberd_s2s and ejabberd_s2s_out","text":"
    If a stanza is destined neither to local virtual host not to a route-registered process, it's passed to ejabberd_s2s.erl module via ejabberd_s2s:route/1 function call. ejabberd_s2s in its turn will look up the internal table (currently it's s2s Mnesia table) for the ejabberd_s2s_out process and, if found, passes the stanza to this process or, otherwise, will start new ejabberd_s2s_out process.
     
    ejabberd_s2s_out.erl handles outbound XMPP S2S streams. This is the only callback module of xmpp_stream_out behaviour.
    "},{"location":"developer/guide/#adding-new-functionality","title":"Adding new functionality","text":"
    There are two common ways to add new functionality to ejabberd:
     
       
    • using IQ Handlers
      •  
    • using hooks
      •  
     
    Here is a rule of thumb on which way to choose:
     
       
    • if you want to handle newly introduced IQs (that is, to generate replies for them), use IQ handlers
      •  
    • if you want to modify ejabberd behaviour along the way of a stanza passing through all layers or want to \"listen\" for some internal events (like ejabberd configuration change), use hooks.
      •  
    "},{"location":"developer/guide/#iq-handlers","title":"IQ Handlers","text":"
    An IQ Handler is a function processing an IQ stanza (internally represented as #iq{} record). There are two types of IQ handlers: local and sm.
     
       
    • local IQ handler is a function processing IQs coming from ejabberd_local, that is, an IQ destined to the local server itself as described in ejabberd_local.
      •  
    • sm IQ handler is a function processing IQs coming from ejabberd_sm, that is, a bare-JID IQ destined to a local user as described in ejabberd_sm.
      •  
     
    An IQ handler is registered as:
     
    gen_iq_handler:add_iq_handler(Type :: ejabberd_local | ejabberd_sm,\n                              Host :: binary(),\n                              Namespace :: binary(),\n                              Module :: module(),\n                              Function :: atom()) -> ok\n
     
    where:
     
       
    • Type is ejabberd_local for local handlers or ejabberd_sm for sm handlers
      •  
    • Host is a virtual host for which the IQ is to be processed
      •  
    • Namespace is an XML namespace of IQ's child element
      •  
     
    Once registered, matching IQ stanzas are handled by calling Module:Function(IQ). The result should be in the form of #iq{} or ignore. When #iq{} is returned, it's treated as a reply and routed back to the IQ originator, otherwise, if ignore is returned, the further processing stops.
     
    NOTE: from and to fields are always set in the IQ, so it's safe to assume that xmpp:get_from(IQ) and xmpp:get_to(IQ) always return #jid{} and never undefined.
     
    If a handler is no longer needed it should be unregistered as:
     
    gen_iq_handler:remove_iq_handler(Type :: ejabberd_local | ejabberd_sm,\n                                 Host :: binary(),\n                                 Namespace :: binary()) -> ok\n
     
    with the same meaning of the arguments.
    "},{"location":"developer/guide/#hooks","title":"Hooks","text":"
    When ejabberd is processing an arbitrary event (incoming IQ, outgoing presence, configuration change, etc), it is convenient to consider some of them notable. In order for someone to be notified of such events, ejabberd executes \"hooks\". A hook is represented by a unique name. All functions associated with the hook's name will be called in some specified order.
     
    NOTE: The conception of hooking is not ejabberd specific, see Hooking Wikipedia page for a general description.
     
    For example, when a packet is received on a client connection, ejabberd runs user_send_packet hook. Several modules need to listen for an event represented by this hook (that is, a packet and a C2S state), so they associate their internal functions with it: mod_ping.erl associates user_send/1 function, mod_privacy.erl associates user_send_packet/1 function and so on. The event is passed as an argument to the \"hooked\" functions, thus, the function from mod_ping.erl will be called as mod_ping:user_send({Stanza, C2SState}), the function from mod_privacy.erl will be called as mod_privacy:user_send_packet({Stanza, C2SState}) and so on.
     
    There are two types of hooks: with an accumulator and without an accumulator.
     
       
    • a hook with an accumulator, as its name suggests, accumulates some state during execution of a list of associated functions: the first argument of the hooked function will always be an accumulator and the function must return the new value for the accumulator (whether it's modified or not) in the form of NewAcc or {stop, NewAcc}. If {stop, NewAcc} is returned, a hook is considered evaluated and next functions in its associated list are not called. Otherwise, the new value NewAcc is passed to the next function in the associated list. An example of hooks with accumulator are: disco_info, filter_packet, muc_process_iq and so on.
      •  
    • a hook without accumulator doesn't accumulate anything during execution of a list of associated functions: the returning values of such functions are simply ignored unless stop is returned. In the latter case, evaluation of next functions in the associated list is not performed. An example of hooks without accumulator are: config_reloaded, component_init and so on.
      •  
     
    Both types of hooks have local or global scope.
     
       
    • a hook with local scope is associated with particular virtual host and is run only when an event is matching this host. Most of the hooks have local scope.
      •  
    • a hook with global scope is not associated with any virtual host and is run for an event matching any hosts. A very few hooks have global scope.
      •  
     
    A function gets associated with a local hook as follows (the type of a hook doesn't matter):
     
    ejabberd_hooks:add(Hook :: atom(),\n                   Host :: binary(),\n                   Module :: module(),\n                   Function :: atom(),\n                   Seq :: integer() -> ok\n
     
    where:
     
       
    • Hook is a hook name
      •  
    • Host is a virtual host
      •  
    • Seq is a sequence number. This number defines position of the function in the list to maintain execution order. Functions with lower sequence number are executed before those with bigger sequence number. For functions with the same sequence number the order is unspecified. A function associated with an accumulating hook is called as Module:Function(Acc, Arg1, Arg2, ...) where Acc is an accumulator value, Arg1, Arg2, ... - arguments of the hook. Recall that such function must return a new accumulator value (whether it's modified or not) in the form of NewAcc or {stop, NewAcc} where NewAcc is the new accumulator value. A function associated with a hook without an accumulator is called as Module:Function(Arg1, Arg2, ...). All returning values except stop are ignored.
      •  
     
    WARNING: a Function with the corresponding arity should be exported by a Module
     
    A function for a global hook gets associated as follows (the type of a hook doesn't matter):
     
    ejabberd_hooks:add(Hook :: atom(),\n                   Module :: module(),\n                   Function :: atom(),\n                   Seq :: integer()) -> ok\n
     
    with the same meaning of the arguments. Note that Host argument is omitted in this case.
     
    For any types of hooks, if an association is no longer needed, it can be deleted by calling ejabberd_hooks:delete/5,6 functions with exactly the same arguments used to create an association.
     
    In some cases a new hook should be introduced. There is no need to explicitly register the new hook, one only needs to run a hook in the required place. The following functions can be used for this:
     
       
    • for local hooks with accumulator: ejabberd_hooks:run_fold(Hook, Host, Acc, Args). The function returns a new accumulator value.
      •  
    • for local hooks without accumulator: ejabberd_hooks:run(Hook, Host, Args). The function always returns ok.
      •  
    • for global hooks with accumulator: ejabberd_hooks:run_fold(Hook, Acc, Args). The function returns a new accumulator value.
      •  
    • for global hooks without accumulator: ejabbed_hooks:run(Hook, Args). The function always returns ok.
      •  
     
    where Args is a list of arguments (other variables have the same meaning as above).
     
    There is a helper script that you can use to check hook correctness and find mishooked functions. The script also generates a module src/hooks_type_test.erl from where you can learn about existing hooks and check execution order. You can place your code inside src directory (if any), and run:
     
    make hooks\n
    "},{"location":"developer/guide/#modules","title":"Modules","text":""},{"location":"developer/guide/#gen_mod-behaviour","title":"gen_mod behaviour","text":"
    As you might know, ejabberd is a modular software. The best method to add new functionality to it is to write a new module. For doing this one should create an Erlang module of gen_mod behaviour:
     
    %% file mod_foo.erl\n-module(mod_foo).\n...\n-behaviour(gen_mod).\n...\n
     
    Several callbacks should be defined in the module:
     
       
    • Module:start(Host, Opts) where Host is a virtual host where the module is about to start and Opts is an option list (typically defined in the modules section of ejabberd.yml). The function is executed when a module is being started. It is intended to initialize a module. This is a good place to register hooks and IQ handlers, as well as to create an initial state of a module (if needed). The function should return either ok or {ok, pid()}.
      •  
    • Module:stop(Host) where Host is a virtual host. The function is executed when a module is being stopped. It is intended to make some module cleanup: most likely unregistering hooks and IQ handlers. The returning value is ignored
      •  
    • Module:reload(Host, NewOpts, OldOpts) where NewOpts and OldOpts is the new and old options list respectively. The function is called every time a module is being reloaded. This is the only optional callback, thus, if undefined, the module will be reloaded by calling sequentially Module:stop/1 and Module:start/2.
      •  
    • Module:depends(Host, Opts) where the meaning of the arguments is the same. The function is called to build modules dependencies on startup. The function must return a list of type [{module(), DependencyType}], where DependencyType is one of hard or soft. The hard dependency means the module is non-functional if the other module is not loaded. The soft dependency means the module has suboptimal functionality if the other module is not loaded.
      •  
    • Module:mod_opt_type(Option). The function is used to process configuration options of Module. The function has the same meaning as Module:opt_type/1 callback described in Configuration validation section.
      •  
    "},{"location":"developer/guide/#stateful-modules","title":"Stateful modules","text":"
    While some modules don't need to maintain an internal state (\"stateless\" modules), others are required to do this (\"stateful\" modules). The common practice is to implement a stateful module as a gen_server process. There is a couple of helpers to deal with such modules:
     
       
    • gen_mod:start_child(Module, Host, Opts) where Module is a name of a stateful module. This function should be called as the last function inside of Module:start/2. It will create a gen_server process with a registered name and will attach it to ejabberd_gen_mod_sup supervisor.
      •  
    • gen_mod:stop_child(Module, Host) should be used inside of Module:stop/1 function and will terminate the corresponding registered gen_server process.
      •  
    • gen_mod:get_module_proc(Host, Module) can be used to obtain a registered name of a stateful module (i.e. its gen_server's name).
      •  
     
    WARNING: don't forget to set process_flag(trap_exit, true) inside Module:init/1 callback function, otherwise, Module:terminate/2 callback will never be called when a module is being stopped.
     
    WARNING: keeping module's configuration options in an internal state is not recommended. Use gen_mod:get_module_opt/4,5 functions to retrieve the options: in this case you don't need to re-initialize options in the state inside Module:reload/3 callback.
     
    If a stateful module is intended to maintain a state in the form of a table, ETS can be used for this. In this case there is no need to implement it as a gen_server process. But make sure you're not calling ets:new/2 several times for several virtual hosts (badarg will be raised in this case). E.g., the following code is incorrect:
     
    start(Host, Opts) ->\n    ...\n    ets:new(some_table, named_table, ...]),\n    ...\n
     
    The correct code will look something like that:
     
    start(Host, Opts) ->\n    ...\n    try ets:new(some_table, [named_table, ...])\n    catch _:badarg -> ok end,\n    ...\n
     
    There is a plenty of examples of modules: pick up any file starting with mod_ inside src directory.
    "},{"location":"developer/guide/#gen_mod-module","title":"gen_mod module","text":"
    Module gen_mod.erl has various useful functions to work with modules, the most notable are:
     
       
    • is_loaded/2: whether or not the module in question is loaded at a given virtual host
      •  
    • get_opt/3,4: gets a value of an option from module's options list (see description of ejabberd_config:get_option/3 function from Fetching configuration options for details)
      •  
    • get_module_opt/4,5: the same as above, but an option is referenced by a virtual host and a module.
      •  
    "},{"location":"developer/guide/#configuration","title":"Configuration","text":"
    ejabberd has quite powerful configuration processor - ejabberd_config.erl. It performs configuration file parsing and validation.
    "},{"location":"developer/guide/#validation","title":"Validation","text":"
    In order to validate options ejabberd_config has to install feedback with the rest of the code. For doing this, it provides ejabberd_config behaviour with a single callback function: Module:opt_type/1. The callback accepts an option name as an atom() and must return either validating function if an option is known for the Module or a list of available options (as a list of atoms). A validating function is a fun() of a single argument - the value of the option. The validating function must return any new value for the option (whether it's modified or not) or should crash if the value doesn't match expected format. Here is an example:
     
    %% file: some.erl\n-module(some).\n-behaviour(ejabberd_config).\n-export([opt_type/1]).\n...\nopt_type(max_connections_number) ->\n    %% max_connections_number should be non-negative integer\n    %% if the condition is satisfied, return this integer\n    %% fail with function_clause otherwise\n    fun(I) when is_integer(I), I>=0 -> I end;\nopt_type(_) ->\n    %% only max_connections_number is known\n    [max_connections_number].\n
     
    NOTE: gen_mod behaviour defines a very similar callback - Module:mod_opt_type/1 with the same meaning of arguments and returning values, except the callback is called to validate the Module's specific options (i.e. options defined in the corresponding subsection of the modules section of a configuration file).
    "},{"location":"developer/guide/#fetching-options","title":"Fetching options","text":"
    The most notable function of the module is:
     
    get_option(Option :: atom() | {atom(), binary() | global},\n           ValidatingFun :: fun(),\n           Default :: term()) -> Value :: term().\n
     
    The function is used to get a value Value of a configuration option Option. The ValidatingFun is a validating function described in the previous section and Default is the default value if the option is not defined in the config.
    "},{"location":"developer/guide/#using-xmpp-library","title":"Using XMPP library","text":""},{"location":"developer/guide/#xmpp-module","title":"xmpp module","text":"
    Prior to version 16.12, ejabberd used to operate with #xmlel{} packets directly: fast_xml API functions have been used for manipulating with #xmlel{} packets (such as fast_xml:get_subtag/2, fast_xml:get_attr_s/2, fast_xml:get_path_s/2 and so on) as well as some functions from jlib.erl module.
     
    This is now deprecated and actually not possible. Instead, the new API functions are used from brand new xmpp library.
     
    NOTE: although direct calling of fast_xml API is deprecated, there are still two useful functions: fxml_stream:parse_element/1 and fxml:element_to_binary/1. You can use these functions for (de)serialization of data stored on disc or in a database.
     
    The library is built on top of XMPP Codec: a number of decoding/encoding modules automatically generated by Fast XML generator from the specification file xmpp_codec.spec. The goal is to avoid manual processing of XML trees and, instead, using well-typed auto-generated structures defined in xmpp_codec.hrl. Every particular XML packet within some namespace has to have a specification defined in xmpp_codec.spec. The advantage of such approach is that you tell the generator what to parse instead of taming fast_xml library how to parse.
     
    NOTE: describing how to write XMPP codec specification is out of scope of this guide
     
    WARNING: you should never use functions from xmpp_codec.erl module directly: use functions from xmpp.erl module. The same is true for header files: do NOT include xmpp_codec.hrl -- include xmpp.hrl instead
    "},{"location":"developer/guide/#xmpp-codec","title":"XMPP codec","text":"
    Once a raw XML packet is parsed by ejabberd_receiver.erl into #xmlel{} record, it's passed to xmpp_stream_in.erl module, where decoding of #xmlel{} into xmpp_element() format (i.e. into well-known record type defined in xmpp_codec.hrl) is performed (refer to XMPP Stream Layer section for details). At that level \"lazy\" decoding is applied: only top-level element is decoded. For example, an xmlel() packet
     
    #xmlel{name = <<\"message\">>,\n       attrs = [{<<\"type\">>,<<\"chat\">>}],\n       children = [#xmlel{name = <<\"composing\">>,\n                          attrs = [{<<\"xmlns\">>,\n                                    <<\"http://jabber.org/protocol/chatstates\">>}],\n                          children = []}]}\n
     
    is decoded into the following xmpp_element():
     
    #message{id = <<>>,type = chat,lang = <<>>,from = undefined,\n         to = undefined,subject = [],body = [],thread = undefined,\n         sub_els = [#xmlel{name = <<\"composing\">>,\n                           attrs = [{<<\"xmlns\">>,\n                                     <<\"http://jabber.org/protocol/chatstates\">>}],\n                           children = []}],\n         meta =\n
     
    Note that the sub-element is still in xmlel() format. This \"semi-decoded\" packet is then passed upstream (at the Routing Layer). Thus, a programmer should explicitly decode sub-elements if needed. To accomplish this one can use the following function:
     
    xmpp:decode(El :: xmlel(), Namespace :: binary(), [Option]) -> xmpp_element()`\n
     
    where the only supported Option is ignore_els: with this option lazy decoding is performed. By default, full decoding is applied, i.e. all known sub-elements get decoded. Namespace is a \"top-level\" namespace: it should be provided only if <<\"xmlns\">> attribute is omitted in El, otherwise decoding would fail (see below).
     
    There is also xmpp:decode(El :: xmlel()) -> xmpp_element() function, which is a short-hand for xmpp:decode(El, ?NS_CLIENT, []) (where ?NS_CLIENT is a predefined namespace for <<\"jabber:client\">>, see Namespaces section).
     
    Both functions might fail with {xmpp_codec, Why} exception. The value of Why can be used to format the failure reason into human readable description using xmpp:format_error/1 function, e.g., using sub-element from example #message{} above, we can write:
     
    try xmpp:decode(El) of\n    #chatstate{} = ChatState -> process_chatstate(ChatState)\ncatch _:{xmpp_codec, Why} ->\n    Text = xmpp:format_error(Why),\n    ?ERROR_MSG(\"failed to decode element: ~s\", [Txt])\nend\n
     
    To apply reverse operation use xmpp:encode/2 functions:
     
    xmpp:encode(Pkt :: xmpp_element(), Namespace :: binary()) -> El :: xmlel()\n
     
    There is also xmpp:encode(Pkt :: xmpp_element()) -> El :: xmlel() function which is a short-hand for xmpp:encode(Pkt, <<>>).
     
    Namespace is a \"top-level\" namespace: it is used to tell the codec whether to include <<\"xmlns\">> attribute into resulting #xmlel{} element or not -- if the Pkt is within the same Namespace, <<\"xmlns\">> attribute will be omitted in the result. For example:
     
    > rr(xmpp).\n...\n> Msg.\n#message{id = <<>>,type = chat,lang = <<>>,from = undefined,\n         to = undefined,subject = [],body = [],thread = undefined,\n         sub_els = [#chatstate{type = composing}],\n         meta =\n> xmpp:encode(Msg).\n#xmlel{name = <<\"message\">>,\n       attrs = [{<<\"type\">>,<<\"chat\">>},\n                {<<\"xmlns\">>,<<\"jabber:client\">>}],\n       children = [#xmlel{name = <<\"composing\">>,\n                          attrs = [{<<\"xmlns\">>,\n                                    <<\"http://jabber.org/protocol/chatstates\">>}],\n                          children = []}]}\n> xmpp:encode(Msg, <<\"jabber:client\">>).\n#xmlel{name = <<\"message\">>,\n       attrs = [{<<\"type\">>,<<\"chat\">>}],\n       children = [#xmlel{name = <<\"composing\">>,\n                          attrs = [{<<\"xmlns\">>,\n                                    <<\"http://jabber.org/protocol/chatstates\">>}],\n                          children = []}]}\n
     
    NOTE: xmpp:encode/1,2 functions would never fail as long as the provided input is a valid xmpp_element() with valid values of its record fields. Use dialyzer checks of your code for validation.
     
    NOTE: there is no need to explicitly decode a sub-element of an IQ passed into an IQ handler because decoding is performed inside gen_iq_handler.erl module and a handler actually will never receive malformed sub-elements.
     
    Luckily, there is a helper function for sub-elements decoding, described in the next section and in a lot of cases it's more convenient to use it.
    "},{"location":"developer/guide/#getting-sub-elements","title":"Getting sub-elements","text":"
    Once a programmer gets a stanza in xmpp_element() format, (s)he might want to get its subelement. To accomplish this the following function can be used:
     
    xmpp:get_subtag(Stanza :: stanza(), Tag :: xmpp_element()) -> Pkt :: xmpp_element() | false\n
     
    This function finds a Tag by its well-known record inside sub-elements of the Stanza. It automatically performs decoding (if needed) and returns either found xmpp_element() or false if no elements have matched. Note that the function doesn't fail if some of sub-elements are invalid.
     
    Example:
     
    > rr(xmpp).\n...\n> Msg.\n#message{id = <<>>,type = chat,lang = <<>>,from = undefined,\n         to = undefined,subject = [],body = [],thread = undefined,\n         sub_els = [#xmlel{name = <<\"composing\">>,\n                           attrs = [{<<\"xmlns\">>,\n                                     <<\"http://jabber.org/protocol/chatstates\">>}],\n                           children = []}],\n         meta =\n> xmpp:get_subtag(Msg, #chatstate{type = composing}).\n#chatstate{type = composing}\n> xmpp:get_subtag(Msg, #chatstate{type = inactive}).\nfalse\n> xmpp:get_subtag(Msg, #disco_info{}).\nfalse\n
    "},{"location":"developer/guide/#setting-and-removing-sub-elements","title":"Setting and removing sub-elements","text":"
    In order to inject a sub-element into or delete one from arbitrary stanza() one can use xmpp:set_subtag/2 and xmpp:remove_subtag/2 respectively.
    "},{"location":"developer/guide/#from-and-to","title":"from and to","text":"
    Every stanza() element has from and to record fields. In order to get/set them one can manipulate with these record fields directly, e.g. via Msg#message.from or Pres#presence.to expressions, or, use xmpp:get_from/1, xmpp:get_to/1, xmpp:set_from/2, xmpp:set_to/2 and xmpp:set_from_to/3 functions, depending on which approach is more convenient in the current situation.
     
    NOTE: although in general from and to fields may have undefined values, these fields are always filled with correct #jid{} records at XMPP Stream Layer, thus, it is safe to assume that the fields always possess valid #jid{} values.
    "},{"location":"developer/guide/#metadata","title":"Metadata","text":"
    Every stanza() element has meta field represented as a map(). It's useful when there is a need to attach some metadata to the stanza before routing it further. A programmer can manipulate with this field directly using maps module, or use xmpp:get_meta/1,2,3, xmpp:set_meta/2, xmpp:put_meta/3, xmpp:update_meta/3 and xmpp:del_meta/2 functions, which is almost always more convenient (except pattern matching).
    "},{"location":"developer/guide/#text-elements","title":"Text elements","text":"
    Some xmpp_element()s has fields defined in [#text{}] format. The example is #message.body and #presence.status fields. To avoid writing a lot of extracting code the following functions can be used: xmpp:mk_text/1,2 to convert some binary text written in some language into [#text{}] term, or xmpp:get_text/1,2 to extract binary text from the [#text{}] element by a language.
    "},{"location":"developer/guide/#generating-errors","title":"Generating errors","text":"
    In order to generate stanza errors or stream errors xmpp:err_/0,2 or xmpp:serr_*/0,2 can be used respectively, such as xmpp:err_service_unavailable() or xmpp:serr_not_authorized(). If a stanza should be bounced back with an error, xmpp:make_error/2 function can be used
    "},{"location":"developer/guide/#namespaces","title":"Namespaces","text":"
    There are many predefined macros for XML namespaces in ns.hrl. However, this file must NOT be included, as it's already included in xmpp.hrl.
     
    A function xmpp:get_ns/1 can be used to retrieve a namespace from xmpp_element() or from xmlel() directly:
     
    > rr(xmpp).\n...\n> xmpp:get_ns(#message{}).\n<<\"jabber:client\">>.\n> xmpp:get_ns(xmpp:encode(#presence{})).\n<<\"jabber:client\">>.\n
    "},{"location":"developer/guide/#jid-module","title":"jid module","text":"
    jid.erl module provides functions to work with XMPP addresses (aka \"JIDs\"). There are two common types of internal representation of JIDs:
     
       
    • jid(): a JID is represented by a record #jid{} defined in   jid.hrl
      •  
    • ljid(): a JID is represented by a tuple {User, Server, Resource} where   User, Server and Resource are stringprepped version of a nodepart,   namepart and resourcepart of a JID respectively. This representation is useful to   use for JIDs comparison and when a JID should be used as a key (in a Mnesia   database, ETS table, etc.)
      •  
     
    The most notable functions in this module are:
     
       
    • decode(Input :: binary()) -> jid():   decodes binary data into jid(). Fails with {bad_jid, Input} otherwise.
      •  
    • encode(JID :: jid() | ljid()) -> binary():   encodes JID into binary data
      •  
    • remove_resource(JID :: jid() | ljid()) -> jid() | ljid():   removes resource part of a JID
      •  
    • replace_resource(JID :: jid() | ljid(), Resource :: binary()) -> jid() | ljid():   replaces resource part of a JID
      •  
    • tolower(JID :: jid() | ljid()) -> ljid():   transforms JID into ljid() representation
      •  
    • make(LJID :: ljid() | jid()) -> jid():   transforms LJID into jid() representation
      •  
     
    Inspect exported functions of jid.erl for more details.
    "},{"location":"developer/guide/#external-authentication","title":"External Authentication","text":"
    You can configure ejabberd to use as authentication method an external script, as described in the Administrator section: External Script.
     
    Let's see the interface between ejabberd and your script, and several example scripts. There are also several old example scripts.
    "},{"location":"developer/guide/#extauth-interface","title":"Extauth Interface","text":"
    The external authentication script follows the Erlang port driver API.
     
    That script is supposed to do these actions, in an infinite loop:
     
       
    •  
      read from stdin: AABBBBBBBBB.....
       
      •  
    •  
      A: 2 bytes of length data (a short in network byte order)
       
      •  
    •  
      B: a string of length found in A that contains operation in         plain text operation are as follows:
       
         
      •  
        auth:User:Server:Password (check if a username/password pair         is correct)
         
        •  
      •  
        isuser:User:Server (check if it\u2019s a valid user)
         
        •  
      •  
        setpass:User:Server:Password (set user\u2019s password)
         
        •  
      •  
        tryregister:User:Server:Password (try to register an         account)
         
        •  
      •  
        removeuser:User:Server (remove this account)
         
        •  
      •  
        removeuser3:User:Server:Password (remove this account if the         password is correct)
         
        •  
       
      •  
    •  
      write to stdout: AABB
       
      •  
    •  
      A: the number 2 (coded as a short, which is bytes length of         following result)
       
      •  
    •  
      B: the result code (coded as a short), should be 1 for         success/valid, or 0 for failure/invalid
       
      •  
     
    As you noticed, the : character is used to separate the fields. This is possible because the User and Server fields can't contain the : character; and Password can have that character, but is always the last field. So it is always possible to parse the input characters unambiguously.
    "},{"location":"developer/guide/#perl-example-script","title":"Perl Example Script","text":"
    This is a simple example Perl script; for example if the file is copied to the path /etc/ejabberd/check_pass_null.pl then configure ejabberd like this:
     
    auth_method: [external]\nextauth_program: /etc/ejabberd/check_pass_null.pl\n
     
    Content of check_pass_null.pl:
     
    #!/usr/bin/perl\n\nuse Unix::Syslog qw(:macros :subs);\n\nmy $domain = $ARGV[0] || \"example.com\";\n\nwhile(1)\n  {\n   # my $rin = '',$rout;\n   # vec($rin,fileno(STDIN),1) = 1;\n   # $ein = $rin;\n   # my $nfound = select($rout=$rin,undef,undef,undef);\n\n    my $buf = \"\";\n    syslog LOG_INFO,\"waiting for packet\";\n    my $nread = sysread STDIN,$buf,2;\n    do { syslog LOG_INFO,\"port closed\"; exit; } unless $nread == 2;\n    my $len = unpack \"n\",$buf;\n    my $nread = sysread STDIN,$buf,$len;\n\n    my ($op,$user,$host,$password) = split /:/,$buf;\n    #$user =~ s/\\./\\//og;\n    my $jid = \"$user\\@$domain\";\n    my $result;\n\n    syslog(LOG_INFO,\"request (%s)\", $op);\n\n  SWITCH:\n      {\n $op eq 'auth' and do\n   {\n             $result = 1;\n   },last SWITCH;\n\n $op eq 'setpass' and do\n   {\n             $result = 1;\n   },last SWITCH;\n\n        $op eq 'isuser' and do\n          {\n             # password is null. Return 1 if the user $user\\@$domain exitst.\n             $result = 1;\n          },last SWITCH;\n\n        $op eq 'tryregister' and do\n          {\n             $result = 1;\n          },last SWITCH;\n\n        $op eq 'removeuser' and do\n          {\n             # password is null. Return 1 if the user $user\\@$domain exitst.\n             $result = 1;\n          },last SWITCH;\n\n        $op eq 'removeuser3' and do\n          {\n             $result = 1;\n          },last SWITCH;\n      };\n    my $out = pack \"nn\",2,$result ? 1 : 0;\n    syswrite STDOUT,$out;\n  }\n\ncloselog;\n
    "},{"location":"developer/guide/#python-example-script","title":"Python Example Script","text":"
    Example Python script:
     
    #!/usr/bin/python\n\nimport sys\nimport struct\n\ndef read_from_stdin(bytes):\n  if hasattr(sys.stdin, 'buffer'):\n    return sys.stdin.buffer.read(bytes)\n  else:\n    return sys.stdin.read(bytes)\n\ndef read():\n    (pkt_size,) = struct.unpack('>H', read_from_stdin(2))\n    pkt = sys.stdin.read(pkt_size)\n    cmd = pkt.split(':')[0]\n    if cmd == 'auth':\n        u, s, p = pkt.split(':', 3)[1:]\n        if u == \"wrong\":\n            write(False)\n        else:\n            write(True)\n    elif cmd == 'isuser':\n        u, s = pkt.split(':', 2)[1:]\n        if u == \"wrong\":\n            write(False)\n        else:\n            write(True)\n    elif cmd == 'setpass':\n        u, s, p = pkt.split(':', 3)[1:]\n        write(True)\n    elif cmd == 'tryregister':\n        u, s, p = pkt.split(':', 3)[1:]\n        write(True)\n    elif cmd == 'removeuser':\n        u, s = pkt.split(':', 2)[1:]\n        write(True)\n    elif cmd == 'removeuser3':\n        u, s, p = pkt.split(':', 3)[1:]\n        write(True)\n    else:\n        write(False)\n    read()\n\ndef write(result):\n    if result:\n        sys.stdout.write('\\x00\\x02\\x00\\x01')\n    else:\n        sys.stdout.write('\\x00\\x02\\x00\\x00')\n    sys.stdout.flush()\n\nif __name__ == \"__main__\":\n    try:\n        read()\n    except struct.error:\n        pass\n
    "},{"location":"developer/hosts/","title":"Understanding ejabberd hosts","text":"
    The host parameter is very commonly used through ejabberd code base. It is very important to understand what it means and how it is used.
    "},{"location":"developer/hosts/#component-subdomains","title":"Component subdomains","text":"
    Most XMPP service are reference as subdomain of the main XMPP domain. For example, Multi User Chat or Publish-Subscribe are available as subdomains of the main XMPP domain served by an installation.
     
    You can also plug external components to an ejabberd server. External components will have their own subdomain as well and will be exchanging data with ejabberd using a simplified XML stream.
     
    Components can be written in any programming language. ejabberd supports XEP-0114: Jabber Component Protocol.
     
    Note the external component have limited rights on the XMPP server. As such, it is less powerful than an ejabberd module written in Erlang or Elixir. Some proposed XMPP extensions, like Privilege Entities, may grant more privileges in the future to external components.
    "},{"location":"developer/hosts/#virtual-hosts","title":"Virtual hosts","text":"
    ejabberd fully support virtual hosting. It means that the same ejabberd cluster can provide the service for multiple user bases using a single deployment. Each virtual hosts is totally independent from the other domain. They can have a different configurations.
    "},{"location":"developer/install-osx/","title":"Installing ejabberd development environment on OSX","text":"
    This short guide will show you how to compile ejabberd from source code on Mac OS X, and get users chatting right away.
    "},{"location":"developer/install-osx/#before-you-start","title":"Before you start","text":"
    ejabberd is supported on Mac OS X 10.6.8 and later. Before you can compile and run ejabberd, you also need the following to be installed on your system:
     
       
    • Gnu Make and GCC (the GNU Compiler Collection). To ensure that these   are installed, you can install the Command Line Tools for Xcode,   available via Xcode or from the Apple Developer website.
      •  
    • Git
      •  
    • Erlang/OTP 19.1 or higher. We recommend using Erlang 21.2.
      •  
    • Autotools
      •  
    "},{"location":"developer/install-osx/#homebrew","title":"Homebrew","text":"
    An easy way to install some of the dependencies is by using a package manager, such as Homebrew \u2013 the Homebrew commands are provided here:
     
       
    • Git: brew install git
      •  
    • Erlang /OTP: brew install erlang
      •  
    • Elixir: brew install elixir
      •  
    • Autoconf: brew install autoconf
      •  
    • Automake: brew install automake
      •  
    • Openssl: brew install openssl
      •  
    • Expat: brew install expat
      •  
    • Libyaml: brew install libyaml
      •  
    • Libiconv: brew install libiconv
      •  
    • Sqlite: brew install sqlite
      •  
    • GD: brew install gd
      •  
    • Rebar: brew install rebar rebar3
      •  
     
    You can install everything with a single command:
     
    brew install erlang elixir openssl expat libyaml libiconv libgd sqlite rebar rebar3 automake autoconf\n
    "},{"location":"developer/install-osx/#installation","title":"Installation","text":"
    To build and install ejabberd from source code, do the following:
     
       
    1. Clone the Git repository: git clone git@github.com:processone/ejabberd.git
      2.  
    2. Go to your ejabberd build directory: cd ejabberd
      3.  
    3.  
      Run the following commands, assuming you want to install your    ejabberd deployment into your home directory:
       
      chmod +x autogen.sh\n./autogen.sh\nexport LDFLAGS=\"-L/usr/local/opt/openssl/lib -L/usr/local/lib -L/usr/local/opt/expat/lib\"\nexport CFLAGS=\"-I/usr/local/opt/openssl/include/ -I/usr/local/include -I/usr/local/opt/expat/include\"\nexport CPPFLAGS=\"-I/usr/local/opt/openssl/include/ -I/usr/local/include -I/usr/local/opt/expat/include\"\n./configure --prefix=$HOME/my-ejabberd --enable-sqlite\nmake && make install\n
       
      4.  
     
    Note that the previous command reference the previously installed dependencies from Homebrew.
    "},{"location":"developer/install-osx/#running-ejabberd","title":"Running ejabberd","text":"
       
    • From your ejabberd build directory, go to the installation directory: cd $HOME/my-ejabberd
      •  
    • To start the ejabberd server, run the following command: sbin/ejabberdctl start
      •  
    •  
      To verify that ejabberd is running, enter the following: sbin/ejabberdctl status   If the server is running, response should be as follow:
       
      $ sbin/ejabberdctl status\nThe node ejabberd@localhost is started with status: started\nejabberd 14.12.40 is running in that node\n
       
      •  
    •  
      To connect to the ejabberd console after starting the server: sbin/ejabberdctl debug
       
      •  
    • Alternatively, you can also run the server in interactive mode: sbin/ejabberdctl live
      •  
    "},{"location":"developer/install-osx/#registering-a-user","title":"Registering a user","text":"
    The default XMPP domain served by ejabberd right after the build is localhost. This is different from the IP address, DNS name of the server. It means remote users can connect to ejabberd even if it is running on your machine with localhost XMPP domain, by using your computer IP address or DNS name. This can prove handy in development phase to get more testers.
    "},{"location":"developer/install-osx/#adium","title":"Adium","text":"
    Adium is a popular XMPP client on OSX. You can use it
     
       
    1. Launch Adium. If the Adium Setup Assistant opens, close it.
      2.  
    2. In the Adium menu, select Preferences, and then select the Accounts tab.
      3.  
    3. Click the + button and select XMPP (Jabber).
      4.  
    4. Enter a Jabber ID (for example, \u201cuser1@localhost\u201d) and password, and then click Register New Account.
      5.  
    5. In the Server field, enter the following:
      6.  
    6. Users registering on the computer on which ejabberd is running: localhost
      7.  
    7. Users registering from a different computer: the ejabberd server\u2019s IP address
      8.  
    8. Click Request New Account.
      9.  
     
    After registration, the user will connect automatically.
     
    Registered users wishing to add an existing account to Adium should enter the ejabberd server\u2019s IP address in the Connect Server field on the Options tab.
    "},{"location":"developer/install-osx/#command-line","title":"Command line","text":"
    You can register a user with the ejabberdctl utility: ejabberdctl register user domain password
     
    For example: ejabberdctl register user1 localhost myp4ssw0rd
    "},{"location":"developer/install-osx/#domains","title":"Domains","text":"
    To use your system\u2019s domain name instead of localhost, edit the following ejabberd configuration file: $HOME/my-ejabberd/etc/ejabberd.yml (point to the place of your real installation).
     
    Note: You may find example ejabberd.cfg files. This is the old obsolete format for configuration file. You can ignore the and focus on the new and more user friendly Yaml format.
     
    Find the line listing the hosts:
     
    hosts:\n  - \"localhost\"\n
     
    Replace localhost with your XMPP domain name, for example:
     
    hosts:\n  - \"example.org\"\n
     
    Save the configuration file and restart the ejabberd server. A user\u2019s Jabber ID will then use the domain instead of localhost, for example: user1@example.org
     
    You can also configure multiple (virtual) domains for one server:
     
    hosts:\n  - \"example1.org\"\n  - \"example2.org\"\n
    "},{"location":"developer/install-osx/#get-chatting","title":"Get chatting","text":"
    Users that are registered on your server can now add their accounts in a chat application like Adium (specifying either the server\u2019s IP address or domain name), add each other as contacts, and start chatting.
    "},{"location":"developer/repositories/","title":"Understanding ejabberd and its dependencies","text":"
    We wanted to make sure that ejabberd is modular and that parts that can be of interest for other Erlang projects can be reused.
     
    Not only we are massive open source contributors to Erlang community and ecosystem, but we are also trying to help even more by reviewing your pull requests. Do not hesitate to submit some on any of the many repositories mentioned here.
    "},{"location":"developer/repositories/#ejabberd-dependencies","title":"ejabberd dependencies","text":"
    ejabberd code based is split among several repositories so effectively ejabberd code is much more than what is in its primary repository.
    "},{"location":"developer/repositories/#required-dependencies","title":"Required dependencies","text":"
    The main ejabberd repository is processone/ejabberd
     
    There is hundreds of forks, but we actively maintain ejabberd to make it the most reliable and up to date version. This is thus your best starting point.
     
    When you build ejabberd yourself, the build chain will download a few Erlang dependencies:
     
       
    • processone/cache_tab:   Flexible in-memory Erlang caching module.
      •  
    • processone/iconv: Native iconv driver for Erlang. This is use for fast character encoding conversion.
      •  
    • processone/fast_xml: Fast native Expat based Erlang XML parsing library. XML is the core of XMPP so we needed to provide the fast and more robust XML parsing stack as possible. It means that if you are looking for a great XML parser, reusing p1_xml is probably a great idea.
      •  
    • processone/stringprep: Fast and efficient Erlang Stringprep native driver. Stringprep is heavily used in XMPP to define encoding rules of various XMPP objects.
      •  
    • processone/fast_yaml: Native Erlang interface to libyaml, for fast robust YAML parsing. This is needed by our new config file format.
      •  
    • processone/ezlib: Native zlib driver for Erlang. Used for fast / efficient stream compression.
      •  
    • processone/fast_tls: Erlang native driver for TLS / SSL. It is build for performance and is more scalable that Erlang SSL driver. If your Erlang server is handling heavy load and is using TLS, we strongly recommend you check / compare with this driver.
      •  
    • processone/esip: ProcessOne SIP protocol support to add SIP-based voice capabilities to ejabberd.
      •  
    • processone/stun: Implementation of Session Traversal Utilities for NAT. It is used for XMPP and SIP media capabilities, to help client discover their visible IP address and allow them to get in touch through NAT. This is basically useful for voice and file transfers.
      •  
    • processone/p1_utils: This is extra Erlang modules developed for ejabberd but that can be useful in other Erlang applications.
      •  
    • processone/p1_logger: Logger wrapper to allow selecting your preferred logger at build time.
      •  
    • basho/lager: Erlang logger module.
      •  
    • DeadZen/goldrush: Small Erlang app that provides fast event stream processing. It is used by lager.
      •  
    • vaxelfel/eHyperLogLog: HyperLogLog, a distinct values estimator, in Erlang. Used for analytics.
      •  
    "},{"location":"developer/repositories/#optional-dependencies","title":"Optional dependencies","text":"
    Then, we use a few other dependent repositories that may be used if you have enabled support in the configure script.
     
    Here are the dependencies for relational database support:
     
       
    • processone/mysql: Pure Erlang MySQL driver.
      •  
    • processone/pgsql: Pure Erlang PostgreSQL driver
      •  
     
    Here are the dependencies for Elixir support:
     
       
    • elixir-lang/elixir: Used to write ejabberd modules in Elixir programming language.
      •  
    • yrashk/rebar_elixir_plugin: Plugin for rebar build tool to support Elixir modules compilation.
      •  
     
    After you have build ejabberd from source, you will find all the dependencies downloaded and build in the deps directory.
     
    As you see, there is much more Erlang code produce at ProcessOne and contributed to the Erlang community than just ejabberd repository.
    "},{"location":"developer/repositories/#ejabberd-contributions","title":"ejabberd contributions","text":"
    This is not dependencies, but simply modules that you may find nice to add to your ejabberd deployment.
     
    We attempted to gather some of the more useful ejabberd modules in a contribution repository to ease discovery.
     
    This repository is available on Github: ejabberd-contribs
     
    We are thinking about a better approach for ejabberd contributions discovery. More on that soon.
    "},{"location":"developer/sql-schema/","title":"ejabberd SQL Database Schema","text":"
    We present the tables that might be in use, depending on your server configuration, together with a short explanation of the fields involved and their intended use. Tables are presented roughly grouped by related functionality.
     
    Consider this document a work in progress, not all tables are documented yet.
     
    Latest version of database schema are available in ejabberd Github repository:
     
       
    • MySQL schema
      •  
    • Postgres schema
      •  
    • SQLite schema
      •  
    • MS SQL Server schema. This   schema need testing / feedback and possibly improvement from SQL   Server users.
      •  
    "},{"location":"developer/sql-schema/#authentication","title":"Authentication","text":""},{"location":"developer/sql-schema/#table-users","title":"Table users","text":"
    Contains the information required to authenticate users.
     Field Type Usage username string User password string User password, can be hashed created_at timestamp When the user account was created 
    The password are hashed if you use SCRAM authentication. In that case the next fields are also defined
     Field Type Usage serverkey string support for salted passwords salt string support for salted passwords iterationcount integer support for salted passwords"},{"location":"developer/sql-schema/#rosters","title":"Rosters","text":""},{"location":"developer/sql-schema/#table-rosterusers","title":"Table rosterusers","text":"
    This is a quite complex table, used as a store for a quite complex protocol that is the one defined to manage rosters and subscriptions on rfc6121.  
     
    In the common case of two users adding each other as contacts, entries in the roster table follows a series of steps  as they moves from a subscription request to the final approval and bi-directional subscription being established. This process can be initiated either by the user, or by the (possible remote) peer. Also need to account for the case where the user, or the contact, might not be online at the moment of the subscription request is made.
     
    Steps are further complicated by the fact that entries in the roster aren't required to have corresponding subscriptions. For details of the meaning of the different fields, refer to the protocol itself, as these are mostly a direct mapping of it.
     
    Note: If you manage users contacts from outside the roster workflow of XMPP (for example your site backends perform the linking between users),  it is likely that you only need to care about the  username, jid and nick fields,  and set the subscription field to be always 'B' for a mutual link between users.
     Field Type Usage username string User jid string Contact jid nick string Contact nickname subscription char 'B'=both | 'T'=To | 'F'=From | 'N'=none ask char 'S'=subscribe | 'U'=unsubscribe | B='both' | 'O'=out | 'I'=in | 'N'=none askmessage string Message to be displayed on the subscription request server char 'N' for normal users contacts subscribe string type string \"item\" created_at timestamp Creation date of this roster entry"},{"location":"developer/sql-schema/#table-rostergroups","title":"Table rostergroups","text":""},{"location":"developer/sql-schema/#table-sr_group","title":"Table sr_group","text":""},{"location":"developer/sql-schema/#table-sr_user","title":"Table sr_user","text":""},{"location":"developer/sql-schema/#messages","title":"Messages","text":""},{"location":"developer/sql-schema/#table-spool","title":"Table spool","text":"
    Messages sent to users that are offline are stored in this table. Do not confuse this with general message archiving: messages are only temporarily stored in this table, removed as soon as the target user is back online and the pending messages delivered to it.
     Field Type Usage username string User xml blob Raw packet seq integer Unique, autoincrement sequence number. created_at timestamp When the message was stored 
    The seq field is used for sorting, and to easily identify a particular user message.
    "},{"location":"developer/sql-schema/#table-privacy_list_data","title":"Table privacy_list_data","text":"
    The table is used to store privacy rules.
     
    The table is a direct translation of the XMPP packet used to set privacy lists. For more details, please read XEP-0016: Privacy Lists, Syntax and Semantics. Here is an example packet coming from privacy list specification:
     
    <item\n     type='[jid|group|subscription]'\n     value='bar'\n     action='[allow|deny]'\n     order='unsignedInt'>\n    [<message/>]\n    [<presence-in/>]\n    [<presence-out/>]\n    [<iq/>]\n </item>\n
     
    The table fields are defined as follow:
     Field Type Usage id int Privacy list rule id. t char Privacy rule type: 'j' for jid, 'g' for group and 's' for subscription. value string Privacy list value for match, whose content depends on privacy list rule type. action char Privacy list action: 'd' for deny and 'a' for allow. ord int Order for applying the privacy list rule. match_all boolean (0 or 1) If true (1), means any packet types will be matched. Other matches should be false (0). match_iq boolean (0 or 1) If true (1), means iq packets will be matched by rule. match_message boolean (0 or 1) If true (1), means message packets type will be matched by rule. match_presence_in boolean (0 or 1) If true (1), means inbound presence packets type will be matched by rule. match_presence_out boolean (0 or 1) If true (1), means outbound packets type will be matched by rule."},{"location":"developer/sql-schema/#multiuser-chat-rooms","title":"Multiuser Chat Rooms","text":""},{"location":"developer/sql-schema/#table-muc_room","title":"Table muc_room","text":"
    It is used to store persistent rooms, that is, rooms that must be automatically started with the server.
     Field Type Usage name string Room name host string Hostname of the conference component opts string Room options, encoded as erlang terms created_at timestamp Creation date 
    The opts field is legible, but not mean to be modified directly. It contents depends on the implementation of mod_muc. It contains the room configuration and affiliations.
    "},{"location":"developer/sql-schema/#table-muc_registered","title":"Table muc_registered","text":"
    Contains a map of user to nicknames.  When a user register a nickname with the conference module, that nick is reserved and can't be used by anyone else, in any room from that conference host.
     Field Type Usage jid string User jid host string Hostname of the conference component nick string Room options, encoded as erlang terms created_at timestamp Creation date"},{"location":"developer/sql-schema/#table-room_history","title":"Table room_history","text":"
    In ejabberd Business Edition, this table is used if persistent room history is enabled. If so, recent room history is saved to the DB before ejabberd is stopped, allowing the recent history to survive server restarts.
     Field Type Usage room string Room jid nick string Nickname that sent the message packet string XML stanza with the message have_subject boolean True if the message stanza had subject created_at timestamp Creation date size integer Size in bytes of the xml packet"},{"location":"developer/sql-schema/#table-muc_online_room","title":"Table muc_online_room","text":"
    This table is used to store rooms that actually exists in the memory of the server.
     Field Type Usage name string Room name host string Hostname of the conference component node string Erlang node where the room is pid string Pid of the thread running the room"},{"location":"developer/sql-schema/#table-muc_online_users","title":"Table muc_online_users","text":"
    This table is used to store MucSub subscriptions.
     Field Type Usage username string User server string Hostname of the user resource string User resource name string Name of the room host string Hostname of the conference component node string Erlang node"},{"location":"developer/sql-schema/#table-muc_room_subscribers","title":"Table muc_room_subscribers","text":"
    This table is used to store MucSub subscriptions.
     Field Type Usage room string Room name host string Hostname of the conference component jid string User jid nick string User nick nodes string MucSub nodes created_at timestamp Creation date"},{"location":"developer/sql-schema/#vcard","title":"VCard","text":""},{"location":"developer/sql-schema/#table-vcard","title":"Table vcard","text":"
    The table is used to store raw vCard content for delivery of the vCard \"as is\".
     
    The table fields are defined as follow:
     Field Type Usage username string Owner of the Vcard vcard text Raw Vcard created_at timestamp Record creation date"},{"location":"developer/sql-schema/#table-vcard_search","title":"Table vcard_search","text":"
    The table is used to store vCard index on a few of the Vcard field used for vCard search in users directory.
     
    You can learn more about the vCard specification on Wikipedia vCard page.
     
    The table fields are defined as follow:
     Field Type Usage username string Raw username for display lusername string Lowercase username for search fn string Raw fullname for display lfn string Lowercase fullname for search family string Raw family name for display lfamilly string Lowercase family name for search given string Raw given name for display lgiven string Lowercase given name for search middle string Raw middle name for display lmiddle string Lowercase middle name for search nickname string Raw nickname for display lnickname string Lowercase nickname for search bday string Raw birthday for display lbday string Lowercase and processed birthday for search ctry string Raw country for display lctry string Lowercase country for search locality string Raw city for display llocality string Lowercase city for search email string Raw email for display lemail string Lowercase email for search orgname string Raw organisation name for display lorgname string Lowercase organisation name for search orgunit string Raw organisation department name for display lorgunit string Lowercase organisation department for search"},{"location":"developer/sql-schema/#others","title":"Others","text":""},{"location":"developer/sql-schema/#table-last","title":"Table last","text":"
    This table is used to store the last time the user was seen online. It is defined as follow:
     Field Type Usage username string User seconds string Timestamp for the last time the user was seen online state string Why user got disconnected. Usually is empty 
    Note that the table is not updated while the user has the session open.
    "},{"location":"developer/sql-schema/#table-caps_features","title":"Table caps_features","text":"
    Ejabberd uses this table to keep a list of the entity capabilities discovered.
     Field Type Usage node string Node subnode string Subnode feature string Entity feature created_at timestamp Creation date 
    The subnode field correspond to the 'ver' (\"verification string\") of XEP-0115. There is one entry in this table for each feature advertised by the given (node,subnode) pair.
    "},{"location":"developer/sql-schema/#table-private_storage","title":"Table private_storage","text":"
    Used for user private data storage.
     Field Type Usage username string User namespace string XEP-0049 namespace of the stored data data string Raw xml created_at timestamp Creation date"},{"location":"developer/vscode/","title":"Developing ejabberd with VSCode","text":"
     added in 23.01
     
    The ejabberd git repository includes basic configuration and a few scripts to get started with ejabberd development using Visual Studio Code.
     
    There are several Visual Studio Code flavours suitable for ejabberd development:
     
       
    • Visual Studio Code desktop app \u2013  local development with no dependencies
      •  
    • VSCodium desktop app \u2013  local development installing dependencies
      •  
    • Coder's code-server container image \u2013  local or remote development
      •  
    • GitHub Codespaces service \u2013  quick and short remote development
      •  
    "},{"location":"developer/vscode/#visual-studio-code","title":"Visual Studio Code","text":"
    The official Visual Studio Code installers provided by Microsoft can use the official marketplace. That allows to install the Dev Container extension to compile and run ejabberd inside a prepared container, which includes Erlang/OTP and all the required libraries, so you don't need to install them in your machine.
     
    However that installer is licensed under a not-FLOSS license and contains telemetry/tracking.
     
    Once installed: install Git as suggested, clone the ejabberd git repository locally, let it install the Dev Container extension, then let it reopen the path inside the devcontainer.
    "},{"location":"developer/vscode/#vscodium","title":"VSCodium","text":"
    VSCodium provides Free/Libre Open Source Software Binaries of VSCode. This is a great alternative to the official VSCode installer.
     
    However, it can't use the official marketplace, uses instead the open-vsx.com marketplace, and the Dev Containers extension is not available. This means that you must install the ejabberd dependencies in your system to compile and debug ejabberd.
     
    Once installed: open your local ejabberd git clone. It's highly recommended to go the EXTENSIONS tab and install the Erlang LS extension.
    "},{"location":"developer/vscode/#coders-code-server","title":"Coder's code-server","text":"
    An easy, zero-cost, way to use VSCode in a web browser is through the ejabberd's code-server container image. This image is based in the Debian docker image and includes Coder's code-server, Erlang/OTP, Elixir, and all the required libraries.
     
    Download and start the container, and provide as volume the path of your local ejabberd git clone:
     
    docker run \\\n    --name coder \\\n    -it \\\n    -p 5208:5208 \\\n    -v $(pwd)/ejabberd:/workspaces/ejabberd \\\n    ghcr.io/processone/code-server\n
     
    Now open in your web browser: http://0.0.0.0:5208/
     
    The next time it can be started with docker start -i coder
    "},{"location":"developer/vscode/#github-codespaces","title":"GitHub Codespaces","text":"
    The ejabberd git repository contains default configuration to use it in the GitHub Codespaces service.
     
    This can be used remotely over a web browser, no need to install anything. Notice this is a service that can be used for free several hours each month, and later requires a subscription.
     
    To start using it:
     
       
    1. Go to https://github.com/codespaces
      2.  
    2. Click \"New codespace\"
      3.  
    3. Select ejabberd repository, desired branch, click \"Create codespace\"
      4.  
    "},{"location":"developer/vscode/#basic-usage","title":"Basic Usage","text":"
    Once you have VSCode running and ejabberd git repository opened, open some erlang file, so Erlang LS extension gets started, and now you can go to RUN and run ejabberd for the first time. The first time it will take some time to compile, be patient.
     
    Now you can:
     
       
    • In RUN click \u25b7 Relive to compile and start ejabberd
      •  
    • In EXPLORER open any source code, and add a breakpoint
      •  
    • In TERMINAL you can call: ejabberdctl register admin localhost somepass
      •  
    • In PORTS you can view the addresses you can use to connect to the running ejabberd
      •  
     
    The ejabberd configuration file is in _build/relive/conf/ejabberd.yml.
     
    You can connect to ejabberd using a XMPP client using HTTPS BOSH or WS on port 5443. Webadmin is on port 5280, if it complains 404, add admin/ to the URL.
    "},{"location":"developer/ejabberd-api/","title":"ejabberd Rest API","text":""},{"location":"developer/ejabberd-api/#introduction","title":"Introduction","text":"
    ejabberd comes with a powerful API serving two goals:
     
       
    1. Manage the XMPP service and integrate the platform with back-end platforms and script tools.
      2.  
    2. Allow users to perform tasks via the client, allowing simple basic clients that do not need to use XMPP protocol.    This can be handy, for example to send a message from your smartwatch, or show the number of offline messages.
      3.  
     
    The system is powerful and very versatile and you can configure it very finely, but it can be quite daunting to set up.
     
    This section is written to demystify ejabberd API configuration and help you integrate ejabberd with your other back-ends or script through an HTTP / HTTPS ReST API.
    "},{"location":"developer/ejabberd-api/#understanding-ejabberd-commands","title":"Understanding ejabberd \"commands\"","text":"
    ejabberd operations are organised around the concept of commands. ejabberd standard modules already provide many commands, but the mechanism is generic and any module can provide its own set of commands. This exposition of commands for third-party modules make it very powerful.
     
    All commands can be exposed through interfaces. Available interfaces are:
     
       
    • ejabberdctl command-line tool,
      •  
    • mod_http_api for ReST calls using JSON data,
      •  
    • ejabberd_xmlrpc for XML-RPC calls,
      •  
    • to some extend, XMPP protocol itself through discovery and adhoc commands, using mod_configure.
      •  
     
    The ejabberd-contrib Github repository provides other interfaces that can be installed to execute ejabberd commands in different ways: mod_rest (HTTP POST service), mod_shcommands (ejabberd WebAdmin page).
     
    Any module in ejabberd can add its own command(s) through ejabberd Erlang/Elixir API, making the whole system totally extensible. A third-party module can expose its own command(s) and feel like a real part of the system. A module that exposes commands allows server admins to expose it the way they want.
     
    ejabberd commands are universal, extensible and widely available through various configurable entrypoints.
     
    Note: The XML-RPC API still works but is deprecated in favor of the ReST API. You should migrate to ReST if you are using it.
    "},{"location":"developer/ejabberd-api/#the-role-of-ejabberd-api","title":"The role of ejabberd API","text":"
    As we have seen, ejabberd API role is to provide and control access to ejabberd commands over HTTP/HTTPS.
     
    Thus, ejabberd API primary goal is to grant access to some or all ejabberd \"commands\".
     
    An admin ejabberd ReST API requires:
     
       
    • At least one admin user, if you plan to check credentials for command access (You can alternatively rely on originating IP addresses).
      •  
    • HTTP/HTTPS handlers configured to expose the desired commands.
      •  
    • The selection of authentication mechanisms that can be used to access the API.   Two mechanisms are available to access the HTTP API:
      •  
    • Basic authentication. This mechanism is enabled by default.
      •  
    • OAuth 2.0 token based authentication. It has to be explicitly added to the config file.
      •  
    "},{"location":"developer/ejabberd-api/#learning-the-basics","title":"Learning the basics","text":"
    The first resources to read to learn about ejabberd ReST API configuration are the following:
     
       
    • Simple API configuration
      •  
    • Using ejabberd client API libraries and tools
      •  
     
    The list of available commands is available in the API Reference section. Additionally, you can check at runtime what commands are available in your installed server using ejabberdctl:
     
    \u276f ejabberdctl\nUsage: ejabberdctl [--no-timeout] [--node nodename] [--version api_version] command [arguments]\n\nAvailable commands in this ejabberd node:\n  backup file\n             Store internal Mnesia database to binary backup file\n  ban_account user host reason\n             Ban an account: kick sessions and set random password\n  ...\n\n\u276f ejabberdctl help\n  ...\n\n\u276f ejabberdctl help ban_account\n  ...\n
    "},{"location":"developer/ejabberd-api/#next-steps","title":"Next steps","text":"
    You can dig deeper into ejabberd ReST API configuration on the following pages:
     
       
    • API Permissions
      •  
    • OAuth Support
      •  
    • Administration API Commands
      •  
    "},{"location":"developer/ejabberd-api/admin-api/","title":"API Reference","text":"
    This section describes API commands of ejabberd 24.02.  If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the Archive. The commands that changed in this version are marked with \ud83d\udfe4.
    "},{"location":"developer/ejabberd-api/admin-api/#abort_delete_old_mam_messages","title":"abort_delete_old_mam_messages","text":"
     added in 22.05
     
    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
     
    Module: mod_mam
     
    Examples:
     
    POST /api/abort_delete_old_mam_messages\n{\n  \"host\": \"localhost\"\n}\n\nHTTP/1.1 200 OK\n\"Operation aborted\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#abort_delete_old_messages","title":"abort_delete_old_messages","text":"
     added in 22.05
     
    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
     
    Examples:
     
    POST /api/abort_delete_old_messages\n{\n  \"host\": \"localhost\"\n}\n\nHTTP/1.1 200 OK\n\"Operation aborted\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#add_rosteritem","title":"add_rosteritem \ud83d\udfe4","text":"
     updated in 24.02
     
    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, v1
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/add_rosteritem\n{\n  \"localuser\": \"user1\",\n  \"localhost\": \"myserver.com\",\n  \"user\": \"user2\",\n  \"host\": \"myserver.com\",\n  \"nick\": \"User 2\",\n  \"groups\": [\n    \"Friends\",\n    \"Team 1\"\n  ],\n  \"subs\": \"both\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#backup","title":"backup","text":"
    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
     
    Examples:
     
    POST /api/backup\n{\n  \"file\": \"/var/lib/ejabberd/database.backup\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#ban_account","title":"ban_account","text":"
    Ban an account: kick sessions and set random password
     
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/ban_account\n{\n  \"user\": \"attacker\",\n  \"host\": \"myserver.com\",\n  \"reason\": \"Spaming other users\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#bookmarks_to_pep","title":"bookmarks_to_pep","text":"
    Export private XML storage bookmarks to PEP
     
    Arguments:
     
       
    • user :: string : Username
      •  
    • host :: string : Server
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: private
     
    Module: mod_private
     
    Examples:
     
    POST /api/bookmarks_to_pep\n{\n  \"user\": \"bob\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n\"Bookmarks exported\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#change_password","title":"change_password","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/change_password\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\",\n  \"newpass\": \"blank\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#change_room_option","title":"change_room_option","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/change_room_option\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\",\n  \"option\": \"members_only\",\n  \"value\": \"true\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#check_account","title":"check_account","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/check_account\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#check_password","title":"check_password","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/check_password\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\",\n  \"password\": \"secret\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#check_password_hash","title":"check_password_hash","text":"
    Check if the password hash is correct
     
    Allows hash methods from the Erlang/OTP 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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/check_password_hash\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\",\n  \"passwordhash\": \"5ebe2294ecd0e0f08eab7690d2a6ee69\",\n  \"hashmethod\": \"md5\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#clear_cache","title":"clear_cache","text":"
    Clear database cache on all nodes
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/clear_cache\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#compile","title":"compile","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/compile\n{\n  \"file\": \"/home/me/srcs/ejabberd/mod_example.erl\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#connected_users","title":"connected_users","text":"
    List all established sessions
     
    Arguments:
     
    Result:
     
       
    • connected_users :: [sessions::string] : List of users sessions
      •  
     
    Tags: session
     
    Examples:
     
    POST /api/connected_users\n{\n\n}\n\nHTTP/1.1 200 OK\n[\n  \"user1@example.com\",\n  \"user2@example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#connected_users_info","title":"connected_users_info","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/connected_users_info\n{\n\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"jid\": \"user1@myserver.com/tka\",\n    \"connection\": \"c2s\",\n    \"ip\": \"127.0.0.1\",\n    \"port\": 42656,\n    \"priority\": 8,\n    \"node\": \"ejabberd@localhost\",\n    \"uptime\": 231,\n    \"status\": \"dnd\",\n    \"resource\": \"tka\",\n    \"statustext\": \"\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#connected_users_number","title":"connected_users_number","text":"
    Get the number of established sessions
     
    Arguments:
     
    Result:
     
       
    • num_sessions :: integer
      •  
     
    Tags: session, statistics
     
    Examples:
     
    POST /api/connected_users_number\n{\n\n}\n\nHTTP/1.1 200 OK\n2\n
    "},{"location":"developer/ejabberd-api/admin-api/#connected_users_vhost","title":"connected_users_vhost","text":"
    Get the list of established sessions in a vhost
     
    Arguments:
     
       
    • host :: string : Server name
      •  
     
    Result:
     
       
    • connected_users_vhost :: [sessions::string]
      •  
     
    Tags: session
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/connected_users_vhost\n{\n  \"host\": \"myexample.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"user1@myserver.com/tka\",\n  \"user2@localhost/tka\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#convert_to_scram","title":"convert_to_scram","text":"
    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
     
    Examples:
     
    POST /api/convert_to_scram\n{\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#convert_to_yaml","title":"convert_to_yaml","text":"
    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
     
    Examples:
     
    POST /api/convert_to_yaml\n{\n  \"in\": \"/etc/ejabberd/ejabberd.cfg\",\n  \"out\": \"/etc/ejabberd/ejabberd.yml\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#create_room","title":"create_room","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/create_room\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#create_room_with_opts","title":"create_room_with_opts","text":"
    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, muc_sub
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/create_room_with_opts\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\",\n  \"host\": \"localhost\",\n  \"options\": [\n    {\n      \"name\": \"members_only\",\n      \"value\": \"true\"\n    },\n    {\n      \"name\": \"affiliations\",\n      \"value\": \"owner:bob@example.com,member:peter@example.com\"\n    },\n    {\n      \"name\": \"subscribers\",\n      \"value\": \"bob@example.com:Bob:messages:subject,anne@example.com:Anne:messages\"\n    }\n  ]\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#create_rooms_file","title":"create_rooms_file","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/create_rooms_file\n{\n  \"file\": \"/home/ejabberd/rooms.txt\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_expired_messages","title":"delete_expired_messages","text":"
    Delete expired offline messages from database
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: purge
     
    Examples:
     
    POST /api/delete_expired_messages\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_expired_pubsub_items","title":"delete_expired_pubsub_items","text":"
     added in 21.12
     
    Delete expired PubSub items
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: purge
     
    Module: mod_pubsub
     
    Examples:
     
    POST /api/delete_expired_pubsub_items\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_mnesia","title":"delete_mnesia","text":"
    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
     
    Examples:
     
    POST /api/delete_mnesia\n{\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_mam_messages","title":"delete_old_mam_messages","text":"
    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
     
    Module: mod_mam
     
    Examples:
     
    POST /api/delete_old_mam_messages\n{\n  \"type\": \"all\",\n  \"days\": 31\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_mam_messages_batch","title":"delete_old_mam_messages_batch","text":"
     added in 22.05
     
    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
     
    Module: mod_mam
     
    Examples:
     
    POST /api/delete_old_mam_messages_batch\n{\n  \"host\": \"localhost\",\n  \"type\": \"all\",\n  \"days\": 31,\n  \"batch_size\": 1000,\n  \"rate\": 10000\n}\n\nHTTP/1.1 200 OK\n\"Removal of 5000 messages in progress\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_mam_messages_status","title":"delete_old_mam_messages_status","text":"
     added in 22.05
     
    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
     
    Module: mod_mam
     
    Examples:
     
    POST /api/delete_old_mam_messages_status\n{\n  \"host\": \"localhost\"\n}\n\nHTTP/1.1 200 OK\n\"Operation in progress, delete 5000 messages\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_messages","title":"delete_old_messages","text":"
    Delete offline messages older than DAYS
     
    Arguments:
     
       
    • days :: integer : Number of days
      •  
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: purge
     
    Examples:
     
    POST /api/delete_old_messages\n{\n  \"days\": 31\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_messages_batch","title":"delete_old_messages_batch","text":"
     added in 22.05
     
    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
     
    Examples:
     
    POST /api/delete_old_messages_batch\n{\n  \"host\": \"localhost\",\n  \"days\": 31,\n  \"batch_size\": 1000,\n  \"rate\": 10000\n}\n\nHTTP/1.1 200 OK\n\"Removal of 5000 messages in progress\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_messages_status","title":"delete_old_messages_status","text":"
     added in 22.05
     
    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
     
    Examples:
     
    POST /api/delete_old_messages_status\n{\n  \"host\": \"localhost\"\n}\n\nHTTP/1.1 200 OK\n\"Operation in progress, delete 5000 messages\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_pubsub_items","title":"delete_old_pubsub_items","text":"
     added in 21.12
     
    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
     
    Module: mod_pubsub
     
    Examples:
     
    POST /api/delete_old_pubsub_items\n{\n  \"number\": 1000\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_push_sessions","title":"delete_old_push_sessions","text":"
    Remove push sessions older than DAYS
     
    Arguments:
     
       
    • days :: integer
      •  
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: purge
     
    Module: mod_push
     
    Examples:
     
    POST /api/delete_old_push_sessions\n{\n  \"days\": 1\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_users","title":"delete_old_users","text":"
    Delete users that didn't log in last days, or that never logged
     
    To protect admin accounts, configure this for example: 
    access_rules:\n  protect_old_users:\n    - allow: admin\n    - deny: all\n
     
    Arguments:
     
       
    • days :: integer : Last login age in days of accounts that should be removed
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: accounts, purge
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/delete_old_users\n{\n  \"days\": 30\n}\n\nHTTP/1.1 200 OK\n\"Deleted 2 users: [\"oldman@myserver.com\", \"test@myserver.com\"]\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_old_users_vhost","title":"delete_old_users_vhost","text":"
    Delete users that didn't log in last days in vhost, or that never logged
     
    To protect admin accounts, configure this for example: 
    access_rules:\n  delete_old_users:\n    - deny: admin\n    - allow: all\n
     
    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, purge
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/delete_old_users_vhost\n{\n  \"host\": \"myserver.com\",\n  \"days\": 30\n}\n\nHTTP/1.1 200 OK\n\"Deleted 2 users: [\"oldman@myserver.com\", \"test@myserver.com\"]\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#delete_rosteritem","title":"delete_rosteritem","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/delete_rosteritem\n{\n  \"localuser\": \"user1\",\n  \"localhost\": \"myserver.com\",\n  \"user\": \"user2\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#destroy_room","title":"destroy_room","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/destroy_room\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#destroy_rooms_file","title":"destroy_rooms_file","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/destroy_rooms_file\n{\n  \"file\": \"/home/ejabberd/rooms.txt\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#dump","title":"dump","text":"
    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
     
    Examples:
     
    POST /api/dump\n{\n  \"file\": \"/var/lib/ejabberd/database.txt\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#dump_config","title":"dump_config","text":"
    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
     
    Examples:
     
    POST /api/dump_config\n{\n  \"out\": \"/tmp/ejabberd.yml\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#dump_table","title":"dump_table","text":"
    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
     
    Examples:
     
    POST /api/dump_table\n{\n  \"file\": \"/var/lib/ejabberd/table-muc-registered.txt\",\n  \"table\": \"muc_registered\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#export2sql","title":"export2sql","text":"
    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 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
     
    Examples:
     
    POST /api/export2sql\n{\n  \"host\": \"example.com\",\n  \"file\": \"/var/lib/ejabberd/example.com.sql\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#export_piefxis","title":"export_piefxis","text":"
    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
     
    Examples:
     
    POST /api/export_piefxis\n{\n  \"dir\": \"/var/lib/ejabberd/\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#export_piefxis_host","title":"export_piefxis_host","text":"
    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
     
    Examples:
     
    POST /api/export_piefxis_host\n{\n  \"dir\": \"/var/lib/ejabberd/\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#gc","title":"gc","text":"
     added in 20.01
     
    Force full garbage collection
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/gc\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#gen_html_doc_for_commands","title":"gen_html_doc_for_commands","text":"
    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
     
    Examples:
     
    POST /api/gen_html_doc_for_commands\n{\n  \"file\": \"/home/me/docs/api.html\",\n  \"regexp\": \"mod_admin\",\n  \"examples\": \"java,json\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#gen_markdown_doc_for_commands","title":"gen_markdown_doc_for_commands","text":"
    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
     
    Examples:
     
    POST /api/gen_markdown_doc_for_commands\n{\n  \"file\": \"/home/me/docs/api.html\",\n  \"regexp\": \"mod_admin\",\n  \"examples\": \"java,json\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#gen_markdown_doc_for_tags","title":"gen_markdown_doc_for_tags","text":"
     added in 21.12
     
    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
     
    Examples:
     
    POST /api/gen_markdown_doc_for_tags\n{\n  \"file\": \"/home/me/docs/tags.md\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_cookie","title":"get_cookie","text":"
    Get the Erlang cookie of this node
     
    Arguments:
     
    Result:
     
       
    • cookie :: string : Erlang cookie used for authentication by ejabberd
      •  
     
    Tags: erlang
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_cookie\n{\n\n}\n\nHTTP/1.1 200 OK\n\"MWTAVMODFELNLSMYXPPD\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_last","title":"get_last","text":"
    Get last activity information
     
    Timestamp is UTC and XEP-0082 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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_last\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n{\n  \"timestamp\": \"2017-06-30T14:32:16.060684Z\",\n  \"status\": \"ONLINE\"\n}\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_loglevel","title":"get_loglevel","text":"
    Get the current loglevel
     
    Arguments:
     
    Result:
     
       
    • levelatom :: string : Tuple with the log level number, its keyword and description
      •  
     
    Tags: logs
     
    Examples:
     
    POST /api/get_loglevel\n{\n\n}\n\nHTTP/1.1 200 OK\n\"warning\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_offline_count","title":"get_offline_count","text":"
    Get the number of unread offline messages
     
    Arguments:
     
       
    • user :: string
      •  
    • host :: string
      •  
     
    Result:
     
       
    • value :: integer : Number
      •  
     
    Tags: offline
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_offline_count\n{\n  \"user\": \"aaaaa\",\n  \"host\": \"bbbbb\"\n}\n\nHTTP/1.1 200 OK\n5\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_presence","title":"get_presence","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_presence\n{\n  \"user\": \"peter\",\n  \"host\": \"myexample.com\"\n}\n\nHTTP/1.1 200 OK\n{\n  \"jid\": \"user1@myserver.com/tka\",\n  \"show\": \"dnd\",\n  \"status\": \"Busy\"\n}\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_room_affiliation","title":"get_room_affiliation","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_room_affiliation\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\",\n  \"jid\": \"user1@example.com\"\n}\n\nHTTP/1.1 200 OK\n\"member\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_room_affiliations","title":"get_room_affiliations","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_room_affiliations\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"username\": \"user1\",\n    \"domain\": \"example.com\",\n    \"affiliation\": \"member\",\n    \"reason\": \"member\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_room_history","title":"get_room_history","text":"
     added in 23.04
     
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_room_history\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"timestamp\": \"aaaaa\",\n    \"message\": \"bbbbb\"\n  },\n  {\n    \"timestamp\": \"ccccc\",\n    \"message\": \"ddddd\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_room_occupants","title":"get_room_occupants","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_room_occupants\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"jid\": \"user1@example.com/psi\",\n    \"nick\": \"User 1\",\n    \"role\": \"owner\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_room_occupants_number","title":"get_room_occupants_number","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_room_occupants_number\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n7\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_room_options","title":"get_room_options","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_room_options\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"name\": \"members_only\",\n    \"value\": \"true\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_roster","title":"get_roster","text":"
     improved in 23.10
     
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_roster\n{\n  \"user\": \"aaaaa\",\n  \"host\": \"bbbbb\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"jid\": \"aaaaa\",\n    \"nick\": \"bbbbb\",\n    \"subscription\": \"ccccc\",\n    \"pending\": \"ddddd\",\n    \"groups\": [\n      \"eeeee\",\n      \"fffff\"\n    ]\n  },\n  {\n    \"jid\": \"ggggg\",\n    \"nick\": \"hhhhh\",\n    \"subscription\": \"iiiii\",\n    \"pending\": \"jjjjj\",\n    \"groups\": [\n      \"kkkkk\",\n      \"lllll\"\n    ]\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_subscribers","title":"get_subscribers","text":"
    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, muc_sub
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_subscribers\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"user2@example.com\",\n  \"user3@example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_user_rooms","title":"get_user_rooms","text":"
    Get the list of rooms where this user is occupant
     
    Arguments:
     
       
    • user :: string : Username
      •  
    • host :: string : Server host
      •  
     
    Result:
     
       
    • rooms :: [room::string]
      •  
     
    Tags: muc
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_user_rooms\n{\n  \"user\": \"tom\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"room1@muc.example.com\",\n  \"room2@muc.example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_user_subscriptions","title":"get_user_subscriptions","text":"
     added in 21.04
     
    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, muc_sub
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/get_user_subscriptions\n{\n  \"user\": \"tom\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"roomjid\": \"room1@muc.example.com\",\n    \"usernick\": \"Tommy\",\n    \"nodes\": [\n      \"mucsub:config\"\n    ]\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_vcard","title":"get_vcard","text":"
    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
     
    Arguments:
     
       
    • user :: string : User name
      •  
    • host :: string : Server name
      •  
    • name :: string : Field name
      •  
     
    Result:
     
       
    • content :: string : Field content
      •  
     
    Tags: vcard
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_vcard\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"name\": \"NICKNAME\"\n}\n\nHTTP/1.1 200 OK\n\"User 1\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_vcard2","title":"get_vcard2","text":"
    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
     
    Arguments:
     
       
    • user :: string : User name
      •  
    • host :: string : Server name
      •  
    • name :: string : Field name
      •  
    • subname :: string : Subfield name
      •  
     
    Result:
     
       
    • content :: string : Field content
      •  
     
    Tags: vcard
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_vcard2\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"name\": \"N\",\n  \"subname\": \"FAMILY\"\n}\n\nHTTP/1.1 200 OK\n\"Schubert\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#get_vcard2_multi","title":"get_vcard2_multi","text":"
    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
     
    Arguments:
     
       
    • user :: string
      •  
    • host :: string
      •  
    • name :: string
      •  
    • subname :: string
      •  
     
    Result:
     
       
    • contents :: [value::string]
      •  
     
    Tags: vcard
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/get_vcard2_multi\n{\n  \"user\": \"aaaaa\",\n  \"host\": \"bbbbb\",\n  \"name\": \"ccccc\",\n  \"subname\": \"ddddd\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"aaaaa\",\n  \"bbbbb\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#halt","title":"halt","text":"
     added in 23.10
     
    Halt ejabberd abruptly with status code 1
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/halt\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#help","title":"help","text":"
    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
     
    Examples:
     
    POST /api/help\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#import_dir","title":"import_dir","text":"
    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
     
    Examples:
     
    POST /api/import_dir\n{\n  \"file\": \"/var/lib/ejabberd/jabberd14/\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#import_file","title":"import_file","text":"
    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
     
    Examples:
     
    POST /api/import_file\n{\n  \"file\": \"/var/lib/ejabberd/jabberd14.spool\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#import_piefxis","title":"import_piefxis","text":"
    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
     
    Examples:
     
    POST /api/import_piefxis\n{\n  \"file\": \"/var/lib/ejabberd/example.com.xml\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#import_prosody","title":"import_prosody","text":"
    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, sql
     
    Examples:
     
    POST /api/import_prosody\n{\n  \"dir\": \"/var/lib/prosody/datadump/\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#incoming_s2s_number","title":"incoming_s2s_number","text":"
    Number of incoming s2s connections on the node
     
    Arguments:
     
    Result:
     
       
    • s2s_incoming :: integer
      •  
     
    Tags: statistics, s2s
     
    Examples:
     
    POST /api/incoming_s2s_number\n{\n\n}\n\nHTTP/1.1 200 OK\n1\n
    "},{"location":"developer/ejabberd-api/admin-api/#install_fallback","title":"install_fallback","text":"
    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 API.
     
    Arguments:
     
       
    • file :: string : Full path to the fallback file
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: mnesia
     
    Examples:
     
    POST /api/install_fallback\n{\n  \"file\": \"/var/lib/ejabberd/database.fallback\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#join_cluster","title":"join_cluster","text":"
    Join this node into the cluster handled by Node
     
    This command works only with ejabberdctl, not mod_http_api or other code that runs inside the same ejabberd node that will be joined.
     
    Arguments:
     
       
    • node :: string : Nodename of the node to join
      •  
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: cluster
     
    Examples:
     
    POST /api/join_cluster\n{\n  \"node\": \"ejabberd1@machine7\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#kick_session","title":"kick_session","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/kick_session\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\",\n  \"resource\": \"Psi\",\n  \"reason\": \"Stuck connection\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#kick_user","title":"kick_user","text":"
    Disconnect user's active sessions
     
    Arguments:
     
       
    • user :: string : User name
      •  
    • host :: string : Server name
      •  
     
    Result:
     
       
    • num_resources :: integer : Number of resources that were kicked
      •  
     
    Tags: session
     
    Examples:
     
    POST /api/kick_user\n{\n  \"user\": \"user1\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n3\n
    "},{"location":"developer/ejabberd-api/admin-api/#leave_cluster","title":"leave_cluster","text":"
    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
     
    Examples:
     
    POST /api/leave_cluster\n{\n  \"node\": \"ejabberd1@machine8\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#list_certificates","title":"list_certificates","text":"
    Lists all ACME certificates
     
    Arguments:
     
    Result:
     
       
    • certificates :: [{domain::string, file::string, used::string}]
      •  
     
    Tags: acme
     
    Examples:
     
    POST /api/list_certificates\n{\n\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"domain\": \"aaaaa\",\n    \"file\": \"bbbbb\",\n    \"used\": \"ccccc\"\n  },\n  {\n    \"domain\": \"ddddd\",\n    \"file\": \"eeeee\",\n    \"used\": \"fffff\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#list_cluster","title":"list_cluster","text":"
    List nodes that are part of the cluster handled by Node
     
    Arguments:
     
    Result:
     
       
    • nodes :: [node::string]
      •  
     
    Tags: cluster
     
    Examples:
     
    POST /api/list_cluster\n{\n\n}\n\nHTTP/1.1 200 OK\n[\n  \"ejabberd1@machine7\",\n  \"ejabberd1@machine8\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#load","title":"load","text":"
    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 API and install_fallback API.
     
    Arguments:
     
       
    • file :: string : Full path to the text file
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: mnesia
     
    Examples:
     
    POST /api/load\n{\n  \"file\": \"/var/lib/ejabberd/database.txt\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#man","title":"man","text":"
     added in 20.01
     
    Generate Unix manpage for current ejabberd version
     
    Arguments:
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: documentation
     
    Examples:
     
    POST /api/man\n{\n\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#mnesia_change_nodename","title":"mnesia_change_nodename","text":"
    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
     
    Examples:
     
    POST /api/mnesia_change_nodename\n{\n  \"oldnodename\": \"ejabberd@machine1\",\n  \"newnodename\": \"ejabberd@machine2\",\n  \"oldbackup\": \"/var/lib/ejabberd/old.backup\",\n  \"newbackup\": \"/var/lib/ejabberd/new.backup\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#mnesia_info","title":"mnesia_info","text":"
    Dump info on global Mnesia state
     
    Arguments:
     
    Result:
     
       
    • res :: string
      •  
     
    Tags: mnesia
     
    Examples:
     
    POST /api/mnesia_info\n{\n\n}\n\nHTTP/1.1 200 OK\n\"aaaaa\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#mnesia_info_ctl","title":"mnesia_info_ctl \ud83d\udfe4","text":"
     renamed in 24.02
     
    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, mnesia
     
    Examples:
     
    POST /api/mnesia_info_ctl\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#mnesia_table_info","title":"mnesia_table_info","text":"
    Dump info on Mnesia table state
     
    Arguments:
     
       
    • table :: string : Mnesia table name
      •  
     
    Result:
     
       
    • res :: string
      •  
     
    Tags: mnesia
     
    Examples:
     
    POST /api/mnesia_table_info\n{\n  \"table\": \"roster\"\n}\n\nHTTP/1.1 200 OK\n\"aaaaa\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#module_check","title":"module_check","text":"
    Check the contributed module repository compliance
     
    Arguments:
     
       
    • module :: string : Module name
      •  
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: modules
     
    Examples:
     
    POST /api/module_check\n{\n  \"module\": \"mod_rest\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#module_install","title":"module_install","text":"
    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
     
    Examples:
     
    POST /api/module_install\n{\n  \"module\": \"mod_rest\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#module_uninstall","title":"module_uninstall","text":"
    Uninstall a contributed module
     
    Arguments:
     
       
    • module :: string : Module name
      •  
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: modules
     
    Examples:
     
    POST /api/module_uninstall\n{\n  \"module\": \"mod_rest\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#module_upgrade","title":"module_upgrade","text":"
    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
     
    Examples:
     
    POST /api/module_upgrade\n{\n  \"module\": \"mod_rest\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#modules_available","title":"modules_available","text":"
    List the contributed modules available to install
     
    Arguments:
     
    Result:
     
       
    • modules :: [{name::string, summary::string}] : List of tuples with module name and description
      •  
     
    Tags: modules
     
    Examples:
     
    POST /api/modules_available\n{\n\n}\n\nHTTP/1.1 200 OK\n{\n  \"mod_cron\": \"Execute scheduled commands\",\n  \"mod_rest\": \"ReST frontend\"\n}\n
    "},{"location":"developer/ejabberd-api/admin-api/#modules_installed","title":"modules_installed","text":"
    List the contributed modules already installed
     
    Arguments:
     
    Result:
     
       
    • modules :: [{name::string, summary::string}] : List of tuples with module name and description
      •  
     
    Tags: modules
     
    Examples:
     
    POST /api/modules_installed\n{\n\n}\n\nHTTP/1.1 200 OK\n{\n  \"mod_cron\": \"Execute scheduled commands\",\n  \"mod_rest\": \"ReST frontend\"\n}\n
    "},{"location":"developer/ejabberd-api/admin-api/#modules_update_specs","title":"modules_update_specs","text":"
    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
     
    Examples:
     
    POST /api/modules_update_specs\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#muc_online_rooms","title":"muc_online_rooms","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/muc_online_rooms\n{\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"room1@muc.example.com\",\n  \"room2@muc.example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#muc_online_rooms_by_regex","title":"muc_online_rooms_by_regex","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/muc_online_rooms_by_regex\n{\n  \"service\": \"muc.example.com\",\n  \"regex\": \"^prefix\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"jid\": \"room1@muc.example.com\",\n    \"public\": \"true\",\n    \"participants\": 10\n  },\n  {\n    \"jid\": \"room2@muc.example.com\",\n    \"public\": \"false\",\n    \"participants\": 10\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#muc_register_nick","title":"muc_register_nick","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/muc_register_nick\n{\n  \"nick\": \"Tim\",\n  \"jid\": \"tim@example.org\",\n  \"service\": \"muc.example.org\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#muc_unregister_nick","title":"muc_unregister_nick","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/muc_unregister_nick\n{\n  \"jid\": \"tim@example.org\",\n  \"service\": \"muc.example.org\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#num_resources","title":"num_resources","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/num_resources\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n5\n
    "},{"location":"developer/ejabberd-api/admin-api/#oauth_add_client_implicit","title":"oauth_add_client_implicit","text":"
    Add OAuth client_id with implicit grant type
     
    Arguments:
     
       
    • client_id :: string
      •  
    • client_name :: string
      •  
    • redirect_uri :: string
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: oauth
     
    Examples:
     
    POST /api/oauth_add_client_implicit\n{\n  \"client_id\": \"aaaaa\",\n  \"client_name\": \"bbbbb\",\n  \"redirect_uri\": \"ccccc\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#oauth_add_client_password","title":"oauth_add_client_password","text":"
    Add OAuth client_id with password grant type
     
    Arguments:
     
       
    • client_id :: string
      •  
    • client_name :: string
      •  
    • secret :: string
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: oauth
     
    Examples:
     
    POST /api/oauth_add_client_password\n{\n  \"client_id\": \"aaaaa\",\n  \"client_name\": \"bbbbb\",\n  \"secret\": \"ccccc\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#oauth_issue_token","title":"oauth_issue_token \ud83d\udfe4","text":"
     updated in 24.02
     
    Issue an OAuth 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, v1
     
    Examples:
     
    POST /api/oauth_issue_token\n{\n  \"jid\": \"user@server.com\",\n  \"ttl\": 3600,\n  \"scopes\": [\n    \"connected_users_number\",\n    \"muc_online_rooms\"\n  ]\n}\n\nHTTP/1.1 200 OK\n{\n  \"token\": \"aaaaa\",\n  \"scopes\": [\n    \"bbbbb\",\n    \"ccccc\"\n  ],\n  \"expires_in\": \"ddddd\"\n}\n
    "},{"location":"developer/ejabberd-api/admin-api/#oauth_list_tokens","title":"oauth_list_tokens","text":"
    List OAuth 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
     
    Examples:
     
    POST /api/oauth_list_tokens\n{\n\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"token\": \"aaaaa\",\n    \"user\": \"bbbbb\",\n    \"scope\": \"ccccc\",\n    \"expires_in\": \"ddddd\"\n  },\n  {\n    \"token\": \"eeeee\",\n    \"user\": \"fffff\",\n    \"scope\": \"ggggg\",\n    \"expires_in\": \"hhhhh\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#oauth_remove_client","title":"oauth_remove_client","text":"
    Remove OAuth client_id
     
    Arguments:
     
       
    • client_id :: string
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: oauth
     
    Examples:
     
    POST /api/oauth_remove_client\n{\n  \"client_id\": \"aaaaa\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#oauth_revoke_token","title":"oauth_revoke_token","text":"
     changed in 22.05
     
    Revoke authorization for an OAuth token
     
    Arguments:
     
       
    • token :: string
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: oauth
     
    Examples:
     
    POST /api/oauth_revoke_token\n{\n  \"token\": \"aaaaa\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#outgoing_s2s_number","title":"outgoing_s2s_number","text":"
    Number of outgoing s2s connections on the node
     
    Arguments:
     
    Result:
     
       
    • s2s_outgoing :: integer
      •  
     
    Tags: statistics, s2s
     
    Examples:
     
    POST /api/outgoing_s2s_number\n{\n\n}\n\nHTTP/1.1 200 OK\n1\n
    "},{"location":"developer/ejabberd-api/admin-api/#print_sql_schema","title":"print_sql_schema \ud83d\udfe4","text":"
     added in 24.02
     
    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, sql
     
    Examples:
     
    POST /api/print_sql_schema\n{\n  \"db_type\": \"pgsql\",\n  \"db_version\": \"16.1\",\n  \"new_schema\": \"true\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#privacy_set","title":"privacy_set","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/privacy_set\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"xmlquery\": \"<query xmlns='jabber:iq:privacy'>...\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#private_get","title":"private_get","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/private_get\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"element\": \"storage\",\n  \"ns\": \"storage:rosternotes\"\n}\n\nHTTP/1.1 200 OK\n\"aaaaa\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#private_set","title":"private_set","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/private_set\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"element\": \"<storage xmlns='storage:rosternotes'/>\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#process_rosteritems","title":"process_rosteritems","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/process_rosteritems\n{\n  \"action\": \"aaaaa\",\n  \"subs\": \"bbbbb\",\n  \"asks\": \"ccccc\",\n  \"users\": \"ddddd\",\n  \"contacts\": \"eeeee\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"user\": \"aaaaa\",\n    \"contact\": \"bbbbb\"\n  },\n  {\n    \"user\": \"ccccc\",\n    \"contact\": \"ddddd\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#push_alltoall","title":"push_alltoall","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/push_alltoall\n{\n  \"host\": \"myserver.com\",\n  \"group\": \"Everybody\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#push_roster","title":"push_roster","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/push_roster\n{\n  \"file\": \"/home/ejabberd/roster.txt\",\n  \"user\": \"user1\",\n  \"host\": \"localhost\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#push_roster_all","title":"push_roster_all","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/push_roster_all\n{\n  \"file\": \"/home/ejabberd/roster.txt\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#register","title":"register","text":"
    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
     
    Examples:
     
    POST /api/register\n{\n  \"user\": \"bob\",\n  \"host\": \"example.com\",\n  \"password\": \"SomEPass44\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#registered_users","title":"registered_users","text":"
    List all registered users in HOST
     
    Arguments:
     
       
    • host :: string : Local vhost
      •  
     
    Result:
     
       
    • users :: [username::string] : List of registered accounts usernames
      •  
     
    Tags: accounts
     
    Examples:
     
    POST /api/registered_users\n{\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"user1\",\n  \"user2\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#registered_vhosts","title":"registered_vhosts","text":"
    List all registered vhosts in SERVER
     
    Arguments:
     
    Result:
     
       
    • vhosts :: [vhost::string] : List of available vhosts
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/registered_vhosts\n{\n\n}\n\nHTTP/1.1 200 OK\n[\n  \"example.com\",\n  \"anon.example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#reload_config","title":"reload_config","text":"
    Reload config file in memory
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: config
     
    Examples:
     
    POST /api/reload_config\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#remove_mam_for_user","title":"remove_mam_for_user","text":"
    Remove mam archive for user
     
    Arguments:
     
       
    • user :: string : Username
      •  
    • host :: string : Server
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: mam
     
    Module: mod_mam
     
    Examples:
     
    POST /api/remove_mam_for_user\n{\n  \"user\": \"bob\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n\"MAM archive removed\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#remove_mam_for_user_with_peer","title":"remove_mam_for_user_with_peer","text":"
    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
     
    Module: mod_mam
     
    Examples:
     
    POST /api/remove_mam_for_user_with_peer\n{\n  \"user\": \"bob\",\n  \"host\": \"example.com\",\n  \"with\": \"anne@example.com\"\n}\n\nHTTP/1.1 200 OK\n\"MAM archive removed\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#reopen_log","title":"reopen_log","text":"
    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.
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: logs
     
    Examples:
     
    POST /api/reopen_log\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#request_certificate","title":"request_certificate","text":"
    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
     
    Examples:
     
    POST /api/request_certificate\n{\n  \"domains\": \"example.com,domain.tld,conference.domain.tld\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#resource_num","title":"resource_num","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/resource_num\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\",\n  \"num\": 2\n}\n\nHTTP/1.1 200 OK\n\"Psi\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#restart","title":"restart","text":"
    Restart ejabberd gracefully
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/restart\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#restart_module","title":"restart_module","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/restart_module\n{\n  \"host\": \"myserver.com\",\n  \"module\": \"mod_admin_extra\"\n}\n\nHTTP/1.1 200 OK\n0\n
    "},{"location":"developer/ejabberd-api/admin-api/#restore","title":"restore","text":"
    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 API.
     
    Arguments:
     
       
    • file :: string : Full path to the backup file
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: mnesia
     
    Examples:
     
    POST /api/restore\n{\n  \"file\": \"/var/lib/ejabberd/database.backup\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#revoke_certificate","title":"revoke_certificate","text":"
    Revokes the selected ACME certificate
     
    Arguments:
     
       
    • file :: string : Filename of the certificate
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: acme
     
    Examples:
     
    POST /api/revoke_certificate\n{\n  \"file\": \"aaaaa\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#rooms_empty_destroy","title":"rooms_empty_destroy","text":"
    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:
     
       
    • rooms :: [room::string] : List of empty rooms that have been destroyed
      •  
     
    Tags: muc
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/rooms_empty_destroy\n{\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"room1@muc.example.com\",\n  \"room2@muc.example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#rooms_empty_list","title":"rooms_empty_list","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/rooms_empty_list\n{\n  \"service\": \"muc.example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"room1@muc.example.com\",\n  \"room2@muc.example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#rooms_unused_destroy","title":"rooms_unused_destroy","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/rooms_unused_destroy\n{\n  \"service\": \"muc.example.com\",\n  \"days\": 31\n}\n\nHTTP/1.1 200 OK\n[\n  \"room1@muc.example.com\",\n  \"room2@muc.example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#rooms_unused_list","title":"rooms_unused_list","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/rooms_unused_list\n{\n  \"service\": \"muc.example.com\",\n  \"days\": 31\n}\n\nHTTP/1.1 200 OK\n[\n  \"room1@muc.example.com\",\n  \"room2@muc.example.com\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#rotate_log","title":"rotate_log","text":"
    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
     
    Examples:
     
    POST /api/rotate_log\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#send_direct_invitation","title":"send_direct_invitation \ud83d\udfe4","text":"
     updated in 24.02
     
    Send a direct invitation to several destinations
     
    Since ejabberd 20.12, 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, v1
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/send_direct_invitation\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\",\n  \"password\": \"\",\n  \"reason\": \"Check this out!\",\n  \"users\": [\n    \"user2@localhost\",\n    \"user3@example.com\"\n  ]\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#send_message","title":"send_message","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/send_message\n{\n  \"type\": \"headline\",\n  \"from\": \"admin@localhost\",\n  \"to\": \"user1@localhost\",\n  \"subject\": \"Restart\",\n  \"body\": \"In 5 minutes\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#send_stanza","title":"send_stanza","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/send_stanza\n{\n  \"from\": \"admin@localhost\",\n  \"to\": \"user1@localhost\",\n  \"stanza\": \"<message><ext attr='value'/></message>\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#send_stanza_c2s","title":"send_stanza_c2s","text":"
    Send a stanza from an existing C2S session
     
    user@host/resource must be an existing C2S session. As an alternative, use 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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/send_stanza_c2s\n{\n  \"user\": \"admin\",\n  \"host\": \"myserver.com\",\n  \"resource\": \"bot\",\n  \"stanza\": \"<message to='user1@localhost'><ext attr='value'/></message>\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_last","title":"set_last","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/set_last\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"timestamp\": 1500045311,\n  \"status\": \"GoSleeping\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_loglevel","title":"set_loglevel","text":"
    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
     
    Examples:
     
    POST /api/set_loglevel\n{\n  \"loglevel\": \"debug\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_master","title":"set_master","text":"
    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
     
    Examples:
     
    POST /api/set_master\n{\n  \"nodename\": \"ejabberd@machine7\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_nickname","title":"set_nickname","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/set_nickname\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"nickname\": \"User 1\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_presence","title":"set_presence \ud83d\udfe4","text":"
     updated in 24.02
     
    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, v1
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/set_presence\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"resource\": \"tka1\",\n  \"type\": \"available\",\n  \"show\": \"away\",\n  \"status\": \"BB\",\n  \"priority\": 7\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_room_affiliation","title":"set_room_affiliation","text":"
    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
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/set_room_affiliation\n{\n  \"name\": \"room1\",\n  \"service\": \"muc.example.com\",\n  \"jid\": \"user2@example.com\",\n  \"affiliation\": \"member\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_vcard","title":"set_vcard","text":"
    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
     
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/set_vcard\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"name\": \"URL\",\n  \"content\": \"www.example.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_vcard2","title":"set_vcard2","text":"
    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
     
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/set_vcard2\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"name\": \"TEL\",\n  \"subname\": \"NUMBER\",\n  \"content\": \"123456\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#set_vcard2_multi","title":"set_vcard2_multi","text":"
    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
     
    Arguments:
     
       
    • user :: string
      •  
    • host :: string
      •  
    • name :: string
      •  
    • subname :: string
      •  
    • contents :: [value::string]
      •  
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: vcard
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/set_vcard2_multi\n{\n  \"user\": \"aaaaa\",\n  \"host\": \"bbbbb\",\n  \"name\": \"ccccc\",\n  \"subname\": \"ddddd\",\n  \"contents\": [\n    \"eeeee\",\n    \"fffff\"\n  ]\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#srg_create","title":"srg_create \ud83d\udfe4","text":"
     updated in 24.02
     
    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, v1
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/srg_create\n{\n  \"group\": \"group3\",\n  \"host\": \"myserver.com\",\n  \"label\": \"Group3\",\n  \"description\": \"Third group\",\n  \"display\": [\n    \"group1\",\n    \"group2\"\n  ]\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#srg_delete","title":"srg_delete","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/srg_delete\n{\n  \"group\": \"group3\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#srg_get_info","title":"srg_get_info","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/srg_get_info\n{\n  \"group\": \"group3\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"key\": \"name\",\n    \"value\": \"Group 3\"\n  },\n  {\n    \"key\": \"displayed_groups\",\n    \"value\": \"group1\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#srg_get_members","title":"srg_get_members","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/srg_get_members\n{\n  \"group\": \"group3\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"user1@localhost\",\n  \"user2@localhost\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#srg_list","title":"srg_list","text":"
    List the Shared Roster Groups in Host
     
    Arguments:
     
       
    • host :: string : Server name
      •  
     
    Result:
     
       
    • groups :: [id::string] : List of group identifiers
      •  
     
    Tags: shared_roster_group
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/srg_list\n{\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"group1\",\n  \"group2\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#srg_user_add","title":"srg_user_add","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/srg_user_add\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"group\": \"group3\",\n  \"grouphost\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#srg_user_del","title":"srg_user_del","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/srg_user_del\n{\n  \"user\": \"user1\",\n  \"host\": \"myserver.com\",\n  \"group\": \"group3\",\n  \"grouphost\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#stats","title":"stats","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/stats\n{\n  \"name\": \"registeredusers\"\n}\n\nHTTP/1.1 200 OK\n6\n
    "},{"location":"developer/ejabberd-api/admin-api/#stats_host","title":"stats_host","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/stats_host\n{\n  \"name\": \"registeredusers\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n6\n
    "},{"location":"developer/ejabberd-api/admin-api/#status","title":"status","text":"
    Get status of the ejabberd server
     
    Arguments:
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/status\n{\n\n}\n\nHTTP/1.1 200 OK\n\"The node ejabberd@localhost is started with status: startedejabberd X.X is running in that node\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#status_list","title":"status_list","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/status_list\n{\n  \"status\": \"dnd\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"user\": \"peter\",\n    \"host\": \"myserver.com\",\n    \"resource\": \"tka\",\n    \"priority\": 6,\n    \"status\": \"Busy\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#status_list_host","title":"status_list_host","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/status_list_host\n{\n  \"host\": \"myserver.com\",\n  \"status\": \"dnd\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"user\": \"peter\",\n    \"host\": \"myserver.com\",\n    \"resource\": \"tka\",\n    \"priority\": 6,\n    \"status\": \"Busy\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#status_num","title":"status_num","text":"
    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, statistics
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/status_num\n{\n  \"status\": \"dnd\"\n}\n\nHTTP/1.1 200 OK\n23\n
    "},{"location":"developer/ejabberd-api/admin-api/#status_num_host","title":"status_num_host","text":"
    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, statistics
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/status_num_host\n{\n  \"host\": \"myserver.com\",\n  \"status\": \"dnd\"\n}\n\nHTTP/1.1 200 OK\n23\n
    "},{"location":"developer/ejabberd-api/admin-api/#stop","title":"stop","text":"
    Stop ejabberd gracefully
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/stop\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#stop_kindly","title":"stop_kindly","text":"
    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
     
    Examples:
     
    POST /api/stop_kindly\n{\n  \"delay\": 60,\n  \"announcement\": \"Server will stop now.\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#stop_s2s_connections","title":"stop_s2s_connections","text":"
    Stop all s2s outgoing and incoming connections
     
    Arguments:
     
    Result:
     
       
    • res :: integer : Status code (0 on success, 1 otherwise)
      •  
     
    Tags: s2s
     
    Examples:
     
    POST /api/stop_s2s_connections\n{\n\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#subscribe_room","title":"subscribe_room \ud83d\udfe4","text":"
     updated in 24.02
     
    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, muc_sub, v1
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/subscribe_room\n{\n  \"user\": \"tom@localhost\",\n  \"nick\": \"Tom\",\n  \"room\": \"room1@conference.localhost\",\n  \"nodes\": [\n    \"urn:xmpp:mucsub:nodes:messages\",\n    \"urn:xmpp:mucsub:nodes:affiliations\"\n  ]\n}\n\nHTTP/1.1 200 OK\n[\n  \"urn:xmpp:mucsub:nodes:messages\",\n  \"urn:xmpp:mucsub:nodes:affiliations\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#subscribe_room_many","title":"subscribe_room_many \ud83d\udfe4","text":"
     updated in 24.02
     
    Subscribe several users to a MUC conference
     
    This command accepts up to 50 users at once (this is configurable with the 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, muc_sub, v1
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/subscribe_room_many\n{\n  \"users\": [\n    {\n      \"jid\": \"tom@localhost\",\n      \"nick\": \"Tom\"\n    },\n    {\n      \"jid\": \"jerry@localhost\",\n      \"nick\": \"Jerry\"\n    }\n  ],\n  \"room\": \"room1@conference.localhost\",\n  \"nodes\": [\n    \"urn:xmpp:mucsub:nodes:messages\",\n    \"urn:xmpp:mucsub:nodes:affiliations\"\n  ]\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#unban_ip","title":"unban_ip","text":"
    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
     
    Module: mod_fail2ban
     
    Examples:
     
    <<<<<<< HEAD\n    POST /api/unban_ip\n    {\n      \"address\": \"::FFFF:127.0.0.1/128\"\n    }\n\n    HTTP/1.1 200 OK\n    3\n=======\nPOST /api/unban_ip\n{\n  \"address\": \"::FFFF:127.0.0.1/128\"\n}\n\nHTTP/1.1 200 OK\n{\"unbanned\": 3}\n>>>>>>> a2c15f3 (Result of running \"make all\" with updated ejabberd)\n
    "},{"location":"developer/ejabberd-api/admin-api/#unregister","title":"unregister","text":"
    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
     
    Examples:
     
    POST /api/unregister\n{\n  \"user\": \"bob\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#unsubscribe_room","title":"unsubscribe_room","text":"
    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, muc_sub
     
    Module: mod_muc_admin
     
    Examples:
     
    POST /api/unsubscribe_room\n{\n  \"user\": \"tom@localhost\",\n  \"room\": \"room1@conference.localhost\"\n}\n\nHTTP/1.1 200 OK\n\"\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#update","title":"update","text":"
    Update the given module
     
    To update all the possible modules, use all.
     
    Arguments:
     
       
    • module :: string
      •  
     
    Result:
     
       
    • res :: string : Raw result string
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/update\n{\n  \"module\": \"mod_vcard\"\n}\n\nHTTP/1.1 200 OK\n\"Success\"\n
    "},{"location":"developer/ejabberd-api/admin-api/#update_list","title":"update_list","text":"
    List modified modules that can be updated
     
    Arguments:
     
    Result:
     
       
    • modules :: [module::string]
      •  
     
    Tags: server
     
    Examples:
     
    POST /api/update_list\n{\n\n}\n\nHTTP/1.1 200 OK\n[\n  \"mod_configure\",\n  \"mod_vcard\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#user_resources","title":"user_resources","text":"
    List user's connected resources
     
    Arguments:
     
       
    • user :: string : User name
      •  
    • host :: string : Server name
      •  
     
    Result:
     
       
    • resources :: [resource::string]
      •  
     
    Tags: session
     
    Examples:
     
    POST /api/user_resources\n{\n  \"user\": \"user1\",\n  \"host\": \"example.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  \"tka1\",\n  \"Gajim\",\n  \"mobile-app\"\n]\n
    "},{"location":"developer/ejabberd-api/admin-api/#user_sessions_info","title":"user_sessions_info","text":"
    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
     
    Module: mod_admin_extra
     
    Examples:
     
    POST /api/user_sessions_info\n{\n  \"user\": \"peter\",\n  \"host\": \"myserver.com\"\n}\n\nHTTP/1.1 200 OK\n[\n  {\n    \"connection\": \"c2s\",\n    \"ip\": \"127.0.0.1\",\n    \"port\": 42656,\n    \"priority\": 8,\n    \"node\": \"ejabberd@localhost\",\n    \"uptime\": 231,\n    \"status\": \"dnd\",\n    \"resource\": \"tka\",\n    \"statustext\": \"\"\n  }\n]\n
    "},{"location":"developer/ejabberd-api/admin-tags/","title":"API Tags","text":"
    This section enumerates the API tags of ejabberd 24.02.  If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the Archive. 
    "},{"location":"developer/ejabberd-api/admin-tags/#accounts","title":"accounts","text":"
       
    •  
      ban_account
       
      •  
    •  
      change_password
       
      •  
    •  
      check_account
       
      •  
    •  
      check_password
       
      •  
    •  
      check_password_hash
       
      •  
    •  
      delete_old_users
       
      •  
    •  
      delete_old_users_vhost
       
      •  
    •  
      register
       
      •  
    •  
      registered_users
       
      •  
    •  
      unban_ip
       
      •  
    •  
      unregister
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#acme","title":"acme","text":"
       
    •  
      list_certificates
       
      •  
    •  
      request_certificate
       
      •  
    •  
      revoke_certificate
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#cluster","title":"cluster","text":"
       
    •  
      join_cluster
       
      •  
    •  
      leave_cluster
       
      •  
    •  
      list_cluster
       
      •  
    •  
      set_master
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#config","title":"config","text":"
       
    •  
      convert_to_yaml
       
      •  
    •  
      dump_config
       
      •  
    •  
      reload_config
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#documentation","title":"documentation","text":"
       
    •  
      gen_html_doc_for_commands
       
      •  
    •  
      gen_markdown_doc_for_commands
       
      •  
    •  
      gen_markdown_doc_for_tags
       
      •  
    •  
      man
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#ejabberdctl","title":"ejabberdctl","text":"
       
    •  
      help
       
      •  
    •  
      mnesia_info_ctl
       
      •  
    •  
      print_sql_schema
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#erlang","title":"erlang","text":"
       
    •  
      compile
       
      •  
    •  
      get_cookie
       
      •  
    •  
      restart_module
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#last","title":"last","text":"
       
    •  
      get_last
       
      •  
    •  
      set_last
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#logs","title":"logs","text":"
       
    •  
      get_loglevel
       
      •  
    •  
      reopen_log
       
      •  
    •  
      rotate_log
       
      •  
    •  
      set_loglevel
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#mam","title":"mam","text":"
       
    •  
      remove_mam_for_user
       
      •  
    •  
      remove_mam_for_user_with_peer
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#mnesia","title":"mnesia","text":"
       
    •  
      backup
       
      •  
    •  
      delete_mnesia
       
      •  
    •  
      dump
       
      •  
    •  
      dump_table
       
      •  
    •  
      export2sql
       
      •  
    •  
      export_piefxis
       
      •  
    •  
      export_piefxis_host
       
      •  
    •  
      import_dir
       
      •  
    •  
      import_file
       
      •  
    •  
      import_piefxis
       
      •  
    •  
      import_prosody
       
      •  
    •  
      install_fallback
       
      •  
    •  
      load
       
      •  
    •  
      mnesia_change_nodename
       
      •  
    •  
      mnesia_info
       
      •  
    •  
      mnesia_info_ctl
       
      •  
    •  
      mnesia_table_info
       
      •  
    •  
      restore
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#modules","title":"modules","text":"
       
    •  
      module_check
       
      •  
    •  
      module_install
       
      •  
    •  
      module_uninstall
       
      •  
    •  
      module_upgrade
       
      •  
    •  
      modules_available
       
      •  
    •  
      modules_installed
       
      •  
    •  
      modules_update_specs
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#muc","title":"muc","text":"
       
    •  
      create_rooms_file
       
      •  
    •  
      destroy_rooms_file
       
      •  
    •  
      get_user_rooms
       
      •  
    •  
      get_user_subscriptions
       
      •  
    •  
      muc_online_rooms
       
      •  
    •  
      muc_online_rooms_by_regex
       
      •  
    •  
      muc_register_nick
       
      •  
    •  
      muc_unregister_nick
       
      •  
    •  
      rooms_empty_destroy
       
      •  
    •  
      rooms_empty_list
       
      •  
    •  
      rooms_unused_destroy
       
      •  
    •  
      rooms_unused_list
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#muc_room","title":"muc_room","text":"
       
    •  
      change_room_option
       
      •  
    •  
      create_room
       
      •  
    •  
      create_room_with_opts
       
      •  
    •  
      destroy_room
       
      •  
    •  
      get_room_affiliation
       
      •  
    •  
      get_room_affiliations
       
      •  
    •  
      get_room_history
       
      •  
    •  
      get_room_occupants
       
      •  
    •  
      get_room_occupants_number
       
      •  
    •  
      get_room_options
       
      •  
    •  
      get_subscribers
       
      •  
    •  
      send_direct_invitation
       
      •  
    •  
      set_room_affiliation
       
      •  
    •  
      subscribe_room
       
      •  
    •  
      subscribe_room_many
       
      •  
    •  
      unsubscribe_room
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#muc_sub","title":"muc_sub","text":"
       
    •  
      create_room_with_opts
       
      •  
    •  
      get_subscribers
       
      •  
    •  
      get_user_subscriptions
       
      •  
    •  
      subscribe_room
       
      •  
    •  
      subscribe_room_many
       
      •  
    •  
      unsubscribe_room
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#oauth","title":"oauth","text":"
       
    •  
      oauth_add_client_implicit
       
      •  
    •  
      oauth_add_client_password
       
      •  
    •  
      oauth_issue_token
       
      •  
    •  
      oauth_list_tokens
       
      •  
    •  
      oauth_remove_client
       
      •  
    •  
      oauth_revoke_token
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#offline","title":"offline","text":"
       
    • get_offline_count
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#private","title":"private","text":"
       
    •  
      bookmarks_to_pep
       
      •  
    •  
      private_get
       
      •  
    •  
      private_set
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#purge","title":"purge","text":"
       
    •  
      abort_delete_old_mam_messages
       
      •  
    •  
      abort_delete_old_messages
       
      •  
    •  
      delete_expired_messages
       
      •  
    •  
      delete_expired_pubsub_items
       
      •  
    •  
      delete_old_mam_messages
       
      •  
    •  
      delete_old_mam_messages_batch
       
      •  
    •  
      delete_old_mam_messages_status
       
      •  
    •  
      delete_old_messages
       
      •  
    •  
      delete_old_messages_batch
       
      •  
    •  
      delete_old_messages_status
       
      •  
    •  
      delete_old_pubsub_items
       
      •  
    •  
      delete_old_push_sessions
       
      •  
    •  
      delete_old_users
       
      •  
    •  
      delete_old_users_vhost
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#roster","title":"roster","text":"
       
    •  
      add_rosteritem
       
      •  
    •  
      delete_rosteritem
       
      •  
    •  
      get_roster
       
      •  
    •  
      process_rosteritems
       
      •  
    •  
      push_alltoall
       
      •  
    •  
      push_roster
       
      •  
    •  
      push_roster_all
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#s2s","title":"s2s","text":"
       
    •  
      incoming_s2s_number
       
      •  
    •  
      outgoing_s2s_number
       
      •  
    •  
      stop_s2s_connections
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#server","title":"server","text":"
       
    •  
      clear_cache
       
      •  
    •  
      gc
       
      •  
    •  
      halt
       
      •  
    •  
      registered_vhosts
       
      •  
    •  
      restart
       
      •  
    •  
      status
       
      •  
    •  
      stop
       
      •  
    •  
      stop_kindly
       
      •  
    •  
      update
       
      •  
    •  
      update_list
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#session","title":"session","text":"
       
    •  
      connected_users
       
      •  
    •  
      connected_users_info
       
      •  
    •  
      connected_users_number
       
      •  
    •  
      connected_users_vhost
       
      •  
    •  
      get_presence
       
      •  
    •  
      kick_session
       
      •  
    •  
      kick_user
       
      •  
    •  
      num_resources
       
      •  
    •  
      resource_num
       
      •  
    •  
      set_presence
       
      •  
    •  
      status_list
       
      •  
    •  
      status_list_host
       
      •  
    •  
      status_num
       
      •  
    •  
      status_num_host
       
      •  
    •  
      user_resources
       
      •  
    •  
      user_sessions_info
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#shared_roster_group","title":"shared_roster_group","text":"
       
    •  
      srg_create
       
      •  
    •  
      srg_delete
       
      •  
    •  
      srg_get_info
       
      •  
    •  
      srg_get_members
       
      •  
    •  
      srg_list
       
      •  
    •  
      srg_user_add
       
      •  
    •  
      srg_user_del
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#sql","title":"sql","text":"
       
    •  
      convert_to_scram
       
      •  
    •  
      import_prosody
       
      •  
    •  
      print_sql_schema
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#stanza","title":"stanza","text":"
       
    •  
      privacy_set
       
      •  
    •  
      send_message
       
      •  
    •  
      send_stanza
       
      •  
    •  
      send_stanza_c2s
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#statistics","title":"statistics","text":"
       
    •  
      connected_users_number
       
      •  
    •  
      incoming_s2s_number
       
      •  
    •  
      outgoing_s2s_number
       
      •  
    •  
      stats
       
      •  
    •  
      stats_host
       
      •  
    •  
      status_num
       
      •  
    •  
      status_num_host
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#v1","title":"v1","text":"
       
    •  
      add_rosteritem
       
      •  
    •  
      oauth_issue_token
       
      •  
    •  
      send_direct_invitation
       
      •  
    •  
      set_presence
       
      •  
    •  
      srg_create
       
      •  
    •  
      subscribe_room
       
      •  
    •  
      subscribe_room_many
       
      •  
    "},{"location":"developer/ejabberd-api/admin-tags/#vcard","title":"vcard","text":"
       
    •  
      get_vcard
       
      •  
    •  
      get_vcard2
       
      •  
    •  
      get_vcard2_multi
       
      •  
    •  
      set_nickname
       
      •  
    •  
      set_vcard
       
      •  
    •  
      set_vcard2
       
      •  
    •  
      set_vcard2_multi
       
      •  
    "},{"location":"developer/ejabberd-api/api_versioning/","title":"API Versioning","text":"
     added in 24.02
    "},{"location":"developer/ejabberd-api/api_versioning/#introduction","title":"Introduction","text":"
    It is possible to support different versions of the ejabberd API. Versioning is used to ensure compatibility with third party backend that uses the API.
     
    When a command is modified (either its declaration or its definition, breaking compatibility), those modifications can be done in a new version of the API, keeping the old command still available in the previous API version. An API version is an integer (sub-versions are not supported).
     
    If the API client does not specify the API version, ejabberd uses by default the most recent available API version.
     
    Alternatively, the API client can specify an API version, and ejabberd will use that one to process the query, or the most recent to the one specified. For example: if a command is defined in API versions 0, 2, 3, 7, and 9, and a client declares to support up to API version 5, then ejabberd uses the command API version 3, which is the most recent available for the one supported by the client.
     
    API versioning is supported by mod_http_api ReST interface and ejabberdctl command line script. However ejabberd_xmlrpc doesn't support API versioning, and consequently it can only use the latest API version.
    "},{"location":"developer/ejabberd-api/api_versioning/#command-definition","title":"Command Definition","text":"
    If a command is modified, a new #ejabberd_commands record should be defined with a version attribute set to the API version (an integer) where this command version is available. There is no need to add a new #ejabberd_commands record for commands that are not modified in a given API version, immediate inferior version is used.
     
    By default, all commands are in API version 0, and latest API is used if no version is specified when calling ejabberd_commands directly without specifying a version.
    "},{"location":"developer/ejabberd-api/api_versioning/#api-documentation","title":"API Documentation","text":"
    The command documentation indicates the api version as a tag: v1, v2... Commands not versioned do not have such a tag: they are version 0.
     
    The ejabberd Docs: API Tags page lists the most recent API versions, and what commands are included.
     
    To know exactly what is the format expected for a command in a specific API version, use ejabberdctl specifying what API version you want to consult and the command name, for example:
     
    ejabberdctl --version 0 help get_roster\n
    "},{"location":"developer/ejabberd-api/api_versioning/#mod_http_api","title":"mod_http_api","text":"
    The server administrator can set the default version when configuring request_handlers, by including a vN in its path, where N is an integer corresponding to the version.
     
    In any case, the API client can specify a version when sending the request, by appending vN to the request path.
     
    For example, when configured like:
     
    listen:\n  -\n    request_handlers:\n      /api/v0: mod_http_api\n      /v1/api: mod_http_api\n      /api: mod_http_api\n
     
    See what API version will be used depending on the URL:
     
       
    • api/command use the latest available version
      •  
    • api/command/v0 use version 0
      •  
    • api/command/v1 use version 1
      •  
    • v1/api/command use version 1
      •  
    • v1/api/command/v0 use version 0
      •  
    • api/v0/command use version 0
      •  
    • api/v0/command/v1 use version 1
      •  
     
    In this example, the server administrator configured the default API version to 0:
     
    listen:\n  -\n    request_handlers:\n      /api/v0: mod_http_api\n
     
    The client doesn't specify any version, so 0 is used:
     
    $ curl -k -X POST -H \"Content-type: application/json\" \\\n  -d '{}' \"http://localhost:5280/api/v0/get_loglevel\"\n{\"levelatom\":\"info\"}\n
     
    This time the client requests the API version 2:
     
    $ curl -k -X POST -H \"Content-type: application/json\" \\\n  -d '{}' \"http://localhost:5280/api/v0/get_loglevel/v2\"\n\"info\"\n
    "},{"location":"developer/ejabberd-api/api_versioning/#ejabberdctl","title":"ejabberdctl","text":"
    By default the latest version of a given command is used. To use a command in a specific API version, use the --version switch, followed by the version number, and then the command name.
     
    Example:
     
    ejabberdctl --version 2 set_loglevel 4\n
     
    Use the most recent API version:
     
    $ ejabberdctl get_roster admin localhost\njan@localhost jan   none    subscribe       group1,group2\ntom@localhost tom   none    subscribe       group3\n
     
    Use version 0:
     
    $ ejabberdctl --version 0 get_roster admin localhost\njan@localhost jan   none    subscribe       group1;group2\ntom@localhost tom   none    subscribe       group3\n
    "},{"location":"developer/ejabberd-api/commands/","title":"ejabberd commands","text":"
    By defining command using api available through ejabberd_commands module, it's possible to add operations that would be available to users through ejabberdctl command, XML-RPC socket or JSON based REST service.
     
    Each command needs to provide information about required arguments and produced result by filling #ejabberd_commands record and registering it in dispatcher by calling ejabberd_commands:register_commands([ListOfEjabberdCommandsRecords]).
    "},{"location":"developer/ejabberd-api/commands/#structure-of-ejabberd_commands-record","title":"Structure of #ejabberd_commands record","text":""},{"location":"developer/ejabberd-api/commands/#writing-ejabberd-commands-supporting-oauth","title":"Writing ejabberd commands supporting OAuth","text":"
    If you have existing commands that you want to make OAuth compliant, you can make them OAuth compliant very easily.
     
    An ejabberd command is defined by an #ejabberd_commands Erlang record. The record requires a few fields:
     
       
    • name: This is an atom defining the name of the command.
      •  
    • tags: This is a list of atoms used to group the command into consistent group of commands. This is mostly used to group commands in ejabberdctl command-line tool. Existing categories are:
      •  
    • session: For commands related to user XMPP sessions.
      •  
    •  
      roster: Commands related to contact list management.   
       
      •  
    •  
      desc: Description of the command for online help.
       
      •  
    • module and function: Module and function to call to execute the command logic.
      •  
    • args: Argument of the command. An argument is defined by a tuple of atoms of the form {argument_name, data_type}. data_type can be one of:
      •  
    •  
      binary   
       
      •  
    •  
      result: defines what the command will return.
       
      •  
    • policy: Is an optional field, containing an atom that define restriction policy of the command. It can be on of: open, admin, user, restricted. Default is restricted, meaning the command can be used from ejabberdctl command-line tool.
      •  
    • version: API version number where this command is available (see API versioning documentation for details).
      •  
     
    To define a command that can be used by server user over ReST or XML-RPC API, you just have to define it with policy user. Then, you have to make sure that the function will take a user binary and a host binary as first parameter of the function. They do not have to be put in the args list in #ejabberd_commands record as the `user policy implicitly expect them.
     
    That's all you need to have commands that can be used in a variety of ways.
     
    Here is a example way to register commands when
     
    start(_Host, _Opts) ->\n    ejabberd_commands:register_commands(commands()).\n\nstop(_Host) ->\n    ejabberd_commands:unregister_commands(commands()).\n\n%%%\n%%% Register commands\n%%%\n\ncommands() ->\n    [#ejabberd_commands{name = user_get_roster,\n                        tags = [roster],\n                        desc = \"Retrieve the roster\",\n                        longdesc =\n                            \"Returns a list of the contacts in a \"\n                            \"user roster.\\n\\nAlso returns the state \"\n                            \"of the contact subscription. Subscription \"\n                            \"can be either  \\\"none\\\", \\\"from\\\", \\\"to\\\", \"\n                            \"\\\"both\\\". Pending can be \\\"in\\\", \\\"out\\\" \"\n                            \"or \\\"none\\\".\",\n                        module = ?MODULE, function = get_roster,\n                        args = [],\n                        policy = user,\n                        result =\n                            {contacts,\n                             {list,\n                              {contact,\n                               {tuple,\n                                [{jid, string},\n                                 {groups, {list, {group, string}}},\n                                 {nick, string}, {subscription, string},\n                                 {pending, string}]}}}}}\n        ].\n
    "},{"location":"developer/ejabberd-api/oauth/","title":"OAuth Support","text":"
     added in 15.09
    "},{"location":"developer/ejabberd-api/oauth/#introduction","title":"Introduction","text":"
    ejabberd includes a full support OAuth 2.0 deep inside the ejabberd stack.
     
    This OAuth integration makes ejabberd:
     
       
    •  
      an ideal project to develop XMPP applications with Web in mind, as it exposes ejabberd features as ReST or XML-RPC HTTP based API endpoints. OAuth makes ejabberd the ideal XMPP server to integrate in a  larger Web / HTTP ecosystem.
       
      •  
    •  
      a more secure tool that can leverage the use of oAuth token to authenticate, hiding your real password from the client itself. As your password is never shared with client directly with our X-OAUTH2 authentication mechanism, user have less risks of having their primary password leaked.
       
      •  
    •  
      a tool that can be used at the core of larger platforms as oauth token can be used by users and admins to delegate rights to subcomponents / subservices.
       
      •  
    •  
      a tool that is friendly to other online services as users can delegate rights to others SaaS platform they are using. This will be possible to let services access your message archive, show your offline message count or with future commands send message to users and chatrooms on your behalf. This is done in a granular way, with a scope limited to a specific function. And the delegation rights for a specific app / third party can always be revoked at any time as this is usually the case with OAuth services.
       
      •  
     
    You can read more on OAuth from OAuth website.
    "},{"location":"developer/ejabberd-api/oauth/#configuration","title":"Configuration","text":""},{"location":"developer/ejabberd-api/oauth/#authentication-method","title":"Authentication method","text":"
    An X-OAUTH2 SASL authentication mechanism is enabled by default in ejabberd.
     
    However, if the ejabberd_oauth HTTP request handler is not enabled, there is no way to generate token from outside ejabberd. In this case, you may want to disable X-OAUTH2 with the disable_sasl_mechanisms top-level option in ejabberd.yml file, either at global or at virtual host level:
     
    disable_sasl_mechanisms: [\"X-OAUTH2\"]\n
    "},{"location":"developer/ejabberd-api/oauth/#ejabberd-listeners","title":"ejabberd listeners","text":"
    To enable OAuth support in ejabberd, you need to edit your ejabberd.yml file to add the following snippets.
     
    You first need to expose more HTTP endpoint in ejabberd_http modules:
     
       
    • ejabberd_oauth is the request handler that will allow generating token for third-parties (clients, services). It is usually exposed on \"/oauth\" endpoint. This handler is mandatory to support OAuth.
      •  
    • mod_http_api request handler enables ReST API endpoint to perform delegated actions on ejabberd using an HTTP JSON API. This handler is usually exposed on \"/api\" endpoint. It is optional.
      •  
    • ejabberd_xmlrpc listener can be set on a separate port to query commands using the XML-RPC protocol.
      •  
     
    Here is a example of the listen section in ejabberd configuration file, focusing on HTTP handlers:
     
    listen:\n  -\n    port: 4560\n    module: ejabberd_http\n    request_handlers:\n      ## Handle ejabberd commands using XML-RPC\n      /: ejabberd_xmlrpc\n  -\n    port: 5280\n    module: ejabberd_http\n    request_handlers:\n      /websocket: ejabberd_http_ws\n      /log: mod_log_http\n      # OAuth support:\n      /oauth: ejabberd_oauth\n      # ReST API:\n      /api: mod_http_api\n
    "},{"location":"developer/ejabberd-api/oauth/#module-configuration","title":"Module configuration","text":"
    Some commands are implemented by ejabberd internals and are always available, but other commands are implemented by optional modules. If the documentation of a command you want to use mentions a module, make sure you have enabled that module in ejabberd.yml. For example the add_rosteritem command is implemented in the mod_admin_extra module.
     
    By the way, ejabberd implements several commands to manage OAuth, check the oauth tag documentation.
    "},{"location":"developer/ejabberd-api/oauth/#oauth-specific-parameters","title":"OAuth specific parameters","text":"
    OAuth is configured using those top-level options:
     
       
    • oauth_access
      •  
    • oauth_cache_life_time
      •  
    • oauth_cache_missed
      •  
    • oauth_cache_rest_failure_life_time
      •  
    • oauth_cache_size
      •  
    • oauth_client_id_check
      •  
    • oauth_db_type
      •  
    • oauth_expire
      •  
    • oauth_use_cache
      •  
     
    A basic setup is to allow all accounts to create tokens, and tokens expire after an hour:
     
    oauth_access: all\noauth_expire: 3600\n
    "},{"location":"developer/ejabberd-api/oauth/#authorization_token","title":"authorization_token","text":"
    An easy way to generate a token is using the oauth_issue_token command with the ejabberdctl shell script:
     
    ejabberdctl oauth_issue_token user1@localhost 3600 ejabberd:admin\n\nr9KFladBTYJS71OggKCifo0GJwyT7oY4 [<<\"ejabberd:admin\">>]  3600 seconds\n
     
    The users can generate tokens themselves by visiting /oauth/authorization_token in a webview in your application or in a web browser. For example, URL can be:
     
    `http://example.net:5280/oauth/authorization_token?response_type=token&client_id=Client1&redirect_uri=http://client.uri&scope=get_roster+sasl_auth`\n
     
    Note: To use the get_roster scope, enable mod_admin_extra, because the get_roster  API is defined in that module. Otherwise, the command is unknown and you will get an invalid_scope error. See Module configuration for details.
     
    Parameters are described in OAuth 2.0 specification:
     
       
    • response_type: Should be token.
      •  
    • client_id: This is the name of the application that is asking for Oauth token.
      •  
    • scope: This is the scope of the rights being delegated to the application. It will limit the feature the application can perform and thus ensure the user is not giving away more right than expected by the application. As a developer, you should always limit the scope to what you actually need.
      •  
    • redirect_uri: After token is generated, token is passed to the application using the redirect URI. It can obviously work for web applications, but also for mobile applications, using a redirect URI that the mobile application have registered: Proper code for handling the token will thus be executed directly in the mobile application.
      •  
    • state: State parameter is optional and use by client to pass information that will be passed as well as state parameter in the redirect URI.
      •  
     
    Directing the user to this URL will present an authentication form summarizing what is the app requiring the token and the scope / rights that are going to be granted.
     
    The user can then put their login and password to confirm that they accept granting delegating rights and confirm the token generation. If the provided credentials are valid, the browser or webview will redirect the user to the redirect_uri, to actually let ejabberd pass the token to the app that requested it. It can be either a Web app or `a mobile / desktop application.
    "},{"location":"developer/ejabberd-api/oauth/#redirect_uri","title":"redirect_uri","text":"
    The redirect_uri originally passed in the authorization_token request will be called on successful validation of user credentials, with added parameters.
     
    For example, redirect URI called by ejabberd can be:
     
    http://client.uri/?access_token=RHIT8DoudzOctdzBhYL9bYvXz28xQ4Oj&token_type=bearer&expires_in=3600&scope=user_get_roster+sasl_auth&state=
     
    Parameters are described in OAuth specification:
     
       
    • access_token: This is the actual token that the client application can use for OAuth authentication.
      •  
    • token_type: ejabberd supports bearer token type.
      •  
    • expires_in: This is the validity duration of the token, in seconds. When the token expires, a new authorization token will need to be generated an approved by the user.
      •  
     
       
    • scope: Confirms the granted scope to the requesting application. Several scopes can be passed, separated by '+'.
      •  
    • state: If a state parameter was passed by requesting application in authorization_token URL, it will be passed back to the   application as a parameter of the redirect_uri to help with the client workflow.
      •  
    "},{"location":"developer/ejabberd-api/oauth/#scopes","title":"Scopes","text":"
       
    • sasl_auth: This scope is use to generate a token that can login over XMPP using SASL X-OAUTH2 mechanism.
      •  
    • ejabberd:admin
      •  
    • ejabberd:user
      •  
    • Scopes for each existing API command.   For example, there is a scope registered_users  because there is a command called registered_users.   Ensure you enable the module that defines the command that you want to use, see Module configuration for details.
      •  
    "},{"location":"developer/ejabberd-api/oauth/#x-oauth2-authentication","title":"X-OAuth2 Authentication","text":"
    You can connect to ejabberd using an X-OAUTH2 token that is valid in the scope sasl_auth. You can use an OAuth token as generated in the previous steps instead of a password when connecting to ejabberd servers support OAuth SASL mechanism.
     
    When enabled, X-OAUTH2 SASL mechanism is advertised in server stream features:
     
    <stream:features>\n  <c xmlns=\"http://jabber.org/protocol/caps\" node=\"http://www.process-one.net/en/ejabberd/\" ver=\"nM19M+JK0ZBMXK7iJAvKnmDuQus=\" hash=\"sha-1\"/>\n  <register xmlns=\"http://jabber.org/features/iq-register\"/>\n  <mechanisms xmlns=\"urn:ietf:params:xml:ns:xmpp-sasl\">\n    <mechanism>PLAIN</mechanism>\n    <mechanism>DIGEST-MD5</mechanism>\n    <mechanism>X-OAUTH2</mechanism>\n    <mechanism>SCRAM-SHA-1</mechanism>\n  </mechanisms>\n</stream:features>\n
     
    Authentication with X-OAUTH2 is done by modifying the SASL auth element as follow:
     
    <auth mechanism='X-OAUTH2'\n      xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>\n  base64(\"\\0\" + user_name + \"\\0\" + oauth_token)\n</auth>\n
     
    The content in the auth element should be the base64 encoding of a string containing a null byte, followed by the user name, another null byte and the string representation of the user\u2019s OAuth token. This is similar to how to authenticate with a password using the PLAIN mechanism, except the token is added instead of the user\u2019s password.
     
    The response is standard for SASL XMPP authentication. For example, on success, server will reply with:
     
    <success xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/>\n
    "},{"location":"developer/ejabberd-api/oauth/#rest-example","title":"ReST Example","text":"
    It is possible to use OAuth to authenticate a client when attempting to perform a ReST or XML-RPC query.
    "},{"location":"developer/ejabberd-api/oauth/#configuring","title":"Configuring","text":"
    First of all check all the required options are setup (listener, OAuth, API and ACL):
     
    listen:\n  -\n    port: 5280\n    ip: \"::\"\n    module: ejabberd_http\n    request_handlers:\n      /api: mod_http_api\n      /oauth: ejabberd_oauth\n\noauth_expire: 3600\noauth_access: all\n\napi_permissions:\n  \"admin access\":\n    who:\n      oauth:\n        scope: \"ejabberd:admin\"\n        access:\n          allow:\n            - acl: loopback\n            - acl: admin\n    what:\n      - \"*\"\n      - \"!stop\"\n      - \"!start\"\n\nacl:\n  admin:\n    user:\n      - user1@localhost\n\nmodules:\n  mod_admin_extra: {}\n  mod_roster: {}\n
     
    Register the account with admin rights, and another one used for the queries:
     
    ejabberdctl register user1 localhost asd\nejabberdctl register user2 localhost asd\nejabberdctl add_rosteritem user2 localhost tom localhost Tom \"\" none\n
    "},{"location":"developer/ejabberd-api/oauth/#obtain-bearer-token","title":"Obtain bearer token","text":"
    Obtain a bearer token as explained in authorization_token, either using ejabberdctl:
     
    ejabberdctl oauth_issue_token user1@localhost 3600 ejabberd:admin\nr9KFladBTYJS71OggKCifo0GJwyT7oY4        [<<\"ejabberd:admin\">>]  3600 seconds\n
     
    Or using a web browser:
     
       
    • visit the URL http://localhost:5280/oauth/authorization_token?response_type=token&scope=ejabberd:admin
      •  
    • User (jid): user1@localhost
      •  
    • Password: asd
      •  
    • and click Accept
      •  
     
    This redirects to a new URL which contains the access_token, for example:
     
    http://localhost:5280/oauth/authorization_token?access_token=r9KFladBTYJS71OggKCifo0GJwyT7oY4&token_type=bearer&expires_in=31536000&scope=ejabberd:admin&state=
    "},{"location":"developer/ejabberd-api/oauth/#passing-credentials","title":"Passing credentials","text":"
    When using ReST, the client authorization is done by using a bearer token (no need to pass the user and host parameters). For that, include an Authorization HTTP header like:
     
    Authorization: Bearer r9KFladBTYJS71OggKCifo0GJwyT7oY4\n
    "},{"location":"developer/ejabberd-api/oauth/#query-examples","title":"Query examples","text":"
    Let's use curl to get the list of registered_users with a HTTP GET query:
     
    curl -X GET \\\n     -H \"Authorization: Bearer r9KFladBTYJS71OggKCifo0GJwyT7oY4\" \\\n     http://localhost:5280/api/registered_users?host=localhost\n\n[\"user1\",\"user2\"]\n
     
    Or provide the bearer token with this option:
     
    curl -X GET \\\n     --oauth2-bearer r9KFladBTYJS71OggKCifo0GJwyT7oY4 \\\n     http://localhost:5280/api/registered_users?host=localhost\n
     
    With a command like get_roster you can get your own roster, or act as an admin to get any user roster.
     
    The HTTP endpoint does not take any parameter, so we can just do an HTTP POST with empty JSON structure list (see -d option).
     
    In this example let's use a HTTP POST query:
     
    curl -v -X POST \\\n     --oauth2-bearer r9KFladBTYJS71OggKCifo0GJwyT7oY4 \\\n     http://localhost:5280/api/get_roster \\\n     -d '{\"user\": \"user2\", \"server\": \"localhost\"}'\n\n[{\"jid\":\"tom@localhost\",\"nick\":\"Tom\",\"subscription\":\"none\",\"ask\":\"none\",\"group\":\"\"}]\n
    "},{"location":"developer/ejabberd-api/oauth/#xml-rpc-example","title":"XML-RPC Example","text":"
    For XML-RPC, credentials must be passed as XML-RPC parameters, including token but also user and host parameters. This is for legacy reason, but will likely change in a future version, making user and host implicit, thanks to bearer token.
     
    Here is an (Erlang) XML-RPC example on how to get your own roster:
     
    xmlrpc:call({127, 0, 0, 1}, 4560, \"/\",\n  {call, get_roster, [\n    {struct, [{user, \"peter\"},\n              {server, \"example.com\"},\n              {token, \"0n6LaEjyAOxVDyZChzZfoKMYxc8uUk6L\"}]}]},\n  false, 60000, \"Host: localhost\\r\\n\", []).\n
     
    This will lead to sending this XML-RPC payload to server:
     
    <?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<methodCall>\n  <methodName>get_roster</methodName>\n  <params>\n    <param>\n      <value>\n        <struct>\n          <member>\n            <name>server</name>\n            <value>\n              <string>example.com</string>\n            </value>\n          </member>\n          <member>\n            <name>user</name>\n            <value>\n              <string>peter</string>\n            </value>\n          </member>\n          <member>\n            <name>token</name>\n            <value>\n              <string>0n6LaEjyAOxVDyZChzZfoKMYxc8uUk6L</string>\n            </value>\n          </member>\n        </struct>\n      </value>\n    </param>\n  </params>\n</methodCall>\n
     
    To get roster of other user using admin authorization, this erlang XML-RPC code can be used:
     
    xmlrpc:call({127, 0, 0, 1}, 4560, \"/\",\n  {call, get_roster, [\n    {struct, [{user, \"admin\"},\n              {server, \"example.com\"},\n              {token, \"0n6LaEjyAOxVDyZChzZfoKMYxc8uUk6L\"}\n              {admin, true}]},\n    {struct, [{user, \"peter\"},\n              {server, \"example.com\"}]}]},\n  false, 60000, \"Host: localhost\\r\\n\", []).\n
     
    This is an equivalent Python 2 script:
     
    import xmlrpclib\n\nserver_url = 'http://127.0.0.1:4560'\nserver = xmlrpclib.ServerProxy(server_url)\n\nLOGIN = {'user': 'admin',\n         'server': 'example.com',\n         'token': '0n6LaEjyAOxVDyZChzZfoKMYxc8uUk6L',\n         'admin': True}\n\ndef calling(command, data):\n    fn = getattr(server, command)\n    return fn(LOGIN, data)\n\nprint calling('get_roster', {'user':'peter', 'server':'example.com'})\n
     
    And this is an equivalent Python 3 script:
     
    from xmlrpc import client\n\nserver_url = 'http://127.0.0.1:4560'\nserver = client.ServerProxy(server_url)\n\nLOGIN = {'user': 'admin',\n         'server': 'example.com',\n         'token': '0n6LaEjyAOxVDyZChzZfoKMYxc8uUk6L',\n         'admin': True}\n\ndef calling(command, data):\n    fn = getattr(server, command)\n    return fn(LOGIN, data)\n\nresult = calling('get_roster', {'user':'peter', 'server':'example.com'})\nprint(result)\n
     
    Those calls would send this XML to server:
     
    <?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<methodCall>\n  <methodName>get_roster</methodName>\n  <params>\n    <param>\n      <value>\n        <struct>\n          <member>\n            <name>admin</name>\n            <value>\n              <boolean>1</boolean>\n            </value>\n          </member>\n          <member>\n            <name>server</name>\n            <value>\n              <string>example.com</string>\n            </value>\n          </member>\n          <member>\n            <name>user</name>\n            <value>\n              <string>admin</string>\n            </value>\n          </member>\n          <member>\n            <name>token</name>\n            <value>\n              <string>0n6LaEjyAOxVDyZChzZfoKMYxc8uUk6L</string>\n            </value>\n          </member>\n        </struct>\n      </value>\n    </param>\n    <param>\n      <value>\n        <struct>\n          <member>\n            <name>user</name>\n            <value>\n              <string>peter</string>\n            </value>\n          </member>\n          <member>\n            <name>server</name>\n            <value>\n              <string>example.com</string>\n            </value>\n          </member>\n        </struct>\n      </value>\n    </param>\n  </params>\n</methodCall>\n
    "},{"location":"developer/ejabberd-api/permissions/","title":"API Permissions","text":"
     added in 16.12
     
    This page describes ejabberd's flexible permission mechanism.
     
    Access to all available endpoints are configured using api_permissions option.
     
    It allows to define multiple groups, each one with separate list of filters on who and what are allowed by rules specified inside it.
     
    Basic rule looks like this:
     
    api_permissions:\n  \"admin access\":\n    who:\n      - admin\n    what:\n      - \"*\"\n      - \"!stop\"\n    from:\n      - ejabberd_ctl\n      - mod_http_api\n
     
    It tells that group named Admin access allows all users that are accepted by ACL rule admin to execute all commands except command stop, using the command-line tool ejabberdctl or sending a ReST query handled by mod_http_api.
     
    Each group has associated name (that is just used in log messages), who section for rules that authentication details must match, what section for specifying list of command, and from with list of modules that API was delivered to.
    "},{"location":"developer/ejabberd-api/permissions/#rules-inside-who-section","title":"Rules inside who section","text":"
    There are 3 types of rules that can be placed in who section:
     
       
    •  
      acl: Name | ACLDefinition   or the short version: Name | ACLRule   This accepts a command when the authentication provided matches   rules of Name Access Control List   (or inline rules from ACLDefinition or ACLRule)
       
      •  
    •  
      access: Name | AccessDefinition   This allows execution if   the Access Rule Name or inline AccessDefinition   returns allowed for command's authentication details
       
      •  
    •  
      oauth: ListOfRules   This rule (and only this) will match for commands that were executed   with OAuth authentication.   Inside ListOfRules you can use any rule   described above (acl: Name, AClName, access: Name) and   additionally you must include scope: ListOfScopeNames with OAuth   scope names that must match scope used to generate OAuth token used   in command authentication.
       
      •  
     
    who allows the command to be executed if at least one rule matches.
     
    If you want to require several rules to match at this same time, use access (see examples below).
     
    Missing who rule is equivalent to who: none which will stop group from accepting any command.
    "},{"location":"developer/ejabberd-api/permissions/#examples-of-who-rules","title":"Examples of who rules","text":"
    This accepts user admin@server.com or commands originating from localhost:
     
    who:\n  user: admin@server.com\n  ip: 127.0.0.1/8\n
     
    This only allows execution of a command if it's invoked by user admin@server.com and comes from localhost address. If one of those restrictions isn't satisfied, execution will fail:
     
    who:\n  access:\n    allow:\n      user: admin@server.com\n      ip: 127.0.0.1/8\n
     
    Those rules match for users from muc_admin ACL both using regular authentication and OAuth:
     
    who:\n  access:\n    allow:\n      acl: muc_admin\n  oauth:\n    scope: \"ejabberd:admin\"\n    access:\n      allow:\n        acl: muc_admin\n
    "},{"location":"developer/ejabberd-api/permissions/#rules-in-what-section","title":"Rules in what section","text":"
    Rules in what section are constructed from \"strings\" literals. You can use:
     
       
    • \"command_name\" of an existing API command
      •  
    • command_name is same as before, but no need to provide \"
      •  
    • \"*\" is a wildcard rule to match all commands
      •  
    • \"[tag: tagname ]\" allows all commands that have been declared with tag tagname.   You can consult the list of tags and their commands with: ejabberdctl help tags
      •  
     
    Additionally each rule can be prepended with ! character to change it into negative assertion rule. Command names that would match what is after ! character will be removed from list of allowed commands.
     
    Missing what rule is equivalent to what: \"!*\" which will stop group from accepting any command.
    "},{"location":"developer/ejabberd-api/permissions/#example-of-what-rules","title":"Example of what rules","text":"
    This allows execution of all commands except command stop:
     
    what:\n  - \"*\"\n  - \"!stop\"\n
     
    This allows execution of status and commands with tag session (like num_resources or status_list):
     
    what:\n  - status\n  - \"[tag:account]\"\n
     
    This matches no command:
     
    what:\n  - start\n  - \"!*\"\n
    "},{"location":"developer/ejabberd-api/permissions/#rules-in-from-section","title":"Rules in from section","text":"
    This section allows to specify list of allowed module names that expose API to outside world. Currently those modules are ejabberd_xmlrpc, mod_http_api and ejabberd_ctl.
     
    If from section is missing from group then all endpoints are accepted, if it's specified endpoint must be listed inside it to be allowed to execute.
    "},{"location":"developer/ejabberd-api/permissions/#examples","title":"Examples","text":"
    Those rules allow execution of any command invoked by ejabberdctl shell command, or all command except start and stop for users in ACL admin, with regular authentication or ejabberd:admin scoped OAuth tokens.
     
    api_permissions:\n  \"console commands\":\n    from:\n      - ejabberd_ctl\n    who: all\n    what: \"*\"\n  \"admin access\":\n    who:\n      access:\n        allow:\n          - acl: admin\n      oauth:\n        scope: \"ejabberd:admin\"\n        access:\n          allow:\n            - acl: admin\n    what:\n      - \"*\"\n      - \"!stop\"\n      - \"!start\"\n
    "},{"location":"developer/ejabberd-api/simple-configuration/","title":"Simple ejabberd Rest API Configuration","text":""},{"location":"developer/ejabberd-api/simple-configuration/#restrict-to-local-network","title":"Restrict to Local network","text":"
    If you are planning to use ejabberd API for admin purpose, it is often enough to configure it to be available local commands. Access is thus generally limited by IP addresses, either restricted to localhost only, or restricted to one of your platform back-end.
     
       
    1.  
      Make sure an ejabberd_http listener is using mod_http_api on a given root URL and on a desired port:
       
      listen:\n  -\n    port: 5281\n    module: ejabberd_http\n    ip: 127.0.0.1\n    request_handlers:\n      /api: mod_http_api\n
       
      The ip option ensures it listens only on the local interface (127.0.0.1) instead of listening on all interface (0.0.0.0).
       
      2.  
    2.  
      By defining api_permissions, you can then allow HTTP request from a specific IP to trigger API commands execution without user credentials:
       
      api_permissions:\n  \"API used from localhost allows all calls\":\n    who:\n      ip: 127.0.0.1/8\n    what:\n      - \"*\"\n      - \"!stop\"\n      - \"!start\"\n
       
      Note: stop and start commands are disabled in that example as they are usually restricted to ejabberdctl command-line tool. They are consider too sensitive to be exposed through API.
       
      3.  
    3.  
      Now you can query the API, for example:
       
      curl '127.0.0.1:5281/api/registered_users?host=localhost'\n\n[\"user2\",\"user8\"]\n
       
      4.  
    "},{"location":"developer/ejabberd-api/simple-configuration/#encryption","title":"Encryption","text":"
    If you already defined certificates and your connection is not on a local network, you may want to use encryption.
     
       
    1.  
      Setup encryption like this:
       
      listen:\n  -\n    port: 5281\n    module: ejabberd_http\n    tls: true\n    request_handlers:\n      /api: mod_http_api\n
       
      2.  
    2.  
      Now you can query using HTTPS:
       
      curl 'https://127.0.0.1:5281/api/registered_users?host=localhost'\n\n[\"user2\",\"user8\"]\n
       
      3.  
    3.  
      If you are using a self-signed certificate, you can bypass the corresponding error message:
       
      curl --insecure 'https://127.0.0.1:5281/api/registered_users?host=localhost'\n\n[\"user2\",\"user8\"]\n
       
      4.  
    "},{"location":"developer/ejabberd-api/simple-configuration/#basic-authentication","title":"Basic Authentication","text":"
    Quite probably you will want to require authentication to execute API queries, either using basic auth or OAuth.
     
       
    1.  
      Assuming you have the simple listener:
       
      listen:\n  -\n    port: 5281\n    module: ejabberd_http\n    ip: 127.0.0.1\n    request_handlers:\n      /api: mod_http_api\n
       
      2.  
    2.  
      Define an ACL with the account that you will use to authenticate:
       
      acl:\n  apicommands:\n    user: john@localhost\n
       
      3.  
    3.  
      Allow only that ACL to use the API:
       
      api_permissions:\n  \"some playing\":\n    from:\n      - ejabberd_ctl\n      - mod_http_api\n    who:\n      acl: apicommands\n    what: \"*\"\n
       
      4.  
    4.  
      If that account does not yet exist, register it:
       
      ejabberdctl register john localhost somePass\n
       
      5.  
    5.  
      Now, when sending an API query, provide the authentication for that account:
       
      curl --basic --user john@localhost:somePass \\\n     '127.0.0.1:5281/api/registered_users?host=localhost'\n\n[\"user2\",\"user8\",\"john\"]\n
       
      6.  
    6.  
      Example Python code:
       
      import requests\n\nurl = \"http://localhost:5281/api/registered_users\"\ndata = {\n    \"host\": \"localhost\"\n}\n\nres = requests.post(url, json=data, auth=(\"john@localhost\", \"somePass\"))\n\nprint(res.text)\n
       
      7.  
    "},{"location":"developer/ejabberd-api/simple-configuration/#oauth-authentication","title":"OAuth Authentication","text":"
    Before using OAuth to interact with ejabberd API, you need to configure OAuth support in ejabberd.
     
    Here are example entries to check / change in your ejabberd configuration file:
     
       
    1.  
      Add a request handler for OAuth:
       
      listen:\n  -\n    # Using a separate port for oauth and API to make it easy to protect it\n    # differently than BOSH and WebSocket HTTP interface.\n    port: 5281\n    # oauth and API only listen on localhost interface for security reason\n    # You can set ip to 0.0.0.0 to open it widely, but be careful!\n    ip: 127.0.0.1\n    module: ejabberd_http\n    request_handlers:\n      /api: mod_http_api\n      /oauth: ejabberd_oauth\n
       
      2.  
    2.  
      Set the oauth_access    top-level option to allow token creation:
       
      oauth_access: all\n
       
      3.  
    3.  
      Define an ACL with the account that you will use to authenticate:
       
      acl:\n  apicommands:\n    user: john@localhost\n
       
      4.  
    4.  
      You can then configure the OAuth commands you want to expose and who can use them:
       
      api_permissions:\n  \"admin access\":\n    who:\n      oauth:\n        scope: \"ejabberd:admin\"\n        scope: \"registered_users\"\n        access:\n          allow:\n            acl: apicommands\n    what: \"*\"\n
       
      5.  
    5.  
      If that account does not yet exist,    register it:
       
      ejabberdctl register john localhost somePass\n
       
      6.  
    6.  
      Request an authorization token. A quick way is using ejabberdctl:
       
      ejabberdctl oauth_issue_token user123@localhost 3600 ejabberd:admin\nerHymcBiT2r0QsuOpDjIrsEvnOS4grkj   [<<\"ejabberd:admin\">>]   3600 seconds\n
       
      7.  
    7.  
      Now, when sending an API query, provide the authentication for that account:
       
      curl -H \"Authorization: Bearer erHymcBiT2r0QsuOpDjIrsEvnOS4grkj\" \\\n     '127.0.0.1:5281/api/registered_users?host=localhost'\n\n[\"user2\",\"user8\",\"john\"]\n
       
      Or quite simply:
       
      curl --oauth2-bearer erHymcBiT2r0QsuOpDjIrsEvnOS4grkj \\\n     '127.0.0.1:5281/api/registered_users?host=localhost'\n\n[\"user2\",\"user8\",\"john\"]\n
       
      8.  
    "},{"location":"developer/extending-ejabberd/","title":"Extending ejabberd","text":"
    This section will help you learn how to develop ejabberd module to customize it to your own needs.
    "},{"location":"developer/extending-ejabberd/architecture/","title":"Architecture","text":"
    This section contains information to help your understand ejabberd architecture and will explain how to integrate ejabberd properly into your overall infrastructure.
    "},{"location":"developer/extending-ejabberd/architecture/#overview","title":"Overview","text":"
    ejabberd is a configurable system where modules can be enabled or disabled based on customer requirements. Users can connect not only from a regular PC but also from mobile devices and from the web. User data can be stored internally in Mnesia or in one of the support SQL or NoSQL backend. Users can be totally managed by your own backend through a ReST interface.
     
    ejabberd internal architecture is organised around its router. Most of the other elements are plugins that can be adapted, enhanced or replaced to build a custom solution tailored to your needs.
     
    ejabberd support a core concept of XMPP: Federation. Federation is a mechanism allowing different independent XMPP servers and clusters to communicate with each other.
     
    Here is a high level diagram of ejabberd internal architecture:
     
    "},{"location":"developer/extending-ejabberd/architecture/#typical-large-scale-deployments","title":"Typical large scale deployments","text":"
    Here is a diagram for a typical ejabberd large scale deployment. It can scale massively and rely on several back-ends.
     
     
    Note that ejabberd ejabberd support a core concept of XMPP: Federation. Federation is a mechanism allowing different independent XMPP servers and clusters to communicate with each other. This is a purely optional layer, but it can help integrate with the rest of the world. It is also sometimes internally by companies to group users in subsidiaries or regions.
    "},{"location":"developer/extending-ejabberd/architecture/#virtual-hosting","title":"Virtual hosting","text":"
    If you need to manage several small XMPP domains, ejabberd supports virtual hosting.  It means you can host as many domain as you want on a single ejabberd deployment.
     
    Instances can be made to be totally independent and invisible for each other if needed (or they can communicate as they would through federation).
    "},{"location":"developer/extending-ejabberd/elixir/","title":"ejabberd for Elixir Developers","text":"
     improved in 21.07
    "},{"location":"developer/extending-ejabberd/elixir/#building-ejabberd-with-mix","title":"Building ejabberd with Mix","text":"
    You can build ejabberd with Elixir mix tool. This allows ejabberd to use Elixir libraries and ejabberd modules written in Elixir.
     
    Please note: Elixir 1.10.3 or higher is required to build a release. Also, if using Erlang/OTP 24, then Elixir 1.11.4 or higher is required.
     
       
    1.  
      Make sure you have the    requirements    installed. On MacOS you need to use Homebrew and    set up your environment.
       
      2.  
    2.  
      Clone ejabberd project from Github:
       
      git clone https://github.com/processone/ejabberd.git\ncd ejabberd\n
       
      3.  
    3.  
      Compile ejabberd:
       
      ./autogen.sh\n./configure --with-rebar=mix\nmake\n
       
      4.  
    4.  
      Build a development release:
       
      make dev\n
       
      5.  
    5.  
      There are many ways to start ejabberd, using the ejabberdctl or ejabberd scripts:
       
      _build/prod/rel/ejabberd/bin/ejabberdctl iexlive\n_build/prod/rel/ejabberd/bin/ejabberdctl live\n_build/prod/rel/ejabberd/bin/ejabberd start_iex\n
       
      6.  
    6.  
      You should see that ejabberd is properly started:
       
      Erlang/OTP 23 [erts-11.1.8] [source] [64-bit] [smp:2:2] [ds:2:2:10] [async-threads:1]\n\n2021-08-03 13:37:36.561603+02:00 [info] Loading configuration from /home/bernar/e/git/ejabberd/_build/dev/rel/ejabberd/etc/ejabberd/ejabberd.yml\n2021-08-03 13:37:37.541688+02:00 [info] Configuration loaded successfully\n...\n2021-08-03 13:37:40.201590+02:00 [info] ejabberd 21.7.9 is started in the node ejabberd@atenea in 3.86s\n2021-08-03 13:37:40.203678+02:00 [info] Start accepting TCP connections at [::]:5222 for ejabberd_c2s\n\nInteractive Elixir (1.10.3) - press Ctrl+C to exit (type h() ENTER for help)\niex(ejabberd@localhost)1>\n
       
      7.  
    7.  
      Now that ejabberd starts correctly, adapt to your needs the default ejabberd    configuration file located at _build/dev/rel/ejabberd/etc/ejabberd/ejabberd.yml    For example, enable this example Elixir ejabberd module:
       
      modules:\n  'ModPresenceDemo': {}\n  mod_adhoc: {}\n
       
      8.  
    "},{"location":"developer/extending-ejabberd/elixir/#embed-ejabberd-in-an-elixir-app","title":"Embed ejabberd in an elixir app","text":"
    ejabberd is available as an Hex.pm application: ejabberd on hex.pm.
     
    This means you can build a customized XMPP messaging platform with Elixir on top of ejabberd by leveraging ejabberd code base in your app and providing only your custom modules. This makes the management of your ejabberd plugins easier and cleaner.
     
    To create your own application depending on ejabberd, you can go through the following steps:
     
       
    1.  
      Create a new Elixir app using mix:
       
      mix new ejapp\ncd ejapp\n
       
      2.  
    2.  
      Add ejabberd package as a    dependency in your mix.exs file:
       
      defmodule Ejapp.MixProject do\n  defp deps do\n    [\n     {:ejabberd, \"~> 21.7\"}\n    ]\n  end\nend\n
       
      3.  
    3.  
      Compile everything:
       
      mix do deps.get, compile\n
       
      4.  
    4.  
      Create paths and files for ejabberd:
       
      mkdir config\nmkdir logs\nmkdir mnesia\nwget -O config/ejabberd.yml https://raw.githubusercontent.com/processone/ejabberd/master/ejabberd.yml.example\n
       
      5.  
    5.  
      Define those paths in config/config.exs:
       
      import Config\nconfig :ejabberd,\n  file: \"config/ejabberd.yml\",\n  log_path: 'logs/ejabberd.log'\nconfig :mnesia,\n  dir: 'mnesia/'\n
       
      6.  
    6.  
      Start your app, ejabberd will be started as a dependency:
       
      iex -S mix\n
       
      7.  
    7.  
      You should see that ejabberd is properly started:
       
      Erlang/OTP 23 [erts-11.1.8] [source] [64-bit] [smp:2:2] [ds:2:2:10] [async-threads:1]\n\nCompiling 1 file (.ex)\nGenerated ejapp app\n\n17:58:35.955 [info]  Loading configuration from config/ejabberd.yml\n\n17:58:36.459 [info]  Configuration loaded successfully\n...\n17:58:39.897 [info]  ejabberd 21.7.0 is started in the node :nonode@nohost in 4.07s\n...\n17:58:39.908 [info]  Start accepting TCP connections at [::]:5222 for :ejabberd_c2s\n\nInteractive Elixir (1.10.3) - press Ctrl+C to exit (type h() ENTER for help)\niex(1)>\n
       
      8.  
    8.  
      Register user from Elixir console:
       
      :ejabberd_auth.try_register(\"test\", \"localhost\", \"passw0rd\")\n
       
      9.  
    9.  
      You are all set, you can now connect with an XMPP client !
       
      10.  
    "},{"location":"developer/extending-ejabberd/elixir/#call-elixir-code-in-erlang-code","title":"Call elixir code in erlang code","text":"
    It's possible to use Elixir libraries in an Erlang module, both the ones included in Elixir, or any other you add as a dependency.
     
    This simple example invokes Elixir's String.duplicate/2 function as shown in one of its documentation examples, and uses the result in the ejabberd vCard nickname field:
     
    --- a/src/mod_vcard.erl\n+++ b/src/mod_vcard.erl\n@@ -209,6 +209,7 @@ process_local_iq(#iq{type = get, to = To, lang = Lang} = IQ) ->\n     VCard = case mod_vcard_opt:vcard(ServerHost) of\n   undefined ->\n       #vcard_temp{fn = <<\"ejabberd\">>,\n+    nickname = 'Elixir.String':duplicate(<<\"abc\">>, 2),\n     url = ejabberd_config:get_uri(),\n     desc = misc:get_descr(Lang, ?T(\"Erlang XMPP Server\")),\n     bday = <<\"2002-11-16\">>};\n
     
    Notice that the elixir code:
     
    String.duplicate(\"abc\", 2)\n
     
    is written in erlang as:
     
    'Elixir.String':duplicate(<<\"abc\">>, 2),\n
     
    Check Erlang/Elixir Syntax: A Crash Course for details.
    "},{"location":"developer/extending-ejabberd/elixir/#use-elixir-library-in-erlang-code","title":"Use elixir library in erlang code","text":"
    This example demonstrates how to add an elixir library as a dependency in ejabberd, and use it in an ejabberd module written in erlang.
     
    It will use QRCodeEx elixir library to build a QR code of ejabberd's URI and return it as the server vCard photo.
     
    First add the dependency to mix.exs:
     
    --- a/mix.exs\n+++ b/mix.exs\n@@ -46,7 +46,7 @@ defmodule Ejabberd.MixProject do\n                     :p1_utils, :stringprep, :yconf],\n      included_applications: [:mnesia, :os_mon,\n                              :cache_tab, :eimp, :mqtree, :p1_acme,\n-                             :p1_oauth2, :pkix, :xmpp]\n+                             :p1_oauth2, :pkix, :xmpp, :qrcode_ex]\n      ++ cond_apps()]\n   end\n\n@@ -113,6 +113,7 @@ defmodule Ejabberd.MixProject do\n      {:p1_oauth2, \"~> 0.6\"},\n      {:p1_utils, \"~> 1.0\"},\n      {:pkix, \"~> 1.0\"},\n+     {:qrcode_ex, \"~> 0.1.1\"},\n      {:stringprep, \">= 1.0.26\"},\n      {:xmpp, \"~> 1.5\"},\n      {:yconf, \"~> 1.0\"}]\n
     
    Then call QRCodeEx.encode/2, QRCodeEx.png/2, and provide the result as the photo in the server vcard:
     
    --- a/src/mod_vcard.erl\n+++ b/src/mod_vcard.erl\n@@ -206,9 +206,13 @@ process_local_iq(#iq{type = set, lang = Lang} = IQ) ->\n     xmpp:make_error(IQ, xmpp:err_not_allowed(Txt, Lang));\n process_local_iq(#iq{type = get, to = To, lang = Lang} = IQ) ->\n     ServerHost = ejabberd_router:host_of_route(To#jid.lserver),\n+    PhotoEncoded = 'Elixir.QRCodeEx':encode(ejabberd_config:get_uri()),\n+    PhotoBin = 'Elixir.QRCodeEx':png(PhotoEncoded, [{color, <<17, 120, 0>>}]),\n+    PhotoEl = #vcard_photo{type = <<\"image/png\">>, binval = PhotoBin},\n     VCard = case mod_vcard_opt:vcard(ServerHost) of\n   undefined ->\n       #vcard_temp{fn = <<\"ejabberd\">>,\n+    photo = PhotoEl,\n     url = ejabberd_config:get_uri(),\n     desc = misc:get_descr(Lang, ?T(\"Erlang XMPP Server\")),\n     bday = <<\"2002-11-16\">>};\n
    "},{"location":"developer/extending-ejabberd/elixir/#write-ejabberd-module-in-elixir","title":"Write ejabberd module in elixir","text":"
    If you plan to write an ejabberd module that heavily depends on Elixir dependencies, you may want to write it in elixir from scratch.
     
    The Elixir source code is placed in the ejabberd's lib/ path. Any elixir module placed in lib/ will be compiled by Mix, installed with all the other erlang modules, and available for you to use.
     
    As you can see, there's a file named mod_presence_demo.ex which defines an ejabberd module written in elixir called ModPresenceDemo. To enable ModPresenceDemo, add it to ejabberd.yml like this:
     
    modules:\n  'Elixir.ModPresenceDemo': {}\n
     
    Let's write a new ejabberd module in elixir, add it to ejabberd's source code, compile and install it. This example module requires the QRCodeEx Elixir library, and adds a simple web page that generates QR code of any given JID.
     
       
    1.  
      Copy the mod_qrcode.ex source code to ejabberd's lib/ path:
       
      lib/mod_qrcode.ex\n
       
      2.  
    2.  
      Recompile and reinstall ejabberd.
       
      3.  
    3.  
      Enable the module in ejabberd.yml:
       
      listen:\n  -\n    port: 5280\n    request_handlers:\n      /qrcode: 'Elixir.ModQrcode'\n\nmodules:\n  'Elixir.ModQrcode': {}\n
       
      4.  
    4.  
      When restarting ejabberd, it will show in the logs:
       
      2022-07-06 13:14:35.363081+02:00 [info] Starting ejabberd module Qrcode\n
       
      5.  
    5.  
      Now the ejabberd internal web server provides QR codes of any given JID.    Try visiting an URL like http://localhost:5280/qrcode/anyusername/somedomain/
       
      6.  
    "},{"location":"developer/extending-ejabberd/elixir/#elixir-module-in-ejabberd-contrib","title":"Elixir module in ejabberd-contrib","text":"
    Using ejabberd-contrib it's possible to install additional ejabberd modules without compiling ejabberd, or requiring ejabberd source code. This is useful if you install ejabberd using binary installers or a container image.
     
    And it's possible to write a custom module and Add your module to an existing ejabberd installation...
     
    Let's write a new ejabberd module in elixir, compile and install in an existing ejabberd deployment without requiring its source code. This example module adds a simple section listing PIDs in the users page in ejabberd WebAdmin.
     
       
    1.  
      First, create this path
       
      $HOME/.ejabberd-modules/sources/mod_webadmin_pid/lib/\n
       
      2.  
    2.  
      and copy the mod_webadmin_pid.ex source code to:
       
      $HOME/.ejabberd-modules/sources/mod_webadmin_pid/lib/mod_webadmin_pid.ex\n
       
      3.  
    3.  
      Create a specification file in YAML format as mod_webadmin_pid.spec (see examples from ejabberd-contrib). So, create the file
       
      $HOME/.ejabberd-modules/sources/mod_webadmin_pid/mod_webadmin_pid.spec\n
       
      with this content:
       
      summary: \"Display PIDs in User page in Web Admin\"\n
       
      4.  
    4.  
      From that point you should see it as available module:
       
      ejabberdctl modules_available\nmod_webadmin_pid Display PIDs in User page in Web Admin\n
       
      5.  
    5.  
      Now you can compile and install that module:
       
      ejabberdctl module_install mod_webadmin_pid\n
       
      6.  
    6.  
      Enable the module in ejabberd.yml:
       
      modules:\n  'Elixir.ModWebAdminPid': {}\n
       
      7.  
    7.  
      When restarting ejabberd, it will show in the logs:
       
      2022-07-06 13:14:35.363081+02:00 [info] Starting ejabberd module WebAdminPid\n
       
      8.  
    8.  
      Finally, go to ejabberd WebAdmin -> Virtual Hosts -> your vhost -> Users ->    some online user -> and there will be a new section \"PIDs\".
       
      9.  
    "},{"location":"developer/extending-ejabberd/elixir/#record-definition","title":"Record definition","text":"
    To use an erlang record defined in ejabberd's header file, use Elixir's Record to extract the fields and define an Elixir record with its usage macros.
     
    For example, add this to the beginning of mod_presence_demo.ex:
     
    require Record\n\nRecord.defrecord(:presence,\n  Record.extract(:presence, from_lib: \"xmpp/include/xmpp.hrl\"))\n
     
    Later you can use those macros, named like your record, see the examples.
     
    In our example, let's improve the on_presence function and use the presence macros to get the to field:
     
    def on_presence(_user, _server, _resource, packet) do\n  to_jid = presence(packet, :to)\n  to_str = :jid.to_string(to_jid)\n  info('Received presence for #{to_str}:~n~p', [packet])\n  :none\nend\n
    "},{"location":"developer/extending-ejabberd/elixir/#mod_qrcodeex","title":"mod_qrcode.ex","text":"
    Example ejabberd module written in elixir:
     mod_qrcode.ex
    defmodule ModQrcode do\n  use Ejabberd.Module\n\n  def start(host, _opts) do\n    info('Starting ejabberd module Qrcode')\n    :ok\n  end\n\n  def stop(host) do\n    info('Stopping ejabberd module Qrcode')\n    :ok\n  end\n\n  def process([username, hostname] = _path, _query) do\n    uri = <<\"xmpp:\", username::binary, \"@\", hostname::binary>>\n    qr = QRCodeEx.svg(QRCodeEx.encode(uri), [{:color, \"#3fb0d2\"}])\n    qxmlel = :fxml_stream.parse_element(qr)\n    {200,\n     [{<<\"Server\">>, <<\"ejabberd\">>},\n      {<<\"Content-Type\">>, <<\"image/svg+xml\">>}],\n     :ejabberd_web.make_xhtml([], [qxmlel])}\n  end\n\n  def process(path, _query) do\n    info('Received HTTP query with path: ~p', [path])\n    {404, [], \"Not Found\"}\n  end\n\n  def depends(_host, _opts) do\n    []\n  end\n\n  def mod_options(_host) do\n    []\n  end\n\n  def mod_doc() do\n    %{:desc => 'This is just a demonstration.'}\n  end\n\nend\n
    "},{"location":"developer/extending-ejabberd/elixir/#mod_webadmin_pidex","title":"mod_webadmin_pid.ex","text":"
    Example ejabberd module written in elixir:
     mod_webadmin_pid.ex
    defmodule ModWebAdminPid do\n  use Ejabberd.Module\n\n  require Record\n\n  Record.defrecord(:xmlel,\n    Record.extract(:xmlel, from_lib: \"xmpp/include/xmpp.hrl\"))\n\n  Record.defrecord(:request,\n    Record.extract(:request, from: \"include/ejabberd_http.hrl\"))\n\n  ##====================================================================\n  ## gen_mod callbacks\n  ##====================================================================\n\n  def start(host, _opts) do\n    info('Starting ejabberd module WebAdminPid')\n    :ejabberd_hooks.add(:webadmin_user, host, __MODULE__, :webadmin_user, 60)\n    :ejabberd_hooks.add(:webadmin_page_host, host, __MODULE__, :webadmin_page, 60)\n    :ok\n  end\n\n  def stop(host) do\n    info('Stopping ejabberd module WebAdminPid')\n    :ejabberd_hooks.delete(:webadmin_user, host, __MODULE__, :webadmin_user, 60)\n    :ejabberd_hooks.delete(:webadmin_page_host, host, __MODULE__, :webadmin_page, 60)\n    :ok\n  end\n\n  def depends(_host, _opts) do\n    []\n  end\n\n  def mod_options(_host) do\n    []\n  end\n\n  def mod_doc() do\n    %{:desc => 'This is just a demonstration.'}\n  end\n\n  ##====================================================================\n  ## Web Admin\n  ##====================================================================\n\n  def webadmin_user(acc, user, server, _lang) do\n    resources = :ejabberd_sm.get_user_resources(user, server)\n\n    pids_elements = Enum.map(resources,\n      fn resource ->\n        pid = :ejabberd_sm.get_session_pid(user, server, resource)\n        pid_string = :erlang.pid_to_list(pid)\n        xmlel(name: \"a\", attrs: [{\"href\", \"pid/#{pid_string}\"}], children: [xmlcdata: pid_string])\n      end)\n\n    pids_separated = Enum.intersperse(pids_elements, {:xmlcdata, \", \"})\n\n    new_element = xmlel(name: \"h3\", children: [xmlcdata: \"PIDs:\"])\n\n    acc ++ [new_element] ++ pids_separated\n  end\n\n  def webadmin_page(_acc, host, request(path: [\"user\", user, \"pid\", pid])) do\n    res = webadmin_pid(user, host, pid)\n    {:stop, res}\n  end\n\n  def webadmin_page(acc, _host, _request) do\n    acc\n  end\n\n  def webadmin_pid(user, host, pid_string) do\n    us = :jid.to_string(:jid.make(user, host))\n    page_title = 'Pid #{pid_string} of #{us}'\n\n    pid = :erlang.list_to_pid(String.to_charlist(pid_string))\n    pid_info = Process.info(pid)\n    pid_info_string = :io_lib.format(\"~p\", [pid_info])\n\n    [xmlel(name: \"h1\", children: [xmlcdata: page_title]),\n     xmlel(name: \"pre\", children: [xmlcdata: pid_info_string])]\n  end\n\nend\n
    "},{"location":"developer/extending-ejabberd/localization/","title":"Internationalization and Localization","text":"
    The source code of ejabberd supports localization: all built-in modules support the xml:lang attribute inside IQ queries, and the Web Admin supports the Accept-Language HTTP header.
     
    There are two ways to improve the translation of a language:
     
       
    •  
      Edit the corresponding .po file in ejabberd-po git repository with a gettext-compatible program (Poedit, KBabel, Lokalize, ...). Then submit a Pull Request.
       
      •  
    •  
      Using the ejabberd-po Weblate online service.
       
      •  
     
    Once the translators have improved the po files, you can run make translations. With that command, the translatable strings are extracted from source code to generate the file ejabberd.pot. This file is merged with each .po file to produce updated .po files. Finally those .po files are exported to .msg files, that have a format easily readable by ejabberd.
    "},{"location":"developer/extending-ejabberd/modules/","title":"ejabberd Modules Development","text":""},{"location":"developer/extending-ejabberd/modules/#introduction","title":"Introduction","text":"
    ejabberd is based on a modular architecture that makes it highly customizable and infinitely extensible.
     
    Here is an overview of ejabberd internal architecture:
     
    "},{"location":"developer/extending-ejabberd/modules/#what-is-a-module","title":"What is a module ?","text":"
    Outside of a few infrastructure core components most of ejabberd features are developed as modules. Modules are used to extend the features of ejabberd (plugins).
    "},{"location":"developer/extending-ejabberd/modules/#how-to-write-a-custom-module","title":"How to write a custom module ?","text":"
    Ejabberd comes with a lot of modules, but sometimes you may need an unsupported feature from the official sources or maybe you need to write your own custom implementation for your very special needs.
     
    Each modules is written in either Erlang or Elixir. To use them, you typically declare them in ejabberd configuration file. That's also the place where you can configure the module, by passing supported options to overload its default behaviour.
     
    On ejabberd launch, the server will start all the declared modules. You can start (or stop) them manually from Erlang shell as well.
     
    As a convention, module names starts with \"mod_\", but you can actually call them as you want.
    "},{"location":"developer/extending-ejabberd/modules/#the-gen_mod-behaviour","title":"The gen_mod behaviour","text":"
    All ejabberd modules are implementing the gen_mod behaviour. It means that a module must provide the following API:
     
    start(Host, Opts) -> ok\nstop(Host) -> ok\ndepends(Host, Opts) -> []\nmod_options(Host) -> []\n
     
    Parameters are:
     
       
    • Host = string()
      •  
    • Opts = [{Name, Value}]
      •  
    • Name = Value = string()
      •  
     
    Host is the name of the virtual host running the module. The start/2 and stop/1 functions are called for each virtual host at start and stop time of the server.
     
    Opts is a lists of options as defined in the configuration file for the module. They can be retrieved with the gen_mod:get_opt/3 function.
    "},{"location":"developer/extending-ejabberd/modules/#mod_hello_world","title":"mod_hello_world","text":"
    The following code shows the simplest possible module.
     mod_hello_world.erl
    -module(mod_hello_world).\n\n-behaviour(gen_mod).\n\n%% Required by ?INFO_MSG macros\n-include(\"logger.hrl\").\n\n%% Required by ?T macro\n-include(\"translate.hrl\").\n\n%% gen_mod API callbacks\n-export([start/2, stop/1, depends/2, mod_options/1, mod_doc/0]).\n\nstart(_Host, _Opts) ->\n    ?INFO_MSG(\"Hello, ejabberd world!\", []),\n    ok.\n\nstop(_Host) ->\n    ?INFO_MSG(\"Bye bye, ejabberd world!\", []),\n    ok.\n\ndepends(_Host, _Opts) ->\n    [].\n\nmod_options(_Host) ->\n    [].\n\nmod_doc() ->\n    #{desc =>\n          ?T(\"This is an example module.\")}.\n
     
    Now you have two ways to compile and install the module: If you compiled ejabberd from source code, you can copy that source code file with all the other ejabberd source code files, so it will be compiled and installed with them. If you installed some compiled ejabberd package, you can create your own module dir, see Add Your Module.
     
    You can enable your new module by adding it in the ejabberd config file. Adding the following snippet in the config file will integrate the module in ejabberd module lifecycle management. It means the module will be started at ejabberd launch and stopped during ejabberd shutdown process:
     
    modules:\n  ...\n  mod_hello_world: {}\n
     
    Or you can start / stop it manually by typing the following commands in an Erlang shell running ejabberd:
     
       
    •  
      To manually start your module:
       
      gen_mod:start_module(<<\"localhost\">>, mod_hello_world, []).\n
       
      •  
    •  
      To manually stop your module:
       
      gen_mod:stop_module(<<\"localhost\">>, mod_hello_world).\n
       
      •  
     
    When the module is started, either on ejabberd start or manually, you should see the following message in ejabberd log file:
     
    19:13:29.717 [info] Hello, ejabberd world!\n
    "},{"location":"developer/extending-ejabberd/modules/#ejabberd-contrib","title":"ejabberd-contrib","text":"
    ejabberd is able to fetch module sources by itself, compile with correct flags and install in a local repository, without any external dependencies. You do not need to know Erlang and have it installed in order to use the contributed modules. The contributed modules repository is ejabberd-contrib on github. It contains most used contributions and also can link to any other external repository. This works with ejabberd modules written in Erlang and will also support new Elixir modules.
    "},{"location":"developer/extending-ejabberd/modules/#basic-usage","title":"Basic usage","text":"
    As a user, this is how it works:
     
       
    1.  
      First you need to get/update the list of available modules.  This must be     done before anything else to let module related features to work correctly.     You may want to repeat this command before you need installing a new module     or an attended server upgrade.
       
      ejabberdctl modules_update_specs\n
       
      2.  
    2.  
      Then you can list available modules:
       
      ejabberdctl modules_available\n...\nmod_admin_extra Additional ejabberd commands\nmod_archive Supports almost all the XEP-0136 version 0.6 except otr\nmod_cron Execute scheduled commands\nmod_log_chat Logging chat messages in text files\n...\n
       
      3.  
    3.  
      Let\u2019s install mod_cron from ejabberd-contrib repository:
       
      ejabberdctl module_install mod_cron\nok\n
       
      4.  
    4.  
      You can check anytime what modules are installed:
       
      ejabberdctl modules_installed\nmod_cron\n
       
      5.  
    5.  
      An example default configuration is installed, and will be read by ejabberd     when it starts. You can find that small configuration in:
       
      $HOME/.ejabberd-modules/mod_cron/conf/mod_cron.yml\n
       
      6.  
    6.  
      And finally, you can remove the module:
       
      ejabberdctl module_uninstall mod_cron\nok\n
       
      7.  
    "},{"location":"developer/extending-ejabberd/modules/#add-your-module","title":"Add your module","text":"
    If you install ejabberd using the official ProcessOne installer, it includes everything needed to build ejabberd modules on its own.
     
       
    1.  
      First, create this path
       
      $HOME/.ejabberd-modules/sources/mod_hello_world/src/\n
       
      2.  
    2.  
      and copy your source code to this location:
       
      $HOME/.ejabberd-modules/sources/mod_hello_world/src/mod_hello_world.erl\n
       
      3.  
    3.  
      Create a specification file in YAML format as mod_hello_world.spec (see examples from ejabberd-contrib). So, create the file
       
      $HOME/.ejabberd-modules/sources/mod_hello_world/mod_hello_world.spec\n
       
      with this content:
       mod_hello_world.spec
      summary: \"Hello World example module\"\n
       
      4.  
    4.  
      From that point you should see it as available module:
       
      ejabberdctl modules_available\nmod_hello_world Hello World example module\n
       
      5.  
    5.  
      Now you can install and uninstall that module like any other,     as described in the previous section.
       
      6.  
    6.  
      If you plan to publish your module, you should check if your module     follows the policy and if it compiles correctly:
       
      ejabberdctl module_check mod_mysupermodule\nok\n
       
      If all is OK, your\u2019re done ! Else, just follow the warning/error messages to fix the issues.
       
      7.  
     
    You may consider publishing your module as a tgz/zip archive or git repository, and send your spec file for integration in ejabberd-contrib repository. ejabberd-contrib will only host a copy of your spec file and does not need your code to make it available to all ejabberd users.
    "},{"location":"developer/extending-ejabberd/modules/#your-module-with-docker","title":"Your module with Docker","text":"
    If you installed ejabberd using the Docker image, these specific instructions allow you to use your module with your Docker image:
     
       
    1.  
      Create a local directory for the contributed modules:
       
      mkdir docker-modules\n
       
      2.  
    2.  
      Then create the directory structure for your custom module:
       
      cd docker-modules\n\nmkdir -p sources/mod_hello_world/\ntouch sources/mod_hello_world/mod_hello_world.spec\n\nmkdir sources/mod_hello_world/src/\nmv mod_hello_world.erl sources/mod_hello_world/src/\n\nmkdir sources/mod_hello_world/conf/\necho -e \"modules:\\n  mod_hello_world: {}\" > sources/mod_hello_world/conf/mod_hello_world.yml\n\ncd ..\n
       
      3.  
    3.  
      Grant ownership of that directory to the UID that ejabberd will use inside the Docker image:
       
      sudo chown 9000 -R docker-modules/\n
       
      4.  
    4.  
      Start ejabberd in Docker:
       
      sudo docker run \\\n  --name hellotest \\\n  -d \\\n  --volume \"$(pwd)/docker-modules:/home/ejabberd/.ejabberd-modules/\" \\\n  -p 5222:5222 \\\n  -p 5280:5280 \\\n  ejabberd/ecs\n
       
      5.  
    5.  
      Check the module is available for installing, and then install it:
       
      sudo docker exec -it hellotest bin/ejabberdctl modules_available\nmod_hello_world []\n\nsudo docker exec -it hellotest bin/ejabberdctl module_install mod_hello_world\n
       
      6.  
    6.  
      If the module works correctly, you will see the Hello string in the ejabberd logs when it starts:
       
      sudo docker exec -it hellotest grep Hello logs/ejabberd.log\n2020-10-06 13:40:13.154335+00:00 [info]\n  <0.492.0>@mod_hello_world:start/2:15 Hello, ejabberd world!\n
       
      7.  
    "},{"location":"developer/extending-ejabberd/modules/#status","title":"Status","text":"
    Please note this is provided as a beta version. We want the work in progress to be released early to gather feedback from developers and users.
     
    For now, you need to edit the configuration snippet provided in module\u2019s conf directory and copy it into your ejabberd\u2019s main configuration. Then you\u2019ll need to restart ejabberd or manually start the module.
     
    However, our plan is to keep iterating on the tool and to make our best to make module installation as easy as possible and avoid need to change main configuration: ejabberd should be able to include module configuration snippets on the fly in a near future.
    "},{"location":"developer/extending-ejabberd/modules/#next-steps","title":"Next steps","text":"
    From there, you know how to package a module to integrate it inside ejabberd environment. Packaging a module allows you to:
     
       
    • Integrate in ejabberd overall application life cycle, i.e. with the   start and stop mechanism.
      •  
    • Get data from ejabberd configuration file.
      •  
     
    Now, to do useful stuff, you need to integrate with ejabberd data flow. You have two mechanisms available from ejabberd modules:
     
       
    •  
      Events and Hooks: This is to handle internal ejabberd triggers and   subscribe to them to perform actions or provide data.
       
      •  
    •  
      IQ Handlers: This is a way to register ejabberd module to handle   XMPP Info Queries. This is the XMPP way to provide new services.
       
      •  
    "},{"location":"developer/extending-ejabberd/pubsub/","title":"PubSub overview","text":"
    This document describes ejabberd's PubSub architecture to understand how to write custom plugins.
     
    XEP-0060 (PubSub) is more than 100 pages of specifications, with 12 very detailed use cases with many possibles options and possible situations:
     
       
    • Subscribe
      •  
    • Unsubscribe
      •  
    • Configure subscription
      •  
    • Retrieve items
      •  
    • Publish item
      •  
    • Delete item
      •  
    • Create node
      •  
    • Configure node
      •  
    • Delete node
      •  
    • Purge node
      •  
    • Manage subscriptions
      •  
    • Manage affiliations
      •  
     
    XEP-0163 (PEP) is based on PubSub XEP-0248 (deprecated) for Collection Nodes and uses generic PubSub functionality, specified in XEP-0060.
    "},{"location":"developer/extending-ejabberd/pubsub/#history","title":"History","text":"
    Initial implementation made by Aleksey Shchepin, ability to organise nodes in a tree added by Christophe Romain in 2007. First attempt to create a flexible API for plugins started in 2007, and improved until 2015.
    "},{"location":"developer/extending-ejabberd/pubsub/#implementation","title":"Implementation","text":"
    PubSub service comes in several parts:
     
       
    • A poll of iq handlers handled by ejabberd router
      •  
    • A sending process
      •  
    • A core router to perform high level actions for every use case
      •  
    • Plugins to handle nodes, affiliations/subscriptions, and items at lower level and interface with data backend
      •  
    "},{"location":"developer/extending-ejabberd/pubsub/#nodetree-plugins","title":"Nodetree plugins","text":"
    They handles storage and organisation of PubSub nodes. Called on get, create and delete node. Default implementation includes three plugins:
     
       
    • tree: (default) both internal and odbc backend.
      •  
    • virtual: no backend, no configurable nodes.
      •  
    • dag: handles XEP-0248.
      •  
     
    If all nodes shares same configuration, I/O on pubsub_node can be avoided using virtual nodetree.
    "},{"location":"developer/extending-ejabberd/pubsub/#node-plugins","title":"Node plugins","text":"
    They handle affiliations, subscriptions and items. They provide default node configuration and features. Called on every pubsub use cases. Each plugin is responsible of checks to handle all possibles cases and reply action result to PubSub engine to let it handle the routing. The most common plugins available in default installation are:
     
       
    • flat: (default) all nodes are in a flat namespace, there are no parent/child nodes
      •  
    • hometree: all nodes are organized as in a filesystem under /home/hostname/user/...
      •  
    • pep: handles XEP-0163
      •  
    • dag: handles XEP-0248.
      •  
    • public, private, ... which are derivate of flat, with different default node configuration.
      •  
    "},{"location":"developer/extending-ejabberd/pubsub/#node_flat","title":"node_flat","text":"
    node_flat is the default plugin, without node hierarchy, which handles standard PubSub case. The default node configuration with this plugin is:
     
    [{deliver_payloads, true},\n {notify_config, false},\n {notify_delete, false},\n {notify_retract, true},\n {purge_offline, false},\n {persist_items, true},\n {max_items, 10},\n {subscribe, true},\n {access_model, open},\n {roster_groups_allowed, []},\n {publish_model, publishers},\n {notification_type, headline},\n {max_payload_size, 60000},\n {send_last_published_item, on_sub_and_presence},\n {deliver_notifications, true},\n {presence_based_delivery, false}].\n
    "},{"location":"developer/extending-ejabberd/pubsub/#node_hometree","title":"node_hometree","text":"
    node_hometree use exact same features as flat plugin, but organise nodes in a tree following same scheme as path in filesystem. Every user can create nodes in its own home. Each node can contain items and/or sub-nodes. Example:
     
    /home/user\n/home/domain/user\n/home/domain/user/my_node\n/home/domain/user/my_node/child_node\n
    "},{"location":"developer/extending-ejabberd/pubsub/#node_pep","title":"node_pep","text":"
    node_pep handles XEP-0163: Personal Eventing Protocol It do not persist items, just keeping last item in memory cache. Node names are raw namespace attached to a given bare JID. Every user can have its own node with a common namespace sharing with others.
    "},{"location":"developer/extending-ejabberd/pubsub/#node_dag","title":"node_dag","text":"
    node_dag handles XEP-0248: PubSub Collection Nodes Contribution from Brian Cully. Every node takes places in a tree and is either a collection node (have only sub-nodes) or a leaf node (contains only items). No restriction on the tree structure
    "},{"location":"developer/extending-ejabberd/pubsub/#plugin-design","title":"Plugin design","text":"
    Due to complexity of XEP-0060, PubSub engine do successive calls to nodetree and node plugins in order to check validity, perform corresponding action and return result or appropriate error to users. Plugin design follows this requirement and divide actions by type of data to allow transient backend implementation without any PubSub engine change.
    "},{"location":"developer/extending-ejabberd/pubsub/#create-node","title":"Create Node","text":""},{"location":"developer/extending-ejabberd/pubsub/#delete-node","title":"Delete Node","text":""},{"location":"developer/extending-ejabberd/pubsub/#subscribe","title":"Subscribe","text":""},{"location":"developer/extending-ejabberd/pubsub/#unsubscribe","title":"Unsubscribe","text":""},{"location":"developer/extending-ejabberd/pubsub/#publish-item","title":"Publish item","text":""},{"location":"developer/extending-ejabberd/pubsub/#delete-item","title":"Delete item","text":""},{"location":"developer/extending-ejabberd/pubsub/#purge-node","title":"Purge Node","text":""},{"location":"developer/extending-ejabberd/pubsub/#get-item","title":"Get item","text":""},{"location":"developer/extending-ejabberd/pubsub/#available-backends","title":"Available backends","text":"
    Flat, hometree and PEP supports mnesia and SQL backends. Any derivated plugin can support the same (public, private, club, buddy...). Adding backend does not require any PubSub engine change. Plugin just need to comply API. Business Edition also supports optimized ets and mdb.
    "},{"location":"developer/extending-ejabberd/pubsub/#customisation","title":"Customisation","text":"
    To write your own plugin, you need to implement needed functions:
     
    [init/3, terminate/2, options/0, features/0,\n create_node_permission/6, create_node/2, delete_node/1,\n purge_node/2, subscribe_node/8, unsubscribe_node/4,\n publish_item/6, delete_item/4, remove_extra_items/3,\n get_entity_affiliations/2, get_node_affiliations/1,\n get_affiliation/2, set_affiliation/3,\n get_entity_subscriptions/2, get_node_subscriptions/1,\n get_subscriptions/2, set_subscriptions/4,\n get_pending_nodes/2, get_states/1, get_state/2,\n set_state/1, get_items/7, get_items/3, get_item/7,\n get_item/2, set_item/1, get_item_name/3, node_to_path/1,\n path_to_node/1]\n
     
    Generic function must call their corresponding partner in node_flat.
     
    Simple plugin would just call node_flat and override some defaults such as:
     
       
    • options/0 and features/0 to match your needs. This triggers the way PubSub controls calls to your plugins.
      •  
    • create_node_permission/6 for example to check an LDAP directory against an access flag
      •  
    • Write your own tests on publish or create node, forbids explicit access to items, etc...
      •  
    "},{"location":"developer/extending-ejabberd/pubsub/#clustering","title":"Clustering","text":"
    ejabberd's implementation tends to cover most generic and standard uses. It's good for common use, but far from optimal for edges or specific cases. Nodes, affiliations, subscriptions and items are stored in a replicated database. Each ejabberd node have access to all the data. Each ejabberd node handles part of the load, but keep locking database cluster wide on node records write (pubsub_node) Affiliations, subscriptions and items uses non blocking write (pubsub_state and pubsub_item)
    "},{"location":"developer/extending-ejabberd/stanza-routing/","title":"ejabberd Stanza Routing","text":""},{"location":"developer/extending-ejabberd/stanza-routing/#message-routing","title":"Message Routing","text":"
    In case of a message sent from User A to User B, both of whom are served by the same domain, the flow of the message through the system is as follows:
     
       
    1. User A's ejabberd_receiver receives the stanza and passes it to    ejabberd_c2s.
      2.  
    2. After some consistency check, user_send_packet is called if the    stanza is correct.
      3.  
    3. The stanza is matched against any privacy lists in use and, in case    of being allowed, routed by ejabberd_router:route/3.
      4.  
    4. ejabberd_router:route/3 runs the filter_packet    hook. filter_packet hook can drop of modify the stanza.
      5.  
    5.  
      ejabberd_router will then consult the routing table to know what    do to next. It is easier to understand by looking at an example of    actual routing table content:
       
      (ejabberd@localhost)2> ets:tab2list(route).\n[{route,<<\"pubsub.localhost\">>,\n  {apply_fun,#Fun<ejabberd_router.2.122122122>}},\n{route,<<\"muc.localhost\">>,\n  {apply_fun,#Fun<mod_muc.2.122122123>}},\n{route,<<\"localhost\">>,{apply,ejabberd_local,route}}]\n
       
      6.  
     
    In that case, user is local so we need to route to same domain (in    our case localhost). We then can see that we have to call    ejabberd_local:route to route the message to local user. As both    user are local (no server-to-server involved), it matches our    expectations.
     
       
    1.  
      ejabberd_local routes the stanza to ejabberd_sm given it's got at    least a bare JID as the recipient.
       
      2.  
    2.  
      ejabberd_sm determines the available resources of User B, takes    into account their session priorities and whether the message is    addressed to a particular resource or a bare JID and appropriately    replicates (or not) the message and sends it to the recipient's    ejabberd_c2s process(es).
       
      3.  
     
    In case no resources are available for delivery (hence no    ejabberd_c2s processes to pass the message to),    offline_message_hook is run to delegate offline message storage.
     
       
    1. ejabberd_c2s verifies the stanza against any relevant privacy    lists and sends it on the user socket if it does exist. In the case    of ejabberd Business Edition and ejabberd Saas, session can be    detached and push notifications can be used as a fallback.    user_receive_packet hook is run to notify the rest of the system    about stanza delivery to User B.
      2.  
     
    Here is a broader diagram, including server-to-server routing:
     
    "},{"location":"developer/extending-ejabberd/testing/","title":"ejabberd Test Suites","text":"
    ejabberd comes with a comprehensive test suite to cover various part of the software platform.
    "},{"location":"developer/extending-ejabberd/testing/#xmpp-end-to-end-protocol-test-suite","title":"XMPP end-to-end protocol test suite","text":""},{"location":"developer/extending-ejabberd/testing/#running-ejabberd-test-suite","title":"Running ejabberd test suite","text":"
    This test suite is a set of end-2-end integration tests that act like XMPP clients connecting with the server and is testing ejabberd at the protocol level.  It also contains tests for the various backends that ejabberd supports.
     
    The test suite is modular and can be run in parts (to focus on a group of features) or run for a specific backend.
     
    The CT_BACKENDS environment variable specifies which backend tests to run. Current CT_BACKENDS values:
     
       
    • extauth
      •  
    • ldap
      •  
    • mnesia
      •  
    • mssql
      •  
    • mysql
      •  
    • odbc
      •  
    • pgsql
      •  
    • redis
      •  
    • sqlite
      •  
     
    Note: You must build ejabberd with proper backend support for the tests to work. If the tests fail and you aren't sure why, check the configure build options to make sure ejabberd is compiled with adequate backend support.
     
    Note: these tests are e2e tests that operate a full ejabberd instance.  So the ports that ejabberd needs must be available for testing.  So you can't run an ejabberd instance at the same time you test.
     
    Other options you can use to limit the tests that will be run is to pass a list of groups to test. Some groups examples:
     
       
    • no_db: Runs subgroups generic and test_proxy65.
      •  
    • component
      •  
    • extauth
      •  
    • ldap
      •  
    • mnesia
      •  
    • mssql
      •  
    • mysql
      •  
    • pgsql
      •  
    • redis
      •  
    • s2s
      •  
    • sqlite
      •  
     
    Usually, it is enough to just limit tests with CT_BACKENDS and let the test suite decide which relevant tests to run. Sometimes you may want to only focus on a specific backend, skipping the generic no_db tests.
     
    Some example commands for running the XMPP end-to-end test suite using rebar and rebar3 ct:
     
    CT_BACKENDS=mnesia rebar  ct suites=ejabberd\nCT_BACKENDS=mnesia rebar  ct suites=ejabberd groups=mnesia\nCT_BACKENDS=mnesia rebar  ct suites=ejabberd groups=generic\nCT_BACKENDS=mnesia rebar3 ct --suite=test/ejabberd_SUITE --group=offline_flex,offline_send_all\nCT_BACKENDS=redis  rebar3 ct --suite=test/ejabberd_SUITE --group=offline_flex,offline_send_all\n
     
    If you have every backend configured, you can run all the tests with:
     
    make test\n
    "},{"location":"developer/extending-ejabberd/testing/#test-suite-conventions","title":"Test suite conventions","text":"
    The records used in test suite are autogenerated and come from tools/xmpp_codec.hrl. This is handy to match packets/results against expected values.
    "},{"location":"developer/extending-ejabberd/testing/#dependency-tests","title":"Dependency tests","text":"
    ejabberd depends on a lot of dependent modules. The dependencies can be tested independently by checking them out and running their test suites directly.
    "},{"location":"developer/extending-ejabberd/testing/#build-test-status","title":"Build test status","text":"
    We run tests for ejabberd and dependencies automatically via Github Actions. We have a Dashboard available on Github to check the overall test status for all projects: ProcessOne Github Dashboard
    "},{"location":"developer/xmpp-clients-bots/","title":"XMPP clients & bots","text":"
    As an XMPP developer, you will have to learn the basic of the XMPP protocol to developer clients and bots.
     
    This section is here to help you get started in writing XMPP powered software.
    "},{"location":"developer/xmpp-clients-bots/#xmpp-extensions","title":"XMPP Extensions","text":"
    Here is a section gathering proposed XMPP extensions:
     
       
    • Muc Sub: Extension to ease use of MUC on mobile by mixing Multi-User Chat with Subscription approach.
      •  
    • Simplified Roster Versioning: ejabberd implements a simplified roster versioning approach, compliant with roster versioning as defined in XEP-0237.
      •  
    "},{"location":"developer/xmpp-clients-bots/#xmpp-development","title":"XMPP Development","text":"
       
    • iOS Development: Getting started with XMPPFramework on iOS.
      •  
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/","title":"MucSub: Multi-User Chat Subscriptions","text":""},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#motivation","title":"Motivation","text":"
    In XMPP, Multi-User Chat rooms design rely on presence. To participate in a MUC room, you need to send a presence to the room. When you get disconnected, you leave the room and stopped being part of the room. User involvement in MUC rooms is not permanent.
     
    This is an issue with the rise of mobile applications. Chatting with friends in a room is a big part of messaging usage on mobile. However, to save battery life, mobile devices will freeze mobile XMPP application after a while when they get to background. It means that the connection is lost and that the session is usually terminated.
     
    Some workaround have been used to try letting user keep on receiving messages from MUC room when the app is in background. The most common one is to keep the session open for a while until a timeout happens. This is the approach promoted on mobile by XEP-0198 - Stream Management. When messages are received and no TCP/IP connection is attached, server usually fallback sending the message to the user using mobile push notification service to warn the user that a message has been received.
     
    This approach has many drawbacks:
     
       
    1. It is not permanent. The idea of having the session kept into    memory for a while is interesting but it is just a long    timeout. After that timeout, the session is closed and the user    will leave the room. No message will be received anymore.
      2.  
    2. It does not play well with normal server / cluster operations. If    you restart the service where the user session is kept, it will    disappear. You can dump them to disk and recreate them on start,    but it means that if the node crashes, your session will be lost    and user will stop receiving messages.
      3.  
    3. It does not change the fundamental nature of MUC chat room. They    are still presence-based. It means that if you need to restart the    MUC service, or if it crashes, presence are lost. For connected    clients, they are expected to join the MUC room again. However, for    mobile clients, it cannot happens until user reopens the    app. Moreover, it means that on new session start, user client is    expected to join all the MUC rooms they want to keep track of on    connect.
      4.  
     
    This specification tries to solve those issues by keeping most of the logic of the MUC room intact. There is attempt to rewrite XMPP Multi-User chat rooms by splitting presence from ability to receive and send messages (XEP-0369: Mediated Information eXchange (MIX)). However, the features covered by the MUC protocol are quite comprehensive and the MIX protocol is not yet ready to cover all the MUC use cases yet. The goal is to produce an intermediate state that is compliant with MUC and leverage most of the MUC features, while adding the most basic feature possible to implement the MUC/Sub extension.
     
    This specifications tries to merge ideas to produce a MUC extension that make MUC rooms mobile clients friendly.
     
    To play well with mobile, MUC room need to support the following features:
     
       
    • Add the ability to send and receive messages to a room without   having to send presence to the room. More generally allow other type   of interaction with the room (like configuration changes for example   or kick and ban). We will leverage existing publish and subscribe   approach.
      •  
    • Add the ability to resync the client for missed messages on   reconnect. We will leverage Message Archive Management service for   MUC.
      •  
    • Finally, ensure that a server can implement push notification   service to ensure alerting of offline users when MUC messages are   received.
      •  
     
    The goal is to learn from real life working implementation to help feeding MIX with feedback from the field, without having to reinvent a complete new protocol.
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#general-principle","title":"General principle","text":"
    The core idea is to expose MUC rooms as PubSub nodes and to introduce the concept of MUC rooms subscribers.
     
    A user affiliated to a MUC room should be able to subscribe to MUC node events and have them routed to their JID, even if they are not a participant in the room. It means that a user can receive messages without having to send presence to the room. In that sense, \"joining the room\" in XEP-0045 becomes more \"Being available in the MUC room\".
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#discovering-support","title":"Discovering support","text":""},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#discovering-support-on-muc-service","title":"Discovering support on MUC service","text":"
    You can check if MUC/Sub feature is available on MUC service by sending Disco Info IQ:
     
    <iq from='hag66@shakespeare.example/pda'\n    to='muc.shakespeare.example'\n    type='get'\n    id='ik3vs715'>\n  <query xmlns='http://jabber.org/protocol/disco#info'/>\n</iq>\n
     
    MUC service will show a feature of type 'urn:xmpp:mucsub:0' to the response if the feature is supported and enabled:
     
    <iq from=\"muc.shakespeare.example\"\n    to=\"hag66@shakespeare.example/pda\"\n    type=\"result\"\n    id=\"ik3vs715\">\n  <query xmlns=\"http://jabber.org/protocol/disco#info\">\n    <identity category=\"conference\"\n              type=\"text\"\n              name=\"Chatrooms\" />\n    ...\n    <feature var=\"urn:xmpp:mucsub:0\" />\n    ...\n  </query>\n</iq>\n
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#discovering-support-on-a-specific-muc","title":"Discovering support on a specific MUC","text":"
    A user can discover support for MUC/Sub feature on a MUC room as follow:
     
    <iq from='hag66@shakespeare.example/pda'\n    to='coven@muc.shakespeare.example'\n    type='get'\n    id='ik3vs715'>\n  <query xmlns='http://jabber.org/protocol/disco#info'/>\n</iq>\n
     
    A conference MUST add 'urn:xmpp:mucsub:0' to the response if the feature is supported and enabled:
     
    <iq from='coven@muc.shakespeare.example'\n    to='hag66@shakespeare.example/pda'\n    type='result'\n    id='ik3vs715'>\n  <query xmlns='http://jabber.org/protocol/disco#info'>\n    <identity category='conference'\n              name='A Dark Cave'\n              type='text' />\n    <feature var='http://jabber.org/protocol/muc' />\n    ...\n    <feature var='urn:xmpp:mucsub:0' />\n    ...\n  </query>\n</iq>\n
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#option-muc-room-support-for-subscriptions","title":"Option MUC room support for subscriptions","text":"
    Even if MUC room supports MUC/Sub feature, it MAY be explicitly enabled or disabled thanks to a new configuration option:
     
       
    • Allow subscription: Users can subscribe to MUC/Sub events.
      •  
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#subscriber-role","title":"Subscriber role","text":"
    Until a subscriber is not joined a conference (see Joining a MUC Room), a subscriber role MUST be 'none'. When a subscriber is joined a conference its role is changed according to XEP-0045 rules, that is, it becomes either 'visitor', 'participant' or 'moderator'.
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#subscribing-to-mucsub-events","title":"Subscribing to MUC/Sub events","text":"
    User can subscribe to the following events, by subscribing to specific nodes:
     
       
    • urn:xmpp:mucsub:nodes:presence
      •  
    • urn:xmpp:mucsub:nodes:messages
      •  
    • urn:xmpp:mucsub:nodes:affiliations
      •  
    • urn:xmpp:mucsub:nodes:subscribers
      •  
    • urn:xmpp:mucsub:nodes:config
      •  
    • urn:xmpp:mucsub:nodes:subject
      •  
    • urn:xmpp:mucsub:nodes:system
      •  
     
    Example: User Subscribes to MUC/Sub events
     
    <iq from='hag66@shakespeare.example'\n    to='coven@muc.shakespeare.example'\n    type='set'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscribe xmlns='urn:xmpp:mucsub:0'\n             nick='mynick'\n             password='roompassword'>\n    <event node='urn:xmpp:mucsub:nodes:messages' />\n    <event node='urn:xmpp:mucsub:nodes:affiliations' />\n    <event node='urn:xmpp:mucsub:nodes:subject' />\n    <event node='urn:xmpp:mucsub:nodes:config' />\n  </subscribe>\n</iq>\n
     
    If user is allowed to subscribe, server replies with success. The password attribute can be provided when subscribing to a password-protected room.
     
    Example: Server replies with success
     
    <iq from='coven@muc.shakespeare.example'\n    to='hag66@shakespeare.example'\n    type='result'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscribe xmlns='urn:xmpp:mucsub:0'>\n    <event node='urn:xmpp:mucsub:nodes:messages' />\n    <event node='urn:xmpp:mucsub:nodes:affiliations' />\n    <event node='urn:xmpp:mucsub:nodes:subject' />\n    <event node='urn:xmpp:mucsub:nodes:config' />\n  </subscribe>\n</iq>\n
     
    Subscription is associated with a nick. It will implicitly register the nick. Server should otherwise make sure that subscription match the user registered nickname in that room. In order to change the nick and/or subscription nodes, the same request MUST be sent with a different nick or nodes information.
     
    Example: User changes subscription data
     
    <iq from='hag66@shakespeare.example'\n    to='coven@muc.shakespeare.example'\n    type='set'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscribe xmlns='urn:xmpp:mucsub:0'\n             nick='newnick'>\n    <event node='urn:xmpp:mucsub:nodes:messages' />\n    <event node='urn:xmpp:mucsub:nodes:presence' />\n  </subscribe>\n</iq>\n
     
    A room moderator can subscribe another user to MUC Room events by providing the user JID as an attribute in the <subscribe/> element.
     
    Example: Room moderator subscribes another user
     
    <iq from='king@shakespeare.example'\n    to='coven@muc.shakespeare.example'\n    type='set'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscribe xmlns='urn:xmpp:mucsub:0'\n             jid='hag66@shakespeare.example'\n             nick='mynick'\n             password='roompassword'>\n    <event node='urn:xmpp:mucsub:nodes:messages' />\n    <event node='urn:xmpp:mucsub:nodes:affiliations' />\n    <event node='urn:xmpp:mucsub:nodes:subject' />\n    <event node='urn:xmpp:mucsub:nodes:config' />\n  </subscribe>\n</iq>\n
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#unsubscribing-from-a-muc-room","title":"Unsubscribing from a MUC Room","text":"
    At any time a user can unsubscribe from MUC Room events.
     
    Example: User unsubscribes from a MUC Room
     
    <iq from='hag66@shakespeare.example'\n    to='coven@muc.shakespeare.example'\n    type='set'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <unsubscribe xmlns='urn:xmpp:mucsub:0' />\n</iq>\n
     
    Example: A MUC Room responds to unsubscribe request
     
    <iq from='coven@muc.shakespeare.example'\n    to='hag66@shakespeare.example'\n    type='result'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7' />\n
     
    A room moderator can unsubscribe another room user from MUC Room events by providing the user JID as an attribute in the <unsubscribe/> element.
     
    Example: Room moderator unsubscribes another room user
     
    <iq from='king@shakespeare.example'\n    to='coven@muc.shakespeare.example'\n    type='set'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <unsubscribe xmlns='urn:xmpp:mucsub:0'\n               jid='hag66@shakespeare.example'/>\n</iq>\n
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#subscriber-actions","title":"Subscriber actions","text":"
    If not stated otherwise in this document, a subscriber MUST perform any actions in the conference as described in XEP-0045. For example, it MUST send messages to all occupants according to 7.4 Sending a Message to All Occupants, it MUST configure a conference according to 10.2 Subsequent Room Configuration and so on.
     
    Here are a few examples:
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#sending-a-message","title":"Sending a message","text":"
    Sending a message is like sending a standard groupchat message in MUC room:
     
    <message from=\"hag66@shakespeare.example\"\n         to=\"coven@muc.shakespeare.example\"\n         type=\"groupchat\">\n  <body>Test</body>\n</message>\n
     
    No need to join it after you connect. As a subscriber, you can send messages at any time.
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#joining-a-muc-room","title":"Joining a MUC Room","text":"
    If a user wants to be present in the room, they just have to join the room as defined in XEP-0045.
     
    A subscriber MAY decide to join a conference (in the XEP-0045 sense). In this case a conference MUST behave as described in XEP-0045 7.2 Entering a Room. A conference MUST process events as described under XEP-0045 7.1 Order of Events except it MUST not send room history. When a subscriber is joined, a conference MUST stop sending subscription events and MUST switch to a regular groupchat protocol (as described in XEP-0045) until a subscriber leaves.
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#receiving-events","title":"Receiving events","text":"
    Here is as an example message received by a subscriber when a message is posted to a MUC room when subscriber is subscribed to node urn:xmpp:mucsub:nodes:messages:
     
    <message from=\"coven@muc.shakespeare.example\"\n         to=\"hag66@shakespeare.example/pda\">\n  <event xmlns=\"http://jabber.org/protocol/pubsub#event\">\n    <items node=\"urn:xmpp:mucsub:nodes:messages\">\n      <item id=\"18277869892147515942\">\n        <message from=\"coven@muc.shakespeare.example/secondwitch\"\n                 to=\"hag66@shakespeare.example/pda\"\n                 type=\"groupchat\"\n                 xmlns=\"jabber:client\">\n          <archived xmlns=\"urn:xmpp:mam:tmp\"\n                    by=\"muc.shakespeare.example\"\n                    id=\"1467896732929849\" />\n          <stanza-id xmlns=\"urn:xmpp:sid:0\"\n                     by=\"muc.shakespeare.example\"\n                     id=\"1467896732929849\" />\n          <body>Hello from the MUC room !</body>\n        </message>\n      </item>\n    </items>\n  </event>\n</message>\n
     
    Presence changes in the MUC room are received wrapped in the same way by subscribers which subscribed to node urn:xmpp:mucsub:nodes:presence:
     
    <message from=\"coven@muc.shakespeare.example\"\n         to=\"hag66@shakespeare.example/pda\">\n  <event xmlns=\"http://jabber.org/protocol/pubsub#event\">\n    <items node=\"urn:xmpp:mucsub:nodes:presences\">\n      <item id=\"8170705750417052518\">\n        <presence xmlns=\"jabber:client\"\n                  from=\"coven@muc.shakespeare.example/secondwitch\"\n                  type=\"unavailable\"\n                  to=\"hag66@shakespeare.example/pda\">\n          <x xmlns=\"http://jabber.org/protocol/muc#user\">\n            <item affiliation=\"none\"\n                  role=\"none\" />\n          </x>\n        </presence>\n      </item>\n    </items>\n  </event>\n</message>\n
     
    If subscriber is subscribed to node urn:xmpp:mucsub:nodes:subscribers, message will ne sent for every mucsub subscription change. When a user becomes a subscriber:
     
    <message from=\"coven@muc.shakespeare.example\"\n         to=\"hag66@shakespeare.example/pda\">\n   <event xmlns=\"http://jabber.org/protocol/pubsub#event\">\n     <items node=\"urn:xmpp:mucsub:nodes:subscribers\">\n       <item id=\"17895981155977588737\">\n         <subscribe xmlns=\"urn:xmpp:mucsub:0\"\n                    jid=\"bob@server.com\"\n                    nick=\"bob\"/>\n       </item>\n     </items>\n   </event>\n</message>\n
     
    When a user lost its subscription:
     
    <message from=\"coven@muc.shakespeare.example\"\n         to=\"hag66@shakespeare.example/pda\">\n   <event xmlns=\"http://jabber.org/protocol/pubsub#event\">\n     <items node=\"urn:xmpp:mucsub:nodes:subscribers\">\n       <item id=\"10776102417321261057\">\n         <unsubscribe xmlns=\"urn:xmpp:mucsub:0\"\n                      jid=\"bob@server.com\"\n                      nick=\"bob\"/>\n       </item>\n     </items>\n   </event>\n</message>\n
     
    Note: Sometimes jid in subscribe/unsubscribe event may be missing if room is set to anonymous and user is not moderator.
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#getting-list-of-subscribed-rooms","title":"Getting List of subscribed rooms","text":"
    A user can query the MUC service to get their list of subscriptions.
     
    Example: User asks for subscriptions list
     
    <iq from='hag66@shakespeare.example'\n    to='muc.shakespeare.example'\n    type='get'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscriptions xmlns='urn:xmpp:mucsub:0' />\n</iq>\n
     
    Example: Server replies with subscriptions list
     
    <iq from='muc.shakespeare.example'\n    to='hag66@shakespeare.example'\n    type='result'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscriptions xmlns='urn:xmpp:mucsub:0'>\n    <subscription nick='mynick'\n                  jid='coven@muc.shakespeare.example'>\n      <event node='urn:xmpp:mucsub:nodes:messages'/>\n      <event node='urn:xmpp:mucsub:nodes:affiliations'/>\n      <event node='urn:xmpp:mucsub:nodes:subject'/>\n      <event node='urn:xmpp:mucsub:nodes:config'/>\n    </subscription>\n    <subscription nick='MyNick'\n                  jid='chat@muc.shakespeare.example'>\n      <event node='urn:xmpp:mucsub:nodes:messages'/>\n    </subscription>\n  </subscriptions>\n</iq>\n
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#getting-list-of-subscribers-of-a-room","title":"Getting list of subscribers of a room","text":"
    A subscriber or room moderator can get the list of subscribers by sending <subscriptions/> request directly to the room JID.
     
    Example: Asks for subscribers list
     
    <iq from='hag66@shakespeare.example'\n    to='coven@muc.shakespeare.example'\n    type='get'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscriptions xmlns='urn:xmpp:mucsub:0' />\n</iq>\n
     
    Example: Server replies with subscribers list
     
    <iq from='coven@muc.shakespeare.example'\n    to='hag66@shakespeare.example'\n    type='result'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <subscriptions xmlns='urn:xmpp:mucsub:0'>\n    <subscription nick='Juliet'\n                  jid='juliet@shakespeare.example'>\n      <event node='urn:xmpp:mucsub:nodes:messages'/>\n      <event node='urn:xmpp:mucsub:nodes:affiliations'/>\n    </subscription>\n    <subscription nick='Romeo'\n                  jid='romeo@shakespeare.example'>\n      <event node='urn:xmpp:mucsub:nodes:messages'/>\n    </subscription>\n  </subscriptions>\n</iq>\n
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#compliance-with-existing-muc-clients","title":"Compliance with existing MUC clients","text":"
    MUC/Sub approach is compliant with existing MUC service and MUC clients. MUC clients compliant with XEP-0045 will receive messages posted by subscribers. They may not see the user's presence, but it should not be an issue for most clients. Most clients already support receiving messages from users that are not currently in the MUC room through history retrieval.
     
    This approach should also help most clients to support better integration with third-party services posting to MUC room through API (as )
     
    However, a server could choose to send presence on behalf of subscribers when a user joins the room (in the XEP-0045 sense) so that the subscriber will be shown in MUC roster of legacy clients.
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#synchronization-of-muc-messages-leveraging-mam-support","title":"Synchronization of MUC messages: Leveraging MAM support","text":"
    To be friendly with mobile, the MAM service should allow a user to connect and easily resync their history for all MUC subscriptions. For details about MAM, see XEP-0313 Message Archive Management and your software's documentation, for instance ejabberd's mod_mam.
     
    Thanks to ability to get the list of all the existing subscription, client can get a starting point to interact with MAM service to resync history and get the messages that were missed while the user was offline.
     
    If you subscribe to MucSub, MAM will add the message to your own user JID on new messages. You will simply be able to query them using your own JID from the standard MAM service.
     
    It means, you can get all new MUC message in subscribed room thanks to MucSub, with a single query. For example, if you ask for all messages sent since a specific date, the result will contain both normal chat and MucSub messages.
     
    You would only need to query MUC for MAM for rooms for which you do not use MucSub as with MucSub you will be \"delivered\" each message (in that case, each message is added your MAM archive).
    "},{"location":"developer/xmpp-clients-bots/extensions/muc-sub/#push-support-compliance","title":"Push support compliance","text":"
    Subscriptions are compliant with push mechanism. It is supported out of the box when using ProcessOne p1:push implementation (deployed on ejabberd SaaS for example).
     
    More generally, it is straightforward to handle them through ejabberd developer API to implement custom mechanisms.
     
    Subscriptions are delivered to online users. If the user has no active session, the server can choose to broadcast to the user through a push notification.
     
    When a session is opened, if the server detects that the user has not been recently active, or for any other reason, the server can still forward the message to a push notification service to warn the user that new messages are available in a MUC room.
    "},{"location":"developer/xmpp-clients-bots/extensions/roster-versioning/","title":"Roster versioning","text":"
    Roster versioning as implemented currently by ejabberd is a simplified approach to roster versioning.
     
    This is an all-or-nothing approach that does not support the granular diff as explained in RFC-6121.
     
    Our implementation conforms to version 0.6 of XEP-0237, sending the full roster in case of change or empty result if the roster did not change.
     
    As a result, as a client developer, when implementing support for roster versioning, you should expect both the traditional form for returning the roster, with version (iq result) and the incremental roster changes (iq set).
    "},{"location":"developer/xmpp-clients-bots/extensions/roster-versioning/#example","title":"Example","text":"
    As a summary, here is how you should expect it to work.
     
    First, you can check that the feature is advertised in the stream:features as urn:xmpp:features:rosterver:
     
    <stream:features>\n <bind xmlns=\"urn:ietf:params:xml:ns:xmpp-bind\"/>\n <session xmlns=\"urn:ietf:params:xml:ns:xmpp-session\">\n  <optional/>\n  </session>\n  <c xmlns=\"http://jabber.org/protocol/caps\" node=\"http://www.process-one.net/en/ejabberd/\" ver=\"/lmQr0llUEtX/pIt+6BDAbnIT/U=\" hash=\"sha-1\"/>\n  <sm xmlns=\"urn:xmpp:sm:2\"/>\n  <sm xmlns=\"urn:xmpp:sm:3\"/>\n  <ver xmlns=\"urn:xmpp:features:rosterver\"/>\n</stream:features>\n
     
    You can then bootstrap the use of roster versioning using empty ver attribute when sending your roster get iq:
     
    <iq id='roster1' to='myuser@domain.com' type='get'>\n <query xmlns='jabber:iq:roster' ver=''/>\n</iq>\n
     
    In return, you get a full roster with the current version:
     
    <iq from=\"myuser@domain.com\" type=\"result\" xml:lang=\"en\" to=\"myuser@domain.com/resource\" id=\"roster1\">\n <query xmlns=\"jabber:iq:roster\" ver=\"81cb523a7b77c7011552be85a3dde55189297590\">\n  <item subscription=\"both\" jid=\"contact@domain.com\">\n   <group>Test</group>\n  </item>\n  ...\n </query>\n</iq>\n
     
    The client can store this version to send subsequent roster queries.
     
    If client send a roster query with reference version it received get an empty iq result meaning the roster did not change:
     
    <iq id=\"roster2\" to=\"myuser@domain.com\" type=\"get\">\n <query xmlns='jabber:iq:roster' ver='81cb523a7b77c7011552be85a3dde55189297590'/>\n</iq>\n
     
    <iq from=\"myuser@domain.com\" type=\"result\" xml:lang=\"en\" to=\"myuser@domain.com/resource\" id=\"roster2\"/>\n
     
    If client send roster query with any other reference version, it will receive the full roster again in the roster iq result.
    "},{"location":"developer/xmpp-clients-bots/ios/getting-started-xmppframework/","title":"Getting Started with XMPPFramework","text":""},{"location":"developer/xmpp-clients-bots/ios/getting-started-xmppframework/#introduction","title":"Introduction","text":"
    XMPP development on smartphone has always been challenging given the constraints on mobile platform.
     
    This area will help you understand the challenges and help you get started with XMPP development on Apple iOS platform.
     
    The main library to support XMPP on iOS is XMPPFramework.
    "},{"location":"developer/xmpp-clients-bots/ios/getting-started-xmppframework/#xmppframework","title":"XMPPFramework","text":"
    XMPPFramework is a large framework relying on several dependencies. The easiest way to get started is to use Cocoapods to integrate XMPPFramework in your own project. It will take care of adding all dependencies and perform all the required configuration steps.
     
    Here are the steps needed to get started:
     
       
    1.  
      Create a new iOS project in Xcode, if you do not have one.
       
      2.  
    2.  
      If you do not yet have a Podfile, create it if pod init command    from the project root directory.
       
      3.  
    3.  
      Edit your Podfile to use XMPPFramework as a target. It may looks like:
       
      4.  
     
    platform :ios, '6.0'\nuse_frameworks!\n\ntarget 'projectname' do\n   pod 'XMPPFramework'\nend\n
     
       
    1.  
      Run pod install command. It should download, install and    configure three pods.
       
      2.  
    2.  
      Open your XCode project with the newly created workspace file    instead of the project file. This is required by Cocoapods so that    you can use the installed Pods.
       
      3.  
    3.  
      At this stage, you should be able to build your project    successfully with the XMPP framework setup.
       
      4.  
    "},{"location":"ejabberd-faq/","title":"Frequently Asked Questions","text":""},{"location":"ejabberd-faq/#development-process","title":"Development process","text":""},{"location":"ejabberd-faq/#why-is-there-a-commercial-version-of-ejabberd","title":"Why is there a commercial version of ejabberd?","text":"
    Different needs for different users. Corporations and large scale deployments are very different from smaller deployments and community projects.
     
    While we put a huge development effort to have a product that is on the edge of innovation with ejabberd community version, we are requested to provide a stable version with long term commitment and high level of quality, testing, audit, etc.
     
    Maintaining such a version in parallel to the community version, along with extremely strong commitment in terms of availability and 24/7 support has a tangible cost. With ejabberd business edition we commit to a level of scalability and optimize the software until it is performing to the level agreed with the customer.
     
    Covering all those costs, along with all our Research and Development cost on ejabberd community in general is the real reason we need a business edition.
     
    The business edition is also a way for our customers to share the code between our customers only, thus retaining a huge competitive edge for a limited time (See next section).
     
    So, even if you are not using our business edition, this is a great benefit for you as a user of the community edition and the reason you have seen so many improvements since 2002. Thanks to our business edition customers, ejabberd project itself is a major contributor to Erlang and Elixir community.
    "},{"location":"ejabberd-faq/#does-processone-voluntarily-hold-some-code-in-ejabberd-community-to-push-toward-the-business-edition","title":"Does ProcessOne voluntarily hold some code in ejabberd community to push toward the business edition?","text":"
    No. We never do that and have no plan doing so with the code we produce and we own.
     
    However, when the code is paid by customer, they retain the ownership of the code. Part of our agreement is that the code produced for them will be limited to a restricted user base, ejabberd business edition until an agreed time expires, generally between 6 months and 1 year.
     
    This is extremely important for both the users of the commercial edition and the users of the community edition:
     
       
    •  
      For the business edition customers, this is a way to keep their business advantage. This is   fair as they paid for the development.
       
      •  
    •  
      This is also a great incentive for our customers as they benefit from   development for other customers (I guess they agree for the   reciprocal sharing of their own code with customers).
       
      •  
    •  
      This is fair for the community as the community edition users know   they will benefit from new extremely advanced features in a relatively near future.    For example, websocket module was contributed to   ejabberd community as part of this process.
       
      •  
     
    This is the model we have found to be fair to our broader user base and lets us produce an amazing code base that benefits all our users.
     
    This dual model is the core strength of our approach and our secret sauce to make sure everyone benefits.
    "},{"location":"ejabberd-faq/#performance","title":"Performance","text":""},{"location":"ejabberd-faq/#is-ejabberd-the-most-scalable-version","title":"Is ejabberd the most scalable version?","text":"
    Yes. Definitely. Despite claims that there is small change you can make to make it more scalable, we already performed the changes during the past year, that make those claims unfunded:
     
       
    •  
      ejabberd reduced memory consumption in 2013 by switching to binary   representation of string instead of list. This can reduce given   string by 8.
       
      •  
    •  
      We have improved the C code performance a lot, using new Erlang   NIF. This provides better performance, removes bottlenecks
       
      •  
    •  
      We have a different clustering mechanism available to make sure we can   scale to large clusters
       
      •  
     
    This is a common misconception, but our feedback for production service on various customer sites shows that ejabberd is the most scalable version. Once it is properly configured, optimized and tuned, you can handle tens of millions of users on ejabberd systems.
     
    ... And we are still improving :)
     
    As a reference, you should read the following blog post: ejabberd Massive Scalability: 1 Node \u2014 2+ Million Concurrent Users
    "},{"location":"ejabberd-faq/#what-are-the-tips-to-optimize-performance","title":"What are the tips to optimize performance?","text":"
    Optimisation of XMPP servers performance, including ejabberd, is highly dependent on the use case. You really need to find your bottleneck(s) by monitoring the process queues, finding out what is your limiting factor, tune that and then move to the next one.
     
    The first step is to make sure you run the latest ejabberd. Each new release comes with a bunch of optimisations and a specific bottleneck you are facing may have gone away in the latest version.
     
    For perspective, ejabberd 15.07 is 2 to 3 times more efficient in memory, latency and CPU compared to ejabberd 2.1.
     
    You should also make sure that you are using the latest Erlang version. Each release of Erlang comes with more optimisation regarding locks, especially on SMP servers, and using the latest Erlang version can also help tremendously.
    "},{"location":"ejabberd-faq/#erlang-support","title":"Erlang support","text":""},{"location":"ejabberd-faq/#is-ejabberd-conforming-to-the-best-erlang-practices","title":"Is ejabberd conforming to the best Erlang practices?","text":"
    Yes. Our build system is primarily based on rebar. However, as we are multiplatform and need to run in many various environments, we rely on a toolchain that can detect required library dependencies using autotools.
     
    This gives developers and admins the best of both worlds. A very flexible and very versatile build chain, that is very adequate to make sure ejabberd can be used in most operating systems and even integrated in Linux distributions.
    "},{"location":"get-started/","title":"Getting started \ud83d\udc4b","text":""},{"location":"get-started/#meet-ejabberd-your-superpowerful-messaging-framework","title":"Meet ejabberd, your superpowerful messaging framework","text":"
    This web site is dedicated to help you use and develop for ejabberd XMPP messaging server.
     
    ejabberd has been in development since 2002 and is used all over the world to power the largest XMPP deployments. This project is so versatile that you can deploy it and customize it for very large scale, no matter what your use case is.
     
    This incredible power comes with a price. You need to learn how to leverage it. Fortunately, the goal of this website is to get you started on your path to mastery. Whether you are a sysadmin, an architect, a developer planning to extend it, or even a simple XMPP user, we have something for you here.
    "},{"location":"get-started/#overview","title":"Overview","text":"
    ejabberd is the de facto XMPP server in the world. The fact that it is used to power the largest deployments in the world should not intimidate you. ejabberd is equally suitable for small instances.
     
    ejabberd has been designed from the ground-up, since 2002 for robust, enterprise deployment. The goal has always been to shoot for the moon and this is what made it a long-lasting success.
     
    ejabberd is specifically designed for enterprise purposes: it is fault-tolerant, can utilise the resources of multiple clustered machines, and can easily scale when more capacity is required (by just adding a box/VM).
     
    Designed at a moment when clients were mostly desktops that only supported a kind of HTTP polling call BOSH, the project managed to adapt to recent changes by introducing support for WebSockets, BOSH improvements, and a solid mobile  stack.
     
    It was developed at a time when XMPP was still known as \"Jabber\", but quickly adopted an evolution process in order to support the various versions of XMPP RFCs. It now encourages innovation and experimentation by supporting most, if not all, extensions produced by the XSF.
     
    ejabberd relies on a dynamic community all over the world. To get an idea of existing contributions, you can check ejabberd main repository or the repository containing a great amount of contributed extensions.
     
    This is possible thanks to a modular architecture based on a core router and an extremely powerful plugin mechanism that is getting richer every day.
     
    Welcome to the beginning of your journey of ejabberd mastery!
    "},{"location":"get-started/#options-to-use-ejabberd","title":"Options to use ejabberd","text":"
    ejabberd can be used in different ways. The most common one is to use ejabberd Community Edition. This is the standard Open Source version that everyone loves: highly scalable and flexible.
     
    Fortunately, if you need more than just the ejabberd platform software, ProcessOne can help you with a commercial offering. Commercial offering come in two type of packaging:
     
       
    •  
      ejabberd Business Edition, including features for large companies   (enhanced geodistributed companies and mobile support to develop   own, rich clients) and world-class support, that can please even the   most demanding businesses, with 24/7 options.
       
      •  
    •  
      Fluux.io being a way to access and benefit of all the features   of ejabberd Business Edition at an attractive and scalable   price. Fluux.io allows you to keep control of your data thanks   to integration API you can implement on your backend to become a   data provider for ejabberd SaaS.
       
      •  
     
    Whatever approach you choose, you can hardly make the wrong choice with ejabberd! In every case you can easily integrate ejabberd with your existing application using:
     
       
    • REST API and ejabberdctl command-line tool
      •  
    • Mobile libraries for iOS: XMPPFramework, Jayme REST API
      •  
    • Mobile libraries for Android: Smack, Retrofit
      •  
    • Web library with WebSocket support and fallback to BOSH: Strophe
      •  
    "},{"location":"get-started/#architecture-of-an-ejabberd-service","title":"Architecture of an ejabberd service","text":"
    ejabberd brings configurability, scalability and fault-tolerance to the core feature of XMPP \u2013 routing messages.
     
    Its architecture is based on a set of pluggable modules that enable different features, including:
     
       
    • One-to-one messaging
      •  
    • Store-and-forward (offline messages)
      •  
    • Contact list (roster) and presence
      •  
    • Groupchat: MUC (Multi-User Chat)
      •  
    • Messaging archiving with Message Archive Management (MAM)
      •  
    • User presence extension: Personal Event Protocol (PEP) and typing indicator
      •  
    • Privacy settings, through privacy list and simple blocking extensions
      •  
    • User profile with vCards
      •  
    • Full feature web support, with BOSH and websockets
      •  
    • Stream management for message reliability on mobile (aka XEP-0198)
      •  
    • Message Delivery Receipts (aka XEP-184)
      •  
    • Last activity
      •  
    • Metrics and full command-line administration
      •  
    • and many many more.
      •  
     
    The full list of supported protocol and extensions is available on Protocols Supported by ejabberd page.
     
    This modular architecture allows high customisability and easy access to the required features.
     
    ejabberd enables authenticating users using external or internal databases (Mnesia, SQL), LDAP or external scripts. It also allows connecting anonymous users, when required.
     
    For storing persistent data, ejabberd uses Mnesia (the distributed internal Erlang database), but you can opt for SQL database like MySQL or PostgreSQL
     
    And of course, thanks to its API, ejabberd can be customised to work with a database chosen by the customer.
    "},{"location":"get-started/#deploying-and-managing-an-ejabberd-service","title":"Deploying and managing an ejabberd service","text":"
    ejabberd can be deployed for a number of scenarios fitting end-user / developer / customer needs. The default installation setup consists of a single ejabberd node using Mnesia, so it does not require any additional configuration. This primary system is sufficient for fast deployment and connecting XMPP clients. It should be good enough for most of the small deployments (and even medium ones).
     
    A more scalable solution would be deploying ejabberd with an external database for persistent data. As Mnesia is caching part of its data in ejabberd memory (actually in Erlang VM node), this kind of setup make your system more scalable and typically easier to integrate with your usual database. As a sysadmin, yes, you can use your standard backup process.
     
    Those larger setup can run as a cluster of ejabberd nodes. This is a clustering mode where all nodes are active, so it can be use for fault-tolerance, but also to increase the capacity of your ejabberd deployment.
     
    With such a deployment you can load balance the traffic to your cluster node using one of the following solution:
     
       
    • traditional TCP/IP load balancer (beware of the cost of your solution, typical XMPP connections are persistent).
      •  
    • DNS load balancing.
      •  
    • Custom approach that requires client cooperation.
      •  
     
    If deployed on a 16 GB RAM machine with at least 4 cores, a single ejabberd node can typically handle 200-300 K online users. This setup is suitable for systems with up to 10 nodes.
     
    Note that your mileage may vary depending on your use case, the feature your are using and how clean the architecture design and the client is developed. That's why, if you plan to reach huge volume, it is recommended to start asking advices from day 1 to an ejabberd expert. Initial mistakes in the solution design are harder to fix once the project is in production.
     
    If the service requires a cluster of more than 10 nodes, we recommend not relying on Mnesia clustering mode. Many solutions are available, the easiest and more inexpensive being to rely on ejabberd Software-as-a-Service approach.
     
    ejabberd also allows connecting different clusters as parts of larger systems. This is a standard XMPP feature call server-to-server (aka s2s in XMPP lingo). It is used in geo-localised services handling massive traffic from all over the world. Special extension are also available from ProcessOne to handle geodistribution in an even more robust way.
     
    To manage the users, rosters, messages and general settings, we provide a command-line tool, ejabberdctl. That command-line allows you to gather metrics from ejabberd to be able to monitor what is happening in your system, understand and even anticipate issues.
     
    The main benefit of ejabberd is the ability to reach a command-line to type Erlang commands. This allows you to fix and troubleshoot most of the tricky situation and even update and reload code without stopping the service. This is a life saver for your uptime.
     
    Welcome to the benefit of Erlang hot-code swapping!
    "},{"location":"get-started/#ejabberd-is-more-than-xmpp","title":"ejabberd is more than XMPP","text":"
    Thanks to the modular architecture of ejabberd, the platform is becoming a core component for messaging applications.
     
    Messaging applications require to transfer more than text messages. ejabberd has grow a full set of media related features that makes ejabberd a great choice to support voice and video applications, but also to proxy various kind of media transfer (images, audio and video files for example).
     
    As such, ejabberd support:
     
       
    • Jingle, XMPP based voice protocol
      •  
    • SIP (Session Initiation Protocol): Yes, you can pass SIP calls using ejabberd :)
      •  
    • ICE (Interactive Connectivity Establishment: A Protocol for Network Address Translator (NAT) Traversal)
      •  
    • STUN
      •  
    • TURN
      •  
    • Proxy65 media relay
      •  
     
    This makes ejabberd the best XMPP server to support SIP and WebRTC based communication tools.
    "},{"location":"get-started/#helping-us-in-the-development-process","title":"Helping us in the development process","text":"
    With thousands of more or less official forks, the core ejabberd team, supported by ProcessOne, is constantly monitoring and reviewing improvements.  We use our 15 years of experience to filter the best ideas or improvements to make sure ejabberd is always your most solid choice in term of scalability, robustness and manageability.
     
    The best way to start developing for ejabberd is to clone, watch and star the project, to get in touch on our developer chatroom (ejabberd@conference.process-one.net) or to join ejabberd community on StackOverflow.
    "},{"location":"livebooks/ejabberd-developer-livebook/","title":"The ejabberd Developer Livebook","text":"
    Info
     
    This page is designed to run interactively using Livebook. Of course, you could simply reproduce the instructions manually yourself. But, if possible, install Livebook in your machine and get the full experience clicking on the button:
     
     
    filename = \"ejabberd.yml\"\n\nif File.exists?(filename) do\n  Mix.install([\n    {:ejabberd, \"~> 24.2\"},\n    {:kino, \"~> 0.12.3\"}\n  ])\nelse\n  url = \"https://raw.githubusercontent.com/processone/ejabberd/master/ejabberd.yml.example\"\n\n  Mix.install([:req]) &&\n    File.write!(\n      filename,\n      String.replace(Req.get!(url).body, \"starttls_required: true\", \"\")\n    )\n\n  IO.puts(\"ejabberd.yml downloaded correctly, click 'Reconnect and setup' to download ejabberd.\")\nend\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#setup-ejabberd-inside-livebook","title":"Setup ejabberd inside livebook","text":"
    This Livebook will download, compile and install ejabberd:
     
       
    1.  
      If you want to use a specific ejabberd.yml configuration file, copy it to your Livebook folder.
       
      2.  
    2.  
      On top of this page, click Setup.
       
      3.  
    3.  
      If ejabberd.yml is not found, it will be downloaded from ejabberd git repository.
       
      4.  
    4.  
      Click Reconnect and setup to download ejabberd and all its dependencies. It will be compiled and started... it may take a pair of minutes.
       
      5.  
     
    Alternatively, if you already have ejabberd installed and running in your system, you can connect livebook to your ejabberd node
    "},{"location":"livebooks/ejabberd-developer-livebook/#execute-some-erlang-code","title":"Execute some Erlang code","text":"
    Now that Livebook is connected a running ejabberd node, you can run Erlang and Elixir code from this page directly in your node.
     
    For example, to run some erlang code, put your mouse over the new lines and click on Evaluate:
     
    ejabberd_admin:registered_vhosts().\n
     
    Let's define the details of an account, we will later register it. You may change those values:
     
    Username = <<\"user1\">>,\nServer = <<\"localhost\">>,\nPassword = <<\"somepass123\">>,\n{Username, Server, Password}.\n
     
    Now let's execute an Erlang function to register the account:
     
    ejabberd_auth:try_register(Username, Server, Password).\n
     
    Let's check the account was registered:
     
    ejabberd_auth:get_users(<<\"localhost\">>).\n
     
    And is the account's password the one we introduced?
     
    Password == ejabberd_auth:get_password(Username, Server).\n
     
    Ok, enough for now, let's remove the account:
     
    ejabberd_auth:remove_user(Username, Server).\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#execute-some-elixir-code","title":"Execute some Elixir code","text":"
    The same code of the previous section can be executed using Elixir:
     
    :ejabberd_admin.registered_vhosts()\n
     
    username = <<\"user1\">>\nserver = <<\"localhost\">>\npassword = <<\"somepass123\">>\n{username, server, password}\n
     
    :ejabberd_auth.try_register(username, server, password)\n
     
    :ejabberd_auth.get_users(server)\n
     
    password == :ejabberd_auth.get_password(username, server)\n
     
    :ejabberd_auth.remove_user(username, server)\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#run-api-commands","title":"Run API commands","text":"
    Let's run some ejabberd API commands using the ejabberd_ctl frontend (there is is also mod_http_api and ejabberd_xmlrpc).
     
    For example, the status API command:
     
    ejabberd_ctl:process([\"status\"]).\n
     
    How to register an account using ejabberd_ctl to call the API command
     
    command = ~c\"register\"\n:ejabberd_ctl.process([command, username, server, password])\n
     
    If you have ejabberd installed in the the system, and the ejabberdctl command-line script is available in your PATH, then you could also try to execute with:
     
    os:cmd(\"ejabberdctl status\").\n
     
    :os.cmd(~c\"ejabberdctl status\")\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#draw-process-structure","title":"Draw process structure","text":"
    Let's view the ejabberd process tree:
     
    Kino.Process.render_app_tree(:ejabberd, direction: :left_right)\n
     
    Let's view the erlang processes that handle XMPP client connections. If this graph is empty, login to ejabberd with a client and reevaluate this code:
     
    Kino.Process.render_sup_tree(:ejabberd_c2s_sup, direction: :left_right)\n
     
    And some information about the erlang process that handles the XMPP client session:
     
    [resource] = :ejabberd_sm.get_user_resources(username, server)\nElixir.Process.info(:ejabberd_sm.get_session_pid(username, server, resource))\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#connect-livebook-to-your-ejabberd-node","title":"Connect Livebook to your ejabberd node","text":"
    By default this livebook downloads, compiles and starts ejabberd by setting up ejabberd sinde livebook. If you already have ejabberd installed and would like to connect this livebook to your existing ejabberd node, follow those steps:
    "},{"location":"livebooks/ejabberd-developer-livebook/#get-erlang-node-name","title":"Get erlang node name","text":"
    To connect Livebook to your running ejabberd node, you must know its erlang node name and its cookie.
     
    The erlang node name is by default ejabberd@localhost. You can check this in many places, for example:
     
       
    • Using ejabberdctl status:
      •  
     
    $ ejabberdctl status\nThe node ejabberd@localhost is started with status: started\nejabberd 24.2.52 is running in that node\n
     
       
    • In the ejabberd.log file, which contains a line like:
      •  
     
    2024-03-26 13:18:35.019288+01:00 [info] <0.216.0>@ejabberd_app:start/2:63\nejabberd 24.2.52 is started in the node ejabberd@localhost in 0.91s\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#setup-ejabberd-node","title":"Setup ejabberd node","text":"
    A Livebook can only connect to an Erlang node that has Elixir support. So, make sure you install not only Erlang, but also Elixir.
     
    When compiling ejabberd, make sure to enable Elixir support. It should get enabled by default, but you can ensure this: either by ./configure --with-rebar=mix or by ./configure --enable-elixir.
     
    Then start ejabberd with IEx shell: ejabberdctl iexlive
    "},{"location":"livebooks/ejabberd-developer-livebook/#get-erlang-cookie","title":"Get erlang cookie","text":"
    The erlang cookie is a random string of capital letters required to connect to an existing erlang node.
     
    You can get it in a running node, simply call:
     
    :erlang.get_cookie()\n:XQFOPGGPSNEZNUWKRZJU\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#connect-this-livebook-to-your-ejabberd-node","title":"Connect this livebook to your ejabberd node","text":"
    Now that you have ejabberd running, and you know the information required to connect to it:
     
       
    1. go to Livebook
      2.  
    2. in the left side bar, click the Runtime settings icon, or press sr keyboard shortcut
      3.  
    3. click the Configure button
      4.  
    4. click the Attached node button
      5.  
    5. introduce the erlang node name (ejabberd@localhost) and cookie (XQFOPGGPSNEZNUWKRZJU) of your ejabberd node
      6.  
    6. click the Connect button (it may say Reconnect)
      7.  
    7. If it connected successfully, it will now show memory consumption of that node
      8.  
    "},{"location":"livebooks/ejabberd-developer-livebook/#test-the-connection","title":"Test the connection","text":"
    Now that Livebook is connected to your running ejabberd node, you can run Erlang and Elixir code from this page directly in your node.
     
    For example, to run some erlang code, put your mouse over the new lines and click on Evaluate:
     
    ejabberd_admin:registered_vhosts().\n
     
    The same code can be executed using Elixir:
     
    :ejabberd_admin.registered_vhosts()\n
    "},{"location":"livebooks/ejabberd-developer-livebook/#stop-ejabberd","title":"Stop ejabberd","text":"
    Let' stop ejabberd insie livebook
     
    :ejabberd.stop()\n
    "},{"location":"roadmap/","title":"ejabberd Roadmap","text":""},{"location":"roadmap/#in-the-works","title":"In the Works","text":"
       
    •  
      Rework ejabberd Docs
       
      The ejabberd Docs site needs some reorganization, as some sections has grown quite a lot and would better be reorganized.
       
      •  
    "},{"location":"roadmap/#planned","title":"Planned","text":"
       
    •  
      Set as default automatic SQL schema update
       
      Automatic SQL schema update was included as a beta-testing feature in ejabberd 23.10 (see the feature announcement), and it will become the default. 
       
      •  
    •  
      Remove support for Rebar2
       
      ejabberd includes many tweaks to support rebar3 and rebar2. By removing support for rebar2, we could simplify rebar.config and other files a lot. But more importantly, dependencies would not need to be updated just because other dependencies are updated: Rebar2 requires exact version numbers to be provided, Rebar3 doesn't require that, and neither does Mix.
       
      •  
    "},{"location":"roadmap/#released","title":"Released","text":""},{"location":"roadmap/#2024","title":"2024","text":"
       
    • 24.02
         
      • Matrix gateway
        •  
      • RFC 9266 Channel Bindings for TLS 1.3
        •  
      • XEP-0386: Bind 2
        •  
      • XEP-0388: Extensible SASL Profile (SASL2)
        •  
      • XEP-0424: Message Retraction
        •  
      • XEP-0440: SASL Channel-Binding Type Capability
        •  
      • XEP-0474: SASL SCRAM Downgrade Protection
        •  
      • XEP-0480: SASL Upgrade Tasks
        •  
      • Automatic SQL schema creation and update
        •  
      • Commands API versioning
        •  
      • Support Elixir 1.16 and Erlang/OTP 27.0-rc1
        •  
       
      •  
    "},{"location":"roadmap/#2023","title":"2023","text":"
       
    •  
      23.10
       
         
      • Support for XEP-0402: PEP Native Bookmarks
        •  
      • Support for XEP-0421: Occupant Id
        •  
      • MySQL Performance enhancements
        •  
       
      •  
    •  
      23.04
       
         
      • mod_mam support for XEP-0425: Message Moderation
        •  
      • New mod_muc_rtbl: Real-Time Block List for MUC rooms
        •  
      • Binaries use Erlang/OTP 25.3, and changes in containers
        •  
       
      •  
    •  
      23.01
       
         
      • New mod_mqtt_bridge: MQTT bridge
        •  
       
      •  
    "},{"location":"roadmap/#2022","title":"2022","text":"
       
    •  
      22.10
       
         
      • Improved MIX support
        •  
      • Improved SQL reconnection Mechanism
        •  
      • Better burst traffix handling
        •  
       
      •  
    •  
      22.05
       
         
      • Improved MQTT, MUC and ConverseJS integration
        •  
      • New installers and container image
        •  
      • Support for Erlang/OTP 25
        •  
       
      •  
    "},{"location":"roadmap/#2021","title":"2021","text":"
       
    •  
      21.12
       
         
      • New mod_conversejs: built-in ConverseJS web client
        •  
      • Support for MUC Hats extension
        •  
      • PubSub, MucSub and Multicast improvements
        •  
       
      •  
    •  
      21.07
       
         
      • Improved database and caching for shared rosters
        •  
      • Broader multicast support for MUC
        •  
      • Improved rebar3 and Elixir support
        •  
       
      •  
    •  
      21.04
       
         
      • Full support for Erlang/OTP 24 and rebar3
        •  
      • New API commands
        •  
      • New CAPTCHA script
        •  
       
      •  
    •  
      21.01
       
         
      • Systemd watchdog support
        •  
      • STUN improvements
        •  
       
      •  
    "},{"location":"roadmap/#2020","title":"2020","text":"
       
    •  
      20.12
       
         
      • Extended SCRAM-SHA support
        •  
      • Microsoft ODBC Driver support
        •  
       
      •  
    •  
      20.07
       
         
      • Support for Unix Domain Sockets
        •  
      • Erlang/OTP 23 compatibility
        •  
       
      •  
    •  
      20.04
       
         
      • New mod_stun_disco: support XEP-0215 including Audio/Video calls
        •  
      • Improved MS SQL support
        •  
       
      •  
    •  
      20.03
       
         
      • SSL connection to MySQL
        •  
      • Improved performance of mod_shared_roster
        •  
       
      •  
    •  
      20.02
       
         
      • Improved compatibility with CockroachDB
        •  
      • Emoji storage in MSSQL
        •  
       
      •  
    •  
      20.01
       
         
      • OAuth support for ejabberd's MQTT
        •  
      • New OTP 22 event logger
        •  
      • New config parser & validator
        •  
       
      •  
    "},{"location":"roadmap/#2019","title":"2019","text":"
       
    •  
      19.09
       
         
      • Significant improvements in ACME support: ACME v2
        •  
      • Erlang/OTP 19.3 is required
        •  
       
      •  
    •  
      19.08
       
         
      • New JWT (JSON Web Token) authentication
        •  
      • New configuration validator, yconf
        •  
      • Improved MUC scalability
        •  
      • Removed Riak support
        •  
       
      •  
    •  
      19.05
       
         
      • MQTT over WebSocket
        •  
      • Improved MucSub
        •  
      • Erlang/OTP 19.1 is required
        •  
       
      •  
    •  
      19.02
       
         
      • MQTT Support
        •  
      • MIX improvements
        •  
       
      •  
    "},{"location":"roadmap/#2018","title":"2018","text":"
       
    •  
      18.12
       
         
      • XML Compression in message archive storage
        •  
      • PROXY protocol support versions 1 and 2
        •  
      • MUC Self-Ping server optimisation (XEP-0410)
        •  
      • Bookmarks Conversion (XEP-0411)
        •  
       
      •  
    •  
      18.09
       
         
      • Default configuration file simplification
        •  
      • Improved logging
        •  
      • OpenSSL 1.1.1 support
        •  
      • Modular ejabberd core
        •  
       
      •  
    •  
      18.06
       
         
      • Stop ejabberd initialization on invalid/unknown options
        •  
      • Support SASL PLAIN
        •  
      • Drop support of mod_irc
        •  
       
      •  
    •  
      18.04
       
      •  
    •  
      18.03
       
         
      • New SQL schemas with server_host
        •  
       
      •  
    •  
      18.01
       
      •  
    "},{"location":"roadmap/#2017","title":"2017","text":"
       
    •  
      17.12
       
         
      • SNI (Server Name Indication) for inbound connections
        •  
      • Rewrite ejabberd system monitor
        •  
      • Support PubSub v1.14 and OMEMO
        •  
       
      •  
    •  
      17.11
       
         
      • ACME Support
        •  
      • Introduce \u2018certfiles\u2019 global option
        •  
      • PubSub improved, and SQL storage
        •  
       
      •  
    •  
      17.09
       
         
      • New mod_avatar
        •  
      • SRV for XMPP over TLS
        •  
       
      •  
    •  
      17.08
       
         
      • XEP-0357: Push Notifications
        •  
      • Modular cluster with cluster_backend
        •  
       
      •  
    •  
      17.07
       
      •  
    •  
      17.06
       
         
      • New Caching system
        •  
      • Extended Riak support
        •  
      • Certificate manager
        •  
       
      •  
    •  
      17.04
       
      •  
    •  
      17.03
       
         
      • Modular code
        •  
      • Dynamic configuration reload
        •  
      • mod_blockstrangers for spam protection
        •  
      • S2S dialback
        •  
       
      •  
    •  
      17.01
       
         
      • PostgreSQL SSL support
        •  
       
      •  
    "},{"location":"roadmap/#2016","title":"2016","text":"
       
    •  
      16.12
       
         
      • New BOSH module
        •  
      • New Commands API permissions framework
        •  
      • XMPP packet handling using dedicated xmpp erlang library
        •  
      • New ejaberd/mix Docker container
        •  
       
      •  
    •  
      16.09
       
         
      • Support for Elixir configuration file
        •  
      • XEP-0355 Namespace Delegation
        •  
      • XEP-0356 Privileged Entity
        •  
       
      •  
    •  
      16.08
       
         
      • New MUC/Sub
        •  
      • Improved Elixir support
        •  
      • Major clean-up and improvement on OAuth ReST API
        •  
       
      •  
    •  
      16.06
       
         
      • New ACL (Access Control List) infrastructure
        •  
       
      •  
    •  
      16.04
       
      •  
    •  
      16.03
       
         
      • Experimental support for MIX (Mediated Information eXchange)
        •  
      • Erlang/OTP 17.5 required
        •  
       
      •  
    •  
      16.02
       
         
      • XEP-0013 Flexible Offline Message Retrieval
        •  
      • Improved Message Archive Management (MAM)
        •  
      • Published ejabberd on hex.pm
        •  
      • Faster and more memory efficient XML parsing and TLS encryption.
        •  
      • Stream compression after SASL
        •  
      • Migration script from Prosody
        •  
       
      •  
    •  
      16.01
       
      •  
    "},{"location":"roadmap/#2015","title":"2015","text":"
       
    •  
      15.11
       
         
      • Improved join_cluster and leave_cluster
        •  
       
      •  
    •  
      15.10
       
         
      • New mod_http_upload with support for XEP-0363 HTTP File Upload
        •  
      • Added support for Grapherl
        •  
       
      •  
    •  
      15.09
       
         
      • OAuth 2.0 delegation framework
        •  
      • Preliminary OAuth and HTTP based ejabberd API
        •  
      • X-AUTH2 authentication mechanism
        •  
       
      •  
    •  
      15.07
       
      •  
    •  
      15.06
       
         
      • New mod_mam with XEP-0313 Message Archive Management
        •  
      • Configuration checking on launch
        •  
      • Added Windows 7/8 installers, RPM and DEB packages
        •  
      • Document protocol support and version inside each module
        •  
       
      •  
    •  
      15.04
       
         
      • Added mod_admin_extra and mod_muc_admin
        •  
      • Added XEP-0033 Extended Stanza Addressing
        •  
      • Support to embed ejabberd in an Elixir app
        •  
      • Erlang/OTP R16B03-1 is required
        •  
       
      •  
    •  
      15.03
       
         
      • Added support for WebSocket
        •  
      • Customizable session backends
        •  
      • SCRAM support for SQL authentication backend
        •  
      • Documentation was converted from LaTeX to Markdown and published in docs.ejabberd.im/
        •  
       
      •  
    •  
      15.02
       
         
      • Added Elixir support
        •  
      • New command to reload configuration withour restart
        •  
      • Bug tracker moves from JIRA to GitHub Issues
        •  
       
      •  
    •  
      Revamped ejabberd website, new logo, new development process and bugtracking migrated from JIRA to GitHub
       
      •  
    "},{"location":"roadmap/#2014","title":"2014","text":"
       
    •  
      14.12
       
         
      • New mod_client_state with XEP-0352: Client State Indication
        •  
      • New mod_fail2ban
        •  
       
      •  
    •  
      14.07
       
         
      • SIP Outbound (RFC 5626)
        •  
       
      •  
    •  
      14.05
       
         
      • RFC-3261 SIP proxy/registrar
        •  
      • RFC-5766 TURN: Traversal Using Relays around NAT
        •  
      • XEP-0198 Stream Management
        •  
      • XEP-0321 Remote Roster Management
        •  
      • Several improvements regarding encryption
        •  
      • New Bash completion script for ejabberdctl
        •  
       
      •  
    "},{"location":"roadmap/#2013","title":"2013","text":"
       
    •  
      13.12
       
         
      • New OpenSSL ciphers option in c2s, s2s and s2s_out
        •  
      • ejabberd_xmlrpc included
        •  
       
      •  
    •  
      13.10
       
         
      • ejabberd configuration file in YAML format
        •  
      • Log files are created using Lager
        •  
      • Rebar2 is used to manage dependencies
        •  
      • Erlang/OTP R15 is required
        •  
       
      •  
    •  
      13.03-beta1 (announcement)
       
         
      • Binarize and indent code
        •  
      • New versioning scheme
        •  
       
      •  
    "},{"location":"roadmap/#2012","title":"2012","text":"
       
    • 2.1.11
         
      • Added ODBC support for several modules
        •  
       
      •  
    "},{"location":"roadmap/#2011","title":"2011","text":"
       
    •  
      2.1.10
       
      •  
    •  
      2.1.9
       
         
      • New SASL SCRAM-SHA-1 authentication mechanism
        •  
       
      •  
    "},{"location":"roadmap/#2010","title":"2010","text":"
       
    •  
      2.1.6
       
         
      • mod_register: New captcha_protected option to require CAPTCHA
        •  
      • Support PostgreSQL 9.0
        •  
       
      •  
    •  
      October: the source code repository and the bug tracker were finally moved to GitHub
       
      •  
    •  
      2.1.5
       
      •  
    •  
      2.1.4
       
         
      • Full support for XEP-0115 Entity Capabilities v1.5
        •  
       
      •  
    •  
      2.1.2
       
      •  
    "},{"location":"roadmap/#2009","title":"2009","text":"
       
    •  
      2.1.1
       
      •  
    •  
      2.1.0
       
         
      • LDAPS support
        •  
      • STUN server
        •  
      • New XEPs supported: XMPP Ping, Roster Versioning, Import/Export Format
        •  
      • Erlang/OTP R13 is supported
        •  
       
      •  
    •  
      2.0.5 (announcement)
       
      •  
    •  
      2.0.4 (announcement)
       
      •  
    •  
      2.0.3 (announcement)
       
      •  
    "},{"location":"roadmap/#2008","title":"2008","text":"
       
    •  
      2.0.2 (announcement)
       
      •  
    •  
      2.0.1 (announcement)
       
      •  
    •  
      2.0.0 (announcement)
       
         
      • New front-end and back-end cluster architecture
        •  
      • Complete rewrite of the PubSub module
        •  
      • New Proxy65 file transfer proxy
        •  
      • BOSH support
        •  
      • Many more improvements
        •  
       
      •  
    "},{"location":"roadmap/#2007","title":"2007","text":"
       
    •  
      1.1.4
       
      •  
    •  
      1.1.3
       
      •  
    "},{"location":"roadmap/#2006","title":"2006","text":"
       
    •  
      1.1.2 (announcement)
       
         
      • LDAP improvements
        •  
      • Microsoft SQL supported
        •  
      • New Windows installer
        •  
       
      •  
    •  
      1.1.1 (announcement)
       
         
      • Erlang/OTP R9C-2 required
        •  
       
      •  
    •  
      1.1.0 (announcement)
       
         
      • JEP-0050: Ad-Hoc Commands
        •  
      • JEP-0138: Stream Compression
        •  
      • JEP-0175: SASL anonymous
        •  
      • Native MySQL support
        •  
      • MUC improvement: Chatroom logging
        •  
       
      •  
    "},{"location":"roadmap/#2005","title":"2005","text":"
       
    •  
      1.0.0 (announcement)
       
         
      • S2S encryption: STARTTLS + SASL_EXTERNAL and STARTTLS + Dialback
        •  
      • Different certificates can be defined for each virtual host.
        •  
      • Support for vCard storage in ODBC
        •  
      • New tool to convert Mnesia to ODBC
        •  
      • Native PostgreSQL support
        •  
       
      •  
    •  
      0.9.8 (announcement)
       
         
      • Enhanced virtual hosting
        •  
      • Enhanced PubSub
        •  
       
      •  
    •  
      0.9.1 (announcement)
       
      •  
    •  
      0.9 (announcement)
       
         
      • Added support for virtual hosts
        •  
      • New mod_shared_roster
        •  
      • Added PostgreSQL support
        •  
       
      •  
    •  
      February: source code moved from SVN to Git, and the bug tracker from Bugzilla to JIRA
       
      •  
    •  
      Beginning of 2005, source code moved from JabberStudio CVS to ProcessOne SVN
       
      •  
    "},{"location":"roadmap/#2004","title":"2004","text":"
       
    •  
      October: website moved from JabberStudio to ejabberd.jabber.ru, and the bug tracker to Jabber.ru\u2019s Bugzilla
       
      •  
    •  
      0.7.5
       
         
      • Support for STARTTLS with C2S connections
        •  
      • Support for authentification via external script
        •  
      • Added module which implement JUD and vCard services using LDAP
        •  
      • Improvements in web-based administration interface (user creation/removal, roster and offline queue management)
        •  
      • Support for message expiration (JEP-0023)
        •  
      • Support for HTTPS in web interface
        •  
       
      •  
    •  
      0.7
       
         
      • Support for LDAP authentification
        •  
      • Support for HTTP Polling
        •  
      • Support for web-based administration interface
        •  
      • Added command-line administration utility \"ejabberdctl\"
        •  
      • Support for history management in MUC rooms
        •  
       
      •  
    "},{"location":"roadmap/#2003","title":"2003","text":"
       
    •  
      16th November, 0.5
       
         
      • First release
        •  
       
      •  
    •  
      January, initial documentation in LaTeX: Ejabberd Installation and Operation Guide
       
      •  
    "},{"location":"roadmap/#2002","title":"2002","text":"
       
    •  
      18th November, first commit to CVS
       
      •  
    •  
      16th November, first erlang modules written
       
      •  
    "},{"location":"tutorials/","title":"ejabberd and XMPP tutorials","text":"
    Learning ejabberd and XMPP through videos and hands-on tutorials.
    "},{"location":"tutorials/#text-tutorials","title":"Text tutorials","text":"
    In the ProcessOne's blog Tutorial tag you will find tutorials about:
     
       
    •  
      How to setup MariaDB, MQTT, PubSub, STUN/TURN, WebSocket.
       
      •  
    •  
      Elixir: Part 1, Part 2, Embed in Phoenix, Embed in Elixir app.
       
      •  
    •  
      Useful configuration steps
       
      •  
    •  
      Configuration for Office IM
       
      •  
    •  
      Configuration for XMPP compliance test
       
      •  
    •  
      Using a local development trusted CA on MacOS
       
      •  
     
    In the so-called ejabberd book there are also old archived ejabberd tutorials.
    "},{"location":"tutorials/#architecture","title":"Architecture","text":"
       
    •  
      Understanding ejabberd SaaS architecture
       
      Excerpt from XMPP Academy #1 starting at 1m33s.
       
      •  
    •  
      What are ejabberd backends? What backends are available in ejabberd and how do they work?
       
      Excerpt from XMPP Academy #2 starting at 2m05s.
       
      •  
    •  
      ejabberd backends architecture
       
      Excerpt from XMPP Academy #2 starting at 14m00s.
       
      •  
    •  
      What are ejabberd session backends and how to use them to scale?
       
      Excerpt from XMPP Academy #2 starting at 19m42s.
       
      •  
    "},{"location":"tutorials/#xmpp-on-mobile-devices-smartphones","title":"XMPP on mobile devices (smartphones)","text":"
       
    •  
      Mobile XMPP support on ejabberd SaaS and Business Edition: Standby, push and detached modes
       
      Excerpt from XMPP Academy #1 starting at 16m44s.
       
      •  
    •  
      How does Apple and Google Push support work on ejabberd SaaS and ejabberd Business Edition?
       
      Excerpt from XMPP Academy #3 starting at 1m20s.
       
      •  
    •  
      What is the relationship between ejabberd Push support and XEP-0357: Push Notifications?
       
      Excerpt from XMPP Academy #3 starting at 22m34s.
       
      •  
    •  
      What are message carbons and how do they work?
       
      Excerpt from XMPP Academy #2 starting at 27m30s.
       
      •  
    •  
      Demo: learning message carbons with Psi XMPP console
       
      Excerpt from XMPP Academy #2 starting at 29m51s.
       
      •  
    "},{"location":"tutorials/#xmpp-for-the-web","title":"XMPP for the Web","text":"
       
    •  
      ejabberd roadmap: announcing OAuth2 support
       
      Excerpt from XMPP Academy #1 starting at 27m43s.
       
      •  
    •  
      What is the impact of Websocket on Web chat performance?
       
      Excerpt from XMPP Academy #3 starting at 25m02s.
       
      •  
    "},{"location":"tutorials/#multi-user-chat","title":"Multi-User Chat","text":"
       
    • Why do avatars / carbons not work in MUC rooms? What is special about MUC rooms? 
      Excerpt from XMPP Academy #2 starting at 34m15s.
       
      •  
    "},{"location":"tutorials/#developer-tools-and-techniques","title":"Developer tools and techniques","text":"
       
    • What are the typical tools for quick XMPP prototyping?
      •  
    "},{"location":"tutorials/#ejabberd-and-xmpp-server-side-implementation","title":"ejabberd and XMPP server-side implementation","text":"
       
    •  
      How does ejabberd internally store messages which are not yet delivered?
       
      •  
    •  
      How are privacy lists managed in ejabberd?
       
      •  
    •  
      Why do we seem to find duplicate in Message Archive Management backend?
       
      Excerpt from XMPP Academy #3 starting at 32m20s.
       
      •  
    "},{"location":"tutorials/mix-010/","title":"Getting started with MIX","text":"
    MIX stands for Mediated Information eXchange and defined in MIX-CORE (XEP-0369), MIX-PRESENCE (XEP-0403) and MIX-PAM (XEP-0405). More concretely, ejabberd supports MIX 0.14.1.
     
    It is a work in progress extension for the XMPP protocol to build a group messaging protocol that does not rely on the presence mechanism. It is designed to overcome the limitation of Multi-User Chat (XEP-0045) , in a context where most clients are mobile clients.
     
    To do so, MIX is built on top of PubSub (XEP-0060) and use different nodes per channel to separate event types. There is five nodes to support five different types of event for each MIX channel:
     
       
    • Messages
      •  
    • Presence
      •  
    • Participant list changes
      •  
    • Subject update
      •  
    • Conversion configuration changes
      •  
     
    This is a work in progress, but this is a very important task and we are happy to provide the very first server implementation of the Mix protocol to get up to speed on that specification.
     
    Here is a short walk through what can already be done.
     
    Also note that the specification can (and will) change significantly before it becomes stable. These examples are based on XEP-0369 v0.1.
    "},{"location":"tutorials/mix-010/#configuration","title":"Configuration","text":"
    Configuration is simple:
     
       
    •  
      Install a recent ejabberd version (19.02 or newer)
       
      •  
    •  
      You need to add mod_mix and mod_mix_pam in ejabberd configuration, modules section:
       
      modules:\n  mod_mix: {}\n  mod_mix_pam: {}\n
       
      •  
    •  
      Make sure you have PubSub enabled. Default configuration is fine:
       
      modules:\n  mod_pubsub:\n    access_createnode: pubsub_createnode\n    plugins:\n      - \"flat\"\n      - \"pep\"\n
       
      •  
    •  
      The examples assume you have this virtual host:
       
      hosts:\n  - shakespeare.example\n
       
      •  
    "},{"location":"tutorials/mix-010/#usage","title":"Usage","text":"
    There is no client supporting MIX yet so here is how it works directly at XMPP stream level.
     
    Here are real-life examples from playing with our MIX implementation:
    "},{"location":"tutorials/mix-010/#creating-a-mix-channel","title":"Creating a MIX Channel","text":"
    First of all, create a new MIX channel following 7.3.2 Creating a Channel:
     
    <iq id='lx09df27'\n    to='mix.shakespeare.example'\n    type='set'>\n  <create channel='coven' xmlns='urn:xmpp:mix:core:0'/>\n</iq>\n
    "},{"location":"tutorials/mix-010/#joining-a-mix-channel","title":"Joining a MIX Channel","text":"
    Now tell your server that you want your account to join that MIX channel, using MIX-PAM: 2.7 Joining a Channel:
     
    <iq type='set'\n    to='hag66@shakespeare.example'\n    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>\n  <client-join xmlns='urn:xmpp:mix:pam:0'\n               channel='coven@mix.shakespeare.example'>\n    <join xmlns='urn:xmpp:mix:core:0'>\n      <nick>third witch</nick>\n      <subscribe node='urn:xmpp:mix:nodes:messages'></subscribe>\n      <subscribe node='urn:xmpp:mix:nodes:presence'></subscribe>\n      <subscribe node='urn:xmpp:mix:nodes:participants'></subscribe>\n      <subscribe node='urn:xmpp:mix:nodes:subject'></subscribe>\n      <subscribe node='urn:xmpp:mix:nodes:config'></subscribe>\n    </join>\n  </client-join>\n</iq>\n
     
    You receive IQ that confirms success:
     
    <iq type=\"result\"\n    from=\"hag66@shakespeare.example\"\n    to=\"hag66@shakespeare.example/MacBook-Pro-de-Mickael\"\n    id=\"E6E10350-76CF-40C6-B91B-1EA08C332FC7\">\n  <client-join xmlns='urn:xmpp:mix:pam:0'>\n    <join xmlns=\"urn:xmpp:mix:core:0\"\n          jid='d79d011852b97adfaad6#coven@mix.shakespeare.example'>\n      <nick>third witch</nick>\n      <subscribe node=\"urn:xmpp:mix:nodes:messages\"></subscribe>\n      <subscribe node=\"urn:xmpp:mix:nodes:presence\"></subscribe>\n      <subscribe node=\"urn:xmpp:mix:nodes:participants\"></subscribe>\n      <subscribe node=\"urn:xmpp:mix:nodes:subject\"></subscribe>\n      <subscribe node=\"urn:xmpp:mix:nodes:config\"></subscribe>\n   </join>\n  </client-join>\n</iq>\n
     
    Subscribers on the participants node for that channel will also receive the new list of participants (so, including ourselves in that case):
     
    <message from=\"coven@mix.shakespeare.example\"\n         type=\"headline\"\n         to=\"hag66@shakespeare.example/MacBook-Pro-de-Mickael\">\n <event xmlns=\"http://jabber.org/protocol/pubsub#event\">\n  <items node=\"urn:xmpp:mix:nodes:participants\">\n   <item id=\"3d1766e2bd1b02167104f350f84b0668f850ef92\">\n    <participant xmlns=\"urn:xmpp:mix:core:0\" jid=\"hag66@shakespeare.example\"></participant>\n   </item>\n  </items>\n </event>\n</message>\n
    "},{"location":"tutorials/mix-010/#setting-a-nick","title":"Setting a nick","text":"
    You may want to set a nick for this channel (see 7.1.4 Setting a Nick):
     
    <iq type='set'\n    to='coven@mix.shakespeare.example'\n    id='7nve413p'>\n  <setnick xmlns='urn:xmpp:mix:core:0'>\n    <nick>thirdwitch</nick>\n  </setnick>\n</iq>\n
     
    Note: Support for MIX nickname registration is not implemented in ejabberd.
    "},{"location":"tutorials/mix-010/#sending-and-receiving-messages","title":"Sending and receiving messages","text":"
    You can now start chatting with your peers, by publishing on the message node (see 7.1.6 Sending a Message):
     
    <message to='coven@mix.shakespeare.example'\n         id='92vax143g'\n         type='groupchat'>\n  <body>Harpier cries: 'tis time, 'tis time.</body>\n</message>\n
     
    The message is received by all subscribers on the message node on that MIX channel:
     
    <message\n to='hag77@shakespeare.example'\n from='coven@mix.shakespeare.example/19be8c262ed618e078b7'\n type='groupchat'\n id='1625493702877370'>\n  <mix xmlns='urn:xmpp:mix:core:0'>\n    <nick>thirdwitch</nick>\n    <jid>hag66@shakespeare.example</jid>\n  </mix>\n  <body>Harpier cries: &apos;tis time, &apos;tis time.</body>\n</message>\n
    "},{"location":"tutorials/mix-010/#querying-participants-list","title":"Querying participants list","text":"
    A participant can always get list of participants with a PubSub query on node items for the channel (see 6.6 Determining the Participants in a Channel):
     
    <iq type='get'\n    to='coven@mix.shakespeare.example'\n    id='mix4'>\n  <pubsub xmlns='http://jabber.org/protocol/pubsub'>\n    <items node='urn:xmpp:mix:nodes:participants'></items>\n  </pubsub>\n</iq>\n
     
    The channel will reply with list of participants:
     
    <iq to='hag66@shakespeare.example/tka1'\n    from='coven@mix.shakespeare.example'\n    type='result'\n    id='kl2fax27'>\n  <pubsub xmlns='http://jabber.org/protocol/pubsub'>\n    <items node='urn:xmpp:mix:nodes:participants'>\n      <item id='19be8c262ed618e078b7'>\n        <participant nick='thirdwitch'\n jid='hag66@shakespeare.example'\n xmlns='urn:xmpp:mix:core:0'/>\n      </item>\n      <item id='6be2b26cbf4d7108f1fb'>\n        <participant jid='hag77@shakespeare.example'\n xmlns='urn:xmpp:mix:core:0'/>\n      </item>\n    </items>\n  </pubsub>\n</iq>\n
    "},{"location":"tutorials/mix-010/#caveats","title":"Caveats","text":"
    At the moment it is unclear from XEP-0369 example how you match a message you receive to a participant. We are going to improve our implementation in the following way:
     
       
    1. Add a participant id on the item tag when broadcasting new participant.
      2.  
    2. Add the participant id on the published items.
      3.  
    3. Add the participant id in participants list on the publisher
      4.  
     
    Another issue is that the current specification and implementation will have trouble scaling and offer plenty of opportunities for \"Denial of Service\" attacks. This is something that will change in the future as the specification matures. However, currently, do not deploy or rely on this implementation for large-scale production services. The work is still an experiment to progress on the specifications by offering client developers to give real life feedback on a reference implementation of the current specification.
    "},{"location":"tutorials/mix-010/#conclusion","title":"Conclusion","text":"
    We are only at the beginning of MIX. However, we are excited to have reached a point where it is already usable in some cases.
     
    It is still missing on administrative tasks, right management, user invitations, relationship with MAM archiving and probably a lot more. And we need consolidations on participants message attribution. However, we want to iterate fast with client developers to prototype implementation changes and have meaningful and real life feedback to improve XEP-0359.
     
    Send us your feedback !
    "},{"location":"tutorials/muc-vcard/","title":"Setting vCards / Avatars for MUC rooms","text":"
    ejabberd supports the ability to set vCard for MUC rooms. One of the most common use case is to be able to define an avatar for your own MUC room.
    "},{"location":"tutorials/muc-vcard/#how-does-it-work","title":"How does it work?","text":"
    To be allowed to set vCard for a given room, you need to be owner of that room.
     
    To set up vCard avatar for your MUC room, you first need to make sure you convert your avatar image to base64 encoding, so that you can pass it on XMPP stream.
     
    If you want to convert it manually from command line, you can use base64 tool. For example:
     
    base64 muc_logo.png > muc_logo.b64\n
     
    However, when coding the client, you can more likely directly do the proper image base64 encoding in your code.
    "},{"location":"tutorials/muc-vcard/#setting-up-muc-vcard","title":"Setting up MUC vCard","text":"
    To set the MUC vCard, you can send a vcard-temp set request, as defined in XEP-0054: vcard-temp, but directly addressed to your MUC room. For example, assuming my room id is test@conference.localhost:
     
    <iq id='set1'\n    type='set'\n    to='test@conference.localhost'>\n<vCard xmlns='vcard-temp'>\n    <PHOTO>\n      <TYPE>image/png</TYPE>\n      <BINVAL>\niVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAACXBIWXMAAAsTAAALEwEAmpwYAAAB1WlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNS40LjAiPgogICA8cmRmOlJERiB4bWxuczpyZGY9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkvMDIvMjItcmRmLXN5bnRheC1ucyMiPgogICAgICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIgogICAgICAgICAgICB4bWxuczp0aWZmPSJodHRwOi8vbnMuYWRvYmUuY29tL3RpZmYvMS4wLyI+CiAgICAgICAgIDx0aWZmOkNvbXByZXNzaW9uPjE8L3RpZmY6Q29tcHJlc3Npb24+CiAgICAgICAgIDx0aWZmOk9yaWVudGF0aW9uPjE8L3RpZmY6T3JpZW50YXRpb24+CiAgICAgICAgIDx0aWZmOlBob3RvbWV0cmljSW50ZXJwcmV0YXRpb24+MjwvdGlmZjpQaG90b21ldHJpY0ludGVycHJldGF0aW9uPgogICAgICA8L3JkZjpEZXNjcmlwdGlvbj4KICAgPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KAtiABQAADkVJREFUeAHtWgtwVNUZ/nY3m0022bxIyItAIBBArZRUUbCoKCgVnWJxxlataO1rlKl2amec1urUdmrp2KE6nXFgGIWpQGmlzCDaoTDUBwoMVcFCeOQFhDwhCXlsNrub3fT7z7l3H8kmm4RUWsNJ7uvcc//zf//r/OectfSxYBwX6zjGrqBfEcDltID/Be+7rBZgsVgup/yvuIBI4LJawGVX//gUQB8iY0/C56EFlWj0Szfi+7+Znow8ThAi5N84GRA1Hek3MvRY/huJkEg4Eq90GAuwtItVbypFayosCM14bIFo0LqtxTK0ZweDfvZr5WHDmAogGAwq3q3W2AwEg33weHrQ6fYgM90Fh8OuzHGgEARILKBh840E2dcXVIBMwcm1t7cbXn8LvN4L8PnOwx+4yLo2+PwNSHfNx8QJi2C1JuKSXUBrW2syErinx4uW1nY0NLbgXP0FNDS34ejJelTVd+Cplbfi9lvKIvlV96ZFuD3n0Ni8DclJ03kUIcmRB0diFhm2hyxGQGsTF01qgXt9LejoOonOrk/g7j5AsJsQCOhW0pzyx6T8LcjJukWBF6sZtQA0cA4jVvEpra229k5UVdfhyLEaHPi0BusPngM+7BR98GjEzKVzsGX1A5h7bWkUYPWga3i2INDrRlPLj9UQJcaUkHA1BXEXUlPmIS31GqQ6i2GzJYU+c3fX4nzrbrS1vw6vb5+ql+/IGr8tQV+wCn18nlp0EBMy5+meDPcbsQuYGje1HQgEUVFVi/f3H8Xf9hzFrjfq2IGXhwNZC11o9VP0B9x4ee1teORbS5DmSoliQD0YJ9OUO7sqcLK6lIIt4RsfgsFapT2JKzYCSU56FJkZy5Hhmou2jkO0lhXopablndVazO8cdC0RvIXXOvXttKL9yM66Ubmc2IRpNSMSgPi4aFsOAX74aAXefOsAfrvuCFDrAaY6YS9woCTVDpfDhkO7W4A5Tux+cQUW33qdghkgDatBw8AdupgC6Og6hZNVM9kPIViy+F5M30XmAzxqKBBt1gJY7qWdzVbKd262reNV6sQqC+j3dSgq2IGC3HtYL7HFfKduh+8CAt7U+qnKs9j4l3fxm58fFHKwLEjD5Bkp8NLJnAlW1Lt70bGrHt9/ugzPrFqOqVPyVW9CwzZIgNTsxDoTNFqJuEm9FIHYbC7e+wiogfc5vE/g/SnjY0oFoqgS+P2VyMpcrcDrl2HNG43jCyDS5Ls9Xry54z2sfGYXcLoHhYsy4aAaznl6UdsTwLSUBFTWUAuVXry++T7cf++tNFcHtaQtxxSg2flwr6JLEbTWO4UhAiHrFksGr208JMZIEZOXvopooZWwJ85FUf531BvTutRDxGnIIGiajDBeW9eEF9Zsw/rfHwZumIDS0hRUU9O9dL4JNPf0RAsqd1/A9cvz8cet92Fe2WzVjbiKTWx1BIU2pfFGfaPNN1wloC+GH3kn/Fosibzz8J4RP+9ljiDZhlBi8zCoAEzw4kv/Lq/Csic3onZPK2bekYcL1PapDr/qPD/ZhgY+t7zfgmdfXIhVjy1Dbo74rfjnyMHLdzqp4Y1WvVQNr6j2Wey3kdF/FlwperTRlhObREwBRIL/9LNTKFuxjlYWxKw7J+CEAZyiRq7DioaabnFHbH/7Ydxz5wKl7cFMXmsoPiplAbH5HbJWU25krMqjC5xATe1qTC9+Hon29EGtIKZdmIyeZLAre2i9BGHMmJGKE+0+wa00k51oRVNjD+5dXIhj//wRlt/1VQVeRXm6jI7CYX5NoYRr4tzFl9MQBEQIhWjvXIPqs6sRCHrJj1UJof9HAwQgjIrPt7R1YNXzm4EzPpQWOVFBzUvSozyRp2QbOTzhw5T8dMwunaLoKn/vF+WFnqTAZgAMSGoWp6g+4rSJ/7qZ2eMsXGx/EbX1m1RzLYRo6lECEM2bjG7Y8g/s2VyD2fPTlb9bCZhDri7E3uILIp2Jzh9+fRgHPy43OtCvhY6ANoGL4BqbWrD+T++g+YIOXCKYwcolKV9zQm37eTTBbs9A04XH0HrxU6O7OAKQVuL3Tz/xPjIXZuMsI73klP3Z7Q70IZNuIGXb2weZiQWU8OQq5i+g5ejodGPnrv248aGX8b2VHD6HUUJBcBhtYzfRc5O+vjbG0WwVS+ubXlETpP6uELIAU/tiolt3fES6QWRxeHNzGBustNIK7Del4aUXjuDY8RrVLMFmU9e2i534+56D+PaTr+KepW/gzLvtmPd1MnPp6h2MnX71phAqGZtK0NW9Aa3tH/drI9mEUczAV326Hqs3HOVY70KbT/w1NscCpIN5/gyXHRVBH3bsOoRZjAVi6h9wXvD69kPY++fTQKETVy3NRnlzDy4yYZLx+XMt5FPsV/htbdvJmeAC3ouShBGLFoAJXhg7cqwaqOpAaUkeTnXKwoER+ORlRFE4aOK1BIXr07HunXLUNa3H2v3ngH3NQEkapi/ORReHz4teCtJD11B/EUT+67da2pJKSy7m9ryEbs8qpDiLqAhtISEXEKAyhH1WfpZsyUIFL/r7IdlkDsRoy3S4uxdr15wAuvwovSMfhZOTUcn40SgNVIltSbGIjzYPiEVL1/VQkdmMU0F09wi+cFEuIDiFPQ9z/eM154G8RPQwyKnKcNuYd2JaXoYJO0eJgpvTqOg+ZTnSWFvP8IGbHaggaD6MyVXS5iSl1B5vQxRFHQMMCXi9PtS1MLNLt8HHYUwkIOehinpPjH7enKGZq0KpCOx43w5Od+RCG5yWvJFAzuSM50CvHoZFOcJhyAX4pCTkF83Tt0cVrISmwfvowYdICEtjXpidGDQ1o1oABtN2uw05LocKWHb15lJgjJ73Me1VEROA2rH0WoIoW14wVxE2Dfxq7j69KINzfb+a54sNm++k3edXxlAECoB4Okc0nh32iQYM3UeUCyQm2nHtrEls4IOdbnDZy5ixkEiNc4LE4T85eXIULG0BDAhmbj7nmmlsYEebt5dWED8IRlEb64exMARFI10tjCY7VsKZLAqWoqUbZQFSPWvGZHzju9PQfLwbeUkU2aiioVAafQnlAZdsAZwCk4YsqAY5QGWmL0eCLVn5vx4FZGwwiswCZfbmSnXi0fvmA83d6qU0vGQ+zE54HY5SQ3nAcBpH0I6+Fa6ZAqNQLY44HGXcE7jJaBImHBJA5MeLFs7Fg09cjZp9HVzp5oqrzOcjG4z03ugv3O1ICYymve7NAiczXOZ22b/i+mBOlPaFahQumb5KLEhxJuGZJ+5m1gBUM7UVVxDriGcJ8j6FNFyMHebBJUMk8hkJFgZW0/OGBqRsjp9YLFyKYgZHqjzSeCTzGE7RsctiuQq+3gruBf6U65RLjA9FMGEkUQKQFip9pd9fM3sa3tr5Te7qnIed7TPIvZpAGGRiXYS0m4LqZDJlHpIcqqyytw/8H6YLkJC05aIG0CNUeXTw4OZL3CJJHC3WMovz/3JuwC5E8aSfcG1C5jcyK4yGrFPhCKKmAKTq7jvnY8PmDjzywF+BBRORyilV1yBzBFFygOBR6yWvtDlRnkiEAqifQDOo9uAkJ006ARHqQxQyKmYrI7HF0h4SmujNahWWJbfvX+StdCirWrMJ/jhsCXmYPvk15je5McELhUG3xvRylpbmlm178eAvdyEpPUElkj7pJ6KkE317ux9fKU7FKz+7l8EmjTuzvWpFyGwWFK0QUUlxIZK4WaKsSeXjZgu5CmEL/L2d6HKf5p2SgGLeZnVwUaMSdY3LSEe0KILgcrQyZ5MhFwVWxO/LuRRWhulTtnIzdfqg4PlxeEFEHiKLMCvLW7LCc8ei6zBl3Xs4w0WNrHQ7WsWWI4pDVNUdQLrTji9z59eZzHR6iBIbvHygtWhPcHHI+tIAClbuCJ9rlOpIAQgvifyykOJr5G8ByjmS/YA7wc+RjwIDvNCNXQa4gNlMmDT38d7ZfRBnuNE5aVEW6mRxo1/xsy1Fr1ygmz+AEAHIjpEIUYnKkJcoXA2rAzQfSVBbnZ7BSb08y0p1AoczjxKRthTOWvlkQTH78FJZNYpI/sTXUJh/PxXnHFLzqjFPgwpAXEC2tCqqz2HlC7uBualq81OwGlyYFovc5AS0pYpfWkJCk28F7GiK/o5xo18JB7BU0s4jQI8CLjylpvwQhbmPI8OwnFgBrx859RhTADIUCgBZH1izdidwvAfTFmdyL5BRWUAZGpWdIRkhTvyrXdbJkTg7M9SHYRSh57G6Ud33tRM4+yQfTufD/LnLI9z7564U44SU4YKXtgMEoIOfHio2vbkXr/7uMGYsmYgKrg+qQsAFBJ7CYbGijsNSuRtPPVuGMw3t2H7kQmhOoRuP7VmA+cgG52zISHsOEzKWUuNzlLlLT/L7AbGSsKXE7z9qFBDNmxsjsqR915KNyL45U632OCW54TDm4zB4up5j83H+AmNeJrb94mtquPR6/TjFX4rIXCLFGZ1vx2dj6BZm0HR76rjB8RED8TzGmaIQUBGMlJEAN3sMCcAc9uTF3g8+we0Pb8LUEieS+IMHWR0ONHF8r5LAwyRpWT4eX1GGZUvmYfKkXJNW6GoyHKoYk5vI4KMJXgpwkyUlAJPhHvr81u3v8rc8G/k+lYe4AqVbkMJfdU3EbdcX44ayGcwSpyJ3ot4Cl29N1kw6ow1+JlNDXU3QEnDHoh8Lzb5PCLVzC2v72x9i977jmFmcw2QmlYcL+bmZPLKQk5NJv5NEI8xepMuEa/+/7iiAPgqAS9vUvp9jt/ykZahfdCiNU+sitLHQwOUWV5QL9GfGBKvqBbDR4IsA3MQaCoICtn/5IgHtj818DuUB4wGsCTryqjOeyJpxdn9FAONM4QPgXrGAASIZZxVXLGCcKXwA3CsWMEAk46ziP3wnyrgPINtbAAAAAElFTkSuQmCC\n      </BINVAL>\n    </PHOTO>\n</vCard>\n</iq>\n
     
    Please, note that you have to set the mime type of the image properly to help the client displaying it.
     
    You can of course add other fields to the vCard if needed.
     
    After that IQ set stanza, the server will reply with success:
     
    <iq from=\"test@conference.localhost\"\n    type=\"result\"\n    to=\"owner@localhost/r\"\n    id=\"set1\">\n <vCard xmlns=\"vcard-temp\"/>\n</iq>\n
     
    The MUC room also broadcasts a notification about non-privacy related configuration change to users that are currently in the room:
     
    <message from=\"test@conference.localhost\"\n         type=\"groupchat\"\n         to=\"owner@localhost/r\"\n         id=\"17095969463368094420\">\n <x xmlns=\"http://jabber.org/protocol/muc#user\">\n  <status code=\"104\"/>\n </x>\n</message>\n
    "},{"location":"tutorials/muc-vcard/#retrieving-a-muc-room-vcard","title":"Retrieving a MUC room vCard","text":"
    Any user can retrieve the MUC vCard but sending a vcard-temp get IQ to the room itself:
     
    <iq to='test@conference.localhost'\n    id='get1'\n    type='get'>\n  <vCard xmlns='vcard-temp'/>\n</iq>\n
     
    Server will reply by sending back the vCard:
     
    <iq from=\"test@conference.localhost\"\n    type=\"result\"\n    to=\"user@localhost/r\"\n    id=\"get1\">\n <vCard xmlns=\"vcard-temp\">\n    <PHOTO>\n      <TYPE>image/png</TYPE>\n      <BINVAL>\niVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAACXBIWXMAAAsTAAALEwEAmpwYAAAB1WlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNS40LjAiPgogICA8cmRmOlJERiB4bWxuczpyZGY9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkvMDIvMjItcmRmLXN5bnRheC1ucyMiPgogICAgICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIgogICAgICAgICAgICB4bWxuczp0aWZmPSJodHRwOi8vbnMuYWRvYmUuY29tL3RpZmYvMS4wLyI+CiAgICAgICAgIDx0aWZmOkNvbXByZXNzaW9uPjE8L3RpZmY6Q29tcHJlc3Npb24+CiAgICAgICAgIDx0aWZmOk9yaWVudGF0aW9uPjE8L3RpZmY6T3JpZW50YXRpb24+CiAgICAgICAgIDx0aWZmOlBob3RvbWV0cmljSW50ZXJwcmV0YXRpb24+MjwvdGlmZjpQaG90b21ldHJpY0ludGVycHJldGF0aW9uPgogICAgICA8L3JkZjpEZXNjcmlwdGlvbj4KICAgPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KAtiABQAADkVJREFUeAHtWgtwVNUZ/nY3m0022bxIyItAIBBArZRUUbCoKCgVnWJxxlataO1rlKl2amec1urUdmrp2KE6nXFgGIWpQGmlzCDaoTDUBwoMVcFCeOQFhDwhCXlsNrub3fT7z7l3H8kmm4RUWsNJ7uvcc//zf//r/OectfSxYBwX6zjGrqBfEcDltID/Be+7rBZgsVgup/yvuIBI4LJawGVX//gUQB8iY0/C56EFlWj0Szfi+7+Znow8ThAi5N84GRA1Hek3MvRY/huJkEg4Eq90GAuwtItVbypFayosCM14bIFo0LqtxTK0ZweDfvZr5WHDmAogGAwq3q3W2AwEg33weHrQ6fYgM90Fh8OuzHGgEARILKBh840E2dcXVIBMwcm1t7cbXn8LvN4L8PnOwx+4yLo2+PwNSHfNx8QJi2C1JuKSXUBrW2syErinx4uW1nY0NLbgXP0FNDS34ejJelTVd+Cplbfi9lvKIvlV96ZFuD3n0Ni8DclJ03kUIcmRB0diFhm2hyxGQGsTF01qgXt9LejoOonOrk/g7j5AsJsQCOhW0pzyx6T8LcjJukWBF6sZtQA0cA4jVvEpra229k5UVdfhyLEaHPi0BusPngM+7BR98GjEzKVzsGX1A5h7bWkUYPWga3i2INDrRlPLj9UQJcaUkHA1BXEXUlPmIS31GqQ6i2GzJYU+c3fX4nzrbrS1vw6vb5+ql+/IGr8tQV+wCn18nlp0EBMy5+meDPcbsQuYGje1HQgEUVFVi/f3H8Xf9hzFrjfq2IGXhwNZC11o9VP0B9x4ee1teORbS5DmSoliQD0YJ9OUO7sqcLK6lIIt4RsfgsFapT2JKzYCSU56FJkZy5Hhmou2jkO0lhXopablndVazO8cdC0RvIXXOvXttKL9yM66Ubmc2IRpNSMSgPi4aFsOAX74aAXefOsAfrvuCFDrAaY6YS9woCTVDpfDhkO7W4A5Tux+cQUW33qdghkgDatBw8AdupgC6Og6hZNVM9kPIViy+F5M30XmAzxqKBBt1gJY7qWdzVbKd262reNV6sQqC+j3dSgq2IGC3HtYL7HFfKduh+8CAt7U+qnKs9j4l3fxm58fFHKwLEjD5Bkp8NLJnAlW1Lt70bGrHt9/ugzPrFqOqVPyVW9CwzZIgNTsxDoTNFqJuEm9FIHYbC7e+wiogfc5vE/g/SnjY0oFoqgS+P2VyMpcrcDrl2HNG43jCyDS5Ls9Xry54z2sfGYXcLoHhYsy4aAaznl6UdsTwLSUBFTWUAuVXry++T7cf++tNFcHtaQtxxSg2flwr6JLEbTWO4UhAiHrFksGr208JMZIEZOXvopooZWwJ85FUf531BvTutRDxGnIIGiajDBeW9eEF9Zsw/rfHwZumIDS0hRUU9O9dL4JNPf0RAsqd1/A9cvz8cet92Fe2WzVjbiKTWx1BIU2pfFGfaPNN1wloC+GH3kn/Fosibzz8J4RP+9ljiDZhlBi8zCoAEzw4kv/Lq/Csic3onZPK2bekYcL1PapDr/qPD/ZhgY+t7zfgmdfXIhVjy1Dbo74rfjnyMHLdzqp4Y1WvVQNr6j2Wey3kdF/FlwperTRlhObREwBRIL/9LNTKFuxjlYWxKw7J+CEAZyiRq7DioaabnFHbH/7Ydxz5wKl7cFMXmsoPiplAbH5HbJWU25krMqjC5xATe1qTC9+Hon29EGtIKZdmIyeZLAre2i9BGHMmJGKE+0+wa00k51oRVNjD+5dXIhj//wRlt/1VQVeRXm6jI7CYX5NoYRr4tzFl9MQBEQIhWjvXIPqs6sRCHrJj1UJof9HAwQgjIrPt7R1YNXzm4EzPpQWOVFBzUvSozyRp2QbOTzhw5T8dMwunaLoKn/vF+WFnqTAZgAMSGoWp6g+4rSJ/7qZ2eMsXGx/EbX1m1RzLYRo6lECEM2bjG7Y8g/s2VyD2fPTlb9bCZhDri7E3uILIp2Jzh9+fRgHPy43OtCvhY6ANoGL4BqbWrD+T++g+YIOXCKYwcolKV9zQm37eTTBbs9A04XH0HrxU6O7OAKQVuL3Tz/xPjIXZuMsI73klP3Z7Q70IZNuIGXb2weZiQWU8OQq5i+g5ejodGPnrv248aGX8b2VHD6HUUJBcBhtYzfRc5O+vjbG0WwVS+ubXlETpP6uELIAU/tiolt3fES6QWRxeHNzGBustNIK7Del4aUXjuDY8RrVLMFmU9e2i534+56D+PaTr+KepW/gzLvtmPd1MnPp6h2MnX71phAqGZtK0NW9Aa3tH/drI9mEUczAV326Hqs3HOVY70KbT/w1NscCpIN5/gyXHRVBH3bsOoRZjAVi6h9wXvD69kPY++fTQKETVy3NRnlzDy4yYZLx+XMt5FPsV/htbdvJmeAC3ouShBGLFoAJXhg7cqwaqOpAaUkeTnXKwoER+ORlRFE4aOK1BIXr07HunXLUNa3H2v3ngH3NQEkapi/ORReHz4teCtJD11B/EUT+67da2pJKSy7m9ryEbs8qpDiLqAhtISEXEKAyhH1WfpZsyUIFL/r7IdlkDsRoy3S4uxdr15wAuvwovSMfhZOTUcn40SgNVIltSbGIjzYPiEVL1/VQkdmMU0F09wi+cFEuIDiFPQ9z/eM154G8RPQwyKnKcNuYd2JaXoYJO0eJgpvTqOg+ZTnSWFvP8IGbHaggaD6MyVXS5iSl1B5vQxRFHQMMCXi9PtS1MLNLt8HHYUwkIOehinpPjH7enKGZq0KpCOx43w5Od+RCG5yWvJFAzuSM50CvHoZFOcJhyAX4pCTkF83Tt0cVrISmwfvowYdICEtjXpidGDQ1o1oABtN2uw05LocKWHb15lJgjJ73Me1VEROA2rH0WoIoW14wVxE2Dfxq7j69KINzfb+a54sNm++k3edXxlAECoB4Okc0nh32iQYM3UeUCyQm2nHtrEls4IOdbnDZy5ixkEiNc4LE4T85eXIULG0BDAhmbj7nmmlsYEebt5dWED8IRlEb64exMARFI10tjCY7VsKZLAqWoqUbZQFSPWvGZHzju9PQfLwbeUkU2aiioVAafQnlAZdsAZwCk4YsqAY5QGWmL0eCLVn5vx4FZGwwiswCZfbmSnXi0fvmA83d6qU0vGQ+zE54HY5SQ3nAcBpH0I6+Fa6ZAqNQLY44HGXcE7jJaBImHBJA5MeLFs7Fg09cjZp9HVzp5oqrzOcjG4z03ugv3O1ICYymve7NAiczXOZ22b/i+mBOlPaFahQumb5KLEhxJuGZJ+5m1gBUM7UVVxDriGcJ8j6FNFyMHebBJUMk8hkJFgZW0/OGBqRsjp9YLFyKYgZHqjzSeCTzGE7RsctiuQq+3gruBf6U65RLjA9FMGEkUQKQFip9pd9fM3sa3tr5Te7qnIed7TPIvZpAGGRiXYS0m4LqZDJlHpIcqqyytw/8H6YLkJC05aIG0CNUeXTw4OZL3CJJHC3WMovz/3JuwC5E8aSfcG1C5jcyK4yGrFPhCKKmAKTq7jvnY8PmDjzywF+BBRORyilV1yBzBFFygOBR6yWvtDlRnkiEAqifQDOo9uAkJ006ARHqQxQyKmYrI7HF0h4SmujNahWWJbfvX+StdCirWrMJ/jhsCXmYPvk15je5McELhUG3xvRylpbmlm178eAvdyEpPUElkj7pJ6KkE317ux9fKU7FKz+7l8EmjTuzvWpFyGwWFK0QUUlxIZK4WaKsSeXjZgu5CmEL/L2d6HKf5p2SgGLeZnVwUaMSdY3LSEe0KILgcrQyZ5MhFwVWxO/LuRRWhulTtnIzdfqg4PlxeEFEHiKLMCvLW7LCc8ei6zBl3Xs4w0WNrHQ7WsWWI4pDVNUdQLrTji9z59eZzHR6iBIbvHygtWhPcHHI+tIAClbuCJ9rlOpIAQgvifyykOJr5G8ByjmS/YA7wc+RjwIDvNCNXQa4gNlMmDT38d7ZfRBnuNE5aVEW6mRxo1/xsy1Fr1ygmz+AEAHIjpEIUYnKkJcoXA2rAzQfSVBbnZ7BSb08y0p1AoczjxKRthTOWvlkQTH78FJZNYpI/sTXUJh/PxXnHFLzqjFPgwpAXEC2tCqqz2HlC7uBualq81OwGlyYFovc5AS0pYpfWkJCk28F7GiK/o5xo18JB7BU0s4jQI8CLjylpvwQhbmPI8OwnFgBrx859RhTADIUCgBZH1izdidwvAfTFmdyL5BRWUAZGpWdIRkhTvyrXdbJkTg7M9SHYRSh57G6Ud33tRM4+yQfTufD/LnLI9z7564U44SU4YKXtgMEoIOfHio2vbkXr/7uMGYsmYgKrg+qQsAFBJ7CYbGijsNSuRtPPVuGMw3t2H7kQmhOoRuP7VmA+cgG52zISHsOEzKWUuNzlLlLT/L7AbGSsKXE7z9qFBDNmxsjsqR915KNyL45U632OCW54TDm4zB4up5j83H+AmNeJrb94mtquPR6/TjFX4rIXCLFGZ1vx2dj6BZm0HR76rjB8RED8TzGmaIQUBGMlJEAN3sMCcAc9uTF3g8+we0Pb8LUEieS+IMHWR0ONHF8r5LAwyRpWT4eX1GGZUvmYfKkXJNW6GoyHKoYk5vI4KMJXgpwkyUlAJPhHvr81u3v8rc8G/k+lYe4AqVbkMJfdU3EbdcX44ayGcwSpyJ3ot4Cl29N1kw6ow1+JlNDXU3QEnDHoh8Lzb5PCLVzC2v72x9i977jmFmcw2QmlYcL+bmZPLKQk5NJv5NEI8xepMuEa/+/7iiAPgqAS9vUvp9jt/ykZahfdCiNU+sitLHQwOUWV5QL9GfGBKvqBbDR4IsA3MQaCoICtn/5IgHtj818DuUB4wGsCTryqjOeyJpxdn9FAONM4QPgXrGAASIZZxVXLGCcKXwA3CsWMEAk46ziP3wnyrgPINtbAAAAAElFTkSuQmCC\n      </BINVAL>\n    </PHOTO>\n </vCard>\n</iq>\n
    "},{"location":"tutorials/mysql/","title":"Using ejabberd with MySQL","text":"
    ejabberd is bundled with a native Erlang driver to use MySQL as a backend for persistent storage. Using MySQL as backend is thus extremely straightforward.
    "},{"location":"tutorials/mysql/#ejabberd-installation","title":"ejabberd installation","text":"
    ejabberd packages and binary installers contain all the modules needed to connect to your MySQL server. You have no extra module to install anymore.
     
    If you are building ejabberd from source, make sure that you configure ejabberd to include MySQL module. It can be done by passing option --enable-mysql to configure script. For example:
     
    cd ejabberd-source\n./configure --enable-mysql\n
    "},{"location":"tutorials/mysql/#mysql-installation","title":"MySQL installation","text":"
    You need a MySQL server that you can point your ejabberd configuration to. The database does not have to be on the same server than ejabberd.
    "},{"location":"tutorials/mysql/#requirements","title":"Requirements","text":"
    ejabberd uses FULLTEXT indexes with InnoDB. Thus, you need MySQL 5.6 or greater to use with ejabberd.
     
    Note: If you do not store message archive in database however, you can try using older 5.5 version. You may need to adapt MySQL database schema to cope with those older MySQL versions.
    "},{"location":"tutorials/mysql/#mysql-on-linux","title":"MySQL on Linux","text":"
    This documentation will not get into the details of making MySQL running on Linux for production. It is dependent on Linux distribution and system administrators preferences and habits.
     
    It is also well documented, so it should not be an issue.
    "},{"location":"tutorials/mysql/#amazon-rds-compliance","title":"Amazon RDS compliance","text":"
    ejabberd is fully compliant with MySQL on Amazon RDS.
     
    You just need to make sure to use MySQL version 5.6 or greater when you create your database.
    "},{"location":"tutorials/mysql/#mysql-on-osx-with-homebrew","title":"MySQL on OSX with Homebrew","text":"
    For testing / development, it is common to start experimenting with MySQL with Homebrew installation.
     
    Here is how to get started to help with setup up environment.
     
    With Homebrew properly installed, you can use the following command to install MySQL:
     
    brew install mysql\n
     
    You can then follow instruction to finish the installation, for example by running mysql_secure_installation.
     
    You can manually start server with:
     
    mysql.server start\n
     
    To connect to your local MySQL server using mysql command-line, assuming you kept the default set up, use:
     
    mysql -uroot\n
     
    To stop it, use:
     
    mysql.server stop\n
    "},{"location":"tutorials/mysql/#mysql-on-windows-with-bash","title":"MySQL on Windows with Bash","text":"
    On Windows you can install MySQL easily like on Linux using Ubuntu Bash:
     
    sudo apt-get install mysql-server-5.6\n
     
    After configuration, you can start MySQL with:
     
    sudo /etc/init.d/mysql start\n
     
    You can connect on the database with your created admin password:
     
    mysql -uroot -ppassword\n
    "},{"location":"tutorials/mysql/#mysql-database-creation","title":"MySQL database creation","text":""},{"location":"tutorials/mysql/#create-ejabberd-user-and-database","title":"Create ejabberd user and database","text":"
    MySQL admins should use this procedure and grant rights to a dedicated ejabberd user (replace password with your desired password):
     
    echo \"GRANT ALL ON ejabberd.* TO 'ejabberd'@'localhost' IDENTIFIED BY 'password';\" | mysql -h localhost -u root\n
     
    You can then create a dedicated ejabberd database (use password created earlier):
     
    echo \"CREATE DATABASE ejabberd;\" | mysql -h localhost -u ejabberd -p\n
     
    You should now be able to connect to ejabberd database with user ejabberd (use password defined on GRANT command):
     
    mysql -h localhost -u ejabberd -p -D ejabberd\n\nWelcome to the MySQL monitor.  Commands end with ; or \\g.\nYour MySQL connection id is 8\nServer version: 5.7.11 Homebrew\n\nCopyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.\n\nOracle is a registered trademark of Oracle Corporation and/or its\naffiliates. Other names may be trademarks of their respective\nowners.\n\nType 'help;' or '\\h' for help. Type '\\c' to clear the current input statement.\n\nmysql>\n
    "},{"location":"tutorials/mysql/#decide-which-sql-schema-to-use","title":"Decide which SQL schema to use","text":"
    Read carefully the Default and New Schemas section and decide which schema is preferable in your case: the default or the new schema.
     
    Then modify the ejabberd.yml configuration file to setup your desired option value:
     
    new_sql_schema: true\n
    "},{"location":"tutorials/mysql/#use-automatic-schema-update","title":"Use automatic schema update","text":"
    Since ejabberd 23.10, ejabberd can take care to create the tables automatically the first time it starts with an empty database, and also takes care to update the database schema when you upgrade ejabberd to a newer version.
     
    That feature works both for default and new SQL schema, for MySQL, PostgreSQL and SQLite.
     
    To enable automatic database schema creation and update, simply add in your ejabberd.yml configuration file:
     
    update_sql_schema: true\n
     
    In that case, you don't need to load the database schema manually: no need to read the next section.
    "},{"location":"tutorials/mysql/#load-database-schema-manually","title":"Load database schema manually","text":"
    MySQL default schema is defined in a file called mysql.sql, and the new schema is mysql.new.sql. Some tables of the schema are described in: ejabberd SQL database schema documentation.
     
    Those schema files can be found:
     
       
    •  
      Git repository and source code package: /sql/ directory
       
      •  
    •  
      When installed from source code or binary installer, the SQL schemas are copied to   PREFIX/lib/ejabberd-VERSION/priv/sql
       
      •  
     
    Load the schema in your ejabberd database with the command:
     
    mysql -h localhost -D ejabberd -u ejabberd -p < mysql.sql\n
     
    To make sure all looks fine, you can show the list of SQL tables:
     
    echo \"SHOW TABLES;\" | mysql -h localhost -D ejabberd -u ejabberd -p --table\n\nmysql: [Warning] Using a password on the command line interface can be insecure.\n+-------------------------+\n| Tables_in_ejabberd      |\n+-------------------------+\n| archive                 |\n| archive_prefs           |\n| caps_features           |\n| last                    |\n| motd                    |\n| muc_registered          |\n| muc_room                |\n| privacy_default_list    |\n| privacy_list            |\n| privacy_list_data       |\n| private_storage         |\n| pubsub_item             |\n| pubsub_node             |\n| pubsub_node_option      |\n| pubsub_node_owner       |\n| pubsub_state            |\n| pubsub_subscription_opt |\n| roster_version          |\n| rostergroups            |\n| rosterusers             |\n| sm                      |\n| spool                   |\n| sr_group                |\n| sr_user                 |\n| users                   |\n| vcard                   |\n| vcard_search            |\n| vcard_xupdate           |\n+-------------------------+\n
     
    Your database is now ready to connect with ejabberd.
    "},{"location":"tutorials/mysql/#ejabberd-configuration","title":"ejabberd configuration","text":""},{"location":"tutorials/mysql/#setup-mysql-connection","title":"Setup MySQL connection","text":"
    In ejabberd.yml, define your database parameters:
     
    sql_type: mysql\nsql_server: \"localhost\"\nsql_database: \"ejabberd\"\nsql_username: \"ejabberd\"\nsql_password: \"password\"\n## If you want to specify the port:\nsql_port: 3306\n
     
    Those parameters are mandatory if you want to use MySQL with ejabberd.
    "},{"location":"tutorials/mysql/#authentication-use-mysql","title":"Authentication use MySQL","text":"
    If you decide to store user password in ejabberd, you need to tell ejabberd to use MySQL instead of internal database for authentication.
     
    You thus need to change ejabberd configuration auth_method to replace internal authentication with sql:
     
    auth_method: sql\n
     
    If you restart ejabberd, it should connect to your database for authentication. In case it does not work as expected, check your config file syntax and log files (ejabberd.log, error.log, crash.log)
     
    For example, you can create a user in database with ejabberdctl:
     
    /sbin/ejabberdctl register \"testuser\" \"localhost\" \"passw0rd\"\n\nUser testuser@localhost successfully registered\n
     
    You should now be able to connect XMPP users based on MySQL user base.
    "},{"location":"tutorials/mysql/#modules-use-mysql","title":"Modules use MySQL","text":"
    At this stage, only the authentication / user base has been moved to MySQL. For data managed by modules, ejabberd still uses the Mnesia internal database by default; you can decide to use MySQL on a module-by-module basis.
     
    For each modules that support SQL backend, you can pass option db_type: sql to use your configured MySQL database. Switch can be done on a module by module basis. For example, if you want to store contact list in MySQL, you can do:
     
    modules:\n  mod_roster:\n    db_type: sql\n
     
    However, if you want to use MySQL for all modules that support MySQL, you can simply use global option default_db: sql:
     
    default_db: sql\n
     
    Note: even if you move all the persistent data you can to MySQL, Mnesia will still be started and used to manage clustering.
    "},{"location":"tutorials/mysql/#migrating-data-from-internal-to-mysql","title":"Migrating data from internal to MySQL","text":"
    To migrate your data, once you have setup your sql service, you can move most of the data to your database.
     
    You need to take precautions before you launch the migration:
     
       
    1.  
      Before you launch migration from internal database, make sure you have made a proper backup.
       
      2.  
    2.  
      Always try the migration first on an instance created from your data backup, to make sure the migration script will work fine on your dataset.
       
      3.  
    3.  
      Then, when doing final migration, make sure your instance is not accepting connections by blocking incoming connections, for example with firewall rules (block port 5222, 5269 and 5280 as default).
       
      4.  
     
    When you are ready, you can:
     
       
    1.  
      Connect to a running ejabberd:
       
      ./ejabberdctl debug\n
       
      2.  
    2.  
      Alternatively, use ejabberdctl live to launch ejabberd with an Erlang shell attached.
       
      3.  
    3.  
      Launch the migration command ejd2sql:export/2 from Erlang shell. First parameter is the XMPP domain name you want to migrate (i.e localhost). Second parameter sql tells ejabberd to export to configured MySQL database. For example:
       
      ejd2sql:export(<<\"localhost\">>, sql).\n
       
      4.  
     
    You should be set now.
    "},{"location":"tutorials/mysql/#converting-database-from-default-to-new-schema","title":"Converting database from default to new schema","text":"
    Please check the section Default and New Schemas.
    "},{"location":"tutorials/mysql/#getting-further","title":"Getting further","text":"
    To get further you can read the ejabberd Configuration section about Databases.
    "},{"location":"use-cases/","title":"ejabberd Use Cases","text":"
    ejabberd is very versatile and is a solid choice to build messaging services across a large number of industries:
    "},{"location":"use-cases/#ejabberd","title":"ejabberd","text":""},{"location":"use-cases/#mobile-messaging","title":"Mobile messaging","text":"
    ejabberd's massive scalability makes it the most solid choice as the backbone for a very large number of mobile messaging services.
     
    This includes:
     
       
    • Chaatz
      •  
    • Libon
      •  
    • Nokia OVI Chat
      •  
    • Roo Kids : Safe & fun instant messaging app for kids with minimum yet critical parental controls.
      •  
    • Swisscom IO
      •  
    • Versapp
      •  
    • Whatsapp
      •  
    "},{"location":"use-cases/#gaming","title":"Gaming","text":"
       
    • Electronic Arts
      •  
    • FACEIT
      •  
    • Kixeye
      •  
    • Machine Zone (Game of War)
      •  
    • Nokia nGage
      •  
    • Riot Games (League of Legends)
      •  
    "},{"location":"use-cases/#voice-and-video-messaging","title":"Voice and video messaging","text":"
       
    • Nimbuzz
      •  
    • ooVoo
      •  
    • Sipphone
      •  
    • WowApp
      •  
    "},{"location":"use-cases/#internet-of-things","title":"Internet of Things","text":"
       
    • AeroFS
      •  
    • IMA Teleassistance
      •  
    • Nabaztag (Violet, Mindscape, then Aldebaran Robotics)
      •  
    "},{"location":"use-cases/#telecom-hosting","title":"Telecom / Hosting","text":"
       
    • Fastmail
      •  
    • GMX
      •  
    • Mailfence
      •  
    • Orange
      •  
    • SAPO - Portugal Telecom
      •  
    "},{"location":"use-cases/#customer-chat-crm","title":"Customer chat / CRM","text":"
       
    • CoBrowser.net: Coder Interview.
      •  
    • iAdvize
      •  
    • LiveHelpercChat: Blog post: Full XMPP chat support for ejabberd
      •  
    "},{"location":"use-cases/#media","title":"Media","text":"
       
    • AFP
      •  
    • BBC
      •  
    "},{"location":"use-cases/#social-media","title":"Social media","text":"
       
    • Facebook
      •  
    • Nasza Klasa (NKTalk messenger)
      •  
    • StudiVZ
      •  
    • Sify
      •  
    • Tuenti
      •  
    "},{"location":"use-cases/#sport","title":"Sport","text":"
       
    • Major League of Baseball (MLB)
      •  
    "},{"location":"use-cases/#education","title":"Education","text":"
       
    • Apollo group
      •  
    • Laureate
      •  
    "},{"location":"use-cases/#push-alerts","title":"Push alerts","text":"
       
    • Nokia push notifications
      •  
    • Notify.me
      •  
    "},{"location":"use-cases/#dating","title":"Dating","text":"
       
    • Grindr
      •  
    • Meetic
      •  
    "},{"location":"use-cases/#community-sites","title":"Community sites","text":"
       
    • Jabber.at
      •  
    • Talkr.im
      •  
    "},{"location":"use-cases/#xmpp-use-cases","title":"XMPP Use Cases","text":"
    XMPP is a very versatile protocol designed to address many use cases of modern real-time messaging needs. However, it is also a very large protocol and it is difficult to understand at first sight all the use cases that XMPP adequately addresses.
     
    This page is gathering XMPP specifications that make XMPP a good fit for a given use case of industry.
    "},{"location":"use-cases/#realtime-web","title":"Realtime web","text":"
    XMPP was designed before the advent of realtime web. However, it managed to adapt thanks to the following specifications:
     
       
    •  
      XMPP PubSub is defined in   XEP-0060. This is a   very powerful mechanism that defines channel based communication on   top of the XMPP protocol itself. A server can handle millions of   channels, called Pubsub nodes. Users interested in specific channels   can subscribe to nodes. When data needs to be send to a given   channel, authorized publishers can send data to that node. The XMPP   server will then broadcast the content to all subscribers. This is   very adequate for realtime web as it allows you to broadcast   relevant events to web pages.
       
      •  
    •  
      WebSocket: XMPP over WebSocket is defined in   RFC 7395. It is more   efficient and more scalable than XMPP for web's previous   specifications called   BOSH. WebSocket being a   true bidirectional channel, it allows lower latency messaging and is   very reliable. Note that BOSH can still be used transparently along   with WebSocket to support old web browsers.
       
      •  
     
    Use cases: News, interactive web page, web chat, web games.
     
    Supported by ejabberd: Yes.
    "}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index 12a51781..c73056fa 100644
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ