geo-update: DNS Database Update Utility

Overview

The geo-update 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.

Usage

The geo-update utility is most often executed by the Urchin scheduler (urchind) based on the __domaindb task. This task is set to check for new updates once per month and can be configured by the user to occur at a certain time using the admin interface.

There are two main functions for this utility:

Download new versions of the domain databases if they are available
Import custom domain entries

The default behavior is to check for updates, download the new databases and overwrite the existing ones, then import the local data from domain.local. The domain.local file must be located in the data/geodata subdirectory of your Urchin installation. The default behaviors can be overridden by running geo-update from the command line with the appropriate options. The usage is:

geo-update [-Hhv] [-D | -F] [-i file]

   -H   log output to History file instead of stdout
   -h   print help information
   -v   print version information for this utility
   -D   disable download of domain databases (Cannot be used with -F)
   -F   force download of domain databases   (Cannot be used with -D)
   -i   import domain data from specified file rather than domain.local

Using the -D option will disable downloading new databases. This is most often useful when importing local changes into the database without causing a complete update. Using the -F option will force the download of new databases even if the databases are already up to date. This feature is useful if you imported incorrect custom domain information or otherwise damaged your domain database and wish to start over with a fresh copy. Logging output to a history file with the -H option will make the run information available when viewing the Task History screen in the Configuration->Scheduler area of the Urchin administration interface.

Examples

To force a download of the latest domains database:
geo-update -F
To import custom entries from the domain.local file without downloading new database:
geo-update -D
To import custom entries from the file mydomains without downloading new database:
geo-update -D -i mydomains

Custom DNS Entriess

When using either the domain.local file in the data/geodata directory or some other custom file, the format of the entries should be one entry per line, starting with the IP or network address followed by a space or tab, and then the domain for that address. Spaces are not allowed in domain name. The allowed forms include the following:

192.168.10.100 somehost.somedomain.net (Explicit hostname IP)
192.168.10.16/24 somedomain.net (IP address with network prefix)
192.168.10.0/24 somedomain.net (subnet with network prefix)

When processing Urchin will check for specific IPs first and then look for encompassing network ranges.

Considerations

Since geo-update will completely overwrite any existing Urchin domains database each time it updates, it is advisable that you always keep your local modifications in the domain.local file so they will automatically be added. Otherwise after an update you will have to add local adjustments manually. Be sure to keep a backup copy of your domain.local file elsewhere.

The geo-update utility needs an internet connection to be able to check for and download new updates. The utility uses port 80 to communicate with the webserver providing the updates. It is possible that you will have problems when going through firewalls and proxy servers when doing updates. Please consult your network administrator if this is the case.