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:
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 Name | Password | Explanation |
---|---|---|
admin | hawkeye | System Administrator, has permissions to modify the entire system |
user | hawkeye | 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.
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.