Command line administration

The recommended method to administer a Funnelback installation is through the web based administration interface. This provides an easy-to-use frontend for administrators.

However, it is also possible to administer Funnelback from the command line. This is useful if other systems need to be integrated with Funnelback.


We assume in the following instructions that the $SEARCH_HOME environment variable is defined. This should point to your installation directory. By default, this is /opt/funnelback/ on Linux and C:\funnelback\ on Windows.

bin contains all administration scripts.
conf contains various global configuration files, as well as collection specific configuration files, under $SEARCH_HOME/conf/<collection name>.
log contains global log files, such as the create.log file, which records creation of collections and the delete.log file, which records deletion of collections.
web contains files relating to the admin console and public search interface (such as the cgi files). Web server configuration files are stored in $SEARCH_HOME/web/conf/.
data contains collection specific data, such as gathered documents, indexes and log files.

The data area has the following structure:

Creating a collection

All collection configuration files are created from a collection template at $SEARCH_HOME/conf/collection.cfg.default.

All configuration information for a collection is stored in a directory at $SEARCH_HOME/conf/<collection name>/. This includes the main collection.cfg file.

To create a collection from the command line, administrators can create the collection configuration directory, copy the collection template to collection.cfg in this directory, edit the collection configuration and run over the collection configuration.

A separate convenience script,, is available and will create the configuration directory and collection configuration file automatically. An optional start URL or location can be passed to this script, as well as a type, allowing the creation of web, local, filecopy, database collections, etc.

The created collection configuration should still be manually checked and edited to change default configuration options. The following options are especially important to check:

Creating a meta collection

A meta collection is one which has no data or indexes of its own but instead points to a set of underlying collections. To create a meta collection, administrators can use the script, specifying a "meta" collection type.

The administrator must then create a meta.cfg file in the appropriate location: $SEARCH_HOME/conf/<collection name>/meta.cfg. This file is used to list the sub-collections which make up the meta collection.

The format is to list the internal names of the sub-collections, one per line. For example, the file might look like:


You also need to create an index.sdinfo file which lists the full path to the index stems for the subsidiary collections. This file should be placed in $SEARCH_HOME/data/<collection name>/live/idx/ and $SEARCH_HOME/data/<collection name>/offline/idx/, and will look something like:


Once this is done the meta collection will be as up to date as its component subcollections. This means that you do not need to call the update script for a meta collection.

Updating a collection

To update a collection, use the script, redirecting the output status messages to an appropriately named update log e.g. update-<collection>.log: $SEARCH_HOME/conf/example/collection.cfg > $SEARCH_HOME/log/update-example.log 2>&1

Note that an update may take a significant amount of time, depending upon the update timeout, number of documents found and other factors.

During the update, messages will be logged to the appropriate logs in $SEARCH_HOME/data/<collection name>/offline/log/ and $SEARCH_HOME/data/<collection name>/log/.

Lock files

To prevent multiple simultaneous updates of the same collection, will create a lock file at the start of an update. This lock file will be placed at $SEARCH_HOME/data/<collection name>/log/<collection name>.lock. A collection update will not occur unless can create and gain exclusive access to this lock file. The lock file is removed at the end of a successful update or if an error occurs during the update.

State files

The various update scripts will also write to a state file at $SEARCH_HOME/data/<collection name>/log/<collection name>.state. This state file will contain text indicating the state of the relevant collection:

An additional collection.state file is written to the $SEARCH_HOME/conf/<collection name>/ directory for web collections. This file contains the following parameter:

which stores the number of incremental gathers that will be done before a full gather is triggered. The value is decremented each time an incremental crawl is done and will be reset to the value of schedule.incremental_crawl_ratio when it reaches zero.

Deleting a Collection

Administrators may fully delete a collection using the script. This script will delete all data and configuration associated with the deleted collection:

User configuration files are also edited to remove references to the deleted collection.

Command line scripts reference

Detailed internal documentation may be gained for many scripts through the standard Perl "perldoc" command. creates a collection, including its collection.cfg file. <collection name> <collection type> [start url] creates a collection from an already existing collection.cfg file. <collection config> deletes a collection, including its gathered documents, indexes, configuration, scheduled updates and logs. It also removes references to the now non-existent collection from user configuration files. <collection config> is a wrapper around the entire update process, and calls the appropriate update subscripts. <collection config> [update type: -incremental, -reindex, …] gathers documents from web collections. <collection config> [update type: -check, -incremental, -instant-update] gracefully stops a web crawl. <collection config> gathers documents from filecopy collections. <collection config> [other options] gathers documents from database collections. <collection config> [--full] [other options] calls Padre to index a collections documents. <collection config> [-reindex] [-instant-update]

For collections using warc files to cache gathered content. builds a new index for the collection's warc files in the live view. Intended to be used when upgrading between versions of Funnelback. <collection name> processes a collections data files, producing reports on their contents. <--collection "collection config"> [--log] … updates the Trend Alerts reports for a collection (or all collections if none is specified). [--collection "collection name"] swaps the live and offline views of a collection after a successful update, placing the newly gathered and indexed data in live for querying, and safely storing the older gathered and indexed data in offline. <collection config> [-force] archives a collections queries.log and clicks.log log files to the collection's archive directory. <collection config> [view] reads a collections log files and stores a binary database for reporting purposes. The admin UI report frontend will read this database for displaying reports. <--collection "collection internal name"> [-v] [-v] [-v] [-v] sends email query reports to users who have requested them for the specified collection (or for all if none was specified). [--collection "collection name"] checks that each link in each collection's best bets file is still available

Update the location of the perl interpreter for all .cgi and .pl scripts

Trigger local or remote administrative tasks --help

Change a users password.

 $SEARCH_HOME/web/bin/ <user> <password>