Back Forward Table of Contents

4. Administration Guide

4.1 Basic System Configuration

Hawkeye's database is based on SQL, and thus uses so-called tables to store both configuration information and data such as email or news message. The easiest way to access the configuration tables is via the Web server, using special function calls to modify Hawkeye's configuration. A set of useful HTML pages which address these internal function calls is shipped with the distribution. Once you have understood how the function mechanism works, you are welcome to modify them to fit your needs perfectly.

Let's go on to the first and most important table, the system configuration. It consists of simple key/value pairs of data, see below for the purpose of each option. Note that you do not have to restart the server if you change something here. All switches which are essential at startup time are specified via the server's command line. See section 2.3 for a reference of the command line options.

System Configuration Options
OptionPossible Value ExampleDescription
email_ttl number of days 30 This specifies how long to keep email message in the database. Emails exceeding this time limit are deleted when the system administrator sweeps the database.
entry_group a user group New Users If you allow new users to be automatically created via the adduser function, those users will be made members of this group. Very useful for the system administrator who can browse the list of group members to view any new users.
file_dir absolute path /files This is the main directory of your file base. The different file areas are subdirectories of the directory specified here.
file_upload absolute path /incoming The upload directory is where your users are allowed to place files per FTP. Once uploaded, those files can be placed in a file area by the addfile command.
homepages special string /user/$f.$l You want to allow your users to upload home pages into your system, you can use this option to specify where they are located. The special strings $f, $l or $n are replaced by the user's first name, last name and login, respectively.
homepage_group a user group Homepage Owners Only users which are members of this group are permitted to create homepages at the location specified by homepages.
hostname server's DNS name www.myhost.com The full name of your server. It is needed for correct logging and by some internal functions that generate links.
mail_domain server's mail domain myhost.com This is the part following the @ of the email addresses you want to manage with Hawkeye. If you want your users to have the email address <login>@domain.com, set this option to domain.com.
mail_relay mail transfer hub mail.myprovider.com If you are connected to the Internet, Hawkeye is able to deliver email messages world-wide by using the SMTP protocol for sending emails on the Internet. The mail hub is the external SMTP server to which all mails are sent. If you are unsure, please ask your Internet provider what to enter here. If you don't enter anything, your server will run fine, but it won't accept any outgoing Internet mails.
queue_ttl number of days 10 If your mail relay (see above) cannot be contacted immediately if outgoing Internet mails are to be sent, those messages will be queued for later delivery. If they get older than this limit, they will be discared silently. In a working environment, however, this will never happen.
use_nntp a user group Registered Users Users who are members of this group are allowed to access your server via the NNTP protocol to use their favourite news readers to read the discussion groups. If you have disabled Hawkeye's NNTP server, this option is without meaning.
use_pop3 a user group Registered Users Users who are members of this group are allowed to access your server via the POP3 protocol to use their favourite mail readers to read their email. If you have disabled Hawkeye's POP3 server, this option is without meaning.

4.2 Users and Groups

One of Hawkeye's major features is the ability to restrict access to all of its services to so-called user groups. This works just like the group permission system of Unix or Windows NT. Once you have created a user, he or she can be member of any number of groups. Access to a certain news group, chat board or file directory can be restricted to one group. Everyone who wants to have access must be a member of that group.

Let's say you have created a chat board called hawkeye.talk.secrets, and you want only a few of your users to have access to it. To achieve this, you would create a user group, let's name it The Wise Men and restrict read and write access of your chat board to this group. Afterwards, just make the users of your choice members of The Wise Men. That's it. Note however, that there is no such thing as an Administrator User (Super User). Even you, the system administrator, won't have access to the chat board if you are not a member of the associated group. To give yourself a maximum of power, you would probably make yourself a member of all groups you have created on your system.

There is a special group called everyone on each Hawkeye installation. 'Members' of this group are not only all of your users, but also anonymous logins from the Internet (users who have not presented a name and a password). Be extra careful when assigning permissions to this group! If you don't want to have any anonymous logins, make sure you have not addressed everyone in any of your access permissions.

It might also be useful to create a group Nobody (or something like this), to explicitely disable certain features. For example, if you don't want to have CGI scripts in a certain directory, you could set the execution permissions for that directory to Nobody and be sure your system security won't be compromised by any evil scripts getting executed. In this case, even you yourself should not be a member of this group.

With the user editor, you can specify the memberships of each user simply by selecting the groups you want her or him to be a member of. If you create a new group using the Web interface (or modify an existing one), there are a few options which can aid you in changing membership of many users at once:

4.3 Service Administration

4.3.1 Discussion Groups ("Newsgroups")

Hawkeye allows you to create any number of discussion groups, which can be accessed both via special functions of the Web server and by NNTP and a custom newsreader software. The following aspects of each group can be customized:

Newsgroup Configuration
OptionPossible Value ExampleDescription
News Group any string hawkeye.manual.help The Newsgroup's name. If you plan to make your groups accessible by NNTP, you should stick to lowercase names with dots in them (no spaces), or certain newsreaders will get confused.
Keep Articles number of days 30 This specifies how long to keep news message in that group. Articles exceeding this time limit are deleted when the system administrator sweeps the database.
Read access user group Registered Users Only members of the specified group will be able to read messages in this discussion group.
Write access user group Registered Users Only members of the specified group will be able to post messages to this discussion group.
Delete access user group System Administrators Members of this group may delete any news message of this discussion group. Usually, only a few selected people should be able to do this.

4.3.2 Chat Boards

Hawkeye's chat boards are places where your users can talk to each other using an easy-to-handle Web interface. You can create any number of chat boards, and may configure a few things:

Chat Board Configuration
OptionPossible Value ExampleDescription
Chat board any string hawkeye.talk The Chat board's name. Use anything you want.
Keep messages number of days 5 This specifies how long to keep the message on this board. Messages exceeding this time limit are deleted when the system administrator sweeps the database. As chat boards can grow quickly, it is not recommended to use a very large limit here.
Read access user group Registered Users Only members of the specified group will be able to read messages on this chat board.
Write access user group Registered Users Only members of the specified group will be able to post messages to this chat board.

4.3.3 Directory Access Permissions

Files provided by Web or FTP services are stored below the htdocs/ subdirectory of your Hawkeye installation. If you add files here manually (on the Unix command line, and not by Hawkeye's FTP server), you must always make sure that the server can properly access these files. Just set the file owner to the user under whose permissions you run the server. If you upload the files using Hawkeye itself, you don't need to worry about Unix permissions at all - the server will do that for you.

Using the directory table, you can specify which of your users have access to certain directories on your system. As the file base is shared between the FTP and HTTP services, some options (such as the CGI permissions) make only sense for one if these servers. If a subdirectory is not explicitly listed, the access restrictions of the parent directory will be used, i.e. if you set the / directory to be readable by your users only, all files on your system will require a user login, unless expressly stated otherwise in a different entry.

Directory Access Permissions
OptionPossible Value ExampleDescription
Directory absolute URL /images/backgrounds The URL path of the directory, always beginning with a slash (/), but without the leading http://hostname.domain.
Read access user group Registered Users Only members of the specified group will be able to access the files in this directory, or to display a directory listing (FTP).
Create access user group System Administrators Only members of the specified group will be able create files or subdirectories in this directory. To overwrite existing files, one needs delete permission, too.
Delete access user group System Administrators Only members of the specified group will be able to delete files and subdirectories in this directory and to remove the directory itself.
Execute access user group Nobody Members of the specified group are allowed to execute CGI scripts located in this directory. CGI scripts must have have Unix execute permission. Please see section 4.4 for details on CGI scripts.

Note that there is one global exception to this access rules: if a user is allowed to create a homepage (and thus is a member of the homepage_group, see above), she has unrestricted read, create and delete access on her own homepage directory and any subdirectories. A homepage can simply be created when the user herself creates her own homepage directory via FTP. The server recognizes this and adds her to the list of "homepage owners". She is removed from this internal list if she deletes her homepage directory.

4.4 The Web Server (HTTP)

Hawkeye's Web server currently supports HTTP/1.0, an Internet standard shared by all major browsers. There are a few advanced features of HTTP/1.1 already supported, such as persistent connections and conditional get methods, which greatly improve server performance. The Web server has many "built-in" functions which are used to read and write email and news messages, search the file database, participate in the chat rooms, display server and user information, and even for administering the server itself.

The server operates on the htdocs/ subdirectory of your Hawkeye installation. This means that if you have installed Hawkeye under /usr/local/hawkeye, the file

	/usr/local/hawkeye/htdocs/test.htm
will be visible on the Web under
	http://your.host.name/test.htm
By default, there are no access restrictions placed on the server root directory, but you may want to change this using the administrator's tools (see
above).

The server's internal functions are addressed by the special URL /bbs?action=xxx which is usually followed by one or more parameters. For example, the following URL,

	http://your.host.name/bbs?action=whoison&chatboard=chat.general&minutes=10
will produce a list of users who have been active in the chat room chat.general during the last 10 minutes. As you can see, the parameters are delimited by an ampersand sign (&). Some functions require a number of parameters to work, others have optional arguments. Please refer to appendix A for a complete list of available function calls. As you can imagine, these functions provide a powerful interface to the services provided by the Hawkeye server suite. Thinking of server performance, this solution is far better than the traditional way of doing this kind of thing via CGI scripts. When an internal function is called no sub-process needs to be started. Please try to experiment a little with these function calls! A good point to start is just to open the URL
	http://your.host.name/bbs?action=testcgi&coffee=hot&tea=cold
and to see what happens. The testcgi function has been created solely for testing internal function calls, because the URLs can become quite long and maybe somewhat confusing. Don't be afraid of using this tools, they are what makes the difference between Hawkeye and a traditional Web server!

As you have become familiar with Hawkeye's internal functions, let me tell you that there is an even more powerful way to call and integrate those function calls into your Web pages. Hawkeye supports so-called parsed HTML pages which allow you to place a function call directly in one of your documents. By default, the documents which are to be parsed that way have a .bbs extension which makes the server recognize them as files who need a special treatment. Just consider the following example (named test.bbs):

	<html>
	<body>

	<h1>Who is online in chat.general?</h1>

	<!--/bbs?action=whoison&chatboard=chat.general-->

	That's it!

	</body>
	</html>
The <!--...--> tells the server to execute the internal function and place the result directly into the current position in your document. You can use any number of internal function calls in a .bbs-document, but please note that there may be only one per line (which is not really a limitation because HTML does not render line breaks as they appear in the document source).

Another feature of the server is the support of CGI executables. CGI, the Common Gateway Interface, defines a standard for external binaries to be executed by the server having their output redirected to a dynamically created Web page. Hawkeye supports the complete CGI/1.1 standard, thus allowing CGI outputs, CGI redirects and the so-called Nonparsed Header Scripts (NPH). To make the server recognize a file as a CGI executable, the Unix execute bit must be set, for example by typing chmod a+x file at the shell prompt of you system. There is a small example script available, just open the URL /cgi-bin/test.cgi and look what happens.

Probably you did already hear this a few hundred times, but let me stress one thing again: CGI scripts always are a security risk for your installation. In Hawkeye, CGI scripts are run under the server's user id, because some scripts may want access to the SQL database. Don't install a script you do not know exactly what it is doing. Never allow untrusted users to have execute permission on their homepage directories.

4.4.1 Function Access Permissions

There is a configuration table which defines access permissions for all functions available on the system. Functions not listed here will not be executed for security reasons. Additionally, a so-called status page can be defined twice for each function. If a status page is configured and the given URL exists, this HTML document is printed when the function returns either successfully or some error occured. A status page for the sendmail function in case of failure could look like this:

	<html>
	<body>

	<h1>Oops, can't send your mail!</h1>

	The server said: <!--result-->

	</body>
	</html>
The <!--result--> tag is used to include the original function output into the status page. In this example, the server will output the reason of the failed mail transfer at this place. Let's take a look at the configuration table for function access and status page definitions:

Function Access Permissions
OptionPossible Value ExampleDescription
Function any string sendmail The function's name. For a complete list of functions, please refer to appendix A.
Access group user group Registered Users Only members of the specified group will be able to execute this function.
Success URL URL path /status/sendmail_ok.htm HTML status page displayed if the function was executed successfully. This page may include the <!--result--> tag to include the original function output (but as it worked OK, this is not very interesting here).
Failure URL URL path /status/sendmail_fail.htm HTML status page displayed if the function did not execute correctly because of an error. This page may include the <!--result--> tag to include the original function output which will contain a description of the error encountered.

4.4.2 MIME Types

The HTTP protocol uses a mechanism known as MIME (Multipurpose Internet Mail Extensions) to identify the contents of a file being transferred. It is a common misunderstanding to believe that a file called foobar.html is assumed to be an HTML source file. Files are, in fact, identified by their file name extensions, but this is done by the server. The client does not need to bother with extension mapping, it will get a hint by the server (a so-called MIME type) which type of file he has to cope with. If you don't understand a thing now, there is no need to get nervous. Hawkeye comes with a reasonable default configuration which should be enough for 98% of all Web site installations. However, for expert users, there is a possibility to change the MIME type mapping:

MIME Types
OptionPossible Value ExampleDescription
File extension any string jpg The file extension (without the dot) used to identify the file's contents. There may be more than one extensions for a file format, for example jpg and jpeg for JPEG encoded image files. Please use seperate entries to reflect this in your configuration. Do not enter multiple file extensions here!
MIME type any string image/jpeg This is the MIME type description Hawkeye will pass to the browser if a file with a matching extension gets transferred.

4.5 The File Server (FTP)

Hawkeye's file server implements the most important parts of the FTP command set as defined by RFC 959, and should thus be compatible with any modern FTP client. The server operates on the same directory structure as the Web browser, which means that the URLs http://your.host/test.html and ftp://your.host/test.html refer to the same file.

Unlike HTTP, where user authentification can be done each time a page is accessed, FTP requires your login name and password directly after the connection has been established. Anonymous login (using "ftp" or "anonymous" as login id and your email address as password) is only allowed if you have configured your root directory ("/") to be readable by everyone. If you want to use extra permissions, as needed for creating new files or directories, you have to use your personal credentials, of course.

Users will need to use the FTP server when creating their homepages or making uploads to the incoming directory. However, the use is also advised when doing large downloads, as Hawkeye's FTP server has the capability of re-starting large, broken downloads. This can save you a lot of time and some nerves, too. We recommend using the FTP server for site administration (updating HTML pages etc.), too, because you don't have to bother with Unix access permissions on the files. Hawkeye will take care of this.

4.6 The Mail Server (SMTP/POP3)

There are two different Internet standards for receiving and sending Internet mail. The SMTP (Simple Mail Transfer Protocol) specifies a way of spooling and relaying outgoing Internet mail. Hawkeye implements the SMTP standard as defined by RFC 821. Each user of the system has two valid Internet mail addresses The mail_domain is taken from the system configuration table and is usually an Internet Domain for which a so-called MX record has been established in the DNS system. If a mail_relay has been specified (a mail relay is another SMTP server used to forward mails to their final destination), outgoing Internet mails will be accepted by the Hawkeye server and immediately forwarded to the mail relay. If this fails for some reason, outgoing mails are queued and delivery is attempted again at some time in the future.

As you have seen, each user is assigned two Internet mail addresses automatically. But sometimes, it can be useful to have certain mail addresses like info@my.firm or sales@company.com without having a user who is called info or sales. To do this, Hawkeye since version 1.1.0 supports a so-called mail alias table. Before a mail is delivered, the server takes a look at this table, and if the desired mail address is found, the mail is instead delivered to the destination address. Note that you can have a chain of aliases here, for example you could have an entry which maps info@... to support@... and another one which forwards support@... to user@.... However, to prevent loops, the server does a maximum of ten lookups on the table.

Mail Aliases
OptionPossible Value ExampleDescription
Alias address email address or login name support@your.mail.domain This is the email address or the login name of a user whose mail you want to forward to someone else. The user specified here does not need to exist on your system at all, so you may specify any possible email address here.
Destination address email address or login name admin@your.mail.domain This is the email address or login name of the user who will actually receive the mail. You must specify exactly one valid address or login name here. Multiple addresses seperated by comma will not work.

Receiving (polling) of Internet mail for the single user can be performed using POP3 (Post Office Protocol, Version 3) which is implemented by all major mail readers. Of course, mail can be read by using the HTML interface, too, but using POP3 and a professional mail reader is the fastest and most comfortable way to handle Internet mail.

By implementing both SMTP and POP3, Hawkeye is a full-featured mail server and you don't need any additional software like sendmail, which can be quite tricky to configure. However, you do need an external mail relay if you want to send mails out to the Internet. If you are unsure, ask your Internet provider. He will probably run a server of his own you can use to forward your mails to.

4.7 The News Server (NNTP)

Even if there are some common features, newsgroup articles use a completely different transportation scheme than mail messages do. The Net News Transfer Protocol (NNTP) was designed to send Usenet news messages over a TCP/IP connection and is today implemented by all news readers. Hawkeye implements NNTP as an interface to its own discussion groups, so your users can use a news reader of their choice to read the newsgroup articles.

As mentioned above, basically any news reader can be used. There is, however, one big difference between Hawkeye and a traditional NNTP server: As news messages are traditionally accessible by everyone on the Net, Hawkeye requires a login name and a password to determine if the user really has access to a newsgroup. To be usable with Hawkeye, a news reader must thus implement the NNTP authentification scheme as specified by the current draft of the NNTP working group. All major newsreaders we have tested have been found to be working well. Just remember to log on with your name and password, anonymous logins won't work.

A last hint about newsgroups: If you plan to provide access via NNTP (which you should probably do if you have discussion groups), you should use only lowercase characters and dots in the names of your discussion groups. Using spaces or some non-alphabetic characters may confuse news readers which do only know names like comp.os.linux.announce.


Back Forward Table of Contents