Medulla server backup and restore
Implementing a regular backup policy is essential to enable the restoration of a Medulla platform in the event of a failure, corruption, loss of the Medulla server, or an error during a maintenance operation.
For a Medulla On-Premise installation, it is recommended to implement multiple levels of protection:
- a full backup of the server or virtual machine;
- a regular dump of the MariaDB instance;
- a logical backup of the OpenLDAP directory using
slapcatwhen it is in use; - a backup of the main Medulla configuration and data directories.
Important:
All commands presented in this documentation must be executed using the root account.
Recommendation:
When your infrastructure allows it, a full backup of the server or virtual machine should remain the primary backup method. MariaDB dumps, OpenLDAP exports, and archives of Medulla directories serve as supplementary safeguards, particularly to facilitate restoration on a new server.
1. Full backup of the Medulla server
When Medulla is installed on a virtual machine, it is recommended that you use your virtualization infrastructure’s backup solution to perform regular backups of the entire machine.
For a physical server, use your usual system backup solution.
The backup must be stored on infrastructure separate from the Medulla server.
In particular, a backup must be performed before:
- a Medulla update;
- a major configuration change;
- work on MariaDB;
- work on OpenLDAP;
- a major system change;
- a migration operation.
Important:
A virtual machine snapshot can be useful before a maintenance operation, but should not constitute your backup policy on its own. A true backup must be stored separately from the Medulla server.
2. Backup of MariaDB databases
Medulla uses MariaDB to store a significant portion of its data.
In addition to the server backup, it is recommended that you perform a regular dump of the entire MariaDB instance.
Backing up the entire instance eliminates the need to manually maintain a list of the various databases required by Medulla.
Manually create a MariaDB dump
Log in to the server with the root account, then run:
mkdir -p /var/backups/medulla
mariadb-dump --all-databases \
--single-transaction \
--routines \
--events \
--triggers \
--hex-blob \
| gzip > /var/backups/medulla/medulla_mariadb_$(date +%Y%m%d_%H%M%S).sql.gz
This command performs a backup of:
- all MariaDB databases;
- the tables and their data;
- stored procedures and functions;
- MariaDB events;
- triggers.
The --single-transaction option allows you to obtain a consistent backup of transactional tables, such as InnoDB tables, without maintaining a global lock on them for the duration of the dump.
A file similar to the following will be generated:
/var/backups/medulla/medulla_mariadb_20260828_100000.sql.gz
Important:
MariaDB dumps may contain sensitive information. They must be secured and transferred to your backup infrastructure.
3. Automate the MariaDB backup
On a production server, it is recommended to automate the creation of MariaDB dumps.
For example, you can create the following script:
/usr/local/sbin/backup_medulla_mariadb.sh
With the following content:
#!/bin/bash
set -e
BACKUP_DIR="/var/backups/medulla"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p "$BACKUP_DIR"
mariadb-dump --all-databases \
--single-transaction \
--routines \
--events \
--triggers \
--hex-blob \
| gzip > "$BACKUP_DIR/medulla_mariadb_${DATE}.sql.gz"
find "$BACKUP_DIR" \
-type f \
-name "medulla_mariadb_*.sql.gz" \
-mtime +7 \
-delete
Then make the script executable:
chmod 700 /usr/local/sbin/backup_medulla_mariadb.sh
You can test it manually:
/usr/local/sbin/backup_medulla_mariadb.sh
Note:
The 7-day local retention period shown in this example can be adjusted to fit your backup policy. Backups should also be transferred to an external infrastructure.
4. Backup of OpenLDAP with slapcat
When OpenLDAP is used on the Medulla server, it is recommended to perform a logical backup of the directory in LDIF format using the slapcat command.
slapcat allows you to directly export the contents of OpenLDAP databases without using the LDAP protocol.
Recommendation:
It is recommended to perform a backup of both the OpenLDAP configuration and the directory data.
Back up the OpenLDAP configuration
The cn=config database corresponds to database number 0.
Create the backup directory if necessary:
mkdir -p /var/backups/medulla
Then run:
slapcat -n 0 | gzip > /var/backups/medulla/openldap_config_$(date +%Y%m%d_%H%M%S).ldif.gz
Back up the OpenLDAP data
The database containing the directory data must also be exported.
You can start by identifying the configured databases with:
slapcat -n 0 | grep "^dn: olcDatabase"
For example, you will see entries similar to:
dn: olcDatabase={-1}frontend,cn=config
dn: olcDatabase={0}config,cn=config
dn: olcDatabase={1}mdb,cn=config
In this example, the database containing the data corresponds to number 1.
It can then be backed up using:
slapcat -n 1 | gzip > /var/backups/medulla/openldap_data_$(date +%Y%m%d_%H%M%S).ldif.gz
Important:
The LDAP database number must be verified before using the command. Do not automatically assume that the database containing the data is database number 1.
The following files will then be available:
openldap_config_YYYYMMDD_HHMMSS.ldif.gz
openldap_data_YYYYMMDD_HHMMSS.ldif.gz
Important:
LDIF exports may contain sensitive information about your directory. They must be protected and stored off-site like other Medulla backups.
5. Automate the OpenLDAP backup
Once the database number containing the LDAP data has been identified, the backup can be automated.
For example, you can create:
/usr/local/sbin/backup_medulla_openldap.sh
With the following content, adapting the LDAP_DATABASE variable to your installation:
#!/bin/bash
set -e
BACKUP_DIR="/var/backups/medulla"
DATE=$(date +%Y%m%d_%H%M%S)
LDAP_DATABASE="1"
mkdir -p "$BACKUP_DIR"
slapcat -n 0 \
| gzip > "$BACKUP_DIR/openldap_config_${DATE}.ldif.gz"
slapcat -n "$LDAP_DATABASE" \
| gzip > "$BACKUP_DIR/openldap_data_${DATE}.ldif.gz"
find "$BACKUP_DIR" \
-type f \
-name "openldap_*.ldif.gz" \
-mtime +7 \
-delete
Make the script executable:
chmod 700 /usr/local/sbin/backup_medulla_openldap.sh
Then test it:
/usr/local/sbin/backup_medulla_openldap.sh
Important:
Before automating this backup, verify that LDAP_DATABASE corresponds to the database containing your server’s OpenLDAP data.
6. Backup of Medulla directories
In addition to MariaDB dumps, OpenLDAP exports, and the full Medulla server backup, the main directories containing the configuration, data, and certain Medulla components can be backed up.
The directories in question are:
/etc/mmc
/etc/pulse-xmpp-agent
/etc/pulse-xmpp-agent-substitute
/var/lib/pulse2
/usr/lib/python3/dist-packages/pulse
/usr/lib/python3/dist-packages/mmc
Important:
The backup must preserve the owners, groups, permissions, and attributes of the files. This information is necessary to ensure a successful restore.
7. Create an archive of Medulla files
Log in with the root account.
Create the backup directory if necessary:
mkdir -p /var/backups/medulla
You can then create an archive using:
tar --acls --xattrs -czpf \
/var/backups/medulla/medulla_files_$(date +%Y%m%d_%H%M%S).tar.gz \
/etc/mmc \
/etc/pulse-xmpp-agent \
/etc/pulse-xmpp-agent-substitute \
/var/lib/pulse2 \
/usr/lib/python3/dist-packages/pulse \
/usr/lib/python3/dist-packages/mmc
A file similar to the following will be generated:
/var/backups/medulla/medulla_files_20260828_100000.tar.gz
Using the --acls and --xattrs options preserves ACLs and extended attributes when creating the archive.
Tip:
Once the archive is created, transfer it to your backup infrastructure. It is not recommended to keep the only backup copy on the Medulla server itself.
8. ejabberd database
The ejabberd database does not require a specific backup/restore procedure as part of this process.
It is generated automatically when Medulla starts.
9. Restoring Medulla files
Previously archived files can be restored, particularly when rebuilding a Medulla server.
Restoration must be performed using the root account.
Example:
tar --acls --xattrs -xzpf medulla_files_YYYYMMDD_HHMMSS.tar.gz -C /
Caution:
Restoring the Medulla directories alone does not constitute a complete Medulla server reconstruction procedure. The system version, the Medulla version, MariaDB, OpenLDAP, and the restored files must all be consistent with one another.
When restoring data to a new server, it is recommended to use a version of Medulla that matches the one used for the backup before restoring the data.
10. Restoring MariaDB
Once the MariaDB environment is ready, a previously generated dump can be restored.
Using the root account:
gunzip -c medulla_mariadb_YYYYMMDD_HHMMSS.sql.gz | mariadb
Caution:
A dump created with --all-databases contains all backed-up databases. Therefore, it should only be restored as part of a controlled restoration procedure.
11. Restoring OpenLDAP
LDIF backups created with slapcat can be restored using the slapadd command.
Caution:
OpenLDAP restoration must be performed with the slapd service stopped. It should only be performed as part of a controlled restoration process, verifying the configuration, storage paths, and owners of the OpenLDAP files.
Stop the service:
systemctl stop slapd
Restore the configuration
Restoring cn=config must be performed in a clean OpenLDAP environment that is compatible with the backup.
The LDIF file can be extracted using:
gunzip -c openldap_config_YYYYMMDD_HHMMSS.ldif.gz > /tmp/openldap_config.ldif
It can then be reimported using slapadd, depending on the server’s OpenLDAP configuration.
Restore the data
Extract the file:
gunzip -c openldap_data_YYYYMMDD_HHMMSS.ldif.gz > /tmp/openldap_data.ldif
Then restore the corresponding database; for example, if the database is database number 1:
slapadd -n 1 -l /tmp/openldap_data.ldif
Important:
The database number used with slapadd must match the restored OpenLDAP configuration. It should not be assumed automatically.
After restoration, verify the owners and permissions of the OpenLDAP files before restarting the service.
Then restart OpenLDAP:
systemctl start slapd
Then check its status:
systemctl status slapd
12. Check the backups
Simply generating a backup file does not guarantee that a restore will be possible.
It is recommended that you regularly verify:
- that backups are running correctly;
- that the generated files are not empty;
- that the TAR archives are readable;
- that the MariaDB dumps are usable;
- that OpenLDAP exports are usable;
- that backups are correctly transferred to an external system;
- that multiple generations of backups are available;
- that a restore procedure has been tested.
To verify the contents of a Medulla archive without extracting it:
tar -tzf medulla_files_YYYYMMDD_HHMMSS.tar.gz
To verify that a compressed MariaDB dump is not corrupted:
gzip -t medulla_mariadb_YYYYMMDD_HHMMSS.sql.gz
To verify OpenLDAP backups:
gzip -t openldap_config_YYYYMMDD_HHMMSS.ldif.gz
gzip -t openldap_data_YYYYMMDD_HHMMSS.ldif.gz
It is also possible to view the beginning of an LDIF export without decompressing it:
zcat openldap_data_YYYYMMDD_HHMMSS.ldif.gz | head
13. Backup frequency
The exact frequency should be tailored to your organization’s constraints and backup policy.
| Item | Recommendation |
|---|---|
| Medulla server / VM | Regular backup |
| MariaDB | Regular automated dump |
| OpenLDAP | Regular automated slapcat export |
| Medulla directories | Regular backup |
| Before a Medulla update | Backup strongly recommended |
| Before making a major change | Backup strongly recommended |
14. Where should backups be stored?
Backups should not be stored solely on the Medulla server.
It is recommended to automatically transfer them to:
- a backup server;
- a centralized backup solution;
- secure remote storage;
- or any other infrastructure specified by your organization’s backup policy.
Important:
A failure or complete loss of the Medulla server would also result in the loss of backups if they were stored only in /var/backups/medulla.
15. Summary
| Item | Recommended backup |
|---|---|
| Medulla server | Full backup of the server or VM |
| MariaDB | Regular full dump using mariadb-dump |
| OpenLDAP configuration | LDIF export using slapcat -n 0 |
| OpenLDAP data | LDIF export using slapcat from the corresponding database |
| MMC configuration | /etc/mmc |
| XMPP configuration | /etc/pulse-xmpp-agent |
| XMPP Substitute configuration | /etc/pulse-xmpp-agent-substitute |
| Pulse data | /var/lib/pulse2 |
| Pulse components | /usr/lib/python3/dist-packages/pulse |
| MMC components | /usr/lib/python3/dist-packages/mmc |
| ejabberd database | Generated automatically when Medulla starts |
| Required permissions | root |
Recommendation:
To ensure the restoration of an On-Premise Medulla platform, set up a full, regular backup of the server, supplemented by regular MariaDB dumps, OpenLDAP exports using slapcat when the directory service is in use, and a backup of the main Medulla directories while preserving their permissions and attributes. Backups should be stored off-site, and their restoration should be tested regularly.