Installing AMS

AMS is a client/server product. This installation is not as 'slick' as it could be. One day I may get round to writing an install script for it, but for now the step-by-step guide is below. The server runs only on Unix platforms, whereas the client should run on any platform where a Java runtime is available.

In order to install it successfully you need a reasonable understanding of Unix, and for the applet HTML & Web servers.

Please read and understand the term of the AMS license before proceeding.

Prerequisites

The server (ams_server) was written and tested using Perl 5.6.0, it may work with an earlier release - I don't know. It utilises the IO::Socket and IO::Select modules. Both these modules are part of the core 5.6 Perl release. The sole purpose of the server is to pass syslog messages from syslog to the GUI front end. The interpreter line at the top of the script specifies the Perl interpreter to be /usr/bin/perl

We recommend that you use a version of Syslog that passes the syslog record through intact such as syslog-ng. You can use it with a generic syslogd implementation but the nice highlighting of messages and counters simply won't occur without the severity code. If you wish to use it with a generic syslog, you'll need to uncomment a single line in the server.

The client side runs as either a standalone Java application or as an applet within a browser. The applet version being most widely used. The client requires a Java runtime release of 1.1 or higher. Most platforms adhere to this specification "out-of-the-box".
Note: If you intend running the client on Linux platforms we recommend NOT using IBM's Java2 runtime, as the performance of this runtime has been found to be than optimal within this real-time environment.

If you wish to use the client as an applet from an HTML page please note that owing to browser/Java security, the applet must be loaded from the same server that the ams_server is running on

Server setup

In order to install the server you will need root access to the syslog system.

Be aware that there is no security or authentication between the client and the server. Thus anyone who can connect to the server's port can view you syslog output.

The client/server defaults to communicating via port 4000. You should ensure that this port is not in use before attempting to start the server. E.g.;

	# netstat -an | grep 4000

If port 4000 is already in use you will need to modify the ams_server script.

You should copy the ams_server.pl script to a location appropriate to your site, though I would highly recommend using a local drive - many sites use /usr/local/adm. The script must be executable by whatever UID you are running syslog as. The install procedure then differs slightly for syslog-ng and generic syslog sites;

Server setup with Syslog-ng

You simply need to add a PROGRAM entry for ams_server to syslog-ng's configuration file. If you are moving from a generic Solaris configuration the following line will do the trick;

destination all { file("/var/adm/messages"); program("/usr/local/adm/ams_server.pl");}; 

      # sh /etc/init.d/syslog-ng stop
      # sh /etc/init.d/syslog-ng start

Now skip to the section marked "Check that the server is running".

The syslog-ng start/stop script is provided in the 'unsupported' directory under the main ams distribution directory - it is not supported..

Server setup with a generic syslog
I should start this section by pointing out that using ams with most generic syslogs is not well tested. It does work, but most of the nice features of ams (priorities & facilities) do not function. Thus most people do not use this configuration....

Most generic syslog's seem incapable of sending their output in an unbuffered fashion to another program, thus the only reliable method is the use of named pipes(fifos). If anyone has a better mechanism please feel free to drop me a line

Edit the ams_server.pl script, removing the first '#' character from the line that reads
     #$pipename="/etc/ams_pipe"
Feel free to change the name, location of the fifo as you see fit. After saving the script, ensure that your editor has not removed execute permissions from it.

Then you need to create the fifo;
      mkfifo -m 666 /etc/ams_pipe

You need to arrange to start ams_server.pl somehow. Because of fifo semantics (esp. under Solaris) ams_server needs to be started before syslog. The simplest way of doing this is to edit the syslog startup script ( on Solaris this is /etc/init.d/syslog ) and insert the line
     /usr/local/adm/ams_server.pl &

Depending on your site, editing the syslog boot script may be inappriopiate. In this case you may need to create a separate init.d script for it. In any case I cannot stress enough that ams_server must be started before syslog.

Finally, you need to add an entry to you syslogd.conf file. As syslog config files differ considerably in this respect I suggest you consult your documentation for the correct syntax. A common example is;
      *.debug        |/etc/ams_pipe

Restart syslog in a manner appropriate to your installation.

Check that the server is running

# ps -ef | grep ams_server
root   149   148  0 14:15:06 ?        0:00 /bin/sh -c /usr/local/adm/ams_server.pl
root   150   149  0 14:15:06 ?        0:17 /usr/bin/perl /usr/local/adm/ams_server.pl 

You should be able telnet to port 4000, and you ought to see a short message from the server, e.g;

-Hello there. You are connected from "laptop [192.9.200.118], port 1066, (client id=0)
-My time is Thu Oct 3 11:17:38 2002
*CLIENTID 0

If you intend to run the applet version of AMS, some sort of http/web server needs to be running on your syslog server. Web server setup is beyond the scope of this document.

Java

In order to run either the applet or standalone client you need to have a Java runtime for your client platform. AMS will run with any Java runtime from version 1.1 up. Many systems including, Microsoft's Windows98 and Windows2000, as well as Sun Solaris have this pre-installed. Some Linux distributions include it - Suse for example. A notable exception is Redhat 7 & 8. In any event the current version of Java for all these platforms is available for free download from from java.sun.com, you only need the J2SE..

Most common browsers come with a Java runtime configured ready to run the applet version of AMS. Thus if you never intend to use the AMS standalone (AMSClient ) you shouldn't need to configure Java at all. If you can a ticking clock at the top of this page then you browser is fine.

Whilst Java is standard on most platforms it is not well integrated in the standard environment of any. Try typing 'java -version' at a Windows command prompt or a Unix shell. Most likely you'll get a Windows 'not recognized' or Unix 'Command not found' message. If you see a java version message then you're sorted can can skip the rest of this section.

You need to arrange for the java interpreter to be in your Path. On Windows platforms this program is 'java.exe', and Unix simply 'java'.

Unix users simply need to add the directory 'java' lives in to their PATH environment via whatever shell startup file is appriopiate - .cshrc, .bashrc, .kshrc, etc...

export JAVAHOME=/usr/local/j2sdk1.4.0
export CLASSPATH=$JAVAHOME/lib/:$HOME/java/:.
export PATH=$PATH:$JAVAHOME/bin

Windows95/98 users will need to edit their autoexec.bat file.

Under Windows NT/2000 the same thing is done via the System icon in the control panel. After double clicking this, select the Advanced tab and click on Environment variables. You should see the window pictured right ---> Exactly how you configure Path is up to you. Here you can see that I've choosen to create a new environment variable called JAVA_HOME and have used that in the Path definition. This is simply because I use different runtimes and this arrangement make it easy to switch versions. You can hardcode the directory the java runtime lives in if you wish....

Application Setup - AMSClient

Running the client is simple, a lot more simple than the applet. We recommend you give the client a try even if you don't intend to use it in practice - it's a great confidence lifter.

Create a new directory/folder, call it say 'ams' and copy all the class files from the tarball into it. We're using Windows syntax here and assuming that the tarball was unpacked into a network drive called h:
c:\> mkdir ams
c:\> cd ams
c:\ams> copy h:*.class

If you have a Java runtime available you can immediately run the client thus;

Where you should substitute host with the name of the host, or the IP address where ams_server.pl is running. If you needed to change the port number from 4000 then that needs to be reflected in this command. Obviously the hostname needs to be resolvable by the client host - try a telnet host, to verify..

New! From version 1.6 AMSClient can read parameters from a configuration files. The parameters are identical to the applet parameters;

     java AMSClient amscfg.txt

amscfg.txt will need to be modified to reflect your site configuration. If you get "class not found" type errors, check that your CLASSPATH environment variable contains the directory where the AMS class files live.

Applet Setup

The applet can only normally connect to an instance of ams_server.pl running on the host that it, itself was loaded from. This is a standard Java/Browser security measure. As a consequence of this your syslog host must be running some sort of http server.

For basic operation the applet requires only the file ams.jar. This file should be copied to an appropriate location on your web server. A sample HTML page is supplied as html/amsclientapplet.html. The jar file is generally in the same location as the HTML but this is not required. See the comments in the HTML for more information.

All Applet parameters are documented in the Java doc file. Please check this out, especially the DEBUG parameter, prior to asking for help.

Facility names
Facility names are hardcoded into ams_server.pl. Clearly you are at liberty to change these at will - have a look for the array facnames.

Database search setup

Starting with version 1.6, AMS includes a facility to search a Database for syslog messages. To achieve this AMS uses JDBC. This allows any database supporting JDBC ( most of them ) to be accessed by AMS. There are two steps required to configure AMS to access a database.

1. Provide AMS your database configuration via the "DB_*" parameters - either via applet parameters or the AMSClient configuration file. These parameters are documented elsewhere. The most important are JDBCDRIVER and DB_CONNECT_STRING. Once these parameters are provided a new button will appear on the UI labeled "Database".

2. Obtain and install a JDBC Driver for your database. The AMS database search was developed against a Postgres7 database, the driver for this being freely available. The JDBC driver Postgres is available via their JDBC website, and that for MySQL is available via this page

Installing the JDBC driver:

In essence this should simply be a case of copy the driver JAR file to a location that your client machine can access, and setting the CLASSPATH environment variable to point at it. Configuring CLASSPATH on Unix systems will be familar to anyone who has ever seen the PATH variable - essentially CLASSPATH works the same way, with the subtle difference that a JAR file needs to be explicitly named. E.g export CLASSPATH=$HOME/postgres.jar:.

Windows users should read Sun's tutorial on the subject - Setting CLASSPATH on Windows
[ http://developer.java.sun.com/developer/onlineTraining/Programming/BasicJava1/windows.html ]

Windows installation has proved problematic, largely because of differences in way various versions of Browser and JavaVM handle the CLASSPATH issue. Thus we recommend first getting AMSClient running with database access.

Some particularly annoying points we have noticed;

1. Netscape 4.51 ( Symantec JavaVM 1.1.5 ) will actually try to load class files specified in applet parameters from CLASSPATH in preference to using HTTP. We consider this is seriously broken behaviour. AMS will fail to operate in this situation because if loaded from via the filesystem it will be unable to perform any network connection - standard Java security constraints.

2. Internet explorer 5 with the Sun Java plugin seems to completely ignore the CLASSPATH setting. This makes it nearly impossible to get a 3rd party JDBC driver loaded....

One approach that you may wish to consider if you have difficulties with CLASSPATH is appending the JDBC driver classes to the ams.jar file. Simply create a empty folder/directory and use the Java SDK tool 'jar' to extract both the ams and JDBC driver classes to that directory. Then repackage them into a new ams.jar file. This is the only workaround we have found to problem#2 above.
N.B. There may be licensing issues with this approach - check the license terms associated with your JDBC driver.