Urchin Q and A: Urchin 5 Back Up

Question:

How do I back up my Urchin configuration on a nightly basis?

Answer:

It is more than likely that you are backing up your website to guard against a hard drive failure, a hacker, or some other unseen disaster. If you are not backing up your data, stop reading, and go setup a basic backup system now.

Most system backups copy vital files to a remote device that can be used to restore missing or damaged files in an emergency. But what about application settings, are those backed up? If your server goes down, could you re-build your Urchin installation?

Rebuilding an Urchin installation can be a fairly simple task if you have a few profiles and filters. You can log in and re-create the profiles and filters manually without much trouble. But what if you have 50 profiles with numerous filters? Could you remember all the settings to rebuild Urchin and get your reports back? This is where a backup of your Urchin configuration becomes useful.

Urchin provides a number of command line tools that can be used to back up and restore an Urchin installation. Using these tools, you can create a simple script that dumps your Urchin configuration into a text file. This text file can then be imported back into Urchin to rebuild settings, profiles and filters.

To completely backup an Urchin installation you will need an Urchin Configuration backup file and the log files that are processed by Urchin. Backing up your log files is not covered in this article but is equally as important as backing up your Urchin configuration. I cannot stress enough how important it is to back up your log files. Without them, there is no way to rebuild your Urchin reports.

Please note that this article assumes you have some knowledge of the *NIX command line interface.

Creating the Urchin configuration backup file
To create a backup of the Urchin configuration, we use the uconf-export command line utility. Urchin command utilities are found in the util directory of your Urchin installation (usually /usr/local/urchin). The uconf-export provides a command line interface for reading the Urchin configuration database and exporting it in a readable text format. The exported data is an XML-type record format which is directly compatible with the uconf-import utility. Each record in the exported data corresponds to a configuration record in the Urchin configuration database.

The uconf-export function has the following options:
uconf-export [-h] (prints usage message and exits)
uconf-export [-v] (prints version and exits)
uconf-export [-f file] (omitting –f will write the file to standard out)

A typical export command would look like this:
/usr/local/urchin/util/uconf-export -f urchin-config-backup.txt

Running this command will export your current Urchin configuration to the file urchin-config-backup.txt. All profiles, filters and settings will be in the new text file. Please note that your server configuration may not allow you to run the uconf-export command. If you are having trouble running the command, please contact your system administrator.

Automating the backup process
Backup processes run the best when automated. Why? Because then you don’t need to think about them. On *NIX machines you can create a small bash script that calls the uconf-export command. Then automate the execution of that script by placing it in the crontab. The first step in creating the script is to actually call the uconf-export command:

#!/usr/local/bin/bash

usr/local/urchin/util uconf-export -f urchin-config

The above command will work just fine. It will output the configuration to the file urchin-config. But what if you want to restore the configuration from two days ago? That data is not available. By tweaking the name of the file you export the configuration to, you can save a week worth of configuration files.

#!/usr/local/bin/bash

/usr/local/urchin/util uconf-export -f urchin-config-`date +%A`

This new command will output the configuration file named after the day that the script was run on. If the script was run on a Monday, you would have a file named urchin-urchin-config-Monday.

That’s all there really is to the backup script. One thing to note is that you want to move the backup script to a secure location that stores all of your backups.

Once the script is complete you need to add it to your crontab to automate the execution. How often you backup your configuration file depends on how often your Urchin configuration changes. In general, having a weeks worth of Urchin Configuration backups is sufficient.

Rebuilding your Urchin Installation
If you ever need to rebuild your Urchin installation you can simply use uconf-import to import the configuration file that is created using the export utility. After importing the Urchin configuration you will need to reprocess your log files to rebuild the reports.

References

To read more about the uconf-export utility visit the Urchin support center: http://help.urchin.com/index.cgi?&id=1488