Notification

Urchin WebAnalytics Software is discontinued and is no longer supported. All Urchin documentation applies only to the Urchin product as it was at the time of discontinuation, and does not apply to any Google Analytics products or services.

Urchin 6 Installation Guide (FreeBSD and Linux)

Urchin 6 Installation Guide (FreeBSD and Linux)

  • This article authored by EpikOne, an Urchin Software Authorized Consultant

Before You Start: Important Note for Urchin 6.500 Users

Urchin 6.501 fixed several issues in the CPC scheduler that were introduced in Urchin 6.500. If you are upgrading from Urchin 6.500 to Urchin 6.602, the processed CPC data might be incorrect or incomplete, resulting in incorrect results in the Urchin reports. In order to get correct data from Google Adwords, we recommend that you either (a) install Urchin 6.602 in a new location or (b)if you wish to install on an existing 6.500 instance, delete the old CPC data. In this latter case, delete all contents of the following directories:

 

<path_to_urchin_6500_installation>/data/cpc/...
<path_to_urchin_6500_installation>/data/history/cpc/...

No action is required if you are not upgrading from Urchin 6.5 (i.e. 6.501 and later releases or from Urchin 6.402 and prior releases).

Before You Start - Important Note for FreeBSD Users

  • FreeBSD has a hard-coded process datasize limit of 500MB, which is too small to allow Urchin to run due to the size of the geodata that has to be memory resident during log processing. The error you will see during runtime is:

 

ERROR: (8011-323-1057) Failed to allocate memory
  • To address this, you'll need to increase the FreeBSD system's default process datasize, which you can do by editing the /boot/loader.conf file and adding these lines:

 

# Increase max process data segment size to 1GB
kern.maxdsiz="1073741824"
  • You'll need to reboot afterwards.
  • FreeBSD has special driver called accf_http. It will buffer incoming connections until a certain complete HTTP requests arrive to speed up and optimize performance. By default this driver is not loaded to kernel and you will see the following warning:

 

[warn] (2)No such file or directory: Failed to enable the ‘httpready’ Accept Filter
  • To avoid this, you'll need to enable the HTTP Accept Filter FreeBSD kernel module (accf_http), which you can do by editing the /boot/loader.conf file and adding these lines:

 

# Wait for full HTTP request accept filter
accf_http_load="YES"
  • You'll need to reboot afterwards.

WARNING!!! Be very careful when changing system limits like this. If you set kern.maxdsiz to be too large, your system may become unbootable. We strongly recommend that you read the FreeBSD documentation before making this modification, and assess the potential risks as they apply to your site-specific configuration.

Overview of Installation Steps

  • Install the desired database server on the Urchin system or add Urchin's database to an existing server. Currently supported database engines:
    • MySQL 5.0.3 or later (Note: Beginning with Urchin 6.6, MySQL 4.x.x is no longer supported)
    • PostgreSQL 8.2.5 or later
  • Create the Urchin database and user in on the database server and grant access permissions
  • Unpack the Urchin distribution in a temporary directory
  • Run the install.sh script
  • License the Urchin installation

Option 1: Using existing MySQL database with Urchin

  • If you don't already have a MySQL server set up on your system, you can obtain a distribution from http://dev.mysql.com/downloads/

  • Install the MySQL server per the instructions on the MySQL site
  • Make sure that you know the MySQL database administrator login (e.g. root) and password
  • Choose the database name, local MySQL user and password you will use with Urchin. Save this information, as you'll need it later during the Urchin installation. The example below creates a database named urchin and a MySQL user name urchin with password urchinpassword (but you should obviously choose your own password!)
  • Create the Urchin database, user and permissions with the following commands:

 

root@yourserver# mysql -u root -p
mysql> create database urchin character set utf8;
mysql> GRANT ALL ON urchin.* to 'urchin'@'localhost' IDENTIFIED BY 'urchinpassword';
  • Determine the pathname of the MySQL socket for communicating with your MySQL server. You can usually find this in the my.cnf file for your MySQL installation, look for the line that looks like socket=/var/lib/mysql/mysql.sock

Option 2: Using existing PostgreSQL database with Urchin

  • If you don't already have a PostgreSQL server set up on your system, you can obtain a distribution from http://www.postgresql.org .

  • Install the PostgreSQL server per the instructions on the PostgreSQL site
  • Make sure that the psql command is in your path and you know the PostgreSQL database administrator login (e.g. pgsql) and password
  • Choose the database name, local PostgreSQL user and password you will use with Urchin. Save this information, as you'll need it later during the Urchin installation. The example below creates a database named urchin and a PostgreSQL user name urchin with password urchinpass (but you should obviously choose your own password!)
  • Create the Urchin database, user and permissions with the following commands:

 

root@yourserver# psql -U pgsql -d postgres
postgres=# CREATE DATABASE urchin WITH ENCODING 'UTF8';
postgres=# CREATE USER urchin WITH PASSWORD 'urchinpass';
postgres=# GRANT ALL ON DATABASE urchin TO urchin;
postgres=# \connect urchin;
postgres=# CREATE LANGUAGE 'PLPGSQL';

Option 3: Using bundled PostgreSQL server with Urchin

  • Urchin 6.602 installer comes with bundled PostgreSQL server as an option during Urchin installation.
  • In order to use this option, Urchin installer should be invoked under user with root privileges. Installer will prompt you to provide port number and password for the user "postgres". Note: If the user "postgres" already exists in the system, then existing password needs to be provided. If user "postgres" doesn't exist in the system, it will be created with provided password.
  • The following limitations apply to the bundled PostgreSQL server:
    • It can't be installed on FreeBSD.
    • It requires glibc version 2.3.3 or above.
    • It should not be installed in upgrade mode.
    • Root privileges are required for installation.

Installing Urchin

  • Make sure that you have the Urchin database name, user and password that you selected above
  • Create a temporary directory and unpack the Urchin distribution into it:

 

mkdir /var/tmp/urchintemp
cd /var/tmp/urchintemp
tar xzvf urchin6602_<platform>_installer.tar.gz

Important! To ensure correct installation, make sure that there is no 'active' instance of Urchin 6 on the target machine. Disable any existing version of Urchin 6 with the following command:

 

/path/to/urchin6/bin/urchinctl stop
  • If you need to run multiple instances of Urchin 6 on the same machine, then the instances should (1) be installed in different locations, (2) have different web server ports and (3) connect to different databases.
  • Urchin copies all necessary files to the target folders and overwrites any existing files. In order to keep any existing customization intact, you'll need to install Urchin 6 in a new directory, or rename the existing installation directory.
  • Urchin 6.602 can either be installed from scratch or upgraded from an existing version of Urchin 6.
    • During 'New' installation, Urchin prompts you for all configuration parameters, such as web server port, db configuration settings, etc. For 'upgrade', Urchin reuses the configuration of the existing Urchin 6 instance.

    • If you are installing bundled PostgreSQL server, then make sure that there is no existing PostgreSQL server on the system. To install, select an option "Install PostgreSQL" and provide PostgreSQL server details such as port number and administrator password. Note: Please refer to http://www.postgresql.org if you have any problems installing the bundled PostgreSQL server.

    • Urchin 6.602 can only be used for upgrading certain earlier versions of Urchin 6. The following versions may be upgraded:
      • Urchin 6.6 - Service Pack 1 : Version 6.601
      • Urchin 6.6 - English Release : Version 6.600
      • Urchin 6.5 - Service Pack 2 : Version 6.501
      • Urchin 6.5 : Version 6.500 (see important note above)
      • Urchin 6 - Service Pack 1 : Version 6.402
      • Urchin 6 - International Release : Version 6.401
      • Urchin 6 - English Release : Version 6.400
    • During 'New' installation, Urchin prompts you to "Initialize database tables". If you want to keep an existing DB configuration, then select 'No'. In this case,Urchin preserves the existing configuration (by not recreating the existing tables), but it may need to create 'additional tables' or 'columns in existing tables'.
  • Now run the Urchin installer. You can either run it interactively and follow the prompts by typing:

 

./install.sh

or you can perform a complete install directly from the command line, supplying all the necessary parameters for the install. You can obtain a list of the command line parameters by typing:

 

./install.sh -h
  • Once the installer completes, you'll have a running version of Urchin on your system. To finish the setup, point your favorite web browser at this URL:

 

http://yourserver:<port>

where <port> is the network port you chose during the installation (default is 9999).

  • If you wish to restore your profile reporting data from an older version of Urchin 6, copy the history, reports and any existing cpc directories from /path/to/old-urchin6/data/ to your new /path/to/new-urchin6/data/ directory.
  • Click on the Obtain Demo License link and follow the licensing steps to enable Urchin and perform the initial setup steps.

Configuring Tracking

Once Urchin is installed, there may be additional steps required to set up tracking on your website depending on your use case.

Case 1: Using Urchin with IP+User-Agent Tracking

No additional configuration is necessary. When adding profiles to Urchin, be sure to specify IP+User-Agent as the Visitor Tracking Method.

Case 2: Using Urchin with UTM Tracking

To use Urchin with UTM tracking, it is necessary to install a small piece of javascript tracking code on each of your website's pages. Here are the steps:

  • Copy the urchin.js and __utm.gif files from the util/utm directory of the Urchin distribution to the document root of your website (e.g. the top level directory of your content)

  • On each page of your website, place the following tracking code right after the any META tags in the HEAD section:

 

<script src="/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
  _userv=0;
  urchinTracker();
</script>
  • When adding profiles to Urchin, be sure to specify Urchin Traffic Monitor (UTM) as the Visitor Tracking Method

Case 3: Using Urchin concurrently with Google Analytics

Please note that the new tracking features in the Google Analytics "ga.js" tracking code are not backward compatible with Urchin 6. If you wish to track your website with both Google Analytics and Urchin Software, we recommend using the urchin.js-based tracking code for best results. If you choose to use urchin.js, you will not be able to use the new ga.js tracking features.

To use Urchin with a website that is already being tracked with Google Analytics, you just need to make a slight modification to the existing tracking code for Google Analytics. Here are the steps:

  • Copy only the __utm.gif file from the util/utm directory of the Urchin distribution to the document root of your website (e.g. the top level directory of your content).

  • Add the line _userv=2; as shown below to the existing tracking code on your website pages. Be sure not to modify any other parts of the existing tracking code!

 

<script src="http://www.google-analytics.com/urchin.js"
type="text/javascript">
<script type="text/javascript">
  _userv=2;
  _uacct="UA-XXXXXXX-Y";
  urchinTracker();
</script>
  • When adding profiles to Urchin, be sure to specify Urchin Traffic Monitor (UTM) as the Visitor Tracking Method
 
true
Search
Clear search
Close search
Main menu
7851580580338100959
true
Search Help Center
true
true
true
false
false