Carbonio Upgrade
Carbonio does not have any installer: whenever new versions are released, the Zextras repositories are updated and packages are available for installation along with the other system updates. Therefore, the upgrade procedure is usually a very quick activity, carried out by means of a few commands to be executed on each Node, be it the (single) Node in a Single-Server installation, or all the Nodes in a Multi-Server installation.
The upgrade procedure consists of a preliminary task, followed by the proper upgrade, which is the same for each Node,
Depending on the packages upgraded, some manual step may be required. Please read carefully section Upgrade Checklist before starting the upgrade, to see if you need to carry out some additional task.
Moreover, incompatibilities may arise in case the upgrade includes third-party software, which may lead to some additional manual steps to be carried out. Section Manual Steps and Troubleshooting below contains information to prevent or fix these issues.
Upgrade Checklist
We define as current version 23.3.0, as previous version the version immediately before, i.e., 23.2.0, and as older versions any version of Carbonio released before these two.
This upgrade impacts the following Roles, which require some manual CLI commands to be run.
the Carbonio VideoServer, so please follow the directions that you find in Section Upgrade Carbonio VideoServer Node when upgrading the Node featuring the Carbonio VideoServer.
the Space functionality in Carbonio Chats is now disabled by default, so please follow the directions that you find in Section Enable Carbonio Chats Space Functionality when upgrading the Node featuring the Carbonio VideoServer.
It is possible to upgrade from an older version to the current one, although we suggest to upgrade whenever a new version is available. However, this type of upgrade may not be as easy as a routine upgrade and you may need to manually execute CLI commands whenever you find yourself in one of the following situations.
In case of Multi-Server installation, make sure you are on the correct node before running the commands.
the Carbonio VideoServer, so please follow the directions that you find in Section Upgrade Carbonio VideoServer Node when upgrading the Node featuring the Carbonio VideoServer.
In case any -db
package is in the upgrade list, execute the steps in
Bootstrap Database.
If the upgrade of Docs Editor ends with errors, check section Upgrade of Docs-Editor.
If you are running a version up to 22.9.0, make sure to install the Administration Panel Packages along with the other upgrades.
For improved security, to prevent any data loss, it is suggested to make a backup or take a snapshot (if you are using an hypervisor) of each Node.
Preliminary Tasks
As a preliminary task, we backup the LDAP data of the Directory Server. On a Multi-Server installation, execute the following commands on the node with the Directory Server Role installed, which is SRV2 in our scenario.
-
Make a dump of the LDAP Database, especially if the if the upgrade includes the Directory Server. This can be done using the command (as the
zextrasuser)zextras$ opt/zextras/libexec/zmslapcat /tmpNote
The dump will be saved in the
/tmp/directory, so make sure to copy it to a safe location. Make a backup copy of file
/opt/zextras/conf/localconfig.xmland store it in a safe place
Upgrade Nodes
If you are on a Multi-Server, remember to start from the node featuring the Directory Server (SRV2 in our Six Nodes Scenario), then all the other in the same order of installation.
As the zextras user, run:
zextras$ zmcontrol stop
# apt clean
# dnf clean all
# apt update && apt upgrade
# dnf upgrade
# pending-setups -a
Once the upgrade has completed successfully, run command:
# reboot
Manual Steps and Troubleshooting
If you are upgrading from 23.2.0 to 23.3.0, you need to execute these steps only if they are mentioned in Sections Upgrade Checklist.
If you are upgrading from an older version (i.e., previous to 23.2.0), you need to verify in section Upgrade Checklist if any of these steps is needed: in other words, depending on the packages that will be upgraded, you might need to run them or not.
Bootstrap Database
Whenever a -db package is upgraded (currently they are
carbonio-mailbox-db, carbonio-files-db, and
carbonio-docs-connector-db), remember to bootstrap the
corresponding Database, by running the command, respectively.
# PGPASSWORD=DB_ADM_PWD carbonio-files-db-bootstrap carbonio_adm 127.0.0.1
In the above command, DB_ADM_PWD is the the password of the
carbonio_adm database role, that is, the one created during
Step 6 of the Single-Server installation or the
installation of SRV1: Postgres in the Multi-Server installation
Finally, since new version of Carbonio packages may include new services, it is strongly suggested to execute the command
# pending-setups -a
This will register the services to Carbonio Mesh, so they can immediately be used.
Hint
The secret needed to run the above command is stored in
file /var/lib/service-discover/password which is accessible
only by the root user.
Administration Panel Packages
If you are upgrading from a version previous to 22.10.0, make sure to install also the packages for the brand new Administration console. In a Multi-Server, the commands must be executed on the Proxy node.
# apt install carbonio-admin-console-ui carbonio-admin-ui
# dnf install carbonio-admin-console-ui carbonio-admin-ui
Upgrade of Docs-Editor
When installing recent version of the Docs-Editor, running the pending-setups -a might abruptly exit with an error message similar to:
Error writing config entry service-defaults/carbonio-docs-editor: Unexpected response code:
400 (Bad request: Request decoding failed: 1 error occurred:
* invalid config key "Websocket"
To avoid this error, make sure that the installed package
service-discover-base is at least version 1.10.12. You can
verify this with the following commands.
# apt search service-discover-base
# dpkg -l service-discover-base
# dnf info service-discover-base
# rpm -q service-discover-base
If the version is older than 1.10.12, please upgrade the package.
After you verified that the version is the correct one, please run this command before pending-setups -a.
# systemctl restart service-discover.service
Preventing docs-connector Conflicts
If you are running a release prior to 22.10.0, there are chances
that you have installed package docs-connector-ce, which was
common between Carbonio and Carbonio CE. If you have it installed, make
sure to remove it and that only the new package
carbonio-docs-connector is installed, by removing the old package
# apt purge carbonio-docs-connector-ce
# dnf remove carbonio-docs-connector-ce
Then installing the new package
# apt install carbonio-docs-connector
# dnf install carbonio-docs-connector
Since this package installs a database component, bootstrap the corresponding database.
# PGPASSWORD=$DB_ADM_PWD carbonio-docs-connector-db-bootstrap carbonio_adm 127.0.0.1
Finally, restart the mailbox service.
zextras$ zmcontrol stop
zextras$ zmcontrol start
Enable Carbonio Chats Space Functionality
Starting from version 23.3.0, the Space functionality in Carbonio Chats is disabled by default. It can be enabled again with the command
zextras$ carbonio config set global teamSpacesEnabled true
Upgrade Carbonio VideoServer Node
The upgrade of Carbonio VideoServer requires to manually change a token used for its correct working. First, upgrade the node like described in Upgrade Nodes.
Then, execute the following command:
# echo "carbonio chats video-server add $(hostname -f) port 8188 \
secret $(grep api_secret /etc/janus/janus.jcfg | cut -f 2 -d '"')"
The output will look similar to:
carbonio chats video-server add mail.example.com port 8188 secret LMGZjsaH9mtyH9mtyCCyOUvCqS51okub
Copy that command and, if you are on a Single-server, execute it right before rebooting the node, while if you are on a Multi-Server installation, execute it on one node on which the AppServer is installed (hence, either on SRV5 or on SRV6), after that node has been upgraded.