Smart tip: This handbook is also designed to be printed... set your printer's page orientation to landscape format, so there is enough space to place hand-written notes on the left and right margin easily.
 

In a common environment, we recommend to create a new sub-directory within the existing "cgi-bin" folder to separate the software from other already installed products.

Required "template.en" directory:

Inside the directory you desired for installation, please create a new sub-directory called "template.en". It's used to hold the content of "template.en" directory delivered with your software package.

Adjust path to Perl:

Open all program files (*.pl and *.cgi) in a text editor and change the first line "#!/usr/bin/perl" that it reflects the correct path to Perl 5 (or higher version) on your system. This is required to let your server know where the Perl interpreter is located.

Usage note: On most systems, /usr/bin/perl is already the default path to Perl and so no modifications are required.
 

Detailed file table: Scheme: [filename | suggested place to upload (short description); file permission]:
 

Filename...	Description...	Filename...	Description...
*	cgi-bin (program & data files); 755	template.en/*	template.en (templates); 666

Important notes: Please double-check file permissions and transfer mode, otherwise the software may not work as intended. Depending upon the server configuration, different file permissions than the ones stated above may be necessary.

Smart tip: Our installation helper install.cgi makes it easier... just call it from your web browsing software (requires correct installation of this script) and it automatically checks your entire installation, adjusts permissions and fixes typical errors.
 

Before you proceed, it is highly recommended to set an administration password. After this is done, access to the admin panel is granted only by authenticating yourself with the chosen password.

Now click on the button "Edit system parameters" and configure the shown parameters according your needs.

Usage note: Since all parameters are automatically filled with correct values, modifications on your side may not be required.

Directories and files:
 

Name of parameter to set...	Description...
CGI files directory Example: /usr/www/cgi-bin/ms	Absolute path to the location of MagicStatistics on your server.

Platform specific settings:
 

Name of parameter to set...	Description...
Mailing program (for Unix only) Example: /usr/bin/sendmail	Absolute path to Sendmail (or compatible) application on your server.
SMTP server Example: smtp.sunnyscript.com	SMTP server for handling mails; when left blank, default mail application is used. This setting is required for non-Unix systems, otherwise optional.
Don't use flock Example: Unchecked	"flock" is normally supported directly by the operating system; should it be unavailable for any reason (e.g. on Win9x, WinMe), mark this checkbox.
Admin e-mail address Example: admin@sunnyscript.com	E-mail address of the system administrator (e.g. webmaster).

Compression settings:
 

Name of parameter to set...	Description...
Use internal gzip compression Example: Checked	Use the internal compression utility (to pack statistical reports) or unmark this checkbox and specify external utility as followed. Technical note: This choice is only available, if there is the Perl module "Compress::Zlib" installed.
External compression utility command Example 1: gzip -fq $file_from Example 2: c:\winrar.exe a $file_to $file_from	Absolute path to a file compression application on your server. Technical note: In some cases, the variables $file_to and $file_from are required to determine source and target files (see available literature).
External compressed file extension Example: gz	File extension used by the external compression utility.

URLs:
 

Name of parameter to set...	Description...
URL of CGI files directory Example: http://www.sunnyscript.com/cgi-bin/ms	URL to the location of MagicStatistics on your server.

After you have verified all settings carefully, click on the button "Save parameters" to take over modifications to the system. It is also possible to bring back previous values with the "Let the script restore defaults" button.
 

The server's raw log file(s) - also called server log - stores records of all accesses made to your website. So the logs are like a diary which contains all actions done by the server within a given time period.

These raw log(s) are the basis for MagicStatistics to create reports and usage statistics for your website and server.

Where are the server log files located ?

The location of the server logs depends upon the used operating system and server software. Normally you find the raw logs placed in a directory called "logs", "accesslogs" or a similar one.

In any case, it is recommended to ask your webhosting provider regarding the correct location. Sometimes your webhoster also needs to enable access to these raw log files before they are useable.

What happens with the log data ?

Each time you start the "Parse log file(s)" function from the admin panel or a scheduled log parsing runs, MagicStatistics will read in the raw log data (server logs) and analyzes their content.

The analyzed raw log data - now called parsed log data - is saved in a special database format, which allows MagicStatistics to access the collected information quickly at any time (more details follows in later chapters).

Whenever you request a report from MagicStatistics, the data is taken from these special report data files. So the server log doesn't need to be analyzed again, which saves much time, disk space and CPU resources.

During log file parsing, additional tasks may be also performed, like DNS lookups, mailing of statistics and log maintenance.
 

Technical note: Each log file line is scanned for matching format prior parsing. If you should decide to switch your log format, you don't need to take care about MagicStatistics.

Important note: Custom log formats are also supported. But please note that some of them may lack of specific information, which leads into missing report types (the ones which would base upon these non-existing data).
 

How reliable are statistics based upon server logs ?

Statistics based upon the raw log files are the most exact ones, because each single access is surely registered by the server without the risk of missing accesses and incomplete or erroneous data.

All website usage reports generated by MagicStatistics are absolutely reliable and can be used for professional applications, like the creation of visitor profiles and marketing research (e.g. target group analyses).
 

Usage note: The top menu line provides links to all menu entries regardless on which page you are currently. This will help you to navigate more convenient through the software.
 

General settings:
 

Auto-mailing options:
 

Search engine settings:

MagicStatistics is able to detect visitors coming from search engines and other web directories to your site. Within the report "Search engines tracking" (report type "Visitor information"), search engines and even the used keywords are listed.

In order to do so, MagicStatistics needs information about the referring URLs and keyword variables (URL is used to determine the search engine, the keyword variable is used to extract the search string). This is done at "Search engine settings".

Helpful hint: Modifications made here take effect also to already processed log data - so you can analyze search engine usage based upon your new settings even for previously parsed log file information.

How to add a new search engine:

Type in the name of the search engine in the appropriate field and click on the "Create new" button. Now the screen "Search engine settings" appears:
 

Integration of EasyData powered applications:

Please refer to the search engine "MaxJump" for details regarding implementation of EasyData powered search engines.

Smart tip: Have a look at SunnyScript's EasyData - reliable database system for versatile applications.

How to delete an existing search engine:

Select the engine you wish to remove from the list and click on the "Delete" button. However please note, that once an engine is removed, their settings cannot be recovered.

How to edit a search engine:

Select the engine you wish to modify and click on the "Edit" button. Now the screen "Search engine settings" appears (see details in the sub-part "How to add a new search engine" above).
 

After you have set all preferences, click on the button "Show report now...".

Smart tip 1: The generated reports can be printed easily: Depending upon the used paper size, you may need to set the printer's page orientation to landscape format. In this case, there is also space for placing hand-written notes at the margins.

Smart tip 2: Since MagicStatistics doesn't use image files to create bar graphs, you can simply copy the report to a disk and carry it to other computers, still keeping the layout (reports are generated in HTML language).

Export reports to 3rd-party applications:

When showing a report, click on "Download" available in the upper right corner of the screen. A "save file" dialog appears to save the report to your local computer in an easy-to-export format understandable by most spreadsheet and database apps.

Such an exported report can be used in software of your choice to develop complex statistic analyses or write presentations on the base of generated reports.

Technical note: At the target application, try to choose "HTML format" or "text format" import type to achieve best results.
 

Expert note: If your server software uses own log files for different dates (split logs), concerned dates' log files are removed instead of being cleared to keep the log directory free from empty files.

How to keep the report data, but clear server logs ?

If you wish to keep the report data and just want to clear the server's raw log files automatically after they got processed, please refer to "Edit software settings" as described above and enable "Erase parsed log entries from server log".
 

MagicStatistics analyzes the raw logs, performs complex operations on its data and saves the results in an internal database system - the "parsed" log file(s); this procedure allows fast access when requesting a report.

Which kinds of log files are detected ?

Please refer to the chapter "General information about the software" for more details.

How is log parsing done ?

Either select "Parse log file(s)" from the admin menu or configure your server to run MagicStatistics automatically for log parsing (explained in the following). If you use the admin panel to parse logs, you can watch MagicStatistics while being "in action".

Please note that parsing of log files takes some time and CPU resources. For this reason, it is recommended to parse logs at a time of low general system usage (e.g. at midnight or early morning).

Technical note: MagicStatistics uses NPH method (non-parsed headers) to prevent timeouts caused by the server or web browsing software (even if your browser crashes for any reason, the process is kept in the background and should be finished).

What happens with parsed raw log data ?

Depending upon your settings, parsed raw log data is either cleared or kept until you do log file maintenance.

When are report mails sent ?

Each time you parse log files, MagicStatistics will also process the selected e-mail reports.

Usage note: You don't need to parse log files daily, just because you have set receiving report mails daily. Each time you parse log files, MagicStatistics sends all pending mail reports automatically.

Technical note: If there were no accesses, reports are skipped for the concerned period (when running a low traffic website, it is recommended to generate report mails on a weekly, bi-weekly and/or monthly basis).

Some technical notes:

Parsed log files can be found within the "parsed_logs" directory at the location of MagicStatistics:
 

Imagine that you just wish to receive reports by e-mail without caring about parsing logs and other technical stuff - or you simply don't have the time to parse logs regularly (and if you have, you may forget it ;-)

The following chapter will describe how to use Cron (Unix platforms) to schedule log parsing and report mailing.

Important note: The scheduling tool of your server (depending upon the used operating system) can be different. In this case, please contact your webhoster's support department for more details.
 

The file to schedule is nph-cron.cgi of MagicStatistics (this works also with other scheduling tools).

Each time this program is executed, it will parse all raw log files according the settings made in the admin panel and also takes care about sending report mails (if enabled).

Usage note: For detailed information about Cron and how to manage scheduling on your server, please refer to available literature or contact your webhoster's support department.

Direct editing of Cron file:

Some possible Cron entries may look like the following:
 

Technical note: <perl> must be replaced with your Perl interpreter; <path> means the path to the MagicStatistics installation (location of nph-cron.cgi). Multiple entries are possible (e.g. to parse logs at different times).

Command line Cron scheduler:

If you're new at Cron scheduling, you can use our command line scheduler to add a new entry to your Cron file. The scheduler will be called from the command line...
 

Technical note: <perl> must be replaced with your Perl interpreter; ensure that you're in the MagicStatistics directory.

Now follow the provided instructions. After configuration, the matching entry will be added to your Cron file automatically.
 

Very few servers may experience problems when having "Erase parsed entries from server log" feature enabled. The reason is, that the server may keep the log files always open and so may show unusual behavior, like stopping to log accesses.

If you experience problems, please add a command to restart the web server software into your Cron and configure it to be ran each time after the logs were parsed. Alternatively you may just disable "Erase parsed entries from server log" and clear the logs from time to time by using the log file maintenance (see admin panel) or a special command of your web server software.

Should just restarting the web server software not show the desired result, then you may need to contact your webhoster and ask them about a shell script inserted into your Cron file: Copy locked log file to an unlocked one, delete locked log file, instruct the server to re-load configuration and re-open log file, let MagicStatistics process the (copied) unlocked log file.
 

Before you contact our customer service department, please read this manual first. In most cases you find the answer here. However if you still experience problems, we will be more than happy to help you...

For all support inquiries, please contact support@sunnyscript.com and provide the following information:

* The license number of the concerned product.
* A close description of the problem or question you have (no file attachments, please).
* For technical inquiries: Used server environment, URL of admin panel & admin password.