Add missing CETS docs and enable Mnesia by default

doc/configuration/general.md

@@ -142,14 +142,17 @@ According to RFC 6210, even when a client sends invalid data after opening a con
 These options can be used to configure the way MongooseIM manages user sessions.
 
 ### `general.sm_backend`
-* **Syntax:** string, `"mnesia"`, `"cets"` or `"redis"`
+* **Syntax:** string: `"mnesia"`, `"cets"` or `"redis"`
 * **Default:** `"mnesia"`
 * **Example:** `sm_backend = "redis"`
 
 Backend for storing user session data. All nodes in a cluster must have access to a complete session database.
 Mnesia is sufficient in most cases, use Redis only in large deployments when you notice issues with the mnesia backend. Requires a redis pool with the `default` tag defined in the `outgoing_pools` section.
 See the section about [redis connection setup](./outgoing-connections.md#redis-specific-options) for more information.
 
+!!! Warning
+    When set to `mnesia` or `cets`, the corresponding [internal database](internal-databases.md) has to be enabled.
+
 ### `general.replaced_wait_timeout`
 * **Syntax:** positive integer, representing time in milliseconds
 * **Default:** `2000`
@@ -160,12 +163,27 @@ When a user's session is replaced (due to a full JID conflict) by a new one, thi
 ## XMPP federation (S2S)
 
 ### `general.s2s_backend`
-* **Syntax:** string, `"mnesia"`, `"cets"`
+* **Syntax:** string: `"mnesia"` or `"cets"`
 * **Default:** `"mnesia"`
 * **Example:** `s2s_backend = "cets"`
 
 Backend for replicating the list of outgoing Server to Server (S2S) connections across the nodes of the local MongooseIM cluster.
 
+!!! Warning
+    The corresponding [internal database](internal-databases.md) has to be enabled.
+
+## External XMPP components
+
+### `general.component_backend`
+* **Syntax:** string: `"mnesia"` or `"cets"`
+* **Default:** `"mnesia"`
+* **Example:** `component_backend = "cets"`
+
+Backend for replicating the list of connected external components across the nodes of the local MongooseIM cluster.
+
+!!! Warning
+    The corresponding [internal database](internal-databases.md) has to be enabled.
+
 ## Message routing
 
 The following options influence the way MongooseIM routes incoming messages to their recipients.

doc/configuration/internal-databases.md

@@ -1,45 +1,44 @@
-Internal databases are used to cluster MongooseIM nodes, and to replicate session list data between them.
+Internal databases are used to cluster MongooseIM nodes, and to replicate in-memory data (e.g. client sessions) between them.
 
 Mnesia is a legacy way to cluster MongooseIM nodes. It is also could be used to store persistent data, but we recommend
 to use RDBMS databases instead because of scalability and stability reasons.
 
 CETS is a new way to cluster MongooseIM nodes.
 CETS needs to know a list of nodes for the node discovery. There are two ways to get a list of nodes:
 
+- RDBMS database. MongooseIM would write into RDBMS its nodename and read a list of other nodes.
+This is the best option if you are already using a relational database.
 - A text file with a list of nodes on each line. It is useful when there is an external script to make this file based on
   some custom logic (for example, a bash script that uses AWS CLI to discover instances in the autoscaling group). This file
-  would be automatilly reread on change.
-- RDBMS database. MongooseIM would write into RDBMS its nodename and read a list of other nodes. It is pretty simple, but
-  RDBMS database could be a single point of failure.
+  would be automatically reread on change.
 
-Section example:
+Omitting this section entirely is equivalent to having only Mnesia enabled:
 
 ```toml
-[internal_databases]
-    [internal_databases.mnesia]
-
-    [internal_databases.cets]
-        backend = "rdbms"
-        cluster_name = "mongooseim"
+[internal_databases.mnesia]
 ```
 
-or
+The following example enables only CETS with the default RDBMS discovery backend:
 
 ```toml
-[internal_databases]
-    [internal_databases.cets]
-        backend = "file"
-        node_list_file = "cets_disco.txt"
+[internal_databases.cets]
 ```
 
-To enable just CETS, define only `internal_databases.cets` section:
+!!! Warning
+    When switching to CETS, you need to configure particular backends to actually use it:
+
+    * general backends: [`sm_backend`](general.md#generalsm_backend), [`s2s_backend`](general.md#generals2s_backend), [`component_backend`](general.md#generalcomponent_backend)
+    * module backends: [`mod_bosh`](../modules/mod_bosh.md#modulesmod_boshbackend), [`mod_stream_management`](../modules/mod_stream_management.md#modulesmod_stream_managementbackend), [`mod_jingle_sip`](../modules/mod_jingle_sip.md#modulesmod_jingle_sipbackend)
+
+Sometimes you might want to have both databases enabled and choose which backends use a particular DB:
 
 ```toml
-[internal_databases]
-    [internal_databases.cets]
+[internal_databases.mnesia]
+
+[internal_databases.cets]
 ```
 
-# CETS Options
+## CETS Options
 
 ### `internal_databases.cets.backend`
 
@@ -65,3 +64,14 @@ Required, if `backend = "file"`.
 * **Syntax:** path.
 * **Default:** not specified.
 * **Example:** `node_list_file = "/etc/mim_nodes.txt"`
+
+### Example
+
+The following example enables CETS with the file discovery backend:
+
+```toml
+
+[internal_databases.cets]
+    backend = "file"
+    node_list_file = "cets_disco.txt"
+```

doc/migrations/6.1.0_6.2.0.md

@@ -0,0 +1,6 @@
+## Internal databases
+
+So far MongooseIM has been using the internal Mnesia database to replicate the in-memory data between cluster nodes.
+Now there is an option to use [CETS](https://github.com/esl/cets/) instead.
+Mnesia is still used by default, so you don't need to change your configuration file.
+If you want to switch to CETS, see [`internal_databases`](../configuration/internal-databases.md).

doc/modules/mod_bosh.md

@@ -9,11 +9,14 @@ If you want to use BOSH, you must enable it both in the `listen` section of
 ## Options
 
 ### `modules.mod_bosh.backend`
-* **Syntax:** non-empty string
+* **Syntax:** string: `"mnesia"` or `"cets"`
 * **Default:** `"mnesia"`
 * **Example:** `backend = "mnesia"`
 
-Backend to use for storing BOSH connections. `"cets"`, `"mnesia"` are supported.
+Backend to use for storing BOSH connections.
+
+!!! Warning
+    The corresponding [internal database](../configuration/internal-databases.md) has to be enabled.
 
 ### `modules.mod_bosh.inactivity`
  * **Syntax:** positive integer or the string `"infinity"`

doc/modules/mod_jingle_sip.md

@@ -103,12 +103,15 @@ MongooseIM packages are built with Jingle/SIP support.
 ## Options
 
 ### `modules.mod_jingle_sip.backend`
-* **Syntax:** string, `"mnesia"`, `"cets"`
+* **Syntax:** string: `"mnesia"` or `"cets"`
 * **Default:** `"mnesia"`
 * **Example:** `backend = "cets"`
 
 Backend for in-memory data for this module.
 
+!!! Warning
+    The corresponding [internal database](../configuration/internal-databases.md) has to be enabled.
+
 ### `modules.mod_jingle_sip.proxy_host`
 * **Syntax:** string
 * **Default:** `"localhost"`

doc/modules/mod_stream_management.md

@@ -7,11 +7,14 @@ the management of the session tables and configuration.
 ## Options
 
 ### `modules.mod_stream_management.backend`
-* **Syntax:** string.
-* **Default:** "mnesia"
+* **Syntax:** string: `"mnesia"` or `"cets"`
+* **Default:** `"mnesia"`
 * **Example:** `backend = "mnesia"`
 
-Currently, only "mnesia" is supported.
+Backend for in-memory session data stored by this module.
+
+!!! Warning
+    The corresponding [internal database](../configuration/internal-databases.md) has to be enabled.
 
 ### `modules.mod_stream_management.buffer`
 * **Syntax:** boolean

mkdocs.yml

@@ -189,6 +189,7 @@ nav:
       - '5.0.0 to 5.1.0': 'migrations/5.0.0_5.1.0.md'
       - '5.1.0 to 6.0.0': 'migrations/5.1.0_6.0.0.md'
       - '6.0.0 to 6.1.0': 'migrations/6.0.0_6.1.0.md'
+      - '6.1.0 to 6.2.0': 'migrations/6.1.0_6.2.0.md'
       - 'MAM MUC migration helper': 'migrations/jid-from-mam-muc-script.md'
   - 'Contributions to the Ecosystem': 'Contributions.md'
   - 'MongooseIM History': 'History.md'

rel/vars-toml.config

@@ -17,8 +17,7 @@
 {http_api_client_endpoint, "port = {{ http_api_client_endpoint_port }}"}.
 {s2s_use_starttls, "\"optional\""}.
 {s2s_certfile, "\"priv/ssl/fake_server.pem\""}.
-{internal_databases, "[internal_databases]
-    [internal_databases.mnesia]"}.
+{internal_databases, "[internal_databases.mnesia]"}.
 
 "./configure.vars.config".
 

src/config/mongoose_config_spec.erl

@@ -100,6 +100,7 @@ root() ->
                  <<"host_config">> => #list{items = host_config(),
                                             wrap = none}
                 },
+       defaults = #{<<"internal_databases">> => default_internal_databases()},
        required = [<<"general">>],
        process = fun ?MODULE:process_root/1,
        wrap = none,
@@ -443,10 +444,12 @@ internal_databases() ->
               <<"mnesia">> => internal_database_mnesia()},
     #section{items = Items,
              format_items = map,
-             wrap = global_config,
-             include = always}.
+             wrap = global_config}.
+
+default_internal_databases() ->
+    #{mnesia => #{}}.
 
-%% path: internal_databases.*.*
+%% path: internal_databases.cets
 internal_database_cets() ->
     #section{
        items = #{<<"backend">> => #option{type = atom,
@@ -459,7 +462,7 @@ internal_database_cets() ->
        defaults = #{<<"backend">> => rdbms, <<"cluster_name">> => mongooseim}
       }.
 
-%% path: internal_databases.*.*
+%% path: internal_databases.mnesia
 internal_database_mnesia() ->
     #section{}.
 

test/common/config_parser_helper.erl

@@ -14,7 +14,7 @@ options("host_types") ->
       [<<"this is host type">>, <<"some host type">>,
        <<"another host type">>, <<"yet another host type">>]},
      {hosts, [<<"localhost">>]},
-     {internal_databases, #{}},
+     {internal_databases, #{mnesia => #{}}},
      {language, <<"en">>},
      {listen, []},
      {loglevel, warning},
@@ -317,7 +317,7 @@ options("outgoing_pools") ->
      {host_types, []},
      {hosts,
       [<<"localhost">>, <<"anonymous.localhost">>, <<"localhost.bis">>]},
-     {internal_databases, #{}},
+     {internal_databases, #{mnesia => #{}}},
      {language, <<"en">>},
      {listen, []},
      {loglevel, warning},
@@ -381,7 +381,7 @@ options("s2s_only") ->
      {hide_service_name, false},
      {host_types, []},
      {hosts, [<<"localhost">>, <<"dummy_host">>]},
-     {internal_databases, #{}},
+     {internal_databases, #{mnesia => #{}}},
      {language, <<"en">>},
      {listen, []},
      {loglevel, warning},

test/config_parser_SUITE.erl

@@ -1182,8 +1182,8 @@ internal_database_cets(_Config) ->
     CetsEnabled = #{<<"internal_databases">> => #{<<"cets">> => #{}}},
     CetsFile = #{<<"internal_databases">> => #{<<"cets">> =>
         #{<<"backend">> => <<"file">>, <<"node_list_file">> => <<"/dev/null">>}}},
-    %% No internal_databases section means an empty list of databases
-    ?cfg([internal_databases], #{}, #{}), % default
+    %% No internal_databases section means only mnesia
+    ?cfg([internal_databases], #{mnesia => #{}}, #{}), % default
     %% Empty internal_databases could be configured explicitly
     ?cfg([internal_databases], #{}, #{<<"internal_databases">> => #{}}),
 

test/config_parser_SUITE_data/miscellaneous.toml

@@ -80,6 +80,6 @@
   tracking_id.id = "G-12345678"
   tracking_id.secret = "Secret"
 
-[internal_databases]
-  [internal_databases.mnesia]
-  [internal_databases.cets]
+[internal_databases.mnesia]
+
+[internal_databases.cets]

test/config_parser_SUITE_data/modules.toml

@@ -5,8 +5,7 @@
   ]
   default_server_domain = "localhost"
 
-[internal_databases]
-  [internal_databases.mnesia]
+[internal_databases.mnesia]
 
 [modules.mod_adhoc]
   iqdisc.type = "one_queue"

test/config_parser_SUITE_data/mongooseim-pgsql.toml

@@ -12,9 +12,9 @@
   sm_backend = "mnesia"
   max_fsm_queue = 1000
 
-[internal_databases]
-  [internal_databases.mnesia]
-  [internal_databases.cets]
+[internal_databases.mnesia]
+
+[internal_databases.cets]
 
 [[listen.http]]
   port = 5280

test/mongoose_config_SUITE.erl

@@ -176,7 +176,7 @@ minimal_config_opts() ->
      {hide_service_name, false},
      {host_types, []},
      {hosts, [<<"localhost">>]},
-     {internal_databases, #{}},
+     {internal_databases, #{mnesia => #{}}},
      {language, <<"en">>},
      {listen, []},
      {loglevel, warning},