ZTD-1233-Rename-active-replica-in-User-Mail-Replica

Jenkinsfile

@@ -31,7 +31,6 @@ pipeline {
       steps {
         container('python-312') {
           sh '''
-git fetch --unshallow
 python3 -m venv .
 . bin/activate
 pip3 install -r requirements.txt

source/_includes/_admincli/docs-tables.rst

@@ -0,0 +1,19 @@
+The following table shows the keys and their default values to
+configure the maximum file size of documents that |docs| can manage
+and open.
+
+.. _docs-sizeopt:
+
+.. card:: File sizes
+
+   The following values can be modified via the |mesh| interface (see
+   Section :ref:`mesh-gui`) or via the CLI, using the commands
+   presented in the :ref:`previous section <modify-kv>`.
+
+   .. csv-table::
+      :header: "Key name", "Default value"
+      :widths: 70, 30
+
+      "carbonio-docs-connector/max-file-size-in-mb/document", "50"
+      "carbonio-docs-connector/max-file-size-in-mb/presentation", "100"
+      "carbonio-docs-connector/max-file-size-in-mb/spreadsheet", "10"

source/_includes/_admincli/files-tables.rst

@@ -0,0 +1,25 @@
+Using the |mesh| :ref:`kv interface <modify-kv>`, it is possible to
+change a few |file| parameters, according to the following table.
+
+.. csv-table::
+   :header: "Key name", "Default value"
+   :widths: 70, 30
+
+   "carbonio-files/max-number-of-versions", "30"
+   "carbonio-files/max-uploadable-size-in-mb", "50"
+   "carbonio-files/max-downloadable-size-in-mb", "unset"
+
+#. The maximum number of versions stored for each supported file (text
+   and word processor documents, spreadsheets, presentations).  You
+   can raise the default **30** number, but keep in mind that this
+   implies that you need more storage to keep all versions.
+
+#. The maximum size of a document, in megabytes, that can be
+   uploaded. By default, the value **is not defined**, meaning that
+   there is no limit to the size of a document.
+
+#. The maximum downloadable size of a document is by default **not
+   set**, meaning there every file can be downloaded. If a limit size
+   (in Megabytes) is set, trying to download a file larger than the
+   limit will result in a message being displayed, showing the current
+   size limit and the download will fail.

source/_includes/_admincli/kv.rst

@@ -0,0 +1,27 @@
+Values can be changed by using, from any Node, the |mesh| kv
+interface: you can access it using the :command:`consul` command from
+the CLI.
+
+* To verify the current value of any key, use command
+
+  .. code:: console
+
+     # consul kv get -token="$CONSUL_TOKEN_PATH" "$KEY"
+
+* To modify one of the values reported in the tables below, use
+  command
+
+  .. code:: console
+
+     # consul kv put -token="$CONSUL_TOKEN_PATH" "$KEY" "$VALUE"
+
+  When changing any of this values, they are immediately picked up by
+  the system, without the need to restart any services.
+
+In the commands, ``$CONSUL_TOKEN_PATH`` is the |mesh| bootstrap token
+stored on the **Directory Service server**, while ``$KEY`` and
+``$VALUE`` are the *key name* and the *new value*, respectively, as
+written in the tables.
+
+.. hint:: The |mesh| bootstrap token can be retrieved using the
+   procedure described in section :ref:`mesh-token`.

source/_includes/_admincli/mesh/agentnoudp.rst

@@ -0,0 +1,31 @@
+There are situations in which a service-discover agent fails to
+connect to the service-discover server or to other agents using
+**UDP**, but is successful via **TCP**. When this happens, in the
+:file:`syslog` log file, warning messages like the following one are
+recorded::
+
+  Mar  9 20:08:29 proxy01 service-discoverd[3189618]: 2025-03-09T20:08:29.578+0100 [WARN]  agent.client.memberlist.lan: memberlist: Was able to connect to srv1.example.com over TCP but UDP probes failed, network may be misconfigured
+
+  Mar  9 20:08:30 proxy01 service-discoverd[3189618]: 2025-03-09T20:08:30.579+0100 [WARN]  agent.client.memberlist.lan: memberlist: Was able to connect to agent-mbox01.example.com over TCP but UDP probes failed, network may be misconfigured
+
+  Mar  9 20:08:31 proxy01 service-discoverd[3189618]: 2025-03-09T20:08:31.580+0100 [WARN]  agent.client.memberlist.lan: memberlist: Was able to connect to agent-files01.example.com over TCP but UDP probes failed, network may be misconfigured
+
+These messages show that **proxy01** (the agent that establishes the
+communication) can not communicate with agents of ``srv1``,
+``agent-mbox01``, ``agent-files01`` and are marked as ``[WARN]]``,
+i.e., warnings, the agents can still communicate via TCP and the
+service-discover is working--as shown also in the :ref:`mesh-gui`,
+this is a symptom of a communication problem within the network.
+
+Possible reasons for the problem are:
+
+* A blocked (destination) UDP Port 8301 between the source agent, i.e
+  the agent starting the communication, and the destination agents or
+  server.
+
+* An unwanted SNAT rule of the agent's source IP address: if the UDP
+  connection is masqueraded with an IP address that is unknown to
+  |mesh| destination agent or server, then the connection fails
+
+In both cases, to fix the problem it is necessary to investigate the
+firewall rules to find a misconfiguration or some offending rule.

source/_includes/_ts/mesh.rst → source/_includes/_admincli/mesh/commands.rst

@@ -1,56 +1,8 @@
-|mesh| is one of the main components of |product|, and is based on
-HashiCorp's `Consul <https://developer.hashicorp.com/consul>`_. This
-page is meant to provide some of the most used CLI commands to inspect
-and fix any issues that may arise with the use of Consul.
 
-It is possible to interact with Consul on any node of a cluster but
-remember that the :command:`consul` operates by default on the current
-node. To operate on a different node, you need to explicitly specify
-it, for example this command show all services running on node with
-#ID *7ea9631e*
+.. _consul-cluster-ops:
 
-  .. code:: console
-
-     # consul catalog services -node 7ea9631e
-
-.. warning:: Some of the commands listed on this page can be used to
-   or modify significantly or remove a service or a node from Consul,
-   thus potentially disrupting |mesh|. These commands are marked with
-   an icon: :octicon:`alert-fill;1em;sd-text-danger` Use them with
-   care!
-
-.. _ts-token:
-
-Retrieve Token
-==============
-
-Whenever you want to use Consul, the first operation is to retrieve
-the *bootstrap-token*, to allow connection and interaction with the
-service.
-
-.. code:: console
-
-   # service-discover bootstrap-token
-
-.. hint:: You need to provide the cluster credential password, which
-   is stored in :file:`/var/lib/service-discover/password`.
-
-Export the token, which is a string similar to *e5a4966f-a83e-689d-618d-08a0fe7e695b*
-
-.. code:: console
-
-   # export CONSUL_HTTP_TOKEN=e5a4966f-a83e-689d-618d-08a0fe7e695b
-
-You can automate the export process by using the following one-liner
-
-.. code:: console
-
-   # export CONSUL_HTTP_TOKEN=$(gpg -qdo - /etc/zextras/service-discover/cluster-credentials.tar.gpg | tar xOf - consul-acl-secret.json | jq .SecretID -r)
-
-.. _ts-consul-cluster:
-
-Common Cluster Operations
-=========================
+Cluster Commands
+================
 
 The following commands are used to inspect a cluster:
 
@@ -77,10 +29,10 @@ The following commands are used to inspect a cluster:
 
          # consul force-leave agent1-example-com
 
-.. _ts-consul-services:
+.. _consul-services-ops:
 
-Common Service Operations
-=========================
+Service Commands
+================
 
 These commands allow to retrieve a list of services registered to a
 Consul cluster and to manipulate them.
@@ -136,7 +88,7 @@ Consul cluster and to manipulate them.
       the case for |product|), simply delete the file and reload the
       agent on all nodes.
 
-.. _ts-consul-other:
+.. _consul-other-ops:
 
 Other Commands
 ==============

source/_includes/_admincli/mesh/findleader.rst

@@ -0,0 +1,19 @@
+To find which |mesh| node is currently the *leader node*, first get the
+|mesh| token.
+
+.. include:: /_includes/_admincli/mesh/gettoken.rst
+
+Query the |mesh| service to retrieve the state of all its Nodes. The
+*leader node* has the attribute *State* set to **leader**.
+
+.. code:: console
+
+   # consul operator raft list-peers
+
+The output of the command will be similar to the following. In this
+case, the leader node is **srv2-example-com**::
+
+  Node                          ID                                    Address              State     Voter  RaftProtocol
+  srv1-example-com  10092f88-53cc-6938-08d3-48d112b5b25e  10.174.166.116:8300  follower  true   3
+  srv2-example-com  04033e5a-5597-20ca-81ef-5cdad4f24581  10.174.166.117:8300  leader    true   3
+  srv3-example-com  0d325666-f792-2258-a351-f74c01249fb3  10.174.166.118:8300  follower  true   3

source/_includes/_admincli/mesh/gettoken.rst

@@ -0,0 +1,26 @@
+The token is encrypted and stored in file
+:file:`/etc/zextras/service-discover/cluster-credentials.tar.gpg` and
+can be retrieved with this command, which will output the token on the CLI
+
+.. code:: console
+
+   # gpg -qdo - /etc/zextras/service-discover/cluster-credentials.tar.gpg | tar xOf - consul-acl-secret.json | jq .SecretID -r
+
+For simplicity you can put the token in a local variable as follows
+
+.. code:: console
+
+   # export CONSUL_HTTP_TOKEN=$(gpg -qdo - /etc/zextras/service-discover/cluster-credentials.tar.gpg | tar xOf - consul-acl-secret.json | jq .SecretID -r)
+
+You can then check the password with command
+
+.. code:: console
+
+   # echo $CONSUL_HTTP_TOKEN
+
+The password will remain in memory until you exit the CLI session, but
+you can explicitly delete it using command
+
+.. code:: console
+
+   # unset CONSUL_HTTP_TOKEN

source/_includes/_admincli/mesh/intro.rst

@@ -0,0 +1,21 @@
+|mesh| is one of the main components of |product|, and is based on
+HashiCorp's `Consul <https://developer.hashicorp.com/consul>`_. This
+page is meant to provide some of the most used CLI commands to inspect
+and fix any issues that may arise with the use of Consul.
+
+It is possible to interact with Consul on any node of a cluster but
+remember that the :command:`consul` operates by default on the current
+node. To operate on a different node, you need to explicitly specify
+it, for example this command show all services running on node with
+#ID *7ea9631e*
+
+.. code:: console
+
+   # consul catalog services -node 7ea9631e
+
+.. warning:: Some of the commands in this section can be used to
+   modify significantly or remove a service or a node from Consul,
+   thus potentially disrupting |mesh|, so use them with care! These
+   commands are marked with an icon
+   :octicon:`alert-fill;1em;sd-text-danger`
+

source/_includes/_admincli/mesh/missingleader.rst

@@ -0,0 +1,90 @@
+When a |Mesh| cluster falls and the election quorum is not met, you
+may find a situation where no leader node exists and the following
+error appears in the :file:`syslog` log file::
+
+  No cluster leader
+
+
+In a case like this, it is possible to forcefully elect a node as the
+new leader and restore the cluster's functionality following this
+procedure.
+
+First, choose one of the |mesh| cluster's nodes that you want to be
+the new leader. We call this node **newleader** in the remainder of
+this procedure.
+
+On all |mesh| nodes, except for *newleader*, stop the
+:command:`service-discover` service
+
+.. code:: console
+
+   # systemctl status service-discover.service
+
+
+On *newleader*, make a backup of :file:`peers.json` file:
+
+.. code:: console
+
+   # cp /var/lib/service-discover/data/raft/peers.json /root/peers.json.bak
+
+Then, retrieve the ``id`` of the consul server
+
+.. code:: console
+
+   # cat /var/lib/service-discover/data/node-id
+
+The output will be a string like::
+
+  61f22310-97de-0965-4958-321840df66b6
+
+
+Use this string to create a new
+:file:`/var/lib/service-discover/data/raft/peers.json` with the
+following content::
+
+  {
+    "id": "<consul_server_node_id>",
+    "address": "<mesh_newleader_IP:8300",
+    "non_voter": false
+  }
+
+.. note:: It is important that the ``non_voter`` attribute be set to
+   ``false``.
+
+The new file will therefore be similar to this::
+
+   {
+       "id": "61f22310-97de-0965-4958-321840df66b6",
+       "address": "10.22.247.11:8300",
+       "non_voter": false
+   }
+
+.. hint:: You can find further information about the format of file
+   :file:`peers.json` inside file
+   :file:`/var/lib/service-discover/data/raft/peers.info`.
+
+Ensure the file has proper ownership:
+
+.. code:: console
+
+   # chown service-discover:service-discover /var/lib/service-discover/data/raft/peers.json
+
+Now, on *newleader*, start the :command:`service-discover.service`,
+then execute command
+
+.. code:: console
+
+   # consul members
+
+The output will include the FQDN of *newleader* as the leader and only
+member of the cluster. The same result can be seen from the
+:ref:`mesh-gui`. This is correct, since the
+:command:`service-discover` service has been stopped on all |mesh|
+nodes at the beginning of the procedure.
+
+To complete the procedure, and bring back the cluster to its full
+efficiency, start the :command:`service-discover` service on the other
+cluster nodes.
+
+Once done, you can check on each |mesh| node that all cluster nodes
+are alive.