Matt's Whois (C) Matt Wilson 2001 ================================= Introduction =----------- Matt's Whois (MWhois) is a free whois lookup script licensed under the GNU Public License (GPL - see COPYING for more details) written for both PHP and Perl to make sure that almost anyone can use it on their site. The script uses a template system so it can integrate easily with existing web pages and sites. Contents =------- This document is split into various sections, they are; 1. Getting started 2. Simple configuration 3. Custom configuration 4. Additional templates 5. Customising templates 6. Updated servers.lst files 7. Credits and contact 1. Getting started =----------------- The first thing that you need to do in order to use this script is to download it, but as you are reading this document i'm guessing that you've already downloaded it, I can also assume that you have succesfully extracted the files from within the mwhois archive. The next thing to do in order to make sure that the script works on your site is to upload the files that you have got onto the web server, most people will use an FTP client to do this and i'm not here to teach you how to do that, so thats upto you to discover (if you don't already know how to do it). Upload all the files in this archive onto your webserver into a directory (mwhois/ would be a good choice I feel) that is accessible via the internet (ie http://mydomainname/mwhois/). If you are using the Perl version of this script and your website is hosted on a Unix webserver then you need to change the file mode/permissions to 0755 (CHMOD or Change file mode) in order for the script to execute, you may also wish to perform this operation for the mwhois_admin.cgi file. For the Perl version to function correctly you may also need to set the "$base_directory" variable at the top of the script to the same directory in which you have place the other Matt's Whois files (the themes and config.cgi), otherwise Matt's Whois will not be able to locate them. The PHP version should not require this alteration. By now visiting the script in a browser (http://mydomainname/mwhois/mwhois.cgi for Perl users and http://mydomainname/mwhois/mwhois.php for PHP users) you should be presented with the default template's search screen. If this does not happen you can check the file permissions etc and then if all else fails you may e-mail me for assitance at matt@mattsscripts.co.uk. 2. Simple configuration =---------------------- Basic configuration of the script can be achieved via the MWhois admin script, if you are using the Perl version then this script is called mwhois_admin.cgi, if you are using the PHP version then this script is called mwhois_admin.php. Whichever version of the script you are using the admin script is located in the same directory as the main script (mwhois.php or mwhois.cgi) and should be accessed in the same way. Once the page loads you can follow the instructions and easily configure the script using the form provided. By using the first drop down menu you can select which template you would like to use with the script (see section 4. Additional templates and section 5. Customising templates for more information on templates). Secondly is the option of whether or not to use the global header and footer templates, when turned on they appear at the beginning and end of every page the script handles. Finally and most importantly the script displays a list of all the top level domains supported by the version of the servers.lst file you have installed (see 6. Updated servers.lst files), simply check the box next to each top level domain you would like to use and the script will be configured for use with it. When all this is done click the "Get config file" button located at the bottom of the page and you will prompted to download a file, download the file and save it as either "config.cgi" for the Perl version of the script, or "config.php" for the PHP version of the script. The final step in configuring MWhois is to upload this downloaded file onto the webserver in the same directory as the main script (either mwhois.cgi for the Perl version of mwhois.php for the PHP version), the file will already exist so you may be asked whether or not to overwrite the file on the server, you should overwrite the file on the server with the local file. 3. Custom configuration =---------------------- Custom configuration involves manually editing the config.cgi or config.php and changing the values that are present to one's more suiting to your needs. This is a generally easy process but can cause problems with the script's execution if performed incorrectly and so I am going to suggest that only more advanced users should perform this step. At present there are not very many options that could be changed, either manually or with the administration script and the only option I would imagine people would want to change manually is the order in which the Top Level Domains appear in the drop down menu on the search page. This is merely set using an array within the config file and is easily altered providing you know how to alter it. If anything goes desperately wrong you can use the admin script and produce another config file or simply reupload an existing file. 4. Additional templates =---------------------- Additional templates are available for download from the Matt's Whois script main page, as of writing the only templates that are available are the default templates for English and German. To use one of the extra templates all you need to do is to download the archive containing the template, extract it into a temporary directory on your computer and then to upload all the extracted file into a sub-directory (english/ for the default English template and deutsch/ for the default German template) within the main MWhois directory (ie you will have /mwhois/english/ or /mwhois/deutsch/ with all the files within these directories). After you have done this you can either use the admin script to generate a config file as the admin script will automatically recognise the newly installed templates provided that they have been installed correctly, or you can manually edit the config file to use the new template. 5. Customising templates =----------------------- The template's config files (templates.cfg and titles.cfg) are plain text files which contain information for the usage of the template, within the templates.cfg are a list of "flags" corresponding to various pages of the script , along with each of these there is a filename which should be loaded as that page's template. The titles.cfg file is very similar although it contains what the title should be for each page. While these files can be changed to accomodate new file names and page titles, I would recommend that they are left with there current values. The main part with customising templates are the template files themselves (*.tml) which contain plain HTML with a few inserted extras that are used by the main script to decide where to place information obtained during the process such as RAW whois data etc. A list of these and what the script uses them for are shown below; [>DOMAIN<] -> The domain name specified to search for. [>EXT<] -> The top level domain of the name to search for. [>RAWOUTPUT<] -> The raw output from the whois server. [>WHOIS_SERVER<] -> The host name of the whois server used for this query. [>AVAIL_LIST<] -> A list of the available domains obtained from a global search or wizard search. [>UNAVAIL_LIST<] -> Same as [>AVAIL_LIST<] except this is a list of the domains that are unavailable. [>ERROR_MSG<] -> When an error occurs the script (by default) shows error.tml as the main template file and replaces this with the error message produced by the script. [>EXT_HTML_LIST<] -> A