Installation Guide (UNIX)

Overview

The basic components of the Urchin 4 installation process are:

  • Creating the distribution directory, unpacking the files, and setting appropriate ownership and file permissions
  • Configuring and launching an Apache webserver to allow web based configuration and report delivery
  • Launching the Urchin 4 task scheduler daemon, which manages log processing jobs
  • Initial configuration and demo licensing of Urchin 4 via the administration interface

The installer image you download is in the form of a shell archive, which when executed will automatically unpack into an install script, some support files, and the Urchin 4 distribution. Urchin 4 can be installed by any legitimate user on your system. It does not expect nor require any special system privileges either to install or operate, and is specifically designed to run as a non-root user for security reasons.

Installation Preparation

You may install as any user, with the exceptions that you will have to install as the superuser if you install in a directory that has write access restrictions, or if you configure your webserver to respond to requests on a port number that is lower than 1025. Only the superuser can configure the webserver with a port number lower than 1025. Please verify that the port you choose does not conflict with existing operational services on your system. The installation process will attempt to check for conflicts.

If you are installing as root, you will also be asked for a user account name and a group name, which are used in the configuration file for the webserver, and also used to set the ownership on the installed Urchin 4 distribution. The user and group names you select must be valid logins recognized by your system; you cannot choose arbitrary names for these. You also are not allowed to use root as the login to own the Urchin 4 files for system security reasons. If you are not logged in as root while installing, you will typically not have the privileges to set the ownership of the files to the user of your choice. The install script will automatically detect this and install the distribution with your login as the owner of the files.

Lastly, you will need access to the Internet from your machine, since it is required for you to connect to the urchin.com site to complete the demo licensing and activate your Urchin distribution once it is installed.

Installation and Upgrade Instructions

The Urchin 4 shell archive will be labeled with a name that identifies it for your OS type (e.g. urchin4100_redhat6x.sh). Copy the .sh file to any writeable area on your system. Unpack the shell archive file simply by typing the filename like so:

./urchin4100_redhat6x.sh

If you get the error "Permission Denied" when executing the file try the following instead:

sh ./urchin4100_redhat6x.sh

The shell archive will report the filenames it is unpacking as it runs. When done you should have the following files-

  • install.sh (the installation script)
  • install.txt (instructions similar to this document)
  • license.txt (legal restrictions, licensing, and purchasing info)
  • inspector (verifies the installed distribution)
  • gunzip (supplied to unpack urchin4.tar.gz)
  • urchin4.tar.gz (a tarred and compressed Urchin distribution)

To install simply type:

./install.sh

and follow the instructions. The installer will prompt you to choose either to install a new Urchin 4 distribution or upgrade a previous one. The Urchin 4 distribution requires approximately 10 megabytes when first installed. However, you should allow for growth of database files as you process logs and choose an installation location that will permit increased disk space usage over time.

Initial Configuration Using the Administration Interface

The installation script will start the Urchin webserver and Task Scheduler daemons. Once they are started you can connect to your Urchin 4 administration interface by using the URL http://yourhost:9999, where yourhost is the DNS hostname for your system. If you have changed the default port number from 9999 to some other port during the installation, then you should use that port number in the URL. You will get a login screen. Use these initial login values:

Username: admin
Password: urchin

Upon initial login, the interface will take you to a License Urchin wizard. You should click on "Obtain Demo License". The interface will connect to the licensing server at the Urchin Software Corporation website and walk you through the process. When finished with the license process, you will be returned to the Urchin 4 administration interface where you will be led through a Setup wizard that will set some required initial configuration parameters.

Managing Urchin 4 Services

There are 2 daemons, urchind and urchinwebd, that need to be running in order for log processing, reporting, and configuration administration to occur. These daemons are stopped and started by the urchinctl program in the bin subdirectory of your Urchin distribution. To start or stop both daemons, use:

./urchinctl start
./urchinctl stop

You can also specify to only start or stop one daemon at a time by using a -w option for the webserver or a -s option for the scheduler. To see all of the available options, execute urchinctl with the -h option.

Any errors encountered when one of the daemons is launched should be reported on the command line. For the urchinwebd daemon, once you think it is running successfully, you should also check the var/error_log file for any startup problems.

At install time, the install.sh script will create a bootup/shutdown script that you can use in conjunction with your system rc files to cause the Urchin services daemons to be started at boot time and halted at shutdown. The script is named urchin4_daemons and is located in the util subdirectory of your Urchin distribution.

User Access to Reports

For users to see their individual reports, they should use the URL http://yourhost:9999, where yourhost should be replaced by the name of the system where Urchin is installed. If, during installation, you have chosen some other port number than the default of 9999 for the Urchin webserver to run on, then that number should be used instead.