From 09e9b0d7f8ed5929f2fb9e923c01ec8f5a21331a Mon Sep 17 00:00:00 2001 From: Piotr Nosek Date: Mon, 8 May 2017 12:11:11 +0200 Subject: [PATCH 1/5] [skip ci] Update some mods' docs - part 2 --- .../mod_muc_light_developers_guide.md | 18 ++-- doc/modules/mod_admin_extra.md | 10 +- doc/modules/mod_http_upload.md | 3 +- doc/modules/mod_muc.md | 19 ++-- doc/modules/mod_muc_light.md | 4 +- doc/modules/mod_muc_log.md | 4 +- doc/modules/mod_pubsub.md | 97 +++++++++++++------ doc/modules/mod_register.md | 32 +++++- doc/modules/mod_vcard.md | 6 +- 9 files changed, 131 insertions(+), 62 deletions(-) diff --git a/doc/developers-guide/mod_muc_light_developers_guide.md b/doc/developers-guide/mod_muc_light_developers_guide.md index 17d9a8bfca..7a14211ccc 100644 --- a/doc/developers-guide/mod_muc_light_developers_guide.md +++ b/doc/developers-guide/mod_muc_light_developers_guide.md @@ -42,7 +42,7 @@ All source files can be found in `apps/ejabberd/src`. * `mod_muc_light_utils.erl` Utilities shared by other MUC Light modules. - It includes the room configuration processing or the affiliation logic. + It includes the room configuration processing and the affiliation logic. The header file can be found in `apps/ejabberd/include`. @@ -61,28 +61,30 @@ There are 2 test suites and one helper module in `test/ejabberd_tests/tests`. Provides handy iterators over room participants. Used in MUC Light suites but in the future could be used in `muc_SUITE` as well. -Hooks used by this extension +Hooks handled by this extension ----------------------- -* `offline_groupchat_message_hook` used by `mod_muc_light:prevent_service_unavailable/3` - Prevents the default behaviour of sending `service-unavailable` error to the room when a groupchat message is sent to an offline occupant. +* `offline_groupchat_message_hook` handled by `mod_muc_light:prevent_service_unavailable/3` - Prevents the default behaviour of sending `service-unavailable` error to the room when a groupchat message is sent to an offline occupant. -* `remove_user` used by `mod_muc_light:remove_user/2` - Triggers DB cleanup of all data related to the removed user. +* `remove_user` handled by `mod_muc_light:remove_user/2` - Triggers DB cleanup of all data related to the removed user. Includes a broadcast of a notification about user removal from occupied rooms. -* `disco_local_items` used by `mod_muc_light:get_muc_service/5` - Adds MUC service item to the Disco result. +* `disco_local_items` handled by `mod_muc_light:get_muc_service/5` - Adds MUC service item to the Disco result. Uses either a MUC Light or a classic MUC namespace when the legacy mode is enabled. -* `roster_get` used by `mod_muc_light:add_rooms_to_roster/2` - Injects room items to the user's roster. +* `roster_get` handled by `mod_muc_light:add_rooms_to_roster/2` - Injects room items to the user's roster. -* `privacy_iq_get`, `privacy_iq_set` used by `mod_muc_light:process_iq_get/5` and `mod_muc_light:process_iq_set/4` respectively - These callbacks handle blocking settings when legacy mode is enabled. +* `privacy_iq_get`, `privacy_iq_set` handled by `mod_muc_light:process_iq_get/5` and `mod_muc_light:process_iq_set/4` respectively - These callbacks handle blocking settings when legacy mode is enabled. -* `is_muc_room_owner`, `muc_room_pid` used by `mod_muc_light:is_room_owner/3` and `mod_muc_light:muc_room_pid/2` respectively - Callbacks that provide essential data for the `mod_mam_muc` extension. +* `is_muc_room_owner`, `muc_room_pid`, `can_access_room`, `can_access_identity` used by `mod_muc_light:is_room_owner/3`, `mod_muc_light:muc_room_pid/2`, `mod_muc_light:can_access_room/3` and `mod_muc_light:can_access_identity/3` respectively - Callbacks that provide essential data for the `mod_mam_muc` extension. Hooks executed by this extension ----------------------- * `filter_room_packet` by codecs - Allows `mod_mam_muc` to archive groupchat messages. +* `room_send_packet` by codecs - Handled by `mod_aws_sns`. + * `forget_room` by `mod_muc_light_db_mnesia` and `mod_muc_light_room` - It is a part of `mod_mam_muc` integration as well. A hook used for MAM cleanup upon room destruction. diff --git a/doc/modules/mod_admin_extra.md b/doc/modules/mod_admin_extra.md index e5f64456a6..47e6e7e99a 100644 --- a/doc/modules/mod_admin_extra.md +++ b/doc/modules/mod_admin_extra.md @@ -2,16 +2,16 @@ This module significantly extends `mongooseimctl` script capabilities. New functionalities appear as additional commands. For detailed description, just run `mongooseimctl` script with no parameters. ### Options -* `submods`: List of function groups added by `mod_admin_extra`. Allowed elements: - * `node`: Adds `load_config`, `get_cookie`, `remove_node` +* `submods` (default: all submodules): List of function groups added by `mod_admin_extra`. Allowed elements: * `accounts`: Adds `change_password`, `check_password_hash`, `delete_old_users`, `delete_old_users_vhost`, `ban_account`, `num_active_users`, `check_account`, `check_password` - * `sessions`: Adds `num_resources`, `resource_num`, `kick_session`, `status_num_host`, `status_num`, `status_list_host`, `status_list`, `connected_users_info`, `connected_users_vhost`, `user_sessions_info`, `set_presence` - * `vcard`: Adds `get_vcard`, `get_vcard2`, `get_vcard2_multi`, `set_vcard`, `set_vcard2`, `set_vcard2_multi` - * `roster`: Adds `add_rosteritem`, `delete_rosteritem`, `process_rosteritems`, `get_roster`, `push_roster`, `push_roster_all`, `push_roster_alltoall` * `last`: Adds `set_last` + * `node`: Adds `load_config`, `get_cookie`, `remove_node` * `private`: Adds `private_get`, `private_set` + * `roster`: Adds `add_rosteritem`, `delete_rosteritem`, `process_rosteritems`, `get_roster`, `push_roster`, `push_roster_all`, `push_roster_alltoall` + * `sessions`: Adds `num_resources`, `resource_num`, `kick_session`, `status_num_host`, `status_num`, `status_list_host`, `status_list`, `connected_users_info`, `connected_users_vhost`, `user_sessions_info`, `set_presence` * `stanza`: Adds `send_message_chat`, `send_message_headline`, `send_stanza_c2s` * `stats`: Adds `stats`, `stats_host` + * `vcard`: Adds `get_vcard`, `get_vcard2`, `get_vcard2_multi`, `set_vcard`, `set_vcard2`, `set_vcard2_multi` ### Example configuration ` {mod_admin_extra, [{submods, [node, accounts, sessions]}]} ` diff --git a/doc/modules/mod_http_upload.md b/doc/modules/mod_http_upload.md index ef471ee2c1..8f172112ff 100644 --- a/doc/modules/mod_http_upload.md +++ b/doc/modules/mod_http_upload.md @@ -7,12 +7,13 @@ Currently, the module supports only the S3 backend using [AWS Signature Version ### Options +* **iqdisc** (default: `one_queue`) * **host** (string, default: `"upload.@HOST@"`): Subdomain for the upload service to reside under. `@HOST@` is replaced with each served domain. * **backend** (atom, default: `s3`) - Backend to use for generating slots. Currently only `s3` can be used. * **expiration_time** (integer, default: `60`) - Duration (in seconds) after which the generated `PUT` URL will become invalid. * **token_bytes** (integer, default: `32`) - Number of random bytes of a token that will be used in a generated URL. The text representation of the token will be twice as long as the number of bytes, e.g. for the default value the token in URL will be 64 characters long. -* **max_file_size** (integer, default: 10 MB) - Maximum file size (in bytes) accepted by the module. Disabled if set to `undefined`. +* **max_file_size** (integer, default: 10485760 (10 MB)) - Maximum file size (in bytes) accepted by the module. Disabled if set to `undefined`. * **s3** (list, default: unset) - Options specific to S3 backend. #### S3 backend options diff --git a/doc/modules/mod_muc.md b/doc/modules/mod_muc.md index 5ab7275384..1d59dc0446 100644 --- a/doc/modules/mod_muc.md +++ b/doc/modules/mod_muc.md @@ -3,7 +3,7 @@ This module implements [XEP-0045: Multi-User Chat](http://xmpp.org/extensions/xe It's a common XMPP group chat solution. This extension consists of two Erlang modules: `mod_muc` and `mod_muc_room`, the latter being the room code itself. Note that only `mod_muc` needs to be enabled in the configuration file. -Also `mod_muc_log` is a logging submodule. +Also `mod_muc_log` is a logging submodule. ### Options * `host` (string, default: `"conference.@HOST@"`): Subdomain for MUC service to reside under. @@ -21,15 +21,15 @@ Also `mod_muc_log` is a logging submodule. * `max_room_desc` (atom or positive integer, default: `infinite`): Maximum room description length. * `min_message_interval` (non-negative integer, default: 0): Minimal interval (in seconds) between messages processed by the room. * `min_presence_interval` (non-negative integer, default: 0): Minimal interval (in seconds) between presences processed by the room. -* `max_user` (positive integer, default: 200): Absolute maximum user count per room on the node. -* `max_users_admin_threshold` (positive integer, default: 5): Absolute maximum administrator count per room on the node. +* `max_users` (positive integer, default: 200): Absolute maximum user count per room on the node. +* `max_users_admin_threshold` (positive integer, default: 5): When the server checks if a new user can join a room and they are an admin, `max_users_admin_threshold` is added to `max_users` during occupant limit check. * `user_message_shaper` (atom, default: `none`): Shaper for user messages processed by a room (global for the room). * `user_presence_shaper` (atom, default: `none`): Shaper for user presences processed by a room (global for the room). * `max_user_conferences` (non-negative, default: 10): Specifies the number of rooms that a user can occupy simultaneously. * `http_auth_pool` (atom, default: `none`): If an external HTTP service is chosen to check passwords for password-protected rooms, this option specifies the HTTP pool name to use (see [External HTTP Authentication](#external-http-authentication) below). * `hibernate_timeout` (timeout, default: `90000`): Timeout (in milliseconds) defining the inactivity period after which the room's process should be hibernated. -* `hibernated_room_check_interval` (timeout, default: `infinity`): Interval defining how often the hibernated rooms will be checked. -* `hibernated_room_timeout` (timeout, default: `inifitniy`): A time after which a hibernated room is stopped (deeply hibernated). +* `hibernated_room_check_interval` (timeout, default: `infinity`): Interval defining how often the hibernated rooms will be checked (a timer is global for a node). +* `hibernated_room_timeout` (timeout, default: `inifitniy`): A time after which a hibernated room is stopped (deeply hibernated). See [MUC performance optimisation](#performance-optimisations). * `default_room_options` (list of key-value tuples, default: `[]`): List of room configuration options to be overridden in the initial state. * `title` (binary, default: `<<>>`): Room title, short free text. @@ -37,7 +37,7 @@ Also `mod_muc_log` is a logging submodule. * `allow_change_subj` (boolean, default: `true`): Allow all occupants to change the room subject. * `allow_query_users` (boolean, default: `true`): Allow occupants to send IQ queries to other occupants. * `allow_private_messages` (boolean, default: `true`): Allow private messaging between occupants. - * `allow_visitor_status` (boolean, default: `true`): Allow occupants to use text statuses in presences. + * `allow_visitor_status` (boolean, default: `true`): Allow occupants to use text statuses in presences. When disabled, text is removed by the room before broadcasting. * `allow_visitor_nickchange` (boolean, default: `true`): Allow occupants to change nicknames. * `public` (boolean, default: `true`): Room is included in the list available via Service Discovery. @@ -47,6 +47,7 @@ Also `mod_muc_log` is a logging submodule. * `members_by_default` (boolean, default: `true`): All new occupants are members by default, unless they have a different affiliation assigned. * `members_only` (boolean, default: `false`): Only users with a member affiliation can join the room. * `allow_user_invites` (boolean, default: `false`): Allow ordinary members to send mediated invitations. + * `allow_multiple_sessions` (boolean, default: `false`): Allow multiple user's session to use the same nick. * `password_protected` (boolean, default: `false`): Room is protected with a password. * `password` (binary, default: `<<>>`): Room password is required upon joining. This option has no effect when `password_protected` is `false`. @@ -54,6 +55,10 @@ Also `mod_muc_log` is a logging submodule. * `max_users` (positive integer, default: 200): Maximum user count per room. Admins and the room owner are not affected. * `logging` (boolean, default: `false`): Enables logging of room events (messages, presences) to a file on the disk. Uses `mod_muc_log`. + * `maygetmemberlist` (list of atoms, default: `[]`): A list of roles and/or privileges that grant privilege to retrieve room's member list like an admin. + * `affiliations` (list of `{{<<"user">>, <<"server">>, <<"resource">>}, affiliation}` tuples, default: `[]`): A default list of affiliations set for every new room. + * `subject` (binary, default: `<<>>`): A default subject for new room. + * `subject_author` (binary, default: `<<>>`): A default subject's author's nick. ### Example Configuration @@ -83,7 +88,7 @@ This optimisation works only for persistent rooms as only these can be restored The improvement works as follows: 1. All room processes are traversed at a chosen `hibernated_room_check_interval`. 1. If a `hibernated_room_timeout` is exceeded, a "stop" signal is sent to a unused room. -1. The room's process is stopped only if there is no online users or if the only one is its owner. +1. The room's process is stopped only if there are no online users or if the only one is its owner. If the owner is online, a presence of a type unavailable is sent to it indicating that the room's process is being terminated. The room's process can be recreated on demand, for example when a presence sent to it, or the owner wants to add more users to the room. diff --git a/doc/modules/mod_muc_light.md b/doc/modules/mod_muc_light.md index a055b01db4..9104b2999f 100644 --- a/doc/modules/mod_muc_light.md +++ b/doc/modules/mod_muc_light.md @@ -1,7 +1,7 @@ ### Module Description -This module implements [XEP Multi-User Chat Light](https://github.com/xsf/xeps/pull/118) (still being reviewed by XMPP community). -It's an experimental XMPP group chat solution. +This module implements [Multi-User Chat Light](../open-extensions/muc_light.md). +It's an experimental XMPP group chat solution. This extension consists of several modules but only `mod_muc_light` needs to be enabled in the config file. ### Options diff --git a/doc/modules/mod_muc_log.md b/doc/modules/mod_muc_log.md index da71c87939..371755be88 100644 --- a/doc/modules/mod_muc_log.md +++ b/doc/modules/mod_muc_log.md @@ -6,7 +6,7 @@ It writes room-related information (configuration) and events (messages, presenc ### Options * `outdir` (string, default: `"www/muc"`): Filesystem directory where the files are stored. -* `access_log` (atom, default: `muc_admin`): +* `access_log` (atom, default: `muc_admin`): ACL that defines who can enable/disable logging for specific rooms. * `dirtype` (atom, default: `subdirs`): Specifies the log directory structure. * `subdirs`: Module will use the following directory structure `[Logs root]/[dirname]/YYYY/MM/` with file names being `DD.[extension]`. * `plain`: Module will use the following directory structure `[Logs root]/[dirname]/` with file names being `YYYY-MM-DD.[extension]`. @@ -18,7 +18,7 @@ It writes room-related information (configuration) and events (messages, presenc * `plaintext`: Just a text file, better suited for processing than HTML. * `css_file` (binary or atom, default: `false`): * `false`: Uses default styles for HTML logs. - * `<<"path to custom CSS file">>`: Links custom CSS inside HTML logs. + * `<<"path to custom CSS file">>`: Links custom CSS inside HTML logs. Please note it won't be copied to logs directory but given path will be linked in HTML files instead. * `timezone` (atom, default: `local`): * `local`: Uses the local server timezone in dates written into the logs. * `universal`: Uses GMT in dates written into the logs. diff --git a/doc/modules/mod_pubsub.md b/doc/modules/mod_pubsub.md index a767c38bf3..f222c8ad49 100644 --- a/doc/modules/mod_pubsub.md +++ b/doc/modules/mod_pubsub.md @@ -1,6 +1,6 @@ ### What is PubSub? -PubSub is a fascinating design pattern which mostly promotes a loose coupling between two kinds of entities - publishers and subscribers. +PubSub is a design pattern which mostly promotes a loose coupling between two kinds of entities - publishers and subscribers. Like their names suggest, in the pubsub world we have publishers who fire events, and subscribers who wish to be notified about those events when publishers push data. There might be several subscribers, several publishers, and even several channels (or nodes) where the events are sent. @@ -13,51 +13,23 @@ It's all about tailoring PubSub to your needs! ### Options +* `iqdisc` (default: `one_queue`) * `host` (string, default: `"pubsub.@HOST@"`): Subdomain for Pubsub service to reside under. `@HOST@` is replaced with each served domain. * `access_create` (atom, default: `all`): Who is allowed to create pubsub nodes. * `max_items_node` (integer, default: `10`): Define the maximum number of items that can be stored in a node. * `max_subscriptions_node` (integer, default: `undefined` - no limitation): The maximum number of subscriptions managed by a node. -* `nodetree` (binary, default: `<<"tree">>`): Specifies the storage and organisation of the pubsub nodes. -Called on `get`, `create` and `delete` node. -Only one nodetree can be used per host and is shared by all node plugins. - * `<<"tree">>"` - store nodes in a database (only mnesia supported). - * `<<"virtual">>` - does not store nodes in a database. - This saves resources on systems when the number of nodes is large. - When using the `<<“virtual”>>` nodetree, you can only enable these node plugins: - `[<<“flat”>>,<<“pep”>>]` or `[<<“flat”>>]`; any other plugin configuration will not work. - Also, all nodes will have the defaut configuration, and this can not be changed. - Using the `<<“virtual”>>` nodetree requires the pubsub module to be started with a clean database, it will not work if you used the default `<<“tree”>>` nodetree before. - * `<<"dag">>"` - provides experimental support for [XEP-0248 (PubSub Collection Nodes)](http://xmpp.org/extensions/xep-0248.html). - In this case you should also add the `<<“dag”>>` node plugin as default, for example: plugins: `[<<"dag">>,<<"flat">>,<<"hometree">>,<<"pep">>]` +* `nodetree` (binary, default: `<<"tree">>`): Specifies the storage and organisation of the pubsub nodes. See the section below. * `ignore_pep_from_offline` (boolean, default: `true`): specify whether or not we should get last published PEP items from users in our roster which are offline when we connect. The default option is `true` hence we will get only the last items from the online contacts. * `last_item_cache` (boolean, default `false`): specifies whether or not pubsub should cache the last items. Such an option provides the ability to send the last published item to a new subscriber. Such caching might speed up pubsub's performance and can increase the number of user connections but in price of memory usage. * `plugins` ([Plugin, ...], default: `[<<"flat">>]`): List of enabled pubsub plugins. -They handle affiliations, subscriptions and items and also provide default node configuration and features. -PubSub clients can define which plugin to use when creating a node by adding `type=’plugin-name’` attribute to the create stanza element. -If such an attribute is not specified, the default plugin will be the first on the plugin list. - * `<<"flat">>` - No node hierarchy. - It handles the standard PubSub case. - * `<<"hometree">>` - Uses the exact same features as the flat plugin but additionally organises nodes in a tree. - Basically it follows a scheme similar to the filesystem's structure. - Every user can create nodes in its own home root: e.g `/home/user`. - Each node can contain items and/or sub-nodes. - * `<<"pep">>` - implementation of [XEP-0060 (Personal Eventing Protocol)](http://xmpp.org/extensions/xep-0163.html). - In this case, items are not persisted but kept in an in-memory cache. - When the `pep` plugin is enabled, a user can have their own node (exposed as their bare jid) with a common namespace. - Requires module `mod_caps` to be enabled. - * `<<"dag">>` - implementation of [XEP-0248 (PubSub Collection Nodes)](https://xmpp.org/extensions/xep-0248.html). - Every node takes a place in a tree and is either a collection node (and have only sub-nodes) or a leaf node (contains only items). - * `<<"push"">>` - special node type that may be used as a target node for [XEP-0357 (Push Notifications)](https://xmpp.org/extensions/xep-0357.html) capable services (e.g. `mod_push`). - For each published notification, a hook `push_notification` is run. - You may enable as many modules that support this hook (all module with `mod_push_service_*` name prefix) as you like (see for example `mod_push_service_mongoosepush`). - This node type **requires** `publish-options` with at least `device_id` and `service` fields supplied. * `pep_mapping` ([{Key, Value}, ...]): This permits creating a Key-Value list to define a custom node plugin on a given PEP namespace. E.g. pair `{"urn:xmpp:microblog:0", "mb"}` will use module `node_mb` instead of `node_pep` when the specified namespace is used. * `default_node_config` ([{Key, Value}, ...]): Overrides the default node configuration, regradless of the node plugin. Node configuration still uses the default configuration defined by the node plugin, and overrides any items by the value defined in this configurable list. +* `item_publisher` (boolean, default: `false`): When enabled, JID of the publisher will be saved in item metadata. This effectively makes them an owner of this item. ### Example Configuration @@ -69,3 +41,64 @@ Node configuration still uses the default configuration defined by the node plug {plugins, [<<"flat">>, <<"pep">>]}} ]}, ``` + +### Nodetrees + +Called on `get`, `create` and `delete` node. +Only one nodetree can be used per host and is shared by all node plugins. + +#### `<<"tree">>` + +Stores nodes in a database (only mnesia supported). + +#### `<<"virtual">>` + +Does not store nodes in a database. +This saves resources on systems when the number of nodes is large. +When using the `<<"virtual">>` nodetree, you can only enable these node plugins: `[<<“flat”>>,<<“pep”>>]` or `[<<“flat”>>]`; any other plugin configuration will not work. +Also, all nodes will have the defaut configuration, and this can not be changed. + +Using the `<<“virtual”>>` nodetree requires the pubsub module to be started with a clean database, it will not work if you used the default `<<“tree”>>` nodetree before. + +#### `<<"dag">>` + +Provides experimental support for [XEP-0248 (PubSub Collection Nodes)](http://xmpp.org/extensions/xep-0248.html). +In this case you should also add the `<<"dag">>` node plugin as default, for example: `{plugins, [<<"dag">>,<<"flat">>,<<"hometree">>,<<"pep">>]}` + +### Plugins + +They handle affiliations, subscriptions and items and also provide default node configuration and features. +PubSub clients can define which plugin to use when creating a node by adding `type='plugin-name'` attribute to the create stanza element. +If such an attribute is not specified, the default plugin will be the first on the plugin list. + +#### `<<"flat">>` + +No node hierarchy. +It handles the standard PubSub case. + +#### `<<"hometree">>` + +Uses the exact same features as the flat plugin but additionally organises nodes in a tree. +Basically it follows a scheme similar to the filesystem's structure. +Every user can create nodes in its own home root: e.g `/home/user`. +Each node can contain items and/or sub-nodes. + +#### `<<"pep">>` + +Implementation of [XEP-0060 (Personal Eventing Protocol)](http://xmpp.org/extensions/xep-0163.html). +In this case, items are not persisted but kept in an in-memory cache. +When the `pep` plugin is enabled, a user can have their own node (exposed as their bare jid) with a common namespace. +Requires module `mod_caps` to be enabled. + +#### `<<"dag">>` + +Implementation of [XEP-0248 (PubSub Collection Nodes)](https://xmpp.org/extensions/xep-0248.html). +Every node takes a place in a tree and is either a collection node (and have only sub-nodes) or a leaf node (contains only items). + +#### `<<"push">>` + +Special node type that may be used as a target node for [XEP-0357 (Push Notifications)](https://xmpp.org/extensions/xep-0357.html) capable services (e.g. `mod_push`). +For each published notification, a hook `push_notification` is run. +You may enable as many modules that support this hook (all module with `mod_push_service_*` name prefix) as you like (see for example `mod_push_service_mongoosepush`). +This node type **requires** `publish-options` with at least `device_id` and `service` fields supplied. + diff --git a/doc/modules/mod_register.md b/doc/modules/mod_register.md index 0483f5e5bf..03f5dd807b 100644 --- a/doc/modules/mod_register.md +++ b/doc/modules/mod_register.md @@ -3,13 +3,14 @@ This module implements [XEP-0077: In-Band Registration](http://xmpp.org/extensio ### Options -* `iqdisc` +* `iqdisc` (default: `one_queue`) * `access` (atom, default: `all`): Defines which ACL should be used for checking if a chosen username is allowed for registration. * `welcome_message` (`{Subject :: string(), Body :: string()}`, default: `{"", ""}`): Body and subject of a `` stanza sent to new users. * `registration_watchers` (list of binaries, default: `[]`): List of JIDs, which should receive a `` notification about every successful registration. -* `access_from` (atom, default: `none`): Allow registrations from existing C2S connections or S2S, that match specified ACL. **Use with caution!** * `password_strength` (non-negative integer, default: 0): Specifies minimal entropy of allowed password. - Entropy is measured with `ejabberd_auth:entropy/1`. Recommended minimum is 32. + Entropy is measured with `ejabberd_auth:entropy/1`. + Recommended minimum is 32. + Entropy calculation algorithm is described in a section below. * `ip_access` (list of `{deny|allow, StringIP|StringSubnet, default: `[]`): Access list for specified IPs or networks. Default value allows registration from every IP. @@ -24,3 +25,28 @@ Deny registration from network 10.20.0.0 with mask 255.255.0.0. ``` {mod_register, [{deny, "10.20.0.0/16"}]} ``` + +### Entropy calculation algorithm + +``` +Entropy = length(Password) * log(X) / log(2) +``` + +Where `X` is initially set to 0 and certain values are added if at least one of these bytes are present: + +* Lower case character: 26 +* Upper case character: 26 +* Digit: 9 +* Printable ASCII (0x21 - 0x7e): 33 +* Any other value: 128 + +*Note:* These values are added only once, no matter how many bytes of specific type are found. + +#### Example entropies: + +* `kotek`: ~23.5 +* `abc123`: ~30.8 +* `L33tSp34k`: ~53.4 +* `CamelCase`: ~51.3 +* `lowUP1#:`: ~45.9 +* `lowUP1#❤`: ~78 diff --git a/doc/modules/mod_vcard.md b/doc/modules/mod_vcard.md index ad9c74d41e..a7f48668bd 100644 --- a/doc/modules/mod_vcard.md +++ b/doc/modules/mod_vcard.md @@ -3,7 +3,7 @@ This module provides support for vCards, as specified in [XEP-0054: vcard-temp]( ### Options -* `iqdisc` +* `iqdisc` (default: `one_queue`) * `host` (string, default: `"vjud.@HOST@"`): Domain of the vCard User Directory, used for searching. `@HOST@` is replaced with the domain(s) supported by the cluster. * `search` (boolean, default: `true`): Enables/disables the domain set in previous option. @@ -20,6 +20,8 @@ This module provides support for vCards, as specified in [XEP-0054: vcard-temp]( For the default setting, please see `[MongooseIM root]/apps/ejabberd/src/mod_vcard_ldap.erl`, line 96. * `ldap_search_reported` (list of `{SearchField, VCardField}`, default: see description): Mappings between the human-readable search fields and VCard fields. For the default setting, please see `[MongooseIM root]/apps/ejabberd/src/mod_vcard_ldap.erl`, line 109. +* `ldap_search_operator` (`or` | `and`, default: `and`): A default operator used for search query items. +* `ldap_binary_search_fields` (list of binaries, default: `[]`): A list of search fields, which values should be Base64-encoded by MongooseIM before sending to LDAP. ### Example Configuration ``` @@ -27,6 +29,6 @@ This module provides support for vCards, as specified in [XEP-0054: vcard-temp]( {search_all_hosts, true}, {matches, 1}, {search, true}, - {host, "directory.example.com"} + {host, "directory.example.com"} ]} ``` From 8e7521e1b364f4b88f21ed6a47bf3367cf9969d2 Mon Sep 17 00:00:00 2001 From: "K. Kraus" Date: Thu, 11 May 2017 13:26:58 +0200 Subject: [PATCH 2/5] [skip ci] mod_muc --- doc/modules/mod_muc.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/modules/mod_muc.md b/doc/modules/mod_muc.md index 1d59dc0446..03126f8b29 100644 --- a/doc/modules/mod_muc.md +++ b/doc/modules/mod_muc.md @@ -47,7 +47,7 @@ Also `mod_muc_log` is a logging submodule. * `members_by_default` (boolean, default: `true`): All new occupants are members by default, unless they have a different affiliation assigned. * `members_only` (boolean, default: `false`): Only users with a member affiliation can join the room. * `allow_user_invites` (boolean, default: `false`): Allow ordinary members to send mediated invitations. - * `allow_multiple_sessions` (boolean, default: `false`): Allow multiple user's session to use the same nick. + * `allow_multiple_sessions` (boolean, default: `false`): Allow multiple user session to use the same nick. * `password_protected` (boolean, default: `false`): Room is protected with a password. * `password` (binary, default: `<<>>`): Room password is required upon joining. This option has no effect when `password_protected` is `false`. @@ -55,10 +55,10 @@ Also `mod_muc_log` is a logging submodule. * `max_users` (positive integer, default: 200): Maximum user count per room. Admins and the room owner are not affected. * `logging` (boolean, default: `false`): Enables logging of room events (messages, presences) to a file on the disk. Uses `mod_muc_log`. - * `maygetmemberlist` (list of atoms, default: `[]`): A list of roles and/or privileges that grant privilege to retrieve room's member list like an admin. + * `maygetmemberlist` (list of atoms, default: `[]`): A list of roles and/or privileges that enable retrieving the room's member list. * `affiliations` (list of `{{<<"user">>, <<"server">>, <<"resource">>}, affiliation}` tuples, default: `[]`): A default list of affiliations set for every new room. * `subject` (binary, default: `<<>>`): A default subject for new room. - * `subject_author` (binary, default: `<<>>`): A default subject's author's nick. + * `subject_author` (binary, default: `<<>>`): A nick name of the default subject's author. ### Example Configuration From 17ed20a4d285066c2607c2864bd9fe38d354955f Mon Sep 17 00:00:00 2001 From: "K. Kraus" Date: Thu, 11 May 2017 13:29:02 +0200 Subject: [PATCH 3/5] [skip ci] muc log --- doc/modules/mod_muc_log.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/modules/mod_muc_log.md b/doc/modules/mod_muc_log.md index 371755be88..7b13f10946 100644 --- a/doc/modules/mod_muc_log.md +++ b/doc/modules/mod_muc_log.md @@ -18,7 +18,7 @@ It writes room-related information (configuration) and events (messages, presenc * `plaintext`: Just a text file, better suited for processing than HTML. * `css_file` (binary or atom, default: `false`): * `false`: Uses default styles for HTML logs. - * `<<"path to custom CSS file">>`: Links custom CSS inside HTML logs. Please note it won't be copied to logs directory but given path will be linked in HTML files instead. + * `<<"path to custom CSS file">>`: Links custom CSS inside HTML logs. Please note it won't be copied to the logs directory but the given path will be linked in HTML files instead. * `timezone` (atom, default: `local`): * `local`: Uses the local server timezone in dates written into the logs. * `universal`: Uses GMT in dates written into the logs. From 8cc3509fa51d0f077ce4f1567a54d79d5aae8a84 Mon Sep 17 00:00:00 2001 From: "K. Kraus" Date: Thu, 11 May 2017 13:33:01 +0200 Subject: [PATCH 4/5] [skip ci] pub sub --- doc/modules/mod_pubsub.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/modules/mod_pubsub.md b/doc/modules/mod_pubsub.md index f222c8ad49..9154681e11 100644 --- a/doc/modules/mod_pubsub.md +++ b/doc/modules/mod_pubsub.md @@ -29,7 +29,8 @@ Such caching might speed up pubsub's performance and can increase the number of E.g. pair `{"urn:xmpp:microblog:0", "mb"}` will use module `node_mb` instead of `node_pep` when the specified namespace is used. * `default_node_config` ([{Key, Value}, ...]): Overrides the default node configuration, regradless of the node plugin. Node configuration still uses the default configuration defined by the node plugin, and overrides any items by the value defined in this configurable list. -* `item_publisher` (boolean, default: `false`): When enabled, JID of the publisher will be saved in item metadata. This effectively makes them an owner of this item. +* `item_publisher` (boolean, default: `false`): When enabled, a JID of the publisher will be saved in the item metadata. + This effectively makes them an owner of this item. ### Example Configuration @@ -80,7 +81,7 @@ It handles the standard PubSub case. Uses the exact same features as the flat plugin but additionally organises nodes in a tree. Basically it follows a scheme similar to the filesystem's structure. -Every user can create nodes in its own home root: e.g `/home/user`. +Every user can create nodes in their own home root: e.g `/home/user`. Each node can contain items and/or sub-nodes. #### `<<"pep">>` From 4ad1126dd0cd8dc713009f80bd0f95545fc2a196 Mon Sep 17 00:00:00 2001 From: "K. Kraus" Date: Thu, 11 May 2017 13:34:05 +0200 Subject: [PATCH 5/5] [skip ci] register --- doc/modules/mod_register.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/modules/mod_register.md b/doc/modules/mod_register.md index 03f5dd807b..133106d1ce 100644 --- a/doc/modules/mod_register.md +++ b/doc/modules/mod_register.md @@ -10,7 +10,7 @@ This module implements [XEP-0077: In-Band Registration](http://xmpp.org/extensio * `password_strength` (non-negative integer, default: 0): Specifies minimal entropy of allowed password. Entropy is measured with `ejabberd_auth:entropy/1`. Recommended minimum is 32. - Entropy calculation algorithm is described in a section below. + The entropy calculation algorithm is described in a section below. * `ip_access` (list of `{deny|allow, StringIP|StringSubnet, default: `[]`): Access list for specified IPs or networks. Default value allows registration from every IP.