DireqCafe 3.0

Users Manual

By A.J. Venter

Index:

Introduction to DireqCafe

Installation

The Administration Panel

Settings

The Ticket Generator

Adding Time For Users

Monitoring Users

User Cleanup

The Transaction Log

HTML Export

Plain Text

CSV Export

SQL Export

The User timer

Credits

Introduction to DireqCafe 3.0:

Direqcafe is an advanced tool for managing internet Cafe's running LTSP based thin client systems. The first version of DireqCafe was written in one evening between the hours of midnight and 3am.

It was a fairly decent base system, on which a lot of future development particularly on the GUI side would follow.

However there was a few crucial design flaws in that original code-base, these made the system hard to install, and impacted on performance.

Thus with DireqCafe 3.0, I decided to do a rewrite from scratch. This new version is written in pure Object Pascal (Delphi) using the Lazarus IDE and the FreePascal Compiler. There is no longer any dependency on Apache.

The reason I started from scratch, is because I wanted to change a large number of core design structures, in order to replace them with better designs based on nearly two years of experience supporting and developing the older versions.

The core changes were:

1) The entire database structure was completely redone in a much

more efficient manner.

2) The system is far more scalable to different environments and less

will install easily on any distribution with the correct libraries.

3) It is much easier to use, and simpler to manage.

4) All files are stored together under /usr/share/direqcafe

5) A series of sanity checks at startup ensure that these files are

always present.

6) The transaction tracker was improved for greater acuracy.

7) Most fundamentally the new backends are more scalable, allowing

many new features. For example already present is the ability to

export transaction logs to many different output formats, for integration with other tools.

I hope that this new release will be useful to people, and that it will greatly improve the experience of running GNU/Linux based Internet Cafe's for them.

Installation:

There are two ways to obtain direqcafe 3.0, the first is as a source package. This is only recommended for programmers who wish to look at the code. The other is as a self-extracting package with a nice graphical installer. This is the recommended way for normal users to install the system as it handles several other pieces of configuration for you. If you would like to have the source, perhaps in order to contribute (wink wink) you will also need the lazarus ide available from http://www.lazarus.freepascal.org in order to compile the code.

The rest of this manual will focus on the self-installer. Please note that the script you download must be run as root inside an X (GUI) environment..

When you run the package, it will extract, and once finished, will start a setup program. The setup program will keep a splash screen open throughout the operation, this was done because I thought it looked cute, it doesn't actually do anything else. Just don't close it.

More important is the sequence of dialog boxes which it will also open, these will run you through the installation process.

The first one will ask you to accept the DireqCafe license agreement (which is the standard GNU General Public License)

Note that you cannot complete the installation without accepting the license.

If you accept the license, the next screen you see looks like this:

The text inside will build up as it does the different tasks. Once they are all complete, the “Next” button will become visible. At this point, the system is installed and all that remains is to set up a few settings which must be done before it can run.

The first of these is the cron job for the counter program:

All you need to do is tell the installer where the root users' crontab file is located on your system. The default value will work on most but not all distributions. RedHat likes (including Mandrake) tend to place it in

/etc/crontab for example. You can skip this if you would rather set the cronjob up manually. Also if you are reinstalling DireqCafe on a system you installed before, you should skip it as it is not repeat safe.

The last bit is sadly, also the most difficult. We need to set up your X-Session management to work with direqcafe. Session Management means the way your graphical system knows that you have logged out of your desktop. In DireqCafe we partially hijack this method to allow us to cleanly log users out who have run out of time. Session management works by means of a script. Every command in the script is run for the user when he logs in. Generally all these commands are placed in the background except the desktop itself which is left in the foreground. Then when the user closes his desktop, the script finishes, and X logs you out.

With DireqCafe installed normal users still work like that, however internet cafe customers do not, their desktops are loaded in the background, and the DireqCafe timer is run in the foreground, when that exits then, the user is logged out. As of version 4.0 X has introduced a set of Session Management error checks. One of which will, if your sessions runs for less than 10 seconds pop up a message before logging you off. This is a problem for direqcafe, as it means that a user with zero time (who should be instantly logged off) can now work all the time by simply not clicking on the message box. To get around this we add another foreground command in the session management script, after the timer.

A simple bash: sleep 15

When the timer now exits, the script runs that, and waits a full 15 seconds before closing, preventing this error from occurring.

The first step in setting up your session manager is to tell the installer where your distribution puts it's session management scripts. The default is correct for redhat likes, but the real value differs between almost all distributions so you will need to check your distributions documentation to find it.

The second question is what command you use to launch your chosen desktop. The default value here is correct for KDE installed from source, or on slackware, yet again the path and command may be different on your system so please check it beforehand.

Again you have the option to skip it if you wish to do so, but it is probably easier to let DireqCafe do as much for you as it can. Once you click next, you will see a screen like this:

Here you can see the generated script, which is basically a simple skeleton. You can make any obvious changes you see a need for here, or even rewrite it entirely if you wish, using it merely to give you the bits direqcafe needs.

When you click next, your old X-Session file will be backed up, and replaced with the version in this window.

The Administration Panel

The screenshot above shows the DireqCafe administration panel. The buttons were layed out according to the frequency with which I expect they will be used. However, this is not the order in which certain elements will be first accessed, hence I will describe the different sections out of order. Please note that the administration panel (which is started with the direqcafe command) will refuse to run unless you are the root user.

Settings:

The first time you start the tool, before you do anything else, you should adjust the core settings to your environment. This screenshot shows the settings menu with the standard default values:

There are two parts to the settings menu, the first is used to adjust direqcafe to your operating environment, the second to adjust it to your business environment.

The first three fields adjust DireqCafe to your operating environment, the first is the browser command field. This is used to specify a web browser. A number of typical defaults are already entered in the drop-down list, but you can enter your own value instead should you wish. This is true of all drop down lists in DireqCafe.

The second field is the Desktop Watch Command, this is used by the counter program. Because the counter cannot start counting down until the desktop is loaded, it needs a way to determine when this has happened. It does so by checking the users' process table for a certain command. Once that command is running, the timer starts to run. The menu contains:

kicker – use this for KDE

gnome-panel - use this for Gnome

You can also enter your own value if you use a different desktop.

The next field is used to set your text editor. DireqCafe uses a text editor for a number of tasks, most importantly to display transaction logs exported to other formats (I felt it better to allow the user to use his favorite text editor, rather than write a text block module from which the data must then be transferred).

The last two fields are used to set the system up to your local business environment. The first is simply your local currency symbol, the menu here provides you with a few common ones but you can enter any string you wish.

Finally there is the price per minute. For now, that remains the standard mechanism for interacting with the transaction log, simply because it is very easy to code. With this, you can set the price specifically in whichever way you wish. The log will know which price was set for any given transaction.

The ticket Generator:

While it is still possible to create internet cafe users manually as was done with earlier versions, the recommend way now is to use the ticket generator. It makes an internet cafe easier to manage, more userfriendly for your customers and above all takes less time.

The ticket generator is basically a specialized user creation tool. It takes a basename, and a counter starting value, then generates as many users as you requested with time prealloted as per your entries. Finally it generates a page of printable tickets with time which you can then sell.

Users created with the ticket generator, is setup for password less login. Remember though, that these tickets are allocated to users, if the user already exists and has time, he will simply receive more time. It is probably best to avoid this, as an earlier ticket may well have been sold to someone who still owns the previous time on it. Therefore I recommend that when generating new tickets, the counter start value be set higher than the last time.

Above you can see some example tickets.

Adding time for users:

After a user buys a ticket, they will often wish to put more time on their accounts, especially if they are about to run out. The time add dialog box looks like this:

In the drop-down list you will find all the available icafe users, in the bottom fields set the amount of time (hours and minutes) to add.

Once done if there are no errors, you'll see a dialog like this, telling you the total time the user now has (i.e. what you added plus what the account already contained) and how much money he owes (the price is for the time now added, NOT including any time already there. This user had 60 minutes available already, and the price was set to $2.00 per minute. I added another hour, giving him a total available time of 120 minutes. He must now pay me another $120.00 (I suspect actual icafe's using USD do not charge quite two dollars per minute).

Monitoring Users:

The user monitor in DireqCafe 3.0 has several important enhancements over it's predecessors. The most important of these are:

More informative status messages.

Real time display updates.

Easier control of the data viewed.

Here is a typical view of the user monitor:

In this default view, only those users that are currently logged in is displayed, here you can see, one logged in user.

You can selected any logged in user, clicking the “Kick Selected” button then will forcefully kick the user of the system, essentially forcing a log-off.

It takes a few seconds for a kick to take effect, during this period the users' status will change to 'kicked' and once he is off, it will change again to 'Not Logged in'.

In this screenshot you can see the view, after clicking the “Show All” button:

Notice how, when selecting any user not currently logged in, the “Kick User” button is disabled. The “Show All” button has also changed, it now says “Show online only” clicking it again will revert to the view we saw before.

User Cleanup:

The user cleanup tool is a new feature in DireqCafe, intended to simplify the management of icafe accounts, both on the DireqCafe and on the Unix level.

It has two versions:

The top part of the window is used to delete a single user. Select a username, and click OK, the user will be removed from the database, the unix account deleted and the home directory removed. Note that this is a destructive process so please double-check your selection before clicking.

Transactions the user made will not be erased.

The second version, known as autoclean, is used to rid yourself of old used up tickets. Clicking the autoclean button will scan the database for users accounts with no time let on them, and then completely erase them as above.

The Transaction Log

Finally there is the transaction log. This is not a full scale accounting system nor is it meant to be, it is merely intended to track sales in your icafe. However unlike the earlier versions of DireqCafe, version 3.0 can export it's transaction log to a variety of formats (rather than simply displaying html) for importing into other packages.

To use it, select a start date, end date and output format then simply click Okay.

HTML Export:

This is the default format, and two varieties are included. The default setting is HTML (View in browser) – this setting will generate an html page showing the transaction log for your chosen period, and display it in the browser you selected.

The other method (just HTML) will open the generated file in a text editor instead, use this if you wish to make changes to the look and feel before saving it permanently.

An HTML Transaction log.

Plain Text

The next available option is Plain Text, the most basic format for data on a computer. Choosing this you will get a simple text output, with field seperated by five spaces, of the log for that period.

CSV Export

Comma Separated Value files are a simple way to do text based tablature of date. The resulting document is hard to read as such, but can be very easilly imported into a variety of other formats, most notably CSV is ideal for importing into a spreadsheet program. Note that these CSV uses the quote (“) character as a text delimiter.

The screenshot shows the same log, exported to CSV format, and then imported in to OpenOffice.ORG calc as a spreadsheet.

SQL Export

Finally there is the SQL export function. This was deliberately kept simple to ensure maximum interoperability with a variety of databases. The file does not specify any specific field types for example. It can be used to import the log into any SQL table with four fields called 'transactions'.

If you want to use it “as is” I suggest you create the transactions table as follows:

The user timer:

The last part of the system is the user timer. This is the part that your customers see. It is a very simple program, that only does three things from a user point of view (quite a lot of other things are handled in the backend like checking when the desktop is logged out etc. but these are all fully transparent to your customers).

The three things the timer does for a users is:

It tells them how much time they have on the system/

It allows them to pause the countdown and lock the display, for example to visit the lavatory.

It allows them to log off (They can also use the desktop log-out button of course).

Here is a typical view of the timer:

The time is displayed in the title bar, so it remains visible even if the window is minimized, and also in the button in the center. Closing the timer logs the user out. Clicking the button in the middle pauses the system.

When the system is paused the screen is locked:

It will not accept any input until it is unpaused. However the timer is also frozen.

Credits

The Lazarus developers for making Delphi work on Linux better than Borland could, and the Lazarus mailing-list members for always happily answering my (often stupid) questions.

DireqLearn, my employers for giving me the opportunity to create Free, Open Source software for a living. The only thing nicer than altruism, is profitable altruism :)

My cat, Vyf, for (forcefully) ensuring I take the occasional break.