raingod >> resources >> Perl >> Software >> Judas

Judas Documentation

Last updated: 08.05.2002

Introduction

Judas is a CGI script written in Perl which can be used to log information about visitors to your Web site. It is intended to be invoked from an <IMG> tag, and will return an image instead of an HTML document.

Requirements

The following things are required for use of Judas:

the ability to install CGI scripts on your server
a Perl 5 interpreter installed on your server

The following things are needed to make use of all of Judas's features:

the ability to write to files in your document area from CGI scripts
the ability to invoke programs such as sendmail.

If you are uncertain whether your server meets these requirements, check with your server administrator.

Installation and configuration

To install Judas, follow the general instructions for installing Perl scripts. The system consists of two files: the Judas.pl file, which is a Perl script, and the Judas.cfg file, which is a text file containing configuration information for the script. You should place both files in the same location, and make sure that the Perl script has been made executable.

If you are installing on a UNIX system, you should not generally need to change anything in the script file itself (except perhaps for the interpreter line at the start of the file if your Perl is installed in a non-standard place). You do, however, need to make some changes to the configuration file.

The behavior of the script is governed by settings that can be acquired in one of three ways. First, some default values for the settings are encoded in the script itself. Second, certain settings may be specified when the script is called from a URL. Thirdly, settings may be specified in a configuration file which is read when the script starts up. Note that settings in the configuration file override anything passed in the URL: this is a security measure.

The following settings are recognised by the program.

Setting	URL	Value	Description
address	no	a mail address	Address to which to send reports by mail
config	yes	a filename	Name of configuration file
debug	yes	1 or 0	Enable debugging?
documentroot	no	a path	Base path to documents
finger	no	1 or 0	Try to finger 'user@host'?
fingerall	no	1 or 0	Try to finger '@host'?
gethost	yes	1 or 0	Try to identify host by name?
image	yes	a path	Image to return
logfile	yes	a path	Path to log file
logformat	yes	a string	Information to write to the log file (see below)
logsize	no	an integer	Maximum size of the logfile (in bytes)
mailer	no	a path	Path to the mailer to be used to send mail reports
mailformat	yes	a string	Information to send by mail (see below)
mode	no	a string	Whether to log information or report by mail. Possible values include 'none'
redirect	yes	a URL	Where to go next
rolloversize	no	an integer	Size of log file (in bytes) after it has been rolled over

Settings marked with a 'yes' in the URL column of the table above may be passed in as part of the URL that invokes the script. While most settings are optional, some are dependent on others: for instance, if you include 'log' in the 'mode' setting, you must provide a valid 'logfile' argument; if you include 'mail' in the 'mode' setting, you must provide a valid 'address' argument and so forth.

Most of the items above should be relatively self-explanatory, but some may need a little more explanation:

debug	If something goes wrong during script execution, it will normally fail silently. If you want it to give you some information about the problem, switch on debugging by setting the 'debug' setting to 1. This can be done either in a configuration file, with: set debug 1 or as part of the URL that invokes the script, i.e. <HREF="/cgi-bin/Judas.pl?debug=1"> Once you have debugged the script, you can set 'debug' to 0 in the configuration file. This will prevent remote users from switching on debugging and perhaps getting access to information that they shouldn't see.
image	You may specify the image that you want to return as a partial path. The image can be specified as an argument to the script, or in a configuration file. This setting is required, however: without it, the script has no way of knowing which image to show. Note that this is not a URL - although it may look like one. It's a path in the file system of your server. The path is relative to the setting for 'documentroot'. For example, if your image was at: /home/yourdomain/www/tests/myimage.gif and 'documentroot' was set to: /home/yourdomain/www/ the path to the image would be: tests/myimage.gif If you specify the image to use in the configuration file, this will override any images passed in as arguments to the script. Effectively, this means that the script can work only with a single image. If you don't specify any images in the configuration file, you will be forced to specify them as arguments in the URL that calls the script, but you are not restricted in the images that you could display.
documentroot	This setting determines where the script expects to find your images. By default, it is set to the path to the root of your HTML document tree, and you can specify - using the 'image' setting - images located anywhere in that tree. By specifying a value for 'documentroot' in your configuration file, you can restrict the images that can be shown to some subpart of the tree. This also allows you to shorten the path given in the 'image' setting. To make this clearer, consider the paths given in the example above. Normally, you'd need to refer to the image as 'tests/myimage.gif'. If, however, you know that all your images are located in the 'tests' directory, you can set 'documentroot' to: /home/yourdomain/www/tests/ and you can then refer to the image simply as: myimage.gif Note that the 'documentroot' should always end with a path separator character ('/' on UNIX).
logsize, rolloversize	To prevent log files from growing too large, they can be set to roll over automatically once they reach a certain size. When this happens, the earliest entries in the file are thrown away, and the file is trimmed down to the size specified by 'rolloversize'.

Information provided by the script

The Judas script works with the environment variables set by the user's browser and by the Web server. It may optionally try to look up the user's host. It will also try to process the information intelligently in order to extract particular details (such as the precise version of the browser in use, or the operating system of the user's computer). This is, however, all it can do. It can't get access to information that the user's browser doesn't give away - such as the user's mail address, or details of files stored on their computer. And it doesn't try to get access to information that's available only via JavaScript, such as the user's screen size or installed plugins.

The information retrieved can be written out as tab-separated text to a log file, or as a list of values in a mail message. You can control what information should be logged using the 'mailformat' and 'logformat' settings. Each setting consists of a string of upper and lower case letters, each letter standing for some piece of information. The different information available is shown in the table below.

Key	Name	Description
u	user	User (e.g. username \|\| identity)
a	address	IP address (e.g. '101.102.103.104')
h	host	Host (e.g. 'bar.foo.com' \|\| IP address)
b	browser	Browser (e.g. "MSIE 3.01")
o	os	Operating System (e.g. "Windows 95")
r	referer	Referer (e.g. "http://www.foo.com/")
p	proxy	Proxy (e.g. "Squid 2.0.1")
g	gateway	Proxy gateway (e.g. "proxy.bar.com")
t	time	Time in ISO 8601 (e.g. '1999-02-18T020:57:57+00:00')
l	languages	Languages (e.g. 'en', 'fr')
c	cookies	Cookies (e.g. counter=17)
U	username	Authenticated user (e.g. 'admin')
I	identity	Value returned by 'identd' (e.g. 'joe')
H	hostname	Hostname (e.g. 'bar.foo.com' \|\| "")
B	browsername	Browser name (e.g. "Mozilla")
V	browserversion	Browser version (e.g. "3.01Gold")
O	osname	OS name (e.g. "Linux")
E	osversion	OS version (e.g. "2.5.1")
G	gatewayaddress	IP of proxy gateway (e.g. '123.123.213.213')
P	gatewayport	Port number of proxy gateway (e.g. 8080)
M	maybehost	Possible hostname of proxy'd host
T	universaltime	universal time in seconds (e.g. 21213142)

So, for example, setting 'logformat' to 'thb' would cause the script to log the time in ISO format, followed by the hostname, followed by the name of the user's browser.

Troubleshooting

If the script gives a server error, review the installation instructions to make sure that you have followed all the steps properly. Also look at the error logs for your server: they should give you a hint as to what went wrong. See also these notes on debugging CGI scripts.

If the script runs but doesn't behave properly, try switching on the 'debug' setting (explained above) to get more information.

If the script doesn't seem to write anything to the log file, use the 'debug' setting to check that it can actually find the log file and write to it. You may need to create an empty log file by hand before running the script. You should also ensure that both the log file and the directory that contain it have their permissions set to allow them to be written by any user (this is a potential security hole, so make sure that the log directory is somewhere outside your HTML document tree, and that there's no possibility of someone harming you by creating or changing files in that directory).

If the script doesn't send mail, check that you have correctly specified your mail address, and the path to the mailer. Both of these settings must be made in the configuration file.

Note that if you have debugging switched on, calling the script from the SRC attribute of an <IMG> tag will just produce a broken image. This is because the debug mode will return a document of type 'text/plain' if anything goes wrong, but your browser is expecting a document of type 'image/*'. To debug, call the script directly: if the script works, you'll see an image. If it doesn't, you'll see an error message.

The script was written to work on UNIX servers. It won't run 'out of the box' on other operating systems. If you want to run it on a different system, you will typically need to do a fair amount of work, in particular with respect to invoking programs such as 'finger' or 'sendmail'.