LinkScan Startup Guide for Unix Systems
|Help Reference HowTo Card|
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:
In order to install and use LinkScan on a Unix system, 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/. 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 ...
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.
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>
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>
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:
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 12.4 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 ===================================
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:
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:
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
Users will need to point a web browser at the
LinkScan Main Menu which typically resides at:
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.
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.
Summary of Available Reports
|Project Summary Report
Summary statistics for the current project
|Summary of All Projects Report
Summary statistics for all configured projects
|Problem Documents Report
List documents containing potential problems
|Selected Status Codes Report
List errors of specific types
|Document Detail Report
List all/selected documents
|All Pages Linking To ... Report
Find pages that link to...
|Critical Errors Report
List most critical errors
|Orphaned Files Report
List orphaned files
|Detailed Errors Report
List all/selected errors
|External History Report
View history of an external link
|Changed Documents Report
Compare two scans of the current project
List a summary of redirections
|Search Documents Report
Ad hoc searching: document-centric
|System Configuration Report
Display current LinkScan configuration settings
|Search Links Report
Ad hoc searching: link-centric
View source code and detailed analysis of a document
Display LinkScan SiteMap
Display LinkScan TapMap
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.
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.
Each of the LinkScan Menus and Reports includes a common LinkScan Toolbar. It contains a number of links:
|Main Menu Preferences Advanced||Help Reference HowTo Card|
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.
** Error: The LinkScan license key is invalid Mail this line to firstname.lastname@example.org - 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 email@example.com and we will send a new Key by return.
When trying to access linkscan.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 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.
If you are still experiencing difficulties, please:
LinkScan Startup Guide for Unix Systems
LinkScan Version 12.4
© Copyright 1997-2013 Electronic Software Publishing Corporation (Elsop)
LinkScan and Elsop are Trademarks of Electronic Software Publishing Corporation
|Help Reference HowTo Card|