Administration Utilities Overview

Overview

Urchin ships with a number of utility programs that are used for diagnostic and configuration purposes. These utilities are located in the util directory of the Urchin distribution. This document is intended as an introductory overview of these utilities. It is not a comprehensive guide to their usage. Please consult the specific documentation for each utility in the Utilities section of the Advanced Topics area of the Urchin Documentation Center at http://www.google.com/support/urchin45 for detailed information about the capabilities and usage of each of these programs.

All utilities support "-h" and "-v" command line arguments. Invoking a utility with the "-h" argument will give a summary of usage and the available options for that tool. Invoking with "-v" argument prints the Urchin version of the utility.

geo-update

This utility is used to check for updates to Urchin's internal DNS database files and download the updates if they are available. The utility can also be used to import custom entries into the DNS databases by using the domain.local file or another specified text file.

inspector

This utility performs basic sanity checks on your installed Urchin distribution, ensuring that the overall structure of the distribution is intact, that all the binaries shipped with the product are the proper version, and that the underlying permissions are correct (on UNIX-type platforms). The utility also reports on the operational status of the Urchin Scheduler (urchind) and the bundled Apache web server (urchinwebd).

u3importer

This utility is used to migrate existing Urchin 3 config file information and report databases into Urchin. It runs interactively and prompts the user for the location of the Urchin 3 config file. The process then imports the Urchin 3 data without disturbing the existing Urchin 3 installation. u3importer cannot import all configuration data specified by Urchin 3 config file directives. Some Urchin 3 directives, such as subreport mode, are not supported in Urchin 5, and have no equivalent. Others such as filters, are organized significantly different in Urchin 5, so they cannot be imported exactly as they were specified in Urchin 3. The main objective of this tool is to get all your Urchin 3 report blocks and data imported in a basic fashion so that you have Urchin 5 reporting operational for all your sites, and past report data is available.

uconf-export/uconf-import

These utilities use an XML-style text format to represent the contents of the Urchin 5 configuration database in a human readable intermediate form. An Urchin configuration can therefore be exported and saved, or imported to restore the state of an Urchin configuration. Saved configurations can also be modified with an editor, or configuration files can constructed from scratch, before being imported back into the Urchin configuration database. You can therefore mimic the "config" file functionality that existed with Urchin 3 if desired. It is recommended that you use uconf-export on a regular basis to save your current configuration state as a backup.

uconf-driver

This utility provides a command line interface for administering the Urchin configuration. All functionality present in the Urchin administration interface is available in this utility, thus it can completely replace the use of the administration interface as far as managing all aspects of Urchin. uconf-driver is intended for use in situations where scriptable actions for managing the Urchin configuration are desired. This makes it ideal for environments such as large shared hosting operations, where the amount of data that must be managed makes it impractical to manage Urchin via the web-based administrative interface.

uconf-schedule

This global task scheduling utility alows you to schedule all configured Profiles to run at a certain time, including scheduling them all to run immediately. The Urchin Task Scheduler (urchind) must be running for uconf-schedule to work.

udb-sanitizer

The udb-sanitizer program is used to effect repairs on your Profile databases when there is a problem that leads to database inconsistency or corruption. The Urchin log processing engine routinely does database consistency checks while processing logs. When it detects a database that needs repair it will report the need for udb-sanitizer to be run. In addition to database repair, this utility allows removal of a single day or a month's worth of data in the event that webserver logs need to be reprocessed.

urchinctl

(Note: this utility lives in the bin directory, not the util directory).
This utility provides a means of starting and stopping the Urchin Scheduler and Urchin Webserver services. On UNIX-type systems, urchinctl is typically called from one of the system's boot-time scripts to automatically start up or shut down Urchin services.

urchin_daemons

On UNIX-type machines Urchin runs a scheduler daemon (urchind) and an Apache webserver (urchinwebd). These programs should be started at boot time. The urchin_daemons script can be added to the system initialization scripts in the location appropriate for your UNIX-type OS, and it will cause the Urchin service daemons to be launched properly.