LinkScan Startup Guide for Unix Systems

Introduction

This document is intended to help new users install and configure LinkScan on Unix systems.

Windows users should see the LinkScan Startup Guide for Windows Systems.

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.

This document covers the following topics:

• Before Installation
• LinkScan Installation
• Configuring LinkScan
• Running the LinkScan Configurator
• Reviewing the Configuration
• Scanning the Website
• Viewing the Results
• Common Questions

Before Installation

In order to install and use LinkScan on a Unix system, you will need:

1. 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.

2. Perl Version 5.002 or later. Perl is included with most Unix distributions but is also available from http://www.perl.com/. You can check the Perl version installed on your server with the following command:

   web:/usr/www/htdocs/linkscan> perl -v
   
   This is perl, version 5.004_04 ...
   

3. 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 and the system hostname. The latter may be obtained using the uname -n command at the shell prompt.

LinkScan Installation

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. For example, /usr/www/htdocs/. Create a LinkScan directory:

cd /usr/www/htdocs/
mkdir linkscan

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/www/htdocs/linkscan> ls -F
README          linkconf.pl*    linkscan.mas    mailfoot.html   template.txt
codes.txt       linkdiag.pl*    linkscan.pl*    mailhead.html   utils/
default/        linkmap.cgi*    linkscan.sys    mime.types      weblint/
dispatch.pl*    linkscan.cfg    linkscan2.pl*   profile.txt
docs/           linkscan.cgi*   linkserv.pl*    quick.cgi*
index.html      linkscan.cron   lsfind.pl*      slave.pl*
web:/usr/www/htdocs/linkscan>

Configuring LinkScan

A basic installation requires that the following two files be configured; additional information about these files may be found in the LinkScan Reference Manual:

• linkscan.sys in the linkscan directory

• linkscan.cfg in the linkscan/default directory

These files are simple ASCII text files. They may be viewed and edited manually just like any other ASCII file. Templates of these files are placed in the LinkScan installation directory. We recommend first time users take advantage of the LinkScan Configurator (see the following step) to customize these files for your system. If you choose to edit the files manually, you will find explanations of the parameters in the LinkScan Reference Manual.

Use whatever editor or other tool you are most comfortable with for inspecting or making changes to these files. 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.

LinkScan needs to know the Absolute Pathnames to certain 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/www/htdocs/linkscan> pwd
/usr/www/htdocs/linkscan
web:/usr/www/htdocs/linkscan> 

Running the LinkScan Configurator

The LinkScan Configurator is a simple interactive shell program that will create a basic linkscan.cfg file. To run the Configurator go to 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). The actual dialog may vary depending on the system and your initial responses:

================================= Begin Example ==================================

web:/usr/www/htdocs/linkscan> perl linkconf.pl

Welcome to the LinkScan 11.6 Configurator. This utility will help you
configure LinkScan on your computer. It will complete the installation on
many servers, but manual adjustment may be required on others. LinkScan
prefers to be installed in its own directory (e.g. linkscan) under your web
server root, but this is not mandatory.

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.
Enter the *absolute pathname* to the Perl 5 executable.
Enter 'return' for the default: /usr/local/bin/perl
Enter Perl 5 Pathname: 


Is LinkScan installed in a web-visible directory under www root? [y/n]: y

Now LinkScan needs a URL to *this* directory so that the documentation
and reports are available via a web browser.
Enter the full URL. For example: http://www.example.com/linkscan/
Enter LinkScan URL: http://www.elsop.com/linkscan/


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.
For example: /usr/www/cgi-bin/
Enter cgi-bin Pathname: /usr/www/cgi-bin/


Enter the full URL to your special cgi-bin directory.
For example: http://www.example.com/cgi-bin/
Enter cgi-bin URL: http://www.elsop.com/cgi-bin/


Do you access the Internet via a Proxy Server?
[y/n]: n


Now LinkScan needs some information about the Website you want to scan.
If LinkScan can access static HTML documents on this server via
the local File System (or NFS) please enter the absolute file system
pathname to the document root directory. Otherwise press return.
For example: /usr/www/htdocs/
Enter Home Directory: 


Please enter the URL of the site you wish to scan.
For example: http://www.elsop.com/
Enter Home URL: http://www.elsop.com/

Writing configuration file linkscan.sys ...
Writing configuration file default/linkscan.cfg ...
Updating shebang headers ...
Updating cgi scripts and copying them to /usr/www/cgi-bin/ ...
Completed.

You may examine the following files using your favorite editor:
  linkscan.sys
  default/linkscan.cfg

Execute linkscan.pl to run LinkScan.

web:/usr/www/htdocs/linkscan> 

================================== End Example ===================================

Reviewing the Configuration

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.

Scanning the Website

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 web pages. On completion, it will commence testing all of the hyperlinks to other web sites and report the percentage completion from time to time.

Later, if you configure additional projects, you may specify the project to be scanned on the command line:

perl linkscan.pl -project mynewproject

Viewing the Results

Users will need to point a web browser at the LinkScan Main Menu which typically resides at:

http://your.server.name/linkscan/linkscan.cgi
or
http://your.server.name/cgi-bin/linkscan.cgi

The first time you access the results, you will be presented with the LinkScan Login and Preferences Menu. Simply click Login Now. No username is required unless you later decide to enable various LinkScan security features.

Once you have logged in, you will be presented with the LinkScan Main Menu.

Report Selection

You must select one of the individual Reports and submit the form by pressing Select Report.

A help page is available for each type of LinkScan Report. You may view the appropriate help page at any time by using the Help option on the context-sensitive LinkScan Toolbar. You may also use the [?] links on the LinkScan Main Menu, or the links provided in the summary table below.

The most frequently used reports have been organized in the left hand column; we suggest new users start there. Also, many of the reports incorporate hyperlinks to other reports. This means you can use a drill-down paradigm to view more detail associated with a specific problem or document. For example, some users may never explicitly select a LinkScan/QuickCheck Report. But they will likely view reports of that type by following the [Src] links from other reports.

Owner Selection

The LinkScan Main Menu may include an Owner Selection Box. If enabled, this option will allow you to select a sub-set of the website to which subsequent reports will apply.

In a default configuration, the Owner Selection Box will include entries for each top-level directory scanned, in addition to the special entry "All". This will be the default selection and subsequent reports will apply to the entire website scanned.

Note however, that the LinkScan Administrator may configure and customize the manner in which Owners are created. Hence your installation may appear and behave somewhat differently from that described herein.

SubMenu Selection

In many cases, when you submit the form by pressing Select Report you will be presented with a second menu of options. Initially, we suggest you accept the default options which have been carefully designed to produce excellent results in the vast majority of situations. However, to learn more, you may use the context-sensitive Help button on the LinkScan Toolbar at any time.

LinkScan Toolbar

Each of the LinkScan Menus and Reports includes a common LinkScan Toolbar. It contains a number of links:

The Main Menu link will always return you to the LinkScan Main Menu.

The Preferences link will always take you to the LinkScan Login and Preferences Menu.

The Advanced link appears when appropriate and it will cause the current menu to be redrawn with additional options.

The Help link will display an appropriate section of the LinkScan Documentation depending upon the current context.

The Reference link will display the table of contents for the LinkScan Reference Manual.

The HowTo link will display a brief How To Guide with instructions for completing certain Common Tasks.

The Card link will display the LinkScan Quick Reference Card.

Solutions to Common Problems

linkscan.pl Terminates with the Error:

** 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:

• LicenseNumber =
• Licensee =
• Key =

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.

Problems running linkscan.cgi

When trying to access linkscan.cgi from your browser, you receive an error similar to one of the following:

• Document Contains No Data
• A Server Error Message such as "304 Forbidden"
• A Server Error Message such as "500 Server Error"

All of these errors generally indicate one of the following problems:

• Your browser is pointing at the wrong URL.

• The linkscan.cgi file is not installed in the correct directory.

• The linkscan.cgi file does 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.

Other Problems?

If you are still experiencing difficulties, please:

• See the: LinkScan Frequently Asked Questions (FAQ) or:

• Send mail to: linkscan@elsop.com.

LinkScan Startup Guide for Unix Systems
LinkScan Version 11.6
© Copyright 1997-2006 Electronic Software Publishing Corporation (Elsop)
LinkScan™ and Elsop™ are Trademarks of Electronic Software Publishing Corporation