Installation Guide

Guide Version: 1.11
Newest Guide Version: http://TrackSite.ru/channel/installguide.html

Warning

Remember that you should keep confidential TrackSite registration name and serial number obtained upon purchase. In some situations, upon upgrade or when authorization name and password are compromised, it serves as second-line-of-defense password. By disclosing it, you weaken the security of your TrackSite installation. In addition, product upgrades and other valuable benefits are tied to registration data and may be lost, if such data is disclosed or misappropriated.

During installation, registration data is required only once upon TrackSite registration stage (see below). You should confidentially enter registration data yourself when such need arise in the course of installation.

Installation Requirements

Overview

TrackSite is installed on a computer that is connected to the Internet (or intranet if you want to analyze intranet traffic)--we call this computer deployment server (or deployment machine), and has webserver software installed on it--we call it deployment webserver. We also call operating system installed on deployment machine the deployment platform. Usually TrackSite is deployed on the same webserver (same machine) that hosts website to be tracked, e.g. directly in cgi-bin directory of tracked website, so that you use the same hosting for both tracked site and TrackSite, but this is not required. Deployment machine and webserver may be rented as hosting service or dedicated server may be used for that end. You can easily install TrackSite remotely via Internet on deployment server, which may physically be located anywhere in the world.

And once TrackSite is installed on deployment server (e.g. hosted by hosting provider), you can access it from anywhere in the world via Internet (or intranet) with your browser. Running on deployment server, TrackSite constantly monitors your site and publishes reports as usual (password protected!) web pages that you can periodically browse with your browser from anywhere (from home, work, Internet-cafe) to see what is going on your site.

Requirements

TrackSite installation requirements are:

Operating system (deployment server):

• Unix derivative: any flavor Linux (RedHat, SuSe, Debian etc.), any flavor of BSD, Solaris, SunOS, AIX, HP-UX; or
• Windows: NT/2000/XP/Server2003

Webserver:

• Webserver software installed on deployment machine (Apache, Domino, IIS, etc.)
• cgi-bin directory available (configured) on deployment webserver

Perl interpreter:

• Perl interpreter 5.7.1 or higher installed on deployment machine; or
• Perl interpreter 5.6.1 or higher installed on deployment machine together with additional Filter module;

On Windows Perl interpreter needs to be located in PATH directories

TrackSite reports are browsable with any browser from any computer connected to the Internet. Browser should have cookies support turned on (default). In particular, Mozilla Firefox and Microsoft Internet Explorer will do. (Note that this requirements apply only to browser that you use to browse TrackSite reports.)

Above installation requirements are met by almost any website hosting plan, even most inexpensive.

If hosting service has Perl version in between 5.6.1 and 5.7.1, but has no Filter module installed (Filter module is standard part of Perl only beginning from version 5.7.1), ask service provider to install it. It is a common practice that Perl modules are installed by provider upon client request, if not yet. Filter module is freely available from CPAN and its installation is a trivial task that takes about 2 minutes or so (there is no rational reason for hosting provider to deny you use of Filter module).

If you are not sure whether installation requirements are met, consult competent person (system administrator, support person, etc.). In case deployment machine and deployment webserver are rented as hosting service, consult your hosting terms or ask hosting provider whether cgi-bin directory and proper version of Perl interpreter are available under your service agreement.

Requirements test

You should use installation of the latest available version of TrackSite Free of TrackSite as ultimate test of whether installation requirements are met. If TrackSite Free of TrackSite runs OK in your case, Standard Edition will also run OK. If installing TrackSite Free hits problems, please e-mail problem description to us, so that we can investigate and possibly issue a patch for your specific situation.

Installation Modes

If targeted deployment webserver runs your CGI scripts under your account, you are installing in Privileged Mode. Otherwise, if targeted deployment webserver use unprivileged  account to run your CGI scripts, you are installing in Default Mode. The distinction between Privileged and Default Mode applies both to Unix derivatives and to Windows systems.

To find out what installation mode you are installing with ask administrator of targeted deployment webserver which system account they use to run your CGI scripts.

Privileged Mode

You are installing in Privileged Mode, if targeted deployment webserver runs your CGI scripts under your account. On shared Unix servers (typical hosting service) this means either:

• setuid wrapper (suEXEC in case of Apache) is used to run CGI scripts
• user runs dedicated webserver software under own user ID
• user is allocated with its own isolated virtual server environment

Privileged Mode provides security benefits on shared systems meaning TrackSite installation has increased protection against peer users of the same deployment machine.

Note: running CGI scripts under user's account is currently the common practice among hosting providers

Default Mode

You are installing in Default Mode, if targeted deployment webserver use unprivileged shared account to run your CGI scripts. Default Mode was the usual installation mode for CGI scripts hosted by hosting providers, but in recent time it becomes increasingly less common.

Be advised that if webserver use shared unprivileged account to run CGI scripts on shared server, all CGI scripts on shared server, including TrackSite, have potential security exposure to actions of peer users of the same server (e.g. users that host they own sites on the same machine; not people on the web). If you have to be true paranoid, e.g. you  concerned with espionage from peer users of hosting service, Default Mode should not be used.

Installing on Windows

This Guide covers installation procedure for both Unix and Windows deployment servers. Installing TrackSite on Unix and installing on Windows requires the same procedure as described by this Guide. Where installation procedure needs to be system-specific, Unix-specific  description is given, while Windows-specific installation details are presented as separate Installing on Windows notes in corresponding sections.

The only major difference of Windows installation is that you will need to set Windows native file permissions equivalent to (or more permissive) than that specified by this Guide in Unix case (and ignore some minor Unix-specific operations that do not apply to Windows). This difference is fully covered by Installing on Windows notes.

Non-Standard Installations

Designing other secure non-standard TrackSite installations, is available as consulting service.

Basic Installation Procedure

What you need to know

To complete installation procedure you will need to know:

• URL of cgi-bin directory where (in subdirectory) you are going to install TrackSite: we designate it as http://domain/cgi-bin/ (although it may well look like http://domain/somepath/cgi-bin/)
• Whether webserver runs scripts in cgi-bin directory under your account (Privileged Mode) or under unprivileged account (Default Mode). See Installation Modes above for details.

Installation Procedure: Executive Summary

Note: If procedure described in Executive Summary hits problems or not clear, refer to corresponding section of its Full Story version.

TrackSite installation: Create custom-named subdirectory in cgi-bin directory of deployment webserver to be the TrackSite's installation directory. We refer to it as TrackSite directory; to illustrate, this Guide use name 'tracksite' for it, but you should use different name (do not name it 'tracksite' after us). Unpack distribution archive and transfer (upload with FTP) tracksite5.pl (tracksite5free.pl) into 'tracksite' directory. Depending on installation mode, set permissions on those files and directories as follows:

After that browse http://domain/cgi-bin/tracksite/tracksite5.pl (or .../tracksite5free.pl) , where http://domain/cgi-bin/tracksite/ is the URL of 'tracksite' directory specific to your case, to trigger installation process and see generated installation report page.

Installing on Windows: Above permissions translate into Windows native permissions:

where "MyAccount" stands for your account name on the Windows deployment server, "IUSR_Machine" stands for unprivileged account that webserver use to run your CGI scripts (consult webserver administrator for exact name of that account).

TrackSite entry: On installation report page click Entry link (or browse URL http://domain/cgi-bin/tracksite/ref.cgi?index.html). Authorize with default name 'user' and password 'tracksite', simultaneously change default name and password (remember new ones); enter TrackSite's front page and bookmark it for regular access; optionally enter Control Center and set options the way you like (refer to Control Center manual).

Tying with website: To start tracking TrackSite needs to be tied with website i.e. each website's page that needs to be tracked must be tagged with special tracking code, the tracking tag. Tracking code can be pasted into html pages manually or automatically by TrackSite. In case of manual tagging, generate tracking code in Control Center. If webserver runs copy of website's original source code kept somewhere else (in different directory or on different machine), the preferred solution is to tie (tag) the source code itself and then either copy tagged source to webserver or similarly tie (tag) current copy on webserver. The advantage is that whenever you edit original page and copy it to webserver it remains tied (tagged). For tying either original source code or its copy on webserver use any of the methods described below. Before proceeding with this step make sure you have backup copies of your entire website.

If TrackSite is deployed on same machine that runs tracked website (e.g. you install TrackSite into cgi-bin directory of website), you have fully automated tying (tagging) solution. Move to 'Tie With Website' section of Control Center and enter full filesystem path to website's root directory on that machine into 'Path to website directory' field and http://domain/cgi-bin/tracksite/ (which should be replaced with your specific value, as described above) into 'URL of TrackSite directory' field. Press 'Tie With Website' button to see tying report. If you need to untie (untag) website, use same approach but leave 'URL of TrackSite directory' field blank.

Automated tying procedure requires that permissions set on website's files and directories allow TrackSite to perform automated tying i.e. files should be readable and writable by TrackSite (for formal description of those requirements see Full Story step 8). In Default Mode requirements will typically not be met, because normally pages of your site should not be writable by unprivileged user account, which is used to run TrackSite in Default Mode. For automated tying in Default Mode, do one of the following:

• run from shell the tiesite.pl script that comes with TrackSite distribution (as described below; requires that you have shell access to machine hosting tracked website); or
• run setuid tiesite.pl script - see Full Story step 8 (this solution is Unix-specific)

If website to be tracked is located on different machine that has recent enough Perl interpreter installed, you still have automated tying solution - run from shell the tiesite.pl script that comes with TrackSite distribution (as described below).

Tying website from shell: You may need to use SSH to do it remotely. Copy tiesite.pl from TrackSite distribution to that machine and in directory where you have copied tiesite.pl issue the following command on shell prompt (as one line):

perl tiesite.pl -path /path/to/websiterootdir -url http://domain/cgi-bin/tracksite/
-skip /path/to/cgi-bin/tracksite

where components in red should be replaced with values specific to your case i.e. /path/to/websiterootdir should be replaced with your specific full path to website's root directory on that machine; http://domain/cgi-bin/tracksite/ should be replaced to your specific value, as described above; and /path/to/cgi-bin/tracksite should be replaced with absolute path to TrackSite directory. The -skip option is required, only if TrackSite directory is itself subdirectory of the /path/to/websiterootdir directory.

For manual installation without help of tiesite.pl automation, see Manual Tying in step 8.

In case of problems, check Installation Troubleshooting of Full Story for proper stage.

Installation Procedure: Full Story

TrackSite installation

1. Make sure you have backed up copy of distribution file in a safe location.
2. Extract (unzip) distribution file into some temporary directory. You may use any program that is able to extract distribution file format (zip; there are plenty of them and you may already have one installed - check it out by trying to open (double click) distribution file). Distribution archive contains two files: tracksite5.pl (tracksite5free.pl) and tiesite.pl, get them extracted into temporary directory.
3. In cgi-bin directory create subdirectory that will be used to install TrackSite. We refer to it as TrackSite (installation) directory; to illustrate, this Guide use name 'tracksite' for it, but you should use different name (do not name it 'tracksite' after us). Copy tracksite5.pl (tracksite5free.pl) into this directory and set permissions on directory and file as described in a table below. As a result, you should end up with the following files, directories and permissions within cgi-bin directory of deployment webserver:

Directory/File	Permissions
	Privileged Mode	Default Mode
tracksite/	0701 (drwx-----x)	01707 (drwx---rwt)
tracksite/tracksite5.pl	0500 (-r-x------)	0505 (-r-x---r-x)

Note: In rare event you may need to make sure that directories in the pathname of (i.e. "above") TrackSite installation directory have at least the following permissions: 0100 (d**x******) in Privileged Mode or  0001 (d********x) in Default Mode, where * indicates arbitrary permissions. This requirement is usually automatically met for properly configured cgi-bin directory and you do not need to bother about them, unless "permissions denial" errors are encountered. On shared servers permissions on top parent directories may be beyond your control, so you may need to ask server administrator to change them (in unlikely event that such need arise).

For detailed instructions on how to set these permissions refer to Appendix A: Setting Permissions on Unix.

Installing on Windows: Above permissions translate into Windows native permissions:

Directory/File	Permissions
	Privileged Mode	Default Mode
tracksite/	MyAccount: Change (RXWD)	IUSR_Machine: Change (RXWD)
tracksite/tracksite5.pl	MyAccount: Read (RX)	IUSR_Machine: Read (RX)

where "MyAccount" stands for your account name on the Windows deployment server, "IUSR_Machine" stands for unprivileged account that webserver use to run your CGI scripts (consult webserver administrator for exact name of that account). In case of IIS webserver, "IUSR_Machine" account, where "Machine" token is replaced with actual machine name, is automatically configured to run CGI scripts. For detailed instructions on how to set these permissions refer to Appendix B: Setting Permissions on Windows.

To perform this step note the following:

Installation Mode: refer to Installation Modes to find out what installation mode you are installing with.

Remote installation: If you perform installation remotely i.e. via Internet or intranet, e.g. into cgi-bin directory of hosted website that is to be tracked (the most common case), copying tracksite5.pl means upload and you will need to use any FTP program (one that you normally use for regular site maintenance) to create 'tracksite' directory and upload tracksite5.pl into it. Depending on functionality of FTP client program used, it may be as easy as drag-and-drop or a like.

Uploading from Windows machine: Unlike modern systems, Windows treats binary and textual files differently, which always create mess. If you have unpacked distribution archive on Windows system (regardless of destination deployment platform, which may be Linux, for example), tracksite5.pl and tiesite.pl should be treated as binary files. FTP programs designed for Windows have special settings that instruct it which files identified by file name extension it should see as textual (binary) files. (Textual mode for file may be called ASCII mode.) Check those settings of your program and temporarily change them to make FTP program treat .pl extensions as binary files (not treat as text files).

Installing from command-line: Alternatively, if you have recent enough Perl interpreter installed on machine from which you try to copy TrackSite installation files to remote server via FTP, you do not even need FTP program. Just change working directory (cd command) to directory where you placed installation file and enter the following command (as one line):

perl tracksite5.pl -host remote.server.com -login mylogin -pwd mypassword -dir cgi-bin/tracksite -filemode 505 -dirmode 01707

where remote.server.com is the host name of deployment server; mylogin and mypassword are login and password for your FTP account on that server; cgi-bin/tracksite should be replaced with specific absolute or relative (against default working directory of your FTP account) path to TrackSite directory (if it does not initially exist, it will be created automatically); values of -filemode and -dirmode options reflect file and directory permissions as described above (depending on installation mode). If FTP server sits on unusual port, that port should be specified with -port option; on some servers you may also need to specify your account with additional -account me@remote.server.com option.

This command will do everything this step is all about, including upload of installation file into TrackSite directory on remote server and setting correct permissions on TrackSite directory and uploaded file (you need to correctly specify them depending on your installation mode, though). After this command runs, verify that directory is created and/or permissions are set correctly. Note: For remote Windows servers this command will perform uploading only, but will not yet set permissions and you will need to use other means described here to set permissions.

In an unusual case that this command failed to set permissions, FTP program will not help you set permissions either, and you will need to use SSH program instead; this rare case is not covered by this guide, but all that needs to be done is again copying installation files and setting correct file permissions.

Local installation: If you perform installation locally, you need just to know where cgi-bin directory is on your machine, create subdirectory and copy files mentioned above using any file manager program (e.g. Explorer on Windows).

Permissions note (Important!): It is very important to set files and 'tracksite' subdirectory permissions exactly as described above. It is not only crucial for successful installation, but also has security implications. Permissions are edited with FTP program in case of remote installation or file manager program in case of local installation. If you have no idea how to manipulate permissions in practice, refer to Appendix A: Setting Permissions on Unix or Appendix B: Setting Permissions on Windows, depending on whether you install on Unix or Windows.

4. For this step you should know URL of cgi-bin directory where you have put 'tracksite' subdirectory. Ask you hosting provider about such URL, if you have no idea about it. Further in the text we will use http://domain/cgi-bin/ as URL of cgi-bin directory, but you should use URL of cgi-bin directory specific to your case instead (it may well look like http://domain/somepath/cgi-bin/). Once you know it, open your browser and browse http://domain/cgi-bin/tracksite/tracksite5.pl, which is the URL of cgi-bin directory with added prefix of tracksite/tracksite5.pl file installed on step 3. If above steps where performed correctly and you have correct http://domain/cgi-bin/ value, browsing this URL will trigger installation process and browser will display installation report page upon completion. Save it for future reference. If installation report says installation OK, proceed to next step. Otherwise consult Installation Troubleshooting: TrackSite installation section.

Warning: When you browse the URL to start installation process, as described above, do not hit Stop button in your browser or otherwise abort this process, until you see installation report. If you do, installation may end up incomplete and you will need to repeat this installation procedure from the start (see Installation Troubleshooting: TrackSite installation section).

Installing on Windows: On Windows browsing URL to trigger installation will work the same way, if Perl interpreter is associated with .pl files. The very installation of Perl interpreter on Windows by default creates such association in Windows Registry, thus in most cases there is no need for special arrangements for this step. If this is not the case, browsing URL will return "Internal Server Error" or a like error and you need either:

• Associate .pl files with Perl interpreter and browse URL again as described above; or
• Run tracksite5.pl from command line by issuing following commands on command line prompt:

cd C:\path\to\cgi-bin\tracksite\

perl tracksite5.pl

where C:\path\to\cgi-bin\tracksite\ should be replaced with specific to your case full filesystem path to TrackSite directory; 'perl' may need to be replaced with full pathname of Perl interpreter, if Perl interpreter is not in a PATH directory. You can issue these commands remotely with SSH; see SSH (Secure SHell) client program description in step 8.

Apache-specific note: Be advised that in case of Apache webserver browsing URL may start installation process and deliver installation report only once. Subsequent browsing of the same URL may return "Client denied by server configuration" or a like error. This is not a problem, provided that initial installation report was OK.

5. On installation report page click Entry link (or browse URL http://domain/cgi-bin/tracksite/ref.cgi?index.html). Again, if above steps where performed correctly and you have correct http://domain/cgi-bin/ value, you should see TrackSite authorization page that will ask you to enter your user name and password. This means TrackSite has been successfully installed. In next steps you will need to enter Control Center to register TrackSite. If you do not see TrackSite's authorization page, then something is wrong and you cannot continue with next steps; check above steps or consult Installation Troubleshooting: TrackSite installation section.

Troubleshooting Recommendations

See Installation Troubleshooting: TrackSite installation section.

TrackSite entry and registration

As soon as you see TrackSite authorization page, enter TrackSite:

6. On authorization page enter name 'user' and password 'tracksite'. These name and password are default name and password that ship with TrackSite and should not be left as such as soon as you install TrackSite, cause they are not secret and bad people may use them to see statistics of your site. You should replace default name and password as soon as possible. We recommend that you do this right at this step using lower part of authorization page. In this case, make sure you remember new name and password; if you forgot them you will not be able to enter TrackSite and will need to reinstall it to remedy such situation. If you choose not to change password at this step, make sure you do it upon next authorization (you may use Exit link in TrackSite navigation to trigger re-authorization). Warning: Do not leave default name and password as your regular name and password, they are insecure.

Press 'Submit' button. If name and password are correct, you will enter TrackSite's front page. If you have specified new name and password in lower part of authorization page and have authorized successfully, you should use new name and password from this moment. If you end up with authorization page again, this means name and/or password are incorrect and you need to enter them again.

Installing from Windows: If you have installed from Windows, i.e. unpacked distribution archive on Windows (regardless of actual deployment platform, which may be Linux, for example), take a close look on TrackSite logo at top left part of the screen. If it is distorted, consult point 4 of  Installation Troubleshooting: TrackSite installation section.

7. On the TrackSite front page, bookmark it in browser's Favorites folder to use this bookmark later for regular TrackSite access. Then, click 'Control Center' link and you will face TrackSite registration page. Enter your TrackSite registration name and serial number as they where supplied to your upon TrackSite purchase (see Warning above). If they are correct, you will end up on Control Center page.

Troubleshooting Recommendations

See  Installation Troubleshooting: TrackSite entry and registration section.

Tying website with TrackSite

At this point TrackSite is completely ready to track your website. To start tracking TrackSite needs to be tied with website i.e. each website's page that needs to be tracked must be tagged with special tracking code, the tracking tag. Tracking code can be pasted into html pages manually or automatically by TrackSite. In case of manual tagging, generate tracking code in Control Center. If webserver runs copy of website's original source code kept somewhere else (in different directory or on different machine), the preferred solution is to tie (tag) the source code itself and then either copy tagged source to webserver or similarly tie (tag) current copy on webserver. The advantage is that whenever you edit original page and copy it to webserver it remains tied (tagged). For tying either original source code or its copy on webserver use any of the methods described below. Before proceeding with next step make sure you have backup copies of your entire website.

8. There are two ways to accomplish this step, automated and manual tying as follows:

Automated Tying

Note: automated tying may produce results that are close, but not exactly what you expect. In such case use manual tying to correct results of automated tying - see Manual Tying section for details.

If TrackSite is deployed on same machine that runs tracked website (e.g. you install TrackSite into cgi-bin directory of website), you have fully automated tying (tagging) solution. Move to 'Tie With Website' section of Control Center and enter full filesystem path to website's root directory on that machine into 'Path to website directory' field and http://domain/cgi-bin/tracksite/ (which should be replaced with your specific value, as described above) into 'URL of TrackSite directory' field. 'Path to tiesite.pl' field should be left blank, except special case described below. Press 'Tie With Website' button to see tying report. If you need to untie (untag) website, use same approach but leave 'URL of TrackSite directory' field blank. Note that in this case you tie entire website with just a click.

To permit such automated tying website's root directory and its sub-directories and html pages should have at least the following (or higher) permissions (* indicates arbitrary permissions):

Directory/File	Permissions
	Privileged Mode	Default Mode
directories	0500 (dr*x******)	0005 (d******r*x)
files	0600 (-rw*******)	0006 (-******rw*)

Note: In rare event you may need to make sure that directories in the pathname of (i.e. "above") TrackSite installation directory have at least the following permissions: 0100 (d**x******) in Privileged Mode or  0001 (d********x) in Default Mode. This requirement is usually automatically met for website that is "visible" to the web and you do not need to bother about them, unless errors are encountered upon tying with website. On shared servers permissions on top parent directories may be beyond your control, so you may need to ask server administrator to change them (in unlikely event that such need arise).

Installing on Windows: Above permissions translate into Windows native permissions:

Directory/File	Permissions
	Privileged Mode	Default Mode
directories	MyAccount: Add and Read (R*W***)	IUSR_Machine: Add and Read (R*W***)
files	MyAccount: Change (R*W***)	IUSR_Machine: Change (R*W***)

where "MyAccount" stands for your account name on the Windows deployment server, "IUSR_Machine" stands for unprivileged account that webserver use to run your CGI scripts (consult webserver administrator for exact name of that account). In case of IIS webserver, "IUSR_Machine" account, where "Machine" token is replaced with actual machine name, is automatically configured to run CGI scripts. For detailed instructions on how to set these permissions refer to Appendix B: Setting Permissions on Windows.

Tying in Default Mode: In Default Mode above file permission requirements will typically not be met, because normally pages of your site should not be writable by unprivileged user account, which is used to run TrackSite in Default Mode. For automated tying in Default Mode, do one of the following:

• run from command line (shell) the tiesite.pl script that comes with TrackSite distribution (as described below; requires that you have command line (shell) access to machine hosting tracked website); or
• run setuid tiesite.pl script as follows (this solution is Unix-specific):

Additionally transfer into TrackSite directory tiesite.pl, which is part of distribution, and set its permissions to 04505 (-r-s---r-x). Then do Control Center manipulations as described above. Warning: Because this will make tiesite.pl a setuid program that will run in privileged mode (run as you), you should drop permissions on that tiesite.pl file to 0500 (-r-x------) as soon as you are done with website tying and after dropping permissions test by looking into html source that tying was done as expected. Only if you have chosen to copy tiesite.pl into location other than prescribed (an unlikely event), specify full pathname of tiesite.pl in 'Path to tiesite.pl' field before pressing 'Tie with TrackSite' button (remember that this location directory should be accessible to unprivileged user). Otherwise simply leave it blank.

If website to be tracked is located on different machine that has recent enough Perl interpreter installed, you still have automated tying solution - run from command line (shell) the tiesite.pl script that comes with TrackSite distribution (as described below).

Tying website from command line (shell) (here things get perhaps a little too technical for non-technical people): Copy tiesite.pl from TrackSite distribution to machine where website to be tied is located (e.g. the same way as you did in the steps 3). Lets designate full pathname of copied tiesite.pl as  /path/to/tiesitedir/tiesite.pl. Get to the command line (shell) prompt (connect to remote machine using SSH program for that) and change current directory to directory where you have put tiesite.pl  by issuing this command on command line (SSH) prompt:

cd /path/to/tiesitedir/

Then, issue the following command on command line (SSH) prompt (as one line):

perl tiesite.pl -path /path/to/websiterootdir -url http://domain/cgi-bin/tracksite/ -skip /path/to/cgi-bin/tracksite

where components in red should be replaced with values specific to your case i.e. /path/to/websiterootdir should be replaced with your specific full path to website's root directory (where top index.html front page usually lives) on that machine; http://domain/cgi-bin/tracksite/ should be replaced to your specific value, as described above; /path/to/cgi-bin/tracksite should be replaced with absolute path to TrackSite directory; the additional -skip option is required, only if TrackSite directory is itself subdirectory of the /path/to/websiterootdir directory; 'perl' may need to be replaced with full pathname of Perl interpreter, if command fails.

Again, if you need to untie website in this case, use same approach, but issue perl command without last argument:

perl tiesite.pl -path /path/to/websiterootdir

Retying website: Having once tied website to TrackSite, you may need to occasionally retie it. Such need arise if values used for tying turned out to be incorrect or whenever you change TrackSite deployment or URL of TrackSite's cgi-bin directory changes (as a result of webserver configuration change). Retying is simple. To retie, untie website first as described above, and then tie it again using new values.

Manual Tying

If automated tying doesn't work for you for some reason, you can always perform website tying manually. For this you need to edit website page to manually insert special tie code inside <HEAD>...</HEAD> tag in HTML code of every page that you want to track. Tie code can be generated using "Get Tie Code" button in Control Center.

Note that there should be only one snippet of tie code per page. To insert tie code you can edit pages directly on server or edit their local sources and then copy them to replace page copies that are currently on server. To insert tie code you may manually paste it in all pages (may be time consuming for large websites) or use advanced cross-file find-and-replace interfaces that some editing programs provide to automatically insert snippet in all site pages (search "<head>" or "</head>" tag and replace it with "<head>snippet..." or "...snippet</head>" respectively). If you need to retie site manually, you need to modify tie code snippets the same way in all pages to reflect new tying values.

One special case when you may need manual tying is to correct automated tying. Both tying tool of Control Center and tiesite.pl automatically tie (tag) every HTML page (regardless of file extension) that they find in and below website root directory so that every visit of that page is tracked. However, some pages may not need to be tracked, e.g. to reduce data noise, the fact automated tying is unaware of. One notorious example is master page that use frames inside to link to other, framed component pages. If framed pages are mere components that are not supposed to be navigated out of master page, they should not be tracked. In contrast, if master page is just auxiliary presentation handler for standalone page, master page do not need to be tracked. Finally, it is quite possible that both framed page and master page need to be tracked. Later case is assumed by automated tying - it ties both master page and frame page. If this assumption is not true in your case, you may need to manually remove automatically installed tie code from pages that do not need to be tracked. For removing tie code either replace tied page with unmodified (untied) version of such page from original/backup copy of website or edit tied page.

9. If all prior steps are completed, you should have completed all procedures necessary to install, configure and start tracking site with TrackSite. On Control Center you may configure some options (refer to Control Center manual), but it is not required--default configuration is enough to start tracking website activity. Your website may now be already be tracked by TrackSite, but you need to verify this. Just visit your site and then go to TrackSite (e.g. using bookmark created at step 7) and see Clickstream report. If you see some traffic recorded, then congratulations!, you are through. If not, check above steps for what you may have done wrong or consult  Installation Troubleshooting: Tying website with TrackSite section.
10. After entire installation is complete, we strongly recommend that you do some cleanup work as soon as possible. Most importantly, installation process will automatically remove installation file tracksite5.pl (tracksite5free.pl) from TrackSite directory, but in some cases this may not happen for variety of reasons. Verify this, and if installation file has not been removed, remove it yourself (or at least make it non-executable with file permissions) - it is no longer necessary, takes space, but more importantly, it may be executable by people on the web.

Executable tracksite5.pl left after installation is not a security hole. Executing it by malicious people on the web or by accident will not harm your database, but custom report and other setting that you have already made since installation will be reset to defaults. This will also reset your authorization name and password back to user/tracksite and, thus, allow malicious people to enter your TrackSite. But this will not get them too far--they will not be able to neither see nor steal statistics of your site, because TrackSite will require new registration from them (and from you a bit later) and they do not know your serial number because you have told it to nobody else, have you. This is one of the reasons why you should not disclose TrackSite's registration data.

Troubleshooting Recommendations

See  Installation Troubleshooting: Tying website with TrackSite section.

 

Installation Troubleshooting

The most powerful way to troubleshoot the installation is to scrupulously follow installation instructions. If you have trouble, check out installation steps performed to adhere strictly to above installation instructions. If you discover deviations, you may need to repeat installation.

To repeat installation from the beginning, in most cases, you do not need to return things to the very initial state i.e. no need to delete or empty 'tracksite' subdirectory or to repeat copying (re-upload) of tracksite5.pl installation file (unless copy used for installation gets corrupt). Simply browsing URL again, as described in step 4, will trigger brand new installation--if successful, it will automatically overwrite files left from previous failed installation. However, if you install on Apache webserver and browsing URL to trigger brand new installation returns "Client denied by server configuration" error, you have to rename already transferred tracksite5.pl to patch.pl (do not re-upload it, simply rename already uploaded file using FTP program) and browse different URL http://domain/cgi-bin/tracksite/patch.pl instead.

TrackSite installation: steps 1 - 5

If instead of installation report at step 4 you see  "Client denied by server configuration" or a like message, first see Apache-specific note to step 4 above and check point 5 of the troubleshooting list below. If instead of installation report at step 4 you see  "Internal Server Error" or a like message, check points 3 and 4 of the troubleshooting list below first. If you see "Error 404. File Not Found..." it is probably reason 1. In any other case, check troubleshooting list points one after one starting from 1.

1. Check whether you have correct URL of cgi-bin directory i.e. value that we designate above as http://domain/cgi-bin/. The most common reason for installation failure is that this URL is (e.g. subtly) incorrect. Consult hosting provider or webserver administrator about this URL.
2. Make sure that you have created TrackSite subdirectory of cgi-bin directory on webserver and transferred tracksite5.pl as described by steps 3. Browse cgi-bin directory (locally with file manager program or remotely with FTP client program) to verify this.
3. Check permissions on subdirectory created and files copied. They should be set exactly as specified in step 3.
4. Installing from Windows: One possible reason that you still can't get installation report OK is that FTP program see tracksite5.pl installation file as textual file. Consult Installing from Windows note of step 3, correct FTP program settings and repeat installation procedure.

If above steps do not detect installation error, the following may require help from deployment webserver administrator or a like:

5. Check webserver-controlled access restrictions configured for people on the web. They may be set to deny you access to http://domain/cgi-bin/tracksite/tracksite5.pl'. Configuration of those restrictions is server-specific. In case of Apache you need to check server-wide configuration files and .htaccess file in cgi-bin directory for that. To check these out ask webserver administrator whether http://domain/cgi-bin/tracksite/tracksite5.pl is accessible on webserver. If they say it is not, ask them to make it accessible and retry step 4.

TrackSite entry and registration: steps 6 - 7

If you have authorization or registration difficulties right after TrackSite installation, make sure that you enter all data correctly. This is especially true for password and serial number, which are typed hidden, so you cannot control whether value you have entered is correct; make sure you enter characters in proper case; also make sure that your keyboard is switched to Latin characters and that Caps Lock is in proper state. If problem persist and reinstallation attempts hit same problem again, contact TrackSite Support using TrackSite website (http://tracksite.ru/).

Tying website with TrackSite: steps 8 - 10

First, check out that you do not have tracking accidentally disabled in Control Center with 'STOP TRACKING' checked. If tracking is disabled, enable it.

The most common reason why TrackSite still do not track your site is that you have made a mistake in URL of TrackSite directory i.e. value that we designate above as http://domain/cgi-bin/tracksite/, but you should use your value. Check once more whether it is correct. If it is not, use automated tying tool on Control Center (or tiesite.pl) as described in step 8 to untie website and then tie it again using correct http://domain/cgi-bin/tracksite/ value. (Or manually correct all HTML code snippets in all pages where it is present in a way described in step 8; make sure that all pages end-up with correct snippet (if page has incorrect snippet, it will not be tracked by TrackSite.)

If you have thoroughly followed instructions and troubleshooting recommendations, but still cannot get TrackSite to track your site, try brand-new installation from scratch. If it hit exactly same problem again, contact TrackSite Support using TrackSite website (http://tracksite.ru/) and provide them with relevant installation and tying reports.

Installing From Downloaded Database Packages

Control Center of TrackSite allows to download TrackSite database package (or simply database package) which is the "snapshot" of TrackSite database and all custom settings within TrackSite that can be used to restore TrackSite installation back to state reflected in "snapshot". Database packages are designed to be used for back up of TrackSite database in just a click and for easy transfer of entire TrackSite database to other deployment machine, e.g. other hosting provider.

If there is no existing installation to replace, to install TrackSite from database package you should use the same Basic Installation Procedure as described above, but use database package file (usually downloaded as mytracks.pl or a like) instead of tracksite5.pl file. In case you want use downloaded package to restore current installation to the state of package's snapshot (not to create different installation) you will need to rename package file to patch.pl and then treat it the same way as you would treat tracksite5.pl file upon installation, as described in Basic Installation Procedure, except that TrackSite directory will initially contain files of current installation (no need to remove them). Retying website to newly (re)installed TrackSite is not necessary, unless URL of TrackSite directory has changed since website was last tied.

Note: On rare occasion you may encounter "Internal Server Error" or a like messages after installing from downloaded database packages. In this case either change (reduce) reported range by one day, or check "Flush" checkbox, if it is available, and try again; this measure is required only once to return to subsequent normal operation of the same report. (This minor bug will be fixed in future release.)

If there is already working installation that you want to replace, follow procedure described in Upgrading Existing Installation section, except that database package file (usually downloaded as mytracks.pl or a like) is used instead of distribution file (tracksite.pl or a like) and possibly Control Center settings may not need be reentered cause database package file restores its own settings.

Upgrading Existing Installation

Before upgrade (!):

• Make sure you have downloaded and backed up current installation as database package (in addition, plain copy of TrackSite directory is recommended), they may be necessary to restore current installation in case upgrade goes wrong for some reason.
• Make sure you have backed up all Control Center settings (especially custom search engine specs, titles map, downloads map) and stored filters - currently they are a not automatically preserved upon upgrade and need to be reentered manually for upgraded installation (old settings may accumulate a lot of knowledge and be highly valuable). Note that old settings are also preserved in backup database package of old installation and can also be retrieved from there by separately installing old installation, if necessary,  but it may be less convenient. In Multi-User mode advise ordinary users to do the same with their custom settings.
• If Webserver Extensions are enabled in existing installation, disable them before upgrade

To upgrade existing installation with new distribution, follow the same Basic Installation Procedure as described above, except add 'patch_' prefix to installation script name i.e. rename tracksite5.pl (or a like) file to patch_tracksite5.pl before transferring (uploading) it to deployment server and then treat it the same way as you would treat tracksite5.pl file upon initial installation, as described in Basic Installation Procedure, except that TrackSite directory will initially contain files of already existing installation - do not remove them! Upgraded installation will automatically preserve old traffic database accumulated so far. Retying website to newly (re)installed TrackSite is not necessary, unless URL of TrackSite directory has changed since website was last tied.

Immediately after upgrade, restore old settings of Control Center. It is recommended that you stop tracking using corresponding Control Center checkbox, before you restore the rest of settings (especially those that affect tracking).

Appendix A: Setting Permissions on Unix

Either in FTP program or in file manager program, file permissions are presented against each file or directory as 'rwxrwxrwx' string of 9 characters. First 3 characters represent permissions for file/directory's owner, next 3 are for group the file/directory belongs to and last 3 are for any other users on the system. Characters mean: 'r' - read permission; 'w' - write permission; 'x' - execute permission. Each character may be replaced with '-' to indicated that corresponding permission is not set (denied). The last 'x' character may also be replaced with 't' in directory case to indicate so called "sticky bit" set on directory.  The 'x' character for owner and/or group (i.e. except last) may also be replaced with 's' in file case to indicate so called "setuid" and "setgid" permission on file. String is prefixed with 'd' character in case of directory and '-' in case of file.

Each permission string also has alternative unique numeric representation that may also be rendered.

Procedure of setting file/directory permissions may vary a bit for different FTP programs and file managers, but it is essentially the same for all of them. To set permissions on file to particular value (given as numeric value or 9 characters string as described above), either in FTP program or in file manager program:

1. Move to desired folder and select file or folder that you want set permissions on.
2. In main menu or in context menu (available with right click on selection) select Properties or a like command (permissions control command may be presented in menu under different name, e.g. "File Permissions", "Chmod", etc.). You will see some graphical interface that either allows to enter permissions as single numeric value ("Chmod" command), or allow to set separate permission bits of  "Read", "Write" and "Execute" as well as "Set UID", "Set GID" and "Sticky" for "Owner", "Group" and "Others" (names may vary), respectively.

3. Using graphical interface set file/directory permissions to that required by this Guide.

Here is example for 0505 (r-x---r-x) for different permission control interfaces:

or

Note that "Set UID", "Set GID" or "Sticky" controls may not be present in specific interface, as in last example, so you may need to ignore corresponding part of permissions string i.e. assume 'x' instead of 't' or 's' (e.g. r-s---r-x can only be approximated by r-x---r-x). In this Guide such approximation will work (except for tiesite.pl fix, see Installation Procedure: Full Story step 8), but we strongly recommend to use FTP program or file manager program that allow to set all permissions exactly.

4. When done, graphical interface will render resulting permissions string and possibly its numeric representation. Make sure they are identical to given string (last 9 chars only) and/or its numeric analog respectively.
5. Click on OK to submit permissions and exit the properties box.

Appendix B: Setting Permissions on Windows

Either in FTP program or in File Manager:

1. Right click on the file or folder.
2. Select properties
3. Select the security tab on the properties sheet.
4. Click on the permissions button.
5. If the file you selected is a subdirectory there are the following check box choices:
   • Replace permissions on subdirectories - Permission changes are applied to all sub folders.
   • Replace permissions on existing files - Permissions are applied to all files in the folder. If both are selected, permissions are applied to all sub folders and files in all files in the folder and its sub folders.
6. Click on OK to exit the permissions box and OK to exit the properties box.

Appendix C: Jargon Booster