Locust Installation Guide

Gregory Kozlovsky

We assume that a basic Linux OS has been already installed. This installation procedure was tested on RedHat 4. It may require some adjustment on other Linux installations.

Every Linux installation may be configured in an infinite number of ways, therefore, the commands we quote are for the user's general orientation and may have to be modified to suit your installation. See Linux documentation for details.

Install required third-party packages

If already not installed, install the following third-party packages.

Install gnu c++ compiler:

     up2date gcc-c++

We tested locust with the compiler version 3.4.4 and it may not work without modification with another compiler version.

Install version 5 MySQL server, client and development packages, for example the following:


Install and configure Apache server.

Install libraries libpthread (thread library) and libz (data-compression library) if not already installed. The thread library is usually included with current versions of the GNU C++ compiler.

If you plan to extensively work on the code, install makedepend that automatically computes source file dependencies for the make.

In order to index documents in a format that is not text or HTML, we need to install a converter. Most popular format requiring conversion on the internet is PDF. A PDF to HTML converter can be downloaded from

Create an account for locust

Create an account for running locust, using the following command (possibly with some options):

     useradd locust

Do not forget to set a strong password for the new account!

Note: If, for some reason, you would like to run locust under a different account name, you should know Unix well enough to change the installation script.

Compile locust

Unpack locust.tar.gz and asearchd.tar.gz in a directory, normally /home/locust with the following commands:

     tar xvfz locust.tar.gz
     tar xvfz asearchd.tar.gz

To compile locust, go to the distribution home directories locust and asearchd and type the command


in each of them.

Install executables, create directories, and install files

Upon successful compilation, logon as root and go to the locust distribution home directory locust.

If a previous version of locust is installed, save your index database configuration files and any generic configuration files that you modified and would like to keep (they are in the directory /etc/locust). Also save the initialization script /etc/init.d/locust if you modified it and would like to merge modifications into the new version. Then run the uninstall script that will remove all the old files and directories:/p>

Now run the installation script:


The script installs executables, creates the necessary directories and copies the sample configuration files. The ownership of the directories is set to locust:locust. The following actions are performed by the script.

Upon installing locust, go to the directory asearchd and copy the search daemon executable asearchd/asearchd to the directory /usr/local/sbin.

If old version configuration files and/or scripts were saved, copy them back into their proper places. If default files in the new distribution changed compared with the previous distribution, the changes may have to be merged into the new files.

Configure MySQL

It is difficult to supply a prepared MySQL configuration file suitable in all circumstances. We describe here the options that need to be changed in a default MySQL configuration file to work with the locust default installation. Other options may have to be changed to improve performance. Refer to the MySQL manual for more information.

To create an initial MySQL configuration, take one of the default MySQL configuration files in the MySQL distribution directory that looks something like /usr/share/doc/mysql-server-4.1.20/ and copy it into /etc/my.cnf. For a large index database containing several million documents the file my-huge.cnf may be used provided your server has a lot of memory.

Now, edit the configuration file /etc/my.cnf to set the location for MySQL data. For standard locust configuration set the option socket as following

     socket = /var/locdata/mysql/mysql.sock

for both the clients and the server. Set the option datadir in the server section as following:

     datadir = /var/locdata/mysql

Set (or uncomment) the option tmpdir in the server section to point to a directory for temporary files:

     tmpdir = /tmp/

If we use nonstandard location for the MySQL data directory, as we do in the locust installation procedure, we have to initialize it and create the system tables (an rpm installation procedure automatically created the data directory and tables in the default location). This is done by running the following command after we have the MySQL configuration file modified:

     mysql_install_db --user=mysql

And, finally, create a MySQL user account (not to be confused with the Unix user account under which we run locust) with the MySQL statement, executed under the root account via, for example, the mysql interactive client:

     grant usage on *.* to account@localhost identified by 'password';

where account is the desired account name and the password is the password to be set for this account. The account name and password will be needed when preparing configuration files for index databases. Several MySQL user accounts can be used if desired for security or accounting reasons.

Note: Make sure that the account under which locust is run is granted read access to the MySQL data directory (by default /var/locdata/mysql). Although the clients access MySQL data via the server and thus do not require access to the data, they still need read access to the file mysql.sock to make the handshake with the server. The MySQL data directory access permissions may be set incorrectly if it was created not by the locust installation script.

Install email service

Cron daemon can forward output of commands it executes via email to interested users. This functionality can be used to monitor spidering. In order to enable emailing from the server, postfix email transfer agent must be installed.