Managing the Knowledge Server

The Istar KBS toolkit has a module within it which allows it to act as a knowledge server, so that it connects to the Internet and runs knowledge bases (KBs) on behalf of clients anywhere in the world. Normally the module is not active, but it may be activated easily if a suitable TCP stack is active on your machine. Thereupon, if your machine has a recognised IP address, anyone can connect to Istar via a simple HTML browser and have it run knowledge bases on their behalf.

This chapter tells you how to manage the knowledge service. It explains what is needed to allow Istar to act as a knowledge server, how to start the server module, and how to prepare KBs for server use. There is also section giving exceptions in use of the server.

Requirements

For Istar to act as knowledge server, the following things are needed:

One or more knowledge bases that the knowledge server will offer over the WWW
A ServerKBs file that tells Istar which knowledge bases to offer via the server
A set of ancillary files
A running TCP/IP stack
That the machine on which Istar runs has a known IP address (which might be a universal address or one on a local network).

Each of these has to be prepared beforehand for running the knowledge server. Click the links above to take you to the section that tells you how to prepare each.

Preparing a KB for Server

(Almost) any KB developed under Istar can be made available worldwide via the knowledge server. Without any modification, though some modification might become advisable. To make it available, you must be the manager of an Istar knowledge server, so that you have access to various files on the server.

In that role, the minimum you need to do is quite simple: to add a line for your KB to the file IstarSys:serverkbs which contains at least the following entries (they are parsed using the same mechanism as CLI program parameters are parsed, namely pairs containing keyword followed by value, or keyword alone if a switch):

KBFile "dd:ff" - where dd:ff is the complete path for the file containing the KB, and it is safer to put it into quotes as shown.
Label "short label" - where "short label" is the name of the KB presented to the user on the welcome page. It should be in quotes unless it contains no spaces. It can be any length you wish, but should normally be short. (In fact, you don't need a label if the KB is not to be shown on the welcome page, such as when it is a direct entry KB, but it's safer to have one.)

So the line so far would be something like:

KBFile "Istarsys:KBs/ServerKBs/Con" Label "Write your own Contract"

That is the minimum. But usually you will also add some other parameters to the line, described below. You would normally have, in addition to these, an identification number and various descriptions and introductory text for the KB. ====ShortDesc and LongDesc which provide short and long descriptions of the KB on the welcome page, Intro which provides an introduction page when a user selects a KB, and QnNote which is a note placed on every question page that the user sees.

The ServerKBs file contains a line for each KB that is to be offered via the server. No others can be offered, which ensures security of files. Note that it is perfectly valid to have several different lines for the same KB. One reason for doing this is that for different users you might wish to have different description or introductory texts. Another is that for direct entry to a KB you might want to provide different texts.

Once you have made up the IstarSys:serverkbs file as needed, you should start the server and test it out. See Local Testing below.

The Connection Link

The standard connection to the knowledge server is via a hyperlink that contains the IP address (or name) of the server and its port number. For example:

http://146.87.82.15:7007/

This sends a very short message to Istar, which in response sends the standard welcome page. However, you can have different links for direct entry to a KB.

Direct Entry to KBs

Normally when the client connects to the knowledge server, from a link that gives only the server name and port number and no other parameter, then they will be presented with the welcome page and will be able to select a KB of their choice. However, often you want a link that accesses one particular KB directly, bypassing the welcome page and giving the user no choice of KB. This would be appropriate when, for example, you have a page discussing the buying of shares and wish to allow users to link to the Shares KB.

When the user connects by direct entry not only do they not receive the welcome page at the start, but they will not have the option of returning to it later. (Should they wish to access the welcome page then they may do so via the Istar home page or by the standard hyperlink connection.)

Any KB mentioned in the ServerKBs file can be accessed directly. All you need to do is set up, in the page from which you want the direct link to be made, a hyperlink that contains the Id number of the KB, for example:

http://146.87.82.15:7007/Dnn

where 'D' means 'direct entry' and nn is the Id number. Note that you have to know the Id number and it must never change after that.

You can also have semi-direct entry, in which direct entry is made to the KB, but the user then has the option of receiving a welcome page once they have been through their first inference session. This is achieved by a similar link, in which the 'D' is replaced by 'S' (for 'start').

http://146.87.82.15:7007/Snn

If you do not want your direct entry KB to appear on the welcome page, then include the NoShow parameter in the line for that KB in the ServerKBs file. If it is important that the user has access to only this KB, and no others, even by the standard entry, then you should set up a server machine that is dedicated to this KB and supports no others.

Local Testing of the KB

A useful way of testing your KB is to have knowledge server started and browser running on the same machine but communicating via the loopback in the TCP stack. I give my machine a local IP address of 10.0.0.1 or similar, and access it by a browser on the same machine with a url of http://10.0.0.1:7007. Alternatively, you can link into it across the network. 7007 is the TCP port number on which Istar listens.

Starting and Stopping the Server

You can either start the server module in Istar automatically when Istar itself starts, or manually after it has started. Normally you would use the first method for the main server, and the command to run up Istar would be in a CLI script that is run on startup. You would normally use the second method when testing Istar or temporarily wanting to allow server access.

In either case, you must provide a ServerKBs file, which contains details of which KBs are to be allowed to run by the server.

Preferences File

To start the server automatically you run Istar with a preferences file that contains at least the parameter:

ServerMode

Two other parameters can also be given. ServerKBs "dd:ff" tells where the ServerKBs file is ("dd:ff" full path and filename). If not given, the file is assumed to be "IstarSys:serverkbs". ServerPort NNNN tells Istar which TCP port to listen on, 7007 being the default.

Normally you won't include these in the standard IstarPrefs file, but in a special IstarPrefs.server version of it.

Starting

In that case, you must run Istar from CLI with a parameter that gives the name of the preferences file:

stack 20000 IstarSys:Istar IstarSys:IstarPrefs.server

Note the stack size. Not sure what it really needs, but it is more than the standard 4096 and (almost certainly) a lot less than 20000.

I have made up an executable file with those two commands that I execute (from a StartServer icon, which also runs up AmiTCP etc.).

Stopping Server

To stop the knowledge server you must be at the host machine. (For security reasons it is not possible to stop the server from a distance.) The normal way is just to stop Istar, but hitting the Stop/Quit button on the initial control panel. But if you want to stop the server but keep Istar running, then hit the StopSV button on that panel.

Preparing the IP Address

(This wee section is included for those who don't know how to do this. But you should read the documentation of your TCP stack.)

The server machine must have a known IP address. This can be either on a local network, or one designated by an internet provider. Only the latter allows worldwide access. It is typically set up quite easily by means of the TCP ifconfig command. In my setup, I include it as a command in my TCP startup file, of the form:

AmiTCP:bin/ifconfig AmigaLink 10.0.0.1

which sets up my machine to be known as '10.0.0.1' on my local AmigaLink network. On my main knowledge server machine I have the commands:

AmiTCP:bin/ifconfig Hydra 146.87.82.15 AmiTCP:bin/ifconfig AmigaLink 10.0.0.3

which sets up the server machine to be known as '146.87.82.15' worldwide on the Internet via my Hydra ethernet connection (which connects to my organization's network and thence out to the Internet), and also '10.0.0.3' on its local AmigaLink network. With this arrangement (the machine being known by two different IP addresses on two different networks), I can link to the main server with a local network, using my '10.0.0.1' machine to test the server.

TCP Port Number

By default Istar will listen on TCP port 7007, but you can set that to be anything you wish (just as long as it doesn't clash with any other TCP service). 7007 has been chosen because it is easily remembered and above 6000, meaning that it is not part of the TCP system.

How you do this depends on how you start the server. If you start the server manually using the StartSV button on the Main Control Panel, you should set the Port gadget to whatever port number you like before you hit the button. If Istar is started in server mode, then the preferences file should contain the port number desired as a parameter:

ServerPort NNNN

where NNNN is the number you wish.

The ServerKBs File

The serverkbs file contains details of the KBs that may be offered by the server. No file, and the server cannot start. The details of each KB must be contained on a single line, which may contain a number of parameters:

Id NN - where NN is a number that identifies this KB uniquely among all others mentioned in the file. Must not be zero, but can be anything up to 32000. If you don't have this then the Id is assumed to be the line number in the serverkbs file - but BEWARE because if another KB is given the same Id, only one of them will be accessible (even though both of them will be apparently offered to the user). Also, the Id would not be absolute, as required if the KB is to be available for direct entry.Normally you should assign your own Ids.
KBFile "dd:ff" - where dd:ff is the complete path for the file containing the KB, and it is safer to put it into quotes as shown.
Label "short label" - where "short label" is the name of the KB presented to the user on the welcome page. It should be in quotes unless it contains no spaces. It can be any length you wish, but should normally be short. (In fact, you don't need a label if the KB is not to be shown on the welcome page, such as when it is a direct entry KB, but it's safer to have one.)
ShortDesc "dd:ff" - where "dd:ff" is a file containing some text to go in a paragraph following on from the label on the welcome page. Normally it will be a couple of sentences to tell the user what the KB is about.
LongDesc "dd:ff" - where "dd:ff" is a file containing a longer description of the KB. It will be placed lower down the welcome page, pointed to from the paragraph containing the label and ShortDesc. The text can be as long as you like, containing HTML paragraphs and even minor sections (h5) or (h6) if you wish; it is preceded by an h4 heading that is the Label text. Typically it will tell the user more about the KB and what it can do for them, so that they can decide whether to access it or not.
Intro "dd:ff" - where "dd:ff" is a file containing introductory text about the KB that will form the main body content of a page presented to the user after they select the KB. It can be as long as you like, including all the page sections and their headings, but not the 'body' keywords, which will be supplied by Istar. When presented to the user, it will be followed by several hyperlinks supplied by Istar, to start the inference process, to set timing, to stop and to return to welcome page. If a KB has no Intro file then no introduction page will be given to the user, and as soon as the user selects the KB the inference session will start and the first question will be sent to the user. This can be a bit disconcerting unless the user knows the KB well. Normally the Intro page will tell the user what to expect when running the KB, such as how many questions might be expected, what to do with results, whether a document can be produced, etc.
QnNote "dd:ff" - where "dd:ff" is a file containing text to be placed at the bottom of every question page presented to the user. Normally it will be a short paragraph, and might typically give a hyperlink to a web page somewhere that describes the KB.
NoShow - which tells Istar to not show this KB on the welcome page. It would be used for KBs that are not for general access, such as test KBs.

You are at liberty to use Label, ShortDesc, LongDesc. Intro and QnNote as you wish. Typical usages have been given above, but feel free to vary them. Keep the needs of the user in mind.

Example of ServerKBs File


Id 1 KBFile "Istarsys:KBs/ServerKBs/Con" Label "Write your own Contract" ShortDesc "IstarSys:files/conshort" LongDesc "IstarSys:files/conlong" Intro "IstarSys:files/conintro"
Id 2 KBFile "Istarsys:KBs/ServerKBs/Trees" Label "Tree Species Selection" ShortDesc "IstarSys:files/treeshort" LongDesc "IstarSys:files/treelong" QnNote "IstarSys:files/treeqnotes" Intro "IstarSys:files/treeintro"
Id 3 KBFile "Istarsys:KBs/ServerKBs/ICT" Label "Internet Trust" ShortDesc "IstarSys:files/ictshort" LongDesc "IstarSys:files/ictlong"
Id 10 KBFile "Istarsys:KBs/ServerKBs/Shares" Label "Shares Advisor" ShortDesc "IstarSys:files/sharesshort" LongDesc "IstarSys:files/shareslong"
Id 90 KBFile "Istarsys:KBs/ServerKBs/inputs.2" Label "Test KB" NoShow

Ancillary Files

The Istar Knowledge Server requires certain files to be present that hold various pieces of text that contribute to various of its pages. The complete list can be found elsewhere and might change with version. For most of them absence is no disaster, merely resulting in no text. But a few are mandatory.

Managing Istar Knowledge Server While Running

Normally the Istar knowledge server just runs without any intervention, but there are a few things you can do while it is running.

From a Distant Client

Send it a 'P' message from any browser and Istar will report a number of things such as date and time the server was started, current date and time, how many clients have connected a KB and how many are currently running, how much memory is available and the linger time.

You can set the default linger time by a 'PLx' message, where x is the number of seconds to set it to. This is only for testing and will probably be removed later. The standard linger time is 2 seconds, but on 0 seconds a browser on a slow machine (mine) will cause a RST and truncation of the HTML page.

I often 'ping' the machine just to check it is still running.

At the Server Machine

While the server is running, you can do any local activity you wish. That is, you can load knowledge bases, make changes, etc. However you cannot alter or interfere with any KBs that clients may be accessing. (Except by stopping the server, of course).

Interpreting The Log

Istar places messages on the TCP log file, showing:

When the server starts and is stopped
When a client accesses the welcome page (with client's IP address)
When a client selects a KB (with client's IP address)
A message telling you when more than one client is active.
When a client restarts a KB (with client's human-readable Id)
When a client returns to welcome page
When a client stops
When a client times out (has been inactive for more then their timeout period)
When various errors occur.

The behaviour of the clients and the popularity of your knowledge service can be inferred as follows:

If they access the welcome page but then do not select a KB, then they have not found a KB they want. Look at the IP addresses to see if there is repeated accesss. If so, maybe this indicates that some knowledge service is missing?
The message telling you there are already X clients active is an indication of the amount of usage to which the knowledge server is put.
Timeout messages can tell you when the client stopped. Subtract the timeout period from the log time and subtract about another minute; that is when they stopped interacting with the server.
If a client selects a KB, then they will be allocated a Human Readable Id, usually starting at 32 and incrementing. Look to see when that client stops, which is either a timeout, or next access of welcome page, or a restart or a stop.
Subtract from this the time when they first selected the KB, and that will tell you whether they started actually answering questions. That indicates how much actual use is made of your KBs.

Exceptions

There are the following exceptions which make a KB unsuitable for use by the knowledge server:

At present only questions whose value types are integers, floats, bayesians, probabilities, proportions, booleans, enums, ordinals or strings can be sent to the client as questions. Other types will not work.

Last updated: 17 September 1999.