Add migration guide for mongoose_c2s

doc/migrations/6.0.0_6.1.0.md

@@ -0,0 +1,46 @@
+## Listener configuration
+
+With the new implementation of the client-to-server (C2S) state machine, `mongoose_c2s`, there are some changes in the listener options:
+
+* The `zlib` option for supporting [stream compression](https://xmpp.org/extensions/xep-0138.html), which was present in the default configuration file, is removed, and **you need to delete it** from your listener configuration unless you have already done so. The extension is [obsolete due to security vulnerability](https://xmpp.org/extensions/xep-0138.html#revision-history-v2.1), and the [CRIME](https://en.wikipedia.org/wiki/CRIME) vulnerability has been found [a long time ago](https://blog.thijsalkema.de/blog/2014/08/07/https-attacks-and-xmpp-2-crime-and-breach/).
+* The `max_fsm_queue` option is no longer supported for C2S listeners. It is incompatible with the new `gen_statem` state machine, and if you need to limit incoming traffic, you should use [traffic shapers](../../configuration/shaper) instead. You need to remove this option from your C2S configuration if you are using it.
+* The default value of the [`backlog`](../../configuration/listen#listenbacklog) option for all XMPP listeners has been increased from 100 to 1024 for performance reasons.
+* You might be interested in the new C2S listener options: [`max_connections`](../../configuration/listen#listenc2smax_connections), [`c2s_state_timeout`](../../configuration/listen#listenc2sc2s_state_timeout), [`reuse_port`](../../configuration/listen#listenc2sreuse_port) and [`backwards_compatible_session`](../../configuration/listen#listenc2sbackwards_compatible_session). The first two options can be set for [websockets](../../configuration/listen#handler-types-websockets-mod_websockets) as well.
+
+## Module configuration
+
+The `mongoose_c2s` module, which provides the core XMPP features, is now separated from modules which used to have their parts hardcoded into the old C2S implementation:
+
+* Presence handling has been exported to a separate module [`mod_presence`](../../modules/mod_presence), which is enabled in the default configuration file. **Enable `mod_presence` in your configuration file** unless you are sure that you don't need server-side presence handling, in which case you could gain some performance by not using this module.
+* Stream management is now handled completely by [`mod_stream_management`](../../modules/mod_stream_management), and if you don't need it, you can now gain more performance than before by disabling it.
+* Client state indication is now handled completely by [`mod_csi`](../../modules/mod_csi), and if you don't need it, you can now gain more performance than before by disabling it.
+
+## Database migration
+
+There is no database migration required when upgrading from version `6.0.0` to `6.1.0`.
+
+## Metrics
+
+The `c2s_unauthenticated_iq` metric has been removed.
+
+## Hooks
+
+Multiple hooks have been added, removed or changed because of the introduction of `mongoose_c2s` - the most important change is the increased granularity of the `user_send_*` and `user_receive_*` hooks. If you have some custom modules (e.g. that implement some XMPP extensions) using the hooks mechanism, please refactor your handlers to be compliant with the new hooks. Refer to [Hooks Description](../../developers-guide/hooks_description) and [Message routing](../../developers-guide/Stanza-routing) for more details.
+
+## Upgrade procedure
+
+As long as you are not using Mnesia for persistent storage (it is not recommended to do so), the safest option would be to prepare a new cluster with version 6.1.0, and switch the traffic to it on a load balancer. The only downside is that clients connected to different clusters would see each other as offline. If you are limited to one cluster, it is recommended to do a split-cluster rolling upgrade by [removing](../../operation-and-maintenance/Cluster-configuration-and-node-management/#leaving-cluster) each node from the cluster before stopping and upgrading it, and gradually forming a **new separate cluster** from the upgraded nodes. This means that for each newly started node except the first one, you should [join](../../operation-and-maintenance/Cluster-configuration-and-node-management/#new-node-joining-cluster) one of the previously started nodes.
+
+### Rolling upgrade issues
+
+If you want to perform a typical [rolling upgrade](../../operation-and-maintenance/Rolling-upgrade) instead, there are a few potential issues caused by the introduction of `mongoose_c2s`. When a node is stopped, upgraded and started again, it reconnects to the cluster. When a stanza is routed between users connected to different nodes of the cluster, an internal message is sent between the nodes. In version 6.1.0 that message has a different format, and routing a stanza between nodes with versions 6.0.0 and 6.1.0 would fail, resulting in a warning message for each stanza. This means that after upgrading the first node you might get a huge amount of warning messages on all nodes, causing a performance drop. What is more, the sender's node would still assume that the recipient is online, and some actions (e.g. responding with the `service-unavailable` error) would be omitted.
+
+!!! Info "Changing the log level"
+    You can set the log level to `error` during the upgrade to silence the excess warnings.
+    Before the upgrade, set the log level on all nodes:
+    ```bash
+    mongooseimctl server setLoglevel --level ERROR
+    ```
+    Before starting the upgraded node, set the [`loglevel`](../../configuration/general/#generalloglevel) option to `error` in the configuration file.
+    After the whole upgrade procedure, use `mongooseimctl` to change the log level back to the previous value (`warning` by default).
+    Change the values in the configuration files as well to make the setting permanent.

mkdocs.yml

@@ -186,6 +186,7 @@ nav:
       - '4.2.0 to 5.0.0': 'migrations/4.2.0_5.0.0.md'
       - '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'
       - 'MAM MUC migration helper': 'migrations/jid-from-mam-muc-script.md'
   - 'Contributions to the Ecosystem': 'Contributions.md'
   - 'MongooseIM History': 'History.md'