Data backup

In iTop all the data (including the uploaded documents) are stored in the MySql database. Therefore it is highly recommended to have a database backup in place on a regular basis !

An iTop backup can be generated using :

the GUI
periodically using a background task
CLI scripts
manually

What does an iTop backup contain?

A backup is made of a single zip file.

It contains all the data that is necessary to restore the application:

The configuration (i.e. the configuration file itop-config.php)
The data (i.e. a full dump of the MySQL database)
the .xml delta file - for Combodo clients having customized their instance using the ITSM Designer
extension modules deployed from the iTop Hub and ITSM Designer

Notes
If you have installed new modules after running a backup, restoring the backup is equivalent to uninstalling the modules.

For those installed through the iTop Hub push them again from the Hub.
For those installed through the ITSM Designer, connect to the ITSM Designer and run a Move To Production again.
For those installed through the “extensions” folder, run the setup again if you wish to have the modules back into the iTop.

If you have upgraded iTop or added new modules since the backup has been made, be aware that restoring may end-up with a database not aligned with the code base. After the restoration, iTop may not work. It's recommended to run the Setup to align the Database to the iTop Datamodel (brought by the new iTop version or recently added extensions).

Limitations

Since iTop 3.0.0 all the backup and restore operations will switch iTop to the read only access mode.

Database backup can only work if the exec PHP function is enabled. Warning, there won't be any error messages if it isn't, and the backup won't get generated.
If this PHP function can't be enabled, you should do a manual backup.

If the database size is bigger than 68GB the backup will be executed without any warning, but you won't be able to restore it. This is due to the implementation of php-tar that corrupt the tar file for size bigger than 68GB
So don't use the iTop integrated backup solution if you have big database. We recommend to use mysqldump command described below and your own backup system.

GUI

Starting with iTop 2.1.0, a special menu “backups” is available to the administrators:

This administration page reminds you the current settings, and lists the backup files:

“Scheduled backups” are referring to the one produced by the background task. For more details refer to the dedicated chapter below.

Click on the Backup now! button to perform a backup (no confirmation requested):

Backup background task

Scheduled backups rely on the background process cron.php. Refer to Background tasks for more information about how this is configured.

Configuration

The automated backup scheme can be adjusted in the iTop configuration file, in the section itop-backup:

Parameter	Type	Description	Default Value
mysql_bindir	string	Directory of the MySQL binaries if not in the “path”. Used both for the scheduled backups and as the default value for the REST services
week_days	string	CSV list of week days (lowercase) when the automated backup must be performed	monday, tuesday, wednesday, thursday, friday
time	string	24h based time when the automated backup must be performed	23:30
retention_count	int	Number of backup files that will be kept in the target directory	5
enabled	bool	Switch on/off the automated backups	true
file_name_format	string	Name of the backup (zip), only for the scheduled backups. The following placeholders are supported: __HOST__, __DB__, __SUBNAME__. Timing information can be given based on PHP/strftime specifications.	__DB__-%Y-%m-%d_%H_%M
itop_backup_incident	string	URL of an iTop. It creates a ticket in this iTop if the backup fails. (This parameter was called `itop_root` in 2.5.2+)	if empty or no parameter will use current itop APP_ROOT
extra_files	array	(since 3.1 / bug N°6133) list of additional file/folder paths to backup/restore through CLI scripts	if empty backup archives contains usual files (conf/dump/…)

Changes in the scheduling (including disabling the feature) the next scheduled backup will still occurred as previously configured, then your change will be taken into account.

The backup overview page does not inform you if the backup is totally disabled.

CLI scripts

CLI backup

you can generate a backup using this command:

php datamodels/2.x/itop-backup/backup.php --auth_user=<LOGIN> --auth_pwd=<PASSWORD>

CLI backup operation can only be done using an administrator profile.

Since iTop 3.0.0 it is possible to launch this script even if the standard scheduled backup (cron.php) is enabled : a wait will prevent two backups to run concurrently.
Before this iTop version (for example in iTop 2.6.* or 2.7.*), script and scheduled backups can conflict with unpredictable results.

CLI backup configuration file (recommended)

We hardly recommend to use a param_file so the authentication won't appear in the shell commands history

A param_file can be passed as a parameter to the backup.php script. For example :

php datamodels/2.x/itop-backup/backup.php --param_file=<this file>[,<another one>]

A sample parameter file is bundled in the module : datamodels/2.x/itop-backup/backup.params.distrib

All of those parameters can be passed either in the command or in the param_file.
If no mysql_bindir parameter is specified (nor in command line, neither in param_file) then the iTop config file parameter will be used.

CLI check backup script

This script is also bundled with the module : datamodels/2.x/itop-backup/check-backup.php.

This is a monitoring utility, it must be executed after backup.php.

It will :

verifies that the resulting backup file does exist as per the filename specifications
it aims at detecting suspicious changes in the file size
if the itop_backup_incident and check_ticket_* parameters are present, then a ticket will be created on the local or a remote iTop instance if the backup fails

Ticket creation in case of failure requires that you have installed the Incident Management module on the iTop on which you want to create the Incident
It can be a different iTop instance than the one on which the backup is performed. It's identified with a param_file itop_backup_incident

CLI restore

This script was introduced in iTop 3.0.0 and isn't available in previous versions.

you can restore a backup using the command:

php datamodels/2.x/itop-backup/restore.php --auth_user=<LOGIN> --auth_pwd=<PASSWORD> --backup_file=<PATHTOBACKUP>

CLI restore operation can only be done with an administrator profile.

File permissions

Restore operation does not set back file permissions.
You may have to do chown (www-data) operation again on the following files:

conf/production/config.itop.php
data/production.delta.xml
data/cache-production
data/production-modules

Passwords encryption

If the datamodel uses password fields with reversible encryption, then be sure that the same encryption algorithm is used on the new and old systems: if the mcrypt PHP extension was present on the old system, then the mcrypt extension must be present on the new system as well. If mcrypt was not present, it must not be present either.

Note: User accounts passwords use a one-way encryption and are not affected by the presence of mcrypt.

Manual backup using mysqldump

As in previous versions of iTop, you can still create your own backups using the mysqldump command line utility which comes with MySQL.

You can run a full backup of the database using the following mysqldump command:

On Linux systems:

/usr/bin/mysqldump --opt --default-character-set=utf8mb4 --single-transaction --add-drop-database --user=<user> --password=<password> <DB> | gzip > <file>

On windows systems:

mysqldump.exe --opt --default-character-set=utf8mb4 --single-transaction --add-drop-database --user=<user> --password=<password> <DB> > <file>

Where:

<user> is the user name to connect to MySQL
<password> is the corresponding password
<DB> is the name of the database in which iTop is installed
<file> is the name of the archive file to produce

Once the content of the database is dumped, just archive this dump and the file conf/production/config-itop.php to keep a full image of your iTop instance.

Make sure that you export the data in UTF-8 MB4 (--default-character-set=utf8mb4) otherwise accentuated characters will be lost.
The option --single-transaction has two effects: it produces a consistent backup since all tables are exported in one transaction, and it provides a workaround for the error 1449 (definer does not exist) which may happen if you export a database that was already re-imported from another system or created by a no longer existing user.

Sidebar