Backup and restore FAQ

Site backups: Site backups, as explained in upgrading Moodle, are recommended in order to have all data saved with the best confidence and the shortest recovery time.

Course backups: Course backups, configured on the backup page, are more expensive in terms of time and CPU usage. The recovery time to have your site running again is longer. Course backups are useful for obtaining "fresh" copies of courses to be re-used or distributed individually, however they should never be used as a primary backup system (unless your hosting doesn't allow the preferred site backups). In order to make scheduled backups, you have to set up CRON to run periodically. Please refer to the cron instructions.

How do I backup my whole Moodle site?

There are two main things you need to make a copy of - the database and the uploaded files. The Moodle scripts themselves are less important, since you can always download a fresh copy if you have to.

There are many ways to do such backups. Here is an outline of a little script you can run on Unix to backup the database (it works well to have such a script run daily via a cron task):

cd /my/backup/directory
mv moodle-database.sql.gz moodle-database-old.sql.gz
mysqldump -h example.com -u myusername --password=mypassword -C -Q -e -a mydatabasename > moodle-database.sql
gzip moodle-database.sql

For the files, you can use rsync regularly to copy only the changed files to another host:

rsync -auvtz --delete -e ssh mysshusername@example.com:/my/server/directory /my/backup/directory/

Character Encoding

When dumping the entire Moodle database, Administrators should be careful to watch for possible character encoding issues. In some instances, backups created with mysqldump or phpmyadmin may not properly encode all of the data resulting in spurious A characters. One solution is to use mySQL Administrator 1.1 or another tool that will force a UTF-8 dump of the data.

How do I restore a backup of my whole Moodle site?

If you have followed the above instructions and created a backup of a Moodle site, you may need to know how to restore the site backup you created. Here is a set of basic steps that make up the restore process.

1. Rename the original moodle directory to something different (so you still have it) and copy the backed up moodle directory or a newly downloaded moodle directory in its place.

2. If you are running mysql, a backup of the database should be a .sql, .gz or .tar.gz file. If it is .tar.gz or .gz you need to extract it until it is an sql file.

tar -xzvf moodlesqlfile.tar.gz

3. If you are running mysql, import the sql file back into a newly created database on the mysql server. Be careful here, some backups try to import right back into the same working database that moodle is connected to. This causes database problems that damage a Moodle installation. The best thing to do is make a new database, restore the backed up database into it, and change the Moodle config.php file to connect to this new database (this way you still have the original database).

once you have created the new database:

mysql -p new_database < moodlesqlfile.sql

What data is not contained in course backups?

By selecting all the options when setting up the backup you can include almost all the data in the course. However you should be aware of the fact that some things are not backed up:

Quiz questions are only backed up if at least one question from their category has been added to a quiz.
Scales are only backed up if they are used by at least one activity.

Error: An error occurred deleting old backup data

This part of the backup (or restore) procedure tries to delete old info, used in previous executions, performing the following tasks:

Delete old records from "backup_ids" table: Check the table exists, repair it and try again.

Delete old records from "backup_files" table: Check the table exists, repair it and try again.

Delete old files from "moodledata/temp/backup": Delete the dir completely and try again.

There are various ways of repairing tables, including using MySQL Admin.

XML error: not well-formed (invalid token) at line YYYY

This problem can appear at any point in the restore process. It's caused when the XML parser detects something incorrect in the backup file that prevent correct operation. Usually, it's caused by some "illegal" characters added in the original course due to some copy/paste of text containing them (control characters, or invalid sequences...).

The best method to handle this issue is:

Unzip the problematic backup file under one empty folder.

Open the moodle.xml with Firefox. It will show you where (exact char) the problem is happening.

Edit the moodle.xml file with some UTF8-compatible editor and delete such characters. Save changes.

Test the moodle.xml file again with Firefox until no error was displayed.

Zip everything again (all the folder contents but not the folder itself!).

Restore the course. It should work now.

Restore still not working? See the next paragraph.

Also, if possible, it's highly recommended to solve those problems in the original course too from Moodle itself. Once "repaired" there, problems will be out if you create new backup files in the future.

Still XML error: how to clean xml borked file

In some cases XML backup files may contain characters causing the restore process to abort, even after the steps described in the previous paragraph. In such cases you may want to try the following:

Download the Atlassian XML Cleanr Utility from the JIRA Atlassian site.

Unzip the problematic Moodle backup file under one empty folder. Moodle will create the course file folders as long as the unclean moodle.xml file. Please unzip using the Moodle unzip feature.

Rename the unclean moodle.xml file to moodle-unclean.xml.

If you don't have access to your Moodle server's command prompt, using the Moodle zip feature, zip the moodle-unclean.xml file only, download the zip file locally and unzip it. It is very important to download the xml file in zipped format to avoid unwanted charachter encoding when transferring from an operating system to another.

Move the downloaded Atlassian XML Cleaner Utility in the same folder where is your moodle-unclean.xml file.

Issue the following command from the command prompt:

java -jar atlassian-xml-cleaner-0.1.jar moodle-unclean.xml > moodle.xml

If you launched the utility on your local computer, zip the just created (and hopefully cleaned) moodle.xml file and upload it in the same place from where you downloaded the moodle-unclean.xml file. Once uploaded, unzip it using the Moodle unzip feature.

Zip everything again (all the folder contents but the folder itself!).

Restore the course. It should work now.

Some of your courses weren't saved!!

There are three possible causes of this problem:

Error - this happens when the backup procedure has found an error and so hasn't finished the backup of a particular course. These are "controlled" errors and the scheduled backup continues with the next course.
Unfinished - this happens when the backup procedure dies without knowing why. When the cron is next executed it detects that the last execution went wrong, and continues skipping the problematic course. A possible solution would be to raise the PHP/Apache limit in your installation (memory, time of execution...). By taking a look to your log tables you should be able to see if the "crash" is happening at exact time intervals (usually a problem with the max_execution_time php's variable), or if there is some exact point were all the courses are breaking (generally internal zip libraries, try to switch to external executables instead).
Skipped - this happens when a course is unavailable to students and has not been changed in the last month (31 days). This isn't an error situation - it's a feature, especially useful for sites with many unavailable old courses, saving process time.

Restoring pre 1.6 non-ISO-8859-1 backups to Moodle 1.6 - Unicode

Any backup files with contents which are not 100% ISO-8859-1 will be a problem to restore to Moodle 1.6 (and upwards) running under Unicode. Instead, please try the following:

Make a clean install of Moodle 1.5.x (the latest version available)
Restore all your courses there (they should work if they were working originally)
Upgrade your site to Moodle 1.6 and run the UTF-8 migration script
Backup your courses again

This will produce a new set of backup files that will be 100% UTF-8 and you will be able to use them with Moodle 1.6 without any problems.

Why are some courses being skipped?

From 1.6 onwards, course backups automatically skip courses which are unavailable to students AND have not been changed in the last month.

External links

Repairing Database Corruption in MySQL

Documentation