capsu.org // Hardwar // HS3 // Partial Code Release 1 Notes

In this document:

• Important!
• Requirements
• Setup
• Brief Code Overview

Important!

This code is not complete or tested. It has not been released as a finished product. It is not supported by the author, nor is the author liable for anything you may experience while using the code.

You should NOT run this code unless you have a reasonable knowledge of computer programming and internet servers. This is not finished software. It has no documentation. No user interface. There is no support. And it will produce unexplained errors.

You should NOT run this code on any mission-critical machine. It will cause excessive CPU usage at times. It probably leaks memory. It may cause the operating system to become unstable. It may expose you to additional security risks.

While all reasonable attempts have been made to secure the code against malicious attacks, it is conceivable that it might be hacked to expose the host's computer. (Theoretically a command sequence might be executed via the in-game robot which somehow runs as code in its own right, much like "; drop database" in a mySQL-powered webform - I simply haven't examined this in enough detail to ensure it isn't possible, although the most obvious exploits have been countered.)

Requirements

• Windows 2000, XP, or later. Windows 98SE (with updates) mostly works, but you must install "Windows Management Instrumentation" from Microsoft. Earlier versions of Windows are not supported.
• Python 2.4 or later (the "subprocess" module is used, which only exists in 2.4 and later) - http://www.python.org/.
• Python for Win32 Extensions (these are heavily used by the server restarting code) - http://starship.python.net/crew/mhammond/win32/.
• A webserver - I have used Apache 2, but anything should work - http://www.apache.org/.
• Hardwar...

Parts of the script were originally intended to work with Hardwar UIM06 only (basic server maintenance and information, not detailed statistics), however I only ever extensively ran it using Smurph's Enhanced2 file. It is highly recommended you use the most recent Enhanced2 (earlier versions may fail due to a change in the way the REPORT function worked).

The script can be downloaded from http://www.capsu.org/hardwar/hs3/download.html.

Setup

The game, webserver and script are all assumed to run on the same machine. Hardwar must be installed and listed in the registry correctly. There are no specific checks on this - you will get meaningless errors about path "" not being found, and such like if the game isn't there. Only one game can be monitored per machine.

Copy the contents of html subdirectory to your webserver. The .css and .ico file should be left in the root (or whatever directory you intend to place the HS³ output). The images should be in a subdirectory called images.

Most settings are held in the registry, in HKEY_CURRENT_USER\Software\Refinery\hardman\Config\HS3. None of the code for editing these was ever written (although the script will create an entry using defaults when it finds none). So you should first run setup.reg, and then use regedit to make changes. Change at least:

• admin_password - set a password for the "admin" user.
• h_password - set a password for the "h" user - the interactive in-game robot.
• root_password - set password for the root user - by default "a", which extracts information from the game.
• output_www_path - path to the webserver directory.
• public_ip - public IP address for the server.

Note that the passwords are not currently encrypted, so are exposed to any application on the machine. There are many different settings, which are explained by running py/_ini.py.

The Terminal Server port must be open on Hardwar (9001 by default). However, this value is not displayed on the web pages by default. It is recommended that you block access to the port from the internet via a firewall.

It is highly recommended that you let HS³ start a new game, rather than applying the script to an existing game. However, an existing game should work. If my reading of the code is correct, HS³ will always default to running and restarting the most recently saved game it finds in the main Hardwar directory. When it creates a new game, it will use the name default.sav. You can safely copy other game saves into subdirectories.

Running hs3.py (or hs3.py -m or hs3.py --monitor) will start the script monitoring the Hardwar server. This:

• Checks the game is running, restarts it when it goes down, and generally logs things.
• Collects pilot data, which it places in XML data files.
• Creates static HTML pages in your webserver directory.

To add the in-game robot "H", you should run a second instance of the script, using hs3.py -b or hs3.py --bot. This can be started at any time, however to avoid accidentally creating duplicate Hs in the Hardwar game (some sort of bug related to pilot creation while the game is loading), it is best to wait until the game has started before launching the robot. This allows users to interact with H - see the user guide - http://www.capsu.org/hardwar/hs3/h_user_guide.html.

Two further text files, allow further information to be fed into the system:

• home.txt - This contains various bits of information found on the homepage. It can be edited at any time, but will only update the homepage when the rest of the information is updated (every 30 seconds by default). Add or delete entries below each [section] - one per line. Basic HTML can be used here, but only things that work within lists (links, text formatting, etc).
• special.txt - This contains the names of pilots with special permissions. Names can be added under each of the [sections] - but do not delete the defaults (admin, a, h, unnamed pilot). A or H would need to be edited if you change the root_username or h_username in the registry.

Each pilot may be listed in special.txt as one or more of:

• Admin: Not included in statistics. May moderate PMs.
• Bot: Online and login status not recorded. Not included in statistics.
• Moderator: May moderate PMs.
• Ghost: Not included in statistics.
• Cheat: Not included in statistics. Marked as cheat.
• Mute: May not send private messages or post to bulletin board.

You may need to tweak your webserver to serve up .wml files (WAP output) correctly. For example, to configure Apache 2.x, you may need to add the following lines to httpd.conf:

Brief Code Overview

Firstly, to anyone that isn't familiar with Python - there are no bracers - these are achieved using tabbed indents. The .py files are viewable in any text editor, and are self-compiling when run. Most classes and functions are documented using """text""" at the top of each section - Python can be used to process all this information.

Unlike the language, my organisation and implementation of it is not easy to follow. I started to break code into modules (the "py" directory) but didn't get very far. Everything else is in hs3.py. Most of the main components are in classes, although take care, because some classes reference functions within other classes. XML is read via parser classes, which aren't quite as easy to follow. The use of XML may seem curious now - it is slow given the volume of data, and its processing causes CPU spikes. However, when I first started writing the code, the amount of data collected was minimal, and a proper database backend seemed excessive. The most confusing parts are the telnet code (I don't fully understand telnet) and server restarting code (I don't fully understand computer process behaviour).

The most manic is the code for the robot H, which needs a complete re-write into a more structured form - it started as a few lines and endlessly had functions added. Since H can't respond to names with spaces in them (Hardwar Terminal Server flaw), this part fo the code was largely ignored. H occupies a separate process because the code isn't currently multi-threaded - it can only do one thing at a time. Indeed, I think H itself is still prone to failure when commands are sent in the few milliseconds that it is processing information and not listening for commands.

I'd love to be able to explain this in detail, but it has been a year since I last looked at it, and parts didn't make much sense then. If you can get any value out of it, then feel free to alter, modify or distribute it as part of another application. If you use a subtantial part of it, you should provide adequate credit. If you do distribute any of the code, you must accept liablity for any errors within it.

Tim ("timski") Howgego
http://www.capsu.org/hardwar/hs3/
29 July 2006