Back Forward Table of Contents

3. Taking a Look at Your System

3.1 A Tour around Your System

To continue with this chapter, you should have installed and started the Hawkeye server as described in chapter 2. Now you need to enter Hawkeye by using a Web browser. You must use a browser which understands frames, for example Netscape Navigator 3.0 (or higher) or Microsoft Internet Explorer 3.0 (or higher).

Just open a second browser window and repeat the following examples as you read them. This is the best way to become familiar with the Hawkeye server. Depending on your hardware and network configuration, you can enter the newly installed Hawkeye server by several ways:

If your Hawkeye server is already connected to an Intranet but you have not assigned any DNS names yet, you may be able to use the IP adress for the URL. However, we strongly recommend that you configure the Hawkeye server first, before you connect it to an Intranet or even the Internet!

By default, there are default passwords for some users in the system, which are quite easy to guess. Don't forget to change them if you are done with the tour! All this is discussed at the end of this chapter (3.12 and following).

Having connected the Hawkeye Web server, you should see the main index page from the Hawkeye sample pages. The Hawkeye sample pages are part of the first Hawkeye installation and are stored in the Web server's root directory:

	/usr/local/hawkeye/htdocs/
Always remember: There is no such thing as a 'typical' Hawkeye site. Everything can be configured and tuned, and you are strongly encouraged to do so. If, at a point, you want to have a look at the original pages, they are stored here:
	/usr/local/hawkeye/htdocs.dist/
The complete set of all sample pages demonstrate all available Hawkeye features and functions. You can do everything you want with the sample pages. Use them as base for your own pages, change or remove them. Remember, the sample pages are very simple but working samples for all available Hawkeye functions and features!

Hint: If you want to edit the HTML sample pages outside the Linux environment, for example on a Windows client machine, you should download them directly from the server using FTP and switching the transfer mode to ASCII! This makes it easier to deal with the different end-of-line marks of Unix (just uses NL to finish the line) and Windows (uses CR/NL).

Our short trip through all pages starts from the main index page. As you go on, you will notice that most frames carry some short explanations which may be worth reading... Plus, all pages contain their source file name at the bottom, to make it easy to find and modify them. If you don't like to read manuals and want to start immediately (we understand this completely), please read at least the text in the main index frame. Then, take a look around, experiment with the features... If you've any questions or problems, well, you need to continue with this chapter anyway.

3.2 Logging in

The server has a default configuration, part of which is the need to enter a login name and password if you want to enter the so-called Member's Area. The main page itself has no access restrictions (well, it has some restrictions. We'll find out about this later). The default configuration contains two users with different permissions:

Login NamePasswordExplanation
adminhawkeye System Administrator, has permissions to modify the entire system
userhawkeye Sample user. Can read and write email, send news, participate in chat rooms.

Both users are allowed to enter the Member's area, but you will probably start with the admin account to be able to use the Aministrator's tools later. Just click on the Member's area link and log in as user admin. Follow the next steps to find out more about Hawkeye functions and features and understand how everything is working. When you have completed your trip, you'll find a complete overview of the default configuration at the end of this chapter.

3.3 The Main Page

Source file: /index.htm

All HTML files for the main index page are stored in the Web server's root directory. The default configuration allows everybody to enter the Hawkeye site and view all pages which are stored in the root directory. Means: you don't have to login to see the site's home page.

The sample pages have a pre-defined directory tree, combined with a pre-defined Hawkeye system configuration, which you are encouraged to change to suit your needs. However, we strongly recommend to use the pre-defined system configuration and make changes there. Building a completely new site 'from scratch' can be difficult and care must be taken not to open any security holes. Of course, once you are an Hawkeye expert, you can try that out, too.

Click at the link to enter the member's area. A login box will appear and ask for your login name and password. Log in as user admin (see above), and you should see the index page of the member's area:

Source file: /mail/index.htm

From here, you can enter all Hawkeye areas. The window is split in two frames. The header frame contains links to other Hawkeye areas. It will change as you move through the different sections of the system. As mentioned here, you should probably remove the link to the "Administrator's Tools" in your own web pages, because it will not be useful for your users... Let us continue with the next area.

3.4 The E-Mail Area

Source file: /mail/index_mail.htm

By opening the E-Mail area, two things will happen. First, the specified Web pages will appear, nothing unusual so far. Second, an SQL database request is done and the result shown in the left frame: if there is new (unread) E-Mail for you, a table with some information about each E-Mail is shown. Otherwise you'll see the notice "No new email available".

The SQL database request is done by a Hawkeye function call. One way to call one of Hawkeye's functions is to use a so-called .bbs file. All files with the extension .bbs are parsed by the Hawkeye server. Such a file is an ordinary HTML page but contains one or more Hawkeye functions calls stored as HTML comment tags (see samples below). So, the function calls are completely compatible with the HTML standard. Look at this example which makes the server display a list of current mails:

	check for new mail: <!--/bbs?action=listmail&amount=new&target=main>
	show all mail:      <!--/bbs?action=listmail&amount=1000&target=main>

The Hawkeye function parser, which scans each .bbs file on it's way from the server to the client browser, will detect the function command line and execute the given command (listmail in the previous example). The function output is inserted in the current document directly at the position the function call was originally placed. So, you can create "dynamic" Web pages which have some kind of interactive content using Hawkeye's internal functions.

In the header table, you see two links to mail functions. You have the choice of only displaying the new (unread) mail, or all the mail you currently have. All this is done by using Hawkeye's functions. You cannot see the function calls themselves, because they are hidden by the command output when the page is displayed in your browser. To see how things have been done here, take a look at the appropriate .bbs files on the server.

You can even write mail online. Once again, a combination of two Hawkeye function calls lets you first enter your information and sends this as an email to any recipient, either an other Hawkeye user or to a world-wide Internet email address. Note however, that is may be not the most comfortable way to write large amounts of mail. Because Hawkeye supports the POP3 and SMTP protocols, the Internet standards for electronic mail exchange, your users can as well use any email software of their choice.

Write a short test mail to yourself! After sending the mail, you should see a nice report page. All of Hawkeye's functions can be assigned specific HTML pages which get displayed when the function executed properly, or in case of an error. You can use those status pages to tell your users what has happened and how they could probably correct a mistake in case of a failed action.

3.5 The Newsgroup Area

Source file: /news/index_news.htm

Opening the newsgroup area, a new set of HTML pages will be used. In the left frame you will see the list of all available newsgroups. Again, this is no static document which you would have to change each time you create a new discussion group. The list is instead created by another Hawkeye function call and thus will be up-to-date all the time. As an additional feature, newsgroups which contain messages not yet read by you are printed in bold style.

Clicking at a newsgroup name, you will get a list of messages currently in this group. Note how this is done using the Hawkeye listnews function. As with mails, it is possible to write news postings on-line using an HTML form. Again, if your users find this not comfortable enough, encourage them to use a news reader (NNTP agent) of their choice to make things easier to handle.

There are three pre-installed newsgroups at this time:

The group hawkeye.admin is only accessible to members of the group "System Administrators". If you login as the test user, you will not be able to see this newsgroup, and you won't get the chance to write an article in it. We will explain the possibility of restricting access to a newsgroup when we come to discuss the administrator's tools.

3.6 The File Area

Source file: /file/index_files.htm

The standard for file transfers on the Internet is called FTP (file transfer protocol). Introducing a quite robust design with several nice features like the re-start of broken downloads, it is perfectly suited for doing its job: transferring files, but little more. Hawkeye implements the full FTP command set, but introduces a new component: a full-text searchable file information database. This database holds meta information about the files, such as a file title, the name of the uploader, the date the upload was done and a complete content description. This makes it easy for the user to find the file he wants.

Each Hawkeye file area is basically represented by a directory under the /files URL, which would normally be /usr/local/hawkeye/htdocs/files. As it is with UNIX, the names used here are alway case-sensitive. Your users don't do their uploads directly to the given directory, but rather to another directory usually called /incoming. Once the file has been placed there, it is ready to be registered with the database and put in the chosen file area. New uploads will be hidden from other users until the system administrator has reviewed the upload and released it for the public.

3.6.1 Downloading a File

Source file: /files/findfile.htm

The file database can be searched for one or more keywords seperated by space characters. Entering no keyword selects all files. Additionally, the search can be limited to a specified file area and the maximum file age can also be specified.

Take a look at the page's source code and find out how this is done using the Hawkeye findfile function! If you add a new file area or rename an existing one, you have to update this page.

Downloading file is pretty easy, as it should probably be. Just display the file information using the search form. Now, you have the choice between using the HTTP link and make the download directly with your Web browser, or to log in via FTP and make the download from the given location.

When you use your favourite FTP client to log in, please remember to log in with your user ID and password. You may be able to connect anonymously, too, but then you won't have permission to enter the file area. Anyway, FTP is the recommended choice for file transfers, because it is generally more stable and robust then HTTP, which was not designed for really big files.

3.6.2 Uploading a File

Source file: /files/addfile.htm

Because HTTP, the protocol of the Web, does not allow file uploads (well, HTTP/1.1 actually does, but the interface is quite new and supported by very few clients at this moment), uploads must be done using an FTP client. As mentioned before, uploaded files are not placed directly into the chosen file area, but are placed instead in a temporary directory called /incoming. To do so, your users will need create permission on this directory. They do not need create permission on the file areas themselves, which is a big security advantage.

Once the upload has been placed in /incoming, the file registration form can be used to associate the file information with your upload. After clicking OK, Hawkeye moves the upload to the specified file area. Due to the features of the Linux ext2 file system, file names can be to 255 characters in length and are always case sensitive. It is generally not recommended to have whitespace characters in either directory or file names.

3.6.3 Checking new Uploads

As mentioned above, new uploads are first invisible for your users. Only the uploader himself and users with create permissions on the file area directory are able to see the upload. The latter persons can change the file's attributes to make it globally visible. Users with delete permissions on the file area can delete the upload and the associated database entry.

If you run a large site with many uploads per day, you may want to have something like an "file area administrator" who is responsible for checking uploads with anti-virus tools and testing them. Just grant the user create permission on the given file area, and he will be able to maintain the files located there. To remove something completely, he will need delete permission, however.

3.7 Chat Boards

A chat board is like a public place users can go to and chat speak to each other. A Hawkeye installation can hold as many chat boards as you want. If a chat boards becomes to crowded, your users could then switch to another one.

The default Hawkeye installation contains two chat boards, one of which is only accessible to members of the group "System Administrators". The chat is basically based on top of two Hawkeye functions, showchat and writechat. As HTML does not provide an interface for ever-changing pages, the chat page is reloaded every couple of seconds. To to this, your browser has to understand the meta/refresh tag combinations. Most modern browsers to (for example Netscape and the Internet Explorer). AOL's Web browser does not, so don't try to use it with the chat. By modifying the HTML pages of the chat, you can tune reload times and chat size. The default installation should have reasonable default values, however.

But the greatest chat does not work very well if you don't see who you are talking to. Therefore, Hawkeye's whoison function provides a method for displaying a list of users currently active in this chat board (active means: he or she wrote a line of text some time ago). Due to the restrictions of the stateless HTTP protocol, it is not really possible to find out what users are "logged on", but if a user writes a line of text in some chat board, the system can definitely tell that he or she is reading active in that room.

3.8 Personal settings

This page allows your users to change their profile, for example their street address or their telephone and fax numbers. The login name and the real name can not be changed by the user himself for security reasons. Opening the page, your existing profile is displayed in an HTML form ready for your changes. Note however, that you must always use a password to let your changes become active.

If you don't choose to use your old password, but want to have a new one instead, you may have to re-start your Web browser after you have changed you password. Some Web browsers have difficulties if the password is changed while a session is active,. So, if you see a message like "access denied" or something like this, re-start your Web browser and everything should be fine.

3.9 System and User Information

Hawkeye has a few functions to display some server statistics and a list if users of the current system. Some usage examples of these functions are given on the system and user information page, which should be self-explaining. If you are interested in how these things are done, take a look at the source code of the page, for example by retrieving it via FTP.

3.10 User Homepages

One of the most interesting features of the Hawkeye software is the possibility to let your users have homepages. Well, you say, Hawkeye is not the only Web server which can handle user homepages (in fact, nearly every Web server can). But Hawkeye handles homepages automatically, reducing the amount of time used for installing and removing homepage locations for your users greatly.

Each user which is a member of the homepage_group as specified in the system configuration is basically allowed to have a homepage. The location of the homepages is controlled by the option homepages, again to be found in the system configuration table. By default, this is /user/$n, where $n is replaced by the login id of the user concerned. Thus, if your login id is jsmith, you have the homepage directory /user/jsmith.

The benefit of this method is that the system can now decide who has access permissions on which directory. As it comes to homepages, the normal directory access permission rules are overridden if the user is the owner of the homepage location. This means, that even if you don't have create permission on the /user directory (and your users probably don't have!), you can edit your own homepage /user/jsmith because Hawkeye can identify you as the "owner" of this homepage.

Creating a new homepage is quite easy, and most importantly can be done by the user himself. All he has to do is to log in using an FTP client, and switch to the /user directory. The next step would be to create his own homepage directory by creating the jsmith subdirectory. Simple FTP clients can achieve this by typing "mkdir jsmith", some more advanced programs may have an extra option for creating a directory. That's it, you are done! Now you can upload your homepage files to your newly created directory.

Since Hawkeye keeps track of the homepages on your system (for being able to produce a list of currently active homepages), you should delete a homepage including the subdirectory if it is not longer used.

3.11 User Registration

Before we come to discuss the administrator's tools, let's take a look at the user registration process. On your site's default home page you will find a link to the "User Registration" form. Purpose of this page is to allow a new user to enter his personal profile and add him to the user database.

Try to add a new user to the database by filling in the registration form with some pieces of information. By successfully submitting the form, the user concerned will be added to the database and be given membership of the so-called entry group. This group does not have any special access permissions, it is solely for recognizing new users. When you - the system administrator - check the user's profile, you may change his group memberships.

3.12 Administrator's tools

Now it is going to get interesting. We are leaving the areas accessible by your users and go straight on to the source of all power: the system administrator's tools. ;-)

Note however, that those tools are nothing very special in Hawkeye's design. They are implemented again using a couple of internal functions, so if you don't like the design we have been using here, you can do it better yourself! The tools are in a way the HTML interface to the MySQL database the Hawkeye server is based on.

In the left frame, you see the tools, whereas the frame on the right side is used for output generated by the functions.

Display
This command is used to display a part of the system configuration. As you press the button, the list is displayed in the right frame. The contents can now be edited by clicking on the appropriate links.

Create
If you don't want to modify an existing database entry, but want to create a new one instead, use this function. Note that merely by clicking on the create button, a new instance is inserted into the database. If you don't want it to stay there, or if you think you have made a mistake, please delete this entry to keep things clean.

Display new users
A special function to check for new users which where added to the database by submitting the registration form.

Display user
As the user list grows very large, it is quite inefficient to re-display the full list every time you want to edit a specific user. Just enter her full name or login id here and click the button.

Who has been online during the last ...?
By clicking below, you can watch who has visited your site lately. Just select a time interval and press the button. If you miss a time interval you can't live without, just edit the HTML source and add it there.

Clean database
Using the sweep function, you can remove email, news and chat messages, which have reached their expiration date (see the "ttl" values in the System configuration). Especially if you run a large site, you should use this option regularly to avoid cluttering your database with old records, which can really slow things down. Cleaning the database may take between a few seconds and several minutes depending on the size of your database.

That's it. We are at the end of our little tour around your system. We hope you have enjoyed it!

3.13 Function Status Pages

As mentioned somewhere above, Hawkeye functions can be configured to use so-called status pages. This can be configured by selecting the Function Access Permissions section of the administrator's tools.

Basically, a status page is a simple HTML document which is loaded by the function if it exits. There are two ways a function can terminate: it can work ok or it can fail. For each of this cases, a seperate status page can be defined. Many functions additionally produce some output of their own, so there has to be a way of including this into the status page. This is done by using the special sequence <--!result--> in the HTML code of the status page.

If you want to learn more about designing status pages, just take a look at the default pages located in the /status directory of your installation path.


Back Forward Table of Contents