Upgrading Urchin 4

Overview

Upgrading from Urchin 4 to Urchin 5 requires using the procedure that is specific both to your operating system and the Urchin version you're running. This document contains upgrade sections that cover all supported platforms and Urchin versions. Please make sure to verify that you are following the appropriate instructions for your situation.

Before performing any upgrades please make sure you do the following:

Shutdown the Urchin services and back up your entire existing Urchin installation. Having the services disabled will guarantee that there is no database activity while the backup is in progress.
Have a record of the existing installation location and port number of the webserver.

Considerations When Upgrading

Licensing: Urchin 4 licenses are not compatible with Urchin 5. You will have to upgrade your Urchin 4 licenses. Speak with your sales rep for assistance with this.
Differences in report numbers: After upgrading to Urchin 5, you may notice some changes in the session counts in your reports compared to using Urchin 4. Please see the article entitled Urchin 3, 4, & 5 Reporting Differences in this section for details on these differences
Visitor tracking with UTM-1: if you are using UTM-1 with Urchin 4 to track unique visitors to your site, no website changes are required. Urchin 5 will process and report on UTM-1 data. Once you have upgraded to Urchin 5, it is advisable, although not required, to edit the Profiles for any UTM enabled sites. Go to the Profile Settings tab and select UTM- Enabled All for the Default Report Set.
It is strongly advised that you upgrade to at least Urchin 5.6 and update your website to use UTM-4. UTM-4 improves visitor tracking metrics and options for campaign tracking. If you do not need the campaign tracking capability UTM-4 provides you can reduce log space overhead by editing the __utm.js file and setting __utmctm=0.

Procedures

Windows with Urchin 4.10x

Doubleclick on the urchin5xxx_win_setup.exe file and follow the instructions in the Welcome and License Agreement dialog screens.
In the dialog screen labeled Preparing to Upgrade Urchin Installation, the installer will present you with a list showing you the directory location and webserver port number it has determined for your existing installation. It will use these parameters for your upgrade.
If you decide you don't want to use these installer settings, you may exit the installation by clicking the Cancel button. It is not an option to alter the settings of your current installation during your software upgrade, since the upgrade has to match the previous configuration information stored in your Urchin 4 databases.
Click the Next button and the installer will proceed with converting your installation to the new version. Your report and configuration data will automatically be preserved during this process.

Windows with Urchin 4.00x

To migrate properly from Urchin 4.00x installations to Urchin 5, you will have to save some of your existing configuration and data files.

Disable your currently running Urchin Services by going to Start->Programs->Urchin->Disable Services
Navigate to your Urchin installation folder (e.g. C:\Program Files\Urchin) and rename the data folder to data-saved
Copy etc\httpd.conf to var\urchinwebd.conf
Launch the urchin5xxx_win_setup.exe installer. The installer should detect your previous installation and determine the configuration parameters. Just follow the instructions in the dialog windows of the installer.
After the installer has finished go to Start->Programs->Urchin->Disable Services to deactivate your currently running Urchin 5 services.
In the Urchin installation folder (e.g. C:\Program Files\Urchin), rename the new data folder to data-notused, and rename the data-saved folder from step 2 back to data
Launch the Urchin services by going to Start->Programs->Urchin- >Enable Services

UNIX with all versions of Urchin 4

The Urchin 5 install.sh script will properly handle all existing installations of Urchin 4 on UNIX-type systems. When running install.sh, be sure to select Upgrade as the installation type when prompted. Please see the Installation Guide (UNIX) section of the Documentation Center for full instructions.

Mac OS X 10.2.x

Note: Mac OS X 10.1 users should use the section on upgrades for UNIX-type systems.

For the majority of cases the Urchin 5 package installer for Mac OS X 10.2 systems will automatically detect existing Urchin 4 installations and upgrade them. You simply use the instructions in the Installation Guide for Mac OS X 10.2. The one exception to this standard package installer upgrade procedure is if you previously installed using the shell archive installer but did not install in the default location of /usr/local/urchin4, and are now using the package installer to upgrade. In this case you should take the following steps:

Turn off your existing Urchin services using the urchinctl program (i.e. ./urchinctl stop)
Install normally using the package installer, but do not do any initial configuration using the admin interface. When the browser launches at the end of the install, simply close the window.
After the package installer has completed, go to the Urchin Preference Pane in the System Preferences and stop all running Urchin services
In the new Urchin 5 installation directory, /usr/local/urchin, rename the data subdirectory to data-saved
Move the entire data subdirectory from your old Urchin version install directory into /usr/local/urchin
In /usr/local/urchin update the ownership of the data subdirectory using the command:
chown -R www:www data
Launch your new Urchin 5 services by using the Urchin preference pane in System Preferences to start the scheduler and webserver

Your old configuration and report data should now be available in your new Urchin installation. Once you have confirmed that the configuration and processing is normal you can remove your old Urchin 4 distribution, as well as the /usr/local/urchin/data-saved directory.

Sun Cobalt

Login to your Sun Cobalt administration interface and navigate to the section where Urchin is listed. Uninstall Urchin 4 by clicking the Uninstall Urchin 4 link. Once the system reports the uninstall process is complete, you can install the Urchin 5 pkg installer normally per instructions in the installation section of this guide. The Urchin 5 installation will detect the existing Urchin 4 data and move it into place as part of the Urchin 5 installation.