Back Forward Table of Contents

2. Installation

2.1 Installing the Packages

Hawkeye is distributed as an RPM (Red Hat Package Manager) archive. Thus, you will need the rpm program to install Hawkeye. If your system lacks RPM support, please download it directly from Red Hat (home page: www.redhat.com, ftp site: ftp.redhat.com).

To install the binary distribution, you will need the following archives, available from our home site hawkeye.net:

Installing the files is pretty simple. You will need root permissions, of course. Just take a look at this example session:
	myhost:~# rpm -i mysql-x.x.x-x.i386.rpm
	Starting mysqld demon with databases from /var/lib/mysql
	myhost:~# rpm -i mysql-client-x.x.x-x.i386.rpm
	myhost:~# rpm -i hawkeye-x.x.x-x.i386.rpm
At this time, the MySQL (which is needed by Hawkeye) server is already up and running. If you are going to do a completely new installation, the next step should be like this:
	myhost:~# cd /usr/local/hawkeye/scripts
	myhost:/usr/local/hawkeye/scripts# ./install
The next steps will be guided by the installation script:
1. User selection
The Hawkeye server needs to know the user under whose id it will operate. It is generally not recommended to run the server itself as root, because this may contain certain security risks. You might want to create a user just for Hawkeye to run as. In this case, just press Enter to accept the default user name, hawkeye, or enter a name of your choice. Otherwise, you may choose an already existing user. The script will the fix the directory permissions on /usr/local/hawkeye so that this user - and Hawkeye itself - has full access.

2. Database access
As Hawkeye will operate under the new user's permissions, the script will make sure that this user has access to the MySQL database engine. There is really no reason why not to say 'y' to this question - unless you really know that this user already has access to the database system.

3. Database creation
The last step is to create a SQL database for the Hawkeye server to operate on. This database is called hawkeye by default - again, there is no reason to change this unless you already have a database called hawkeye.
Congratulations, your installation is complete! All you have to do now is to start the server up...

2.2 Starting the Server

The install script has already given you a hint which command line options to use. Please note: Server startup must be done with root permissions, because the server must be able to bind TCP/IP services to the well-known service ports. After doing so, the server will switch its id to the specified user and drop root permissions for security reasons.

So, just try to fire the server up by typing the command the script has given you. If you just get a new prompt, you're done. Please change to chapter 3 and learn how to access your Hawkeye installation.

But if you get an error message like this:

	myhost:~# /usr/sbin/hawkeye
	Failed to bind socket to FTP port: Address already in use
Don't panic. Starting the server can be quite tricky, because Hawkeye does provide a lot of services, and some of them may be already 'occupied' by other processes running on your system. In this case, there is another process blocking the FTP service port. This is probably the inetd super server handling FTP connects on your machine. To make inetd release the service port, edit /etc/inetd.conf and place a hash sign (#) in front of the line beginning with 'ftp'. Then, restart the server by sending it a hang-up signal, like this:
	myhost:~# killall -HUP inetd
If your system doesn't have the killall command, figure out the process id of inetd by typing ps -ax and use kill -HUP id. Then, try to start the Hawkeye server again. If it complains about blocked POP3, NNTP or SMTP ports, you may have a look at inetd, too. SMTP, NNTP and HTTP may also be provided by stand-alone servers such as Sendmail, Innd and Apache. Be sure to terminate those servers before running Hawkeye, or use the -s command line switch described below to make Hawkeye ignore this service.

If Hawkeye complains that it can't connect your database, although everything as been installed correctly, you may have to reboot your machine an try again. We have not yet tracked down this problem (which is probably related to the MySQL server), but several users have reported that the program will run smoothly once the computer has been re-started.

2.3 Summary of Command Line Options

The following command line options may be passed to the Hawkeye server:

Command Line Switches
SwitchPossible values Default valueDescription
-b database name hawkeye This switch tells the Hawkeye server which database to operate on. A database must be first created with the install or init_db scripts.
-d data root directory /usr/local/hawkeye The data root directory contains the sub directories database/ and htdocs/, where your database contents and HTML/FTP documents are stored. If you don't want to use the defaults here, please make sure that the specified user has full access to these directories, or the server will not start.
-h your host's valid DNS name any This option forces Hawkeye to bind its services only to a specific host name on your system. It is only used if you want to run multiple Hawkeye servers at once, or if you want Hawkeye to cooperate with other programs such as Apache. The default any is not to bind the sockets to a specific address.
-l a file name or one of none, stderr none This switch tells Hawkeye where log to HTTP traffic (using the so-called 'common log file format'). You may give the name of a file to write the log to. If this file already exists, data will be appended. The default none is not to log HTTP accesses at all. stderr is only used for debugging purposes and makes the server log everything the the standard error output of your console. Please note: If you specify logging to a file or no logging, important system messages will continue to be logged via the syslog daemon facility.
-p database port number MySQL default Selects the database TCP port. It is currently not used.
-r - - Tells Hawkeye not to do reverse DNS hostname lookups for clients connecting the various TCP services. Useful if you have an Intranet which has no properly configured reverse address mapping or you want to skip the sometimes time consuming DNS lookups. Note however, that HTTP logs will only contain numeric IP addresses, and this may be bad if you want to analyze them with certain tools.
-s any combination of http, smtp, smtprelay, pop3, nntp, ftp all services With this option, you can enable only specific services the Hawkeye server can provide. The argument is a comma-seperated list of the service keywords, which may not contain spaces. smtprelay means the spooling of outgoing Internet mails. Select this only if you are connected to the Internet.
-t host running database localhost You can use this switch if you don't want to run the MySQL server on the same host as the Hawkeye program. Network installation and access restrictions can be very difficult. If you really want to do this, please consult the MySQL FAQ about accessing the database from external hosts. For most people, it should be fine to run the database server at the local host and not to use this switch.
-u any user login name hawkeye Specifies the user id the Hawkeye server is going to use. The server itself must be startet as root to initialize the service port. Afterwards, it switches to the specified user id. The user must have access to the MySQL database system and to the server root directory.

Here are a few examples on how to use the various command line switches:

2.4 Upgrading Hawkeye

Upgrading the Hawkeye server to a newer version is fairly easy. However, it is of course recommended that you have a complete backup at least of your database tables and the database/ subdirectory of your data root directory.

Just get the new binary package, and then take down the running Hawkeye server. Make 100% sure that Hawkeye is not running (for example by typing ps -ax), or your database may be damaged! Next, issue the following commands on the newly downloaded package:

	myhost:~# rpm -U hawkeye-x.x.x-x.i386.rpm
	[some help text]
	myhost:~# cd /usr/local/hawkeye/scripts
	myhost:/usr/local/hawkeye/scripts# ./update_db hawkeye
Note that you have to replace the database name 'hawkeye', if your database name is different. Do not run install if you don't want to create a complete new installation. If you have multiple databases, repeat to update_db script for each database. If everything was successful, you may start the new Hawkeye server. If update_db failed and you cannot get it to work, you can downgrade to the old version with the rpm -U command and the old package without fear.

2.5 Getting the Source Code

If you are interested in the ways Hawkeye works, or want to have a try on compiling Hawkeye for a different platform or operating system, you are welcome to download the source RPM (hawkeye-x.x.x-x.src.rpm). Please note: Getting the source code does not mean you have the right to do with it what you want. We have made the sourcecode available because we think this may be helpful. You may modify the source code only for internal use, and the modification of the program does not void the license agreement - if you use the modified version commercially, you have to pay for it. You may not distribute any modified version of the source code, and you may not use portions of it for your own programs without written permission of the author. Please see the license and copyright terms for details.


Back Forward Table of Contents