This document is intended to help new users install and configure LinkScan on Unix systems. Additional LinkScan features are described in the LinkScan User Guide and the LinkScan Reference Manual.
Windows users should see the LinkScan Startup Guide for Windows.
Existing users upgrading from earlier LinkScan versions must read Upgrading to LinkScan 6.1.
LinkScan installation is a straightforward procedure. However, users who are not familiar with their server environment or have not previously installed CGI scripts, may wish to seek assistance from the support personnel at their Internet Service Provider (ISP), a System Administrator, or another experienced user.
In summary, the procedure is:
Check the pre-requisites: Perl 5.002 or later, and a copy of the LinkScan Software with License Key. The weblint program is highly recommended but not required.
Install the software: Extract the file linkscan.tar.gz into a linkscan directory, located we suggest, directly under www root.
Configure the software: Execute the LinkScan Configurator, linkconf.pl.
Run the software: Execute the main LinkScan program, linkscan.pl.
View the results: Point your browser at the CGI script linkscan.cgi. You may also generate reports from the command line.
In order to install and use LinkScan, you will need:
Access to a shell (command line) account on a Unix Internet or Intranet server where your website is installed. Installation does not require system administrator privileges although some LinkScan features do require the ability to install and run CGI scripts.
Perl Version 5.002 or later. Perl is included with most Unix distributions but is also available from http://www.perl.com/.
The weblint program is highly recommended but not required. Weblint is an excellent HTML syntax checker that integrates tightly with LinkScan. It is available from the Weblint Home Page.
A copy of the LinkScan software and a License Key, available from the LinkScan Home Page.
In order to obtain a LinkScan License Key you will need to know:
Your login username on that server.
The system name of your server. We strongly recommended that you login onto your server and check - guessing almost never works! Use the following command:
uname -n
All of the files distributed with LinkScan and created during execution are stored under a single LinkScan directory. We recommend that you create this directory immediately under www root. We further suggest that you configure your HTTP Server to provide HTTP Password Authentication on the LinkScan directory to prevent unauthorized access.
Create a LinkScan directory:
cd xxxxxx mkdir linkscan
Where xxxxxx is the directory containing your top level web pages
LinkScan is distributed as a single file archive called linkscan.tar.gz. Copy this file into the newly created LinkScan directory.
If you use ftp to transfer the file, be sure to transfer it in BINARY mode.
Extract the LinkScan files from the distribution archive file using the following Unix commands:
gunzip linkscan.tar.gz tar -xvf linkscan.tar
Note: linkscan.tar.gz will be extracted into the current directory. i.e. It does not automatically create a subdirectory.
The files will be extracted and assigned access permissions that will work on most servers. However, if your server has special requirements and you encounter difficulties, consult your System Administrator.
After extraction, a directory listing (obtained with the ls command) should look something like this:
web:/usr/local/www/data/linkscan> ls -F README linkconf.pl linkscan.mas linkserv.pl upgrade.pl default/ linkdiag.pl linkscan.pl mailfoot.html utils/ dispatch.pl linkmap.cgi linkscan.sys mailhead.html docs/ linkscan.cfg linkscan2.pl mime.types index.html linkscan.cgi linkscan3.pl quick.cgi web:/usr/local/www/data/linkscan>
LinkScan requires Perl Version 5.002 or later. You can check the Perl version installed on your server with the following command:
web:/usr/local/www/data/linkscan> perl -v This is perl, version 5.004_04 ...
A basic installation requires that the following two files be configured:
linkscan.sys in the linkscan directory
linkscan.cfg in the linkscan/default directory
They are simple ASCII text files. They can be viewed and edited just like any other ASCII file. We recommend that you use whatever editor or other tool you are most comfortable with for inspecting or making changes. Experienced Unix users may use emacs, joe, pico, vi or other Unix editors. Users less familiar with Unix may prefer to transfer the file to a Windows or Macintosh client for editing. You should be sure to transfer the file in ASCII mode and not in BINARY mode.
Templates of the required parameters are contained within the linkscan.sys and linkscan.cfg files included with the LinkScan distribution. However, we recommend that first time users take advantage of the LinkScan Configurator program to set up a basic installation as described in the following steps.
LinkScan needs to know the Absolute Pathnames to the directories that contain your web site and the LinkScan files. If you followed the previous steps, the Configurator will determine those Pathnames automatically. If not, the Configurator will prompt you for the information. You can obtain the Absolute Pathname of a directory by going to that directory and using the "pwd" command:
web:/usr/local/www/data/linkscan> pwd /usr/local/www/data/linkscan web:/usr/local/www/data/linkscan>
On some servers, there can be more than one valid Absolute Pathname to any given directory. This is a powerful but potentially confusing feature of Unix. Furthermore, an Absolute Pathname that works one day may be invalid the following day! Some servers are configured with "preferred" Absolute Pathname formats. If you encounter difficulties with Absolute Pathnames and/or Directory and File Permissions, please consult your System Administrator.
The LinkScan Configurator is a simple interactive shell program that will create a basic linkscan.cfg file. To run the Configurator goto the linkscan directory on your server and type:
perl linkconf.pl
You can terminate the Configurator and start over by using the <Control-C> key.
Here is an example of the LinkScan Configurator dialog (responses in bold):
================================= Begin Example ================================== web:/usr/local/www/data/linkscan> perl linkconf.pl Welcome to the LinkScan 6.1 Configurator. This utility will help you set up the linkscan.sys file in the linkscan directory and a linkscan.cfg file in the linkscan/default subdirectory on your server. It will complete the installation process on many servers, but manual adjustment may be required on others. The LinkScan configurator prefers (but does not require) that LinkScan be installed in its own directory (e.g. linkscan) under your web server root. Your Server and Login names are: Server Name: myserver Login Name: wwwadmin Do you have a LinkScan License Key for this Server and Login? [y/n]: y Good. Let's start by entering your License Key details Enter the following License Key details *exactly* as they appear on the e-mail notification you received. If the backspace key echoes strange characters when entering this data, try using <control-H> instead. Enter License Number [10 digits]: 1000000001 Enter Licensee: Electronic Software Publishing Enter License Key: 1234:123456:123456:1234:1234 Enter the name of your organization or web site as you wish it to appear on the LinkScan reports. Enter Organization Name: Electronic Software Publishing Now LinkScan needs to know where to find some other programs on your server. Enter the *absolute pathname* to the Perl 5 executable. Enter 'return' for the default: /usr/local/bin/perl Enter Perl 5 Pathname: Enter the *absolute pathname to the Sort executable. Use '*in' for the input file and '*out' for the output file. Enter 'return' for the default: /usr/bin/sort -o *out *in Enter Sort Pathname: Enter the *absolute pathname* to the weblint executable. More on weblint at http://www.weblint.org/ Enter 'none' to ignore or 'return' for the default: /usr/local/bin/weblint Enter weblint Pathname: Enter any weblint options. Enter 'return' for the default: -x netscape Enter weblint Options: Enter the *absolute pathname* to the sendmail executable. Hit 'return' for the default: /usr/lib/sendmail Enter sendmail Pathname: /usr/sbin/sendmail Enter the hostname of your SMTP mail server. Enter SMTP Hostname: elsop.com LinkScan needs to know where to find the website on your server Enter the *absolute pathname* to the Home Directory of your web site. If you installed LinkScan in a sub-directory of your Home Directory (highly recommended) you can simply hit the 'return' key. Enter Home Directory: Enter the filename of your Home Page (eg index.html, home.htm). Enter Filename: index.html Enter the full URL of your Home Directory. eg: http://www.elsop.com/ Enter Home URL: http://www.elsop.com/ Does your server require that cgi scripts be installed in a special directory (e.g. cgi-bin)? [y/n]: y Enter the *absolute pathname* of your special cgi-bin directory Enter cgi-bin Pathname: /usr/local/www/data/cgi-bin/ Enter the full URL to your special cgi-bin directory Enter cgi-bin URL: http://www.elsop.com/cgi-bin/ Do you access the Internet via a Proxy Server? [y/n]: n Writing configuration file linkscan.sys ... Writing configuration file default/linkscan.cfg ... Updating #! headers ... Updating cgi scripts and copying them to /usr/local/www/data/cgi-bin/ ... Completed! You may examine the following files using your favorite editor: linkscan.sys default/linkscan.cfg Type "perl linkscan.pl" (without the quotes) to run LinkScan. web:/usr/local/www/data/linkscan> ================================== End Example ===================================
At this point, we recommend that you review the linkscan.cfg and linkscan.sys files for any obvious errors. Simply open the files using your preferred editor or list them on the terminal using:
cat linkscan.sys
cat ./default/linkscan.cfg
Some servers are configured in a manner that impose special security or other requirements. In these cases you must manually edit the linkscan.sys and/or linkscan.cfg files. See the LinkScan Quick Reference Card for a summary.
Now you are ready to use your LinkScan installation. In the linkscan directory, type:
perl linkscan.pl
The program will start executing. During the first phase (a period of between a few seconds and a few minutes depending upon the speed of your server and the size of your web site) it will analyze your local html source code. On completion, it will commence testing all of the hyperlinks to other web sites and report the percentage completion from time to time.
When the program terminates, users may submit many different queries to the LinkScan Database via one of two user interfaces:
An interactive browser-based interface
An interactive (or batch) command line interface
** Error: The LinkScan license key is invalid Mail this line to key@elsop.com - 1000000001:xxxxxx:yyyyyy
Ensure that the following parameters in linkscan.sys are configured in accordance with the License Key information that we mailed to you:
If you need a new or different License Key, please e-mail the message to key@elsop.com and we will send a new Key by return.
** Error: sort: no space on device
LinkScan uses the sort utility on your system. Most Unix sort implementations create temporary files in the /tmp/ directory. This error almost certainly means that sort could not find enough space in /tmp/. Edit the file linkscan.sys and specify an alternate temporary directory. For example:
Sortpath = /usr/bin/sort -T /some/other/directory/ -o *out *in
You should ensure that "/some/other/directory/" exists and is writable; sort will not normally create it for you. See 'man sort' for any other operating system specific issues or restrictions associated with the sort implementation on your server.
When trying to access linkscan.cgi or linkmap.cgi from your browser, you receive an error similar to one of the following:
All of these errors generally indicate one of the following problems:
Your browser is pointing at the wrong URL.
The linkscan.cgi or linkmap.cgi files are not installed in the correct directory.
The linkscan.cgi or linkmap.cgi files do not have the correct File Permissions.
LinkScan has not been installed in a manner that complies with some security requirement that is specific to your server. Perhaps the CGI files need to be installed in a specially reserved cgi-bin directory.
If you are experiencing difficulties with these CGI scripts and are not familiar with the installation of CGI's on your particular server, we strongly recommend that you consult with your System Administrator or another user that is familiar with the specific requirements of your server.
Also, it is possible to generate LinkScan reports by running the linkscan.cgi program from your shell account. See Generating Reports from the Command Line.
If you are still experiencing difficulties, please:
See the: LinkScan Frequently Asked Questions (FAQ) or:
Send mail to: linkscan@elsop.com.
Electronic Software Publishing Corporation (Elsop)
[ Elsop ] -
[ About ] -
[ Contact ] -
[ LinkScan ] -
[ SiteMap ]
© Copyright 1997-99 Electronic Software Publishing Corporation
Updated: November 28, 1999