How can I move Urchin and all of the report data to another server?

Moving Urchin 5.x from one server to another requires the following basic steps:

Upgrading to the latest version
Moving the Urchin reporting databases for the profiles
Moving the Urchin configuration data
Moving any custom files and templates
Checking new file permissions
Re-activation of the Urchin license

NOTE The following detailed instructions can be applied to cross-platform moves as well. The Urchin reporting database files can be moved to any operating system supported by Urchin. Considerations when moving data and files from one platform type to another include command line syntax (such as adding './' or 'sudo ./' for Unix and Mac OSX systems respectively). Other considerations include directory syntax changes such as 'Standard\Windows\folders\' vs. '/standard/unix/directories/.'

Preliminary setup
If you are upgrading to a new major version of Urchin (for example, 4.x to 5.x), or if you are not currently using the most up-to-date release of the product, it is strongly recommended that you upgrade Urchin on the old server before moving any data or configuration files. More information on upgrading Urchin can be found here:
Urchin 4.x to Urchin 5.x
Urchin 5.x to Urchin 5.x (latest)

Moving the Reporting Databases
By default, All Urchin reporting data is stored in a child directory of the main Urchin directory; ~/urchin/data
This directory should be archived to maintain the subdirectory structure, then moved to the new server after installing Urchin there. It should be restored in the same directory location on the new server when possible; ~/urchin/data.

Moving the Configuration
The configuration also must be moved. However, if the new directory structure is different from that of the older server, Urchin will not be able to process logs and write data correctly. For instance, if Profile-A on the old server has the following parameters:

	Log Source: /home/www/site1/logs/access_log
	Data directory: /usr/home/urchin/data

and the new server has a slightly different directory structure:

	Log Source: /usr/www/site#/logs/access_log
	Data Directory: /usr/local/urchin/data

then, the old Urchin configuration cannot be imported "as is" and must be either recreated or edited before importing.

Exporting and Importing the configuration
The Urchin 5 configuration can be edited as a text file. To do this, you must first export it from the ~/urchin/util directory by running this command:

	uconf-export -f config.txt

This will create a file called config.txt that can be edited and imported later.

In most cases, you should install and complete the basic setup of Urchin 5 on the new server first. Do not create any profiles or log sources though. Only complete the basic Administration and system setup. When that is finished and you are prompted to add new profiles, "stop." This is when you will want to import your configuration file from the old server.

Because you completed the basic setup, the new Urchin configuration will already contain "Global Settings" and "Process Settings." In most cases, these should not be changed. So, before you import your old configuration file, open it for editing. Remove the "Global Settings" and "Process Settings" configuration records from the old configuration file.

Those records will have more data, but look something like this:

#---------------------
#  Global Settings
#---------------------

   ct_name=Access Settings
   cr_remoteadmin=on
   cr_remoteaccess=on
   ct_port=9999


#---------------------
#  Process Settings
#---------------------

   ct_name=Process Settings
   ct_priority=normal
   cs_limitdbtable=10000

NOTE If you have added any special global changes to the old configuration that could only be done through text based configuration editing, make the necessary changes to the new configuration at this time.

Now you are ready to import the remaining configuration settings from the old server. Move the old configuration file into the new ~/urchin/util directory and run the uconf-import tool to restore the old server's Urchin configuration:

  uconf-import -o -f config.txt

Copying Site-specific Customizations
Customizations made to Urchin, including custom log formats and report sets, are not kept in Urchin's "data" directory. Rather, these customizations are kept in a separate location under the "lib" directory of the Urchin distribution. When Urchin is installed on your new server, any customizations that have been made to the old Urchin system will need to be copied to your new Urchin installation. These files are usually kept in ~/urchin/lib/custom/.

To do this, go to the old Urchin server and navigate to the "lib" directory of the Urchin distribution. Next, create an archive of the entire "custom" directory (and all subdirectories) using an archive utility like tar or ZIP. Now copy this archive over to your new Urchin server and unpack it in the "lib" directory of your Urchin distribution.

Checking file permissions
After all files have been moved to the new server, you should perform a thorough check to ensure that all files have the required permissions and that all files are owned by the same user (UNIX systems only).
To check for permissions, run the following command from the ~/urchin/util/ directory:

inspector -r

To check for file ownership (UNIX only) run the following command from the ~/urchin/ directory:

chown -R urchin_user:urchin_group ./

Reactivate the Urchin License
After you have completed the configuration import, you'll need to relicense Urchin on the new server. If you are upgrading from one major version of Urchin to another, contact your Urchin Account Manager to obtain a new license. If you are simply moving an existing license from the old server to the new server, contact Urchin's Technical Support department by submitting a trouble ticket at http://www.urchin.com/support/hosted_urchin.html

After Support resets the license, you can login and select "Activate Pre-purchased License." This will complete the migration and licensing process.