MagicStats 2.0 Quick Install Guide

Abstract:

This document gives a quick explanation of how to get MagicStats 2.0 set up and running. Full details of configuration can be found in the User Guide.
  1. Installation Overview:
  2. Compiling MagicStats:
  3. Using Precompiled Binaries:
  4. Installing MagicStats as root:
  5. Installing MagicStats as a normal user:
  6. Installing MagicStats on Windows:
  7. Configuring MagicStats:
  8. Final Steps for Unix:
  9. Final Steps for Win32:
  10. Conclusion:

Installation Overview:

Installing MagicStats is simply a matter of getting the right files in the right places, then configuring the system to find them. This document describes how to go from the source distribution to a working setup on both windows (in progress) and unix platforms.

If you chose to download a precompiled distribution of MagicStats, you can jump ahead to Using Precompiled Binaries.

If you already has MagicStats files installed on your computer, go ahead and skip ahead to "Configuring MagicStats"...

Compiling MagicStats:

Compiling MagicStats shouldn't be too hard if you're using a supported platform (and adding them isn't that tough either, just create a new Makefile.common for your platform). On a unix platform, do this:

prompt> gunzip MagicStats2-pre8.tar.gz
prompt> tar xvf MagicStats2-pre8.tar
... lots of info about file extraction...
prompt> make
Lots of stuff should go by, and in then end, you should get a new "Install" directory tree. This directory tree is what you get when you download the precompiled binaries, and is all you need to run MagicStats.

To compile MagicStats under Win32, open up MagicStats.dsw in Visual Studio (6.0 is tested, good luck with anything else! :). Compile the "All" project. You should now get a "Install" directory as mentioned before.

Note that although MagicStats has been built in several different configurations with several different C++ compilers, g++ is the most well tested compiler. Any fairly recent variant should work fine (if it doesn't, let me know!).

Now that MagicStats has been built, skip ahead to the section that applys to you:

Using Precompiled Binaries:

If you chose to use precompiled binaries for your platform, then much of the work is done for you... if there isn't a set of precompiled binaries for your platform, then you can Compile a set and then contribute them back so that others can use them.

To use a set of precompiled binaries, uncompress them (using gunzip and tar on unix, or unzip them on windows), then jump head to:

  • Installing as root...
  • Installing MagicStats as a normal user...
  • Installing MagicStats on Windows...

    Installing MagicStats as root:

    "Installing MagicStats as root" does not imply that MagicStats will run as root, just that files live in root's filespace. Specifically, by default, files are installed in /var/lib/MagicStats. If you want files installed here, just do this after compilation:

    prompt> su
(enter password here)
prompt> make install
    This performs the following steps (which you have to do manually if you have a pre-compiled tarball):

    1. Copies Install/MagicStats to /usr/local/bin
    2. Copies Install/Plugins to /var/lib/MagicStats/Plugins
    3. Copies Install/Plugins_g to /var/lib/MagicStats/Plugins_g (which are debug versions of the plugins)
    4. Copies Install/Themes to /var/lib/MagicStats/Themes
    5. Copies Install/Docs to /usr/doc/MagicStats/
    6. Makes a symlink from /usr/doc/magicstats to /usr/doc/MagicStats
    After doing this, you will need to make a symlink from your httpd namespace into the MagicStats directory (so that web browsers can find theme files like graphics and java applets). So, do something like this (to make MagicStats files visible as /MagicStats on your webserver):

    prompt> cd /home/httpd/html
prompt> ln -s /var/lib/MagicStats MagicStats
    Note that this just puts files into a convenient place for all of your users to access. This does not modify the system at all, or cause things to automatically get run. MagicStats does not run as root (unless root wants statistics, and manually sets it up).

    Important things to note with this setup:

    1. BINARY_PATH = /usr/local/bin/MagicStats
    2. RESOURCES_PATH = /var/lib/MagicStats/
    3. RESOURCES_URL = /MagicStats/
    Now skip ahead to "    Configuring MagicStats".

    Installing MagicStats as a Normal User:

    If you don't have root access on a system that you would like to gather statistics from (ie it hosts your web page), then you can still run MagicStats (as long as you have permissions to read the web server log files that is). Just aquire an Install directory (either by compiling one yourself or downloading precompiled binaries), and follow these steps:

    1. Pick a permanent directory for the MagicStats files to live in.
      I keep my custom programs in a ~/local directory, so for this example, I'll assume that the files are installed into ~/local/MagicStats. You can pick anything that works for you...
    2. Create the directory to install it in:
      prompt> mkdir ~/local/MagicStats
    3. Copy all of the install files into that directory (preserving subdirectories):
      prompt> cp -r Install/* ~/local/MagicStats
    4. Make a symlink from your webpage to the MagicStats directory, so that Theme files are accessable to a web browser:
      prompt> cd ~/public_html
      prompt> ls -s ~/local/MagicStats MagicStats
    ...and that is all there is to it! Important things to note with this setup:

    1. BINARY_PATH = ~/local/MagicStats/MagicStats
    2. RESOURCES_PATH = ~/local/MagicStats/
    3. RESOURCES_URL = /~{username}/MagicStats/
    Now skip ahead to "Configuring MagicStats".

    Installing MagicStats on Windows:

    TODO. It's pretty much the same as above, just put it in Program Files or something.

    Anyone want to contribute a writeup of this? I don't have an NT box with a webserver on it...

    Now skip ahead to "Configuring MagicStats".

    Configuring MagicStats:

    Okay, if you got this far, then things are compiled, and they are installed someplace. You should now know the values for BINARY_PATH, RESOURCES_PATH, and RESOURCES_URL depending on how you set up your system.

    The first step to do is decide what statistics you want to monitor, and where the log file for the web server is. (common log file locations are: /usr/local/httpd/logs/access_log, /var/log/httpd/access_log, and /var/lib/httpd/logs/access_log. Call this LOG_PATH). Perform these steps:

    1. Log into the computer as a user account.
    2. Create a web accessable directory to store your statistics in:
      prompt> mkdir ~/public_html/stats
    3. Create a ~/.MagicStats directory to hold your configuration file:
      prompt> mkdir ~/.MagicStats
    4. Create your MagicStats.cfg file in your ~/.MagicStats directory (this directory may be overridden by giving a command line option to MagicStats):
      prompt> vi ~/.MagicStats/MagicStats.cfg
    Okay, so what goes in that MagicStats.cfg file? Heres an example that should get you started quickly:

    #=======================================================================#
#                              MagicStats.cfg                           #
#=======================================================================#
#------------------------------------------------------------------------
[Global]
#------=
Access Log             : "LOG_PATH";
# Only change this if you don't have a ~/.MagicStats directory...
#Data Filename         : "~/.MagicStats/MagicStats.dat";
# Tell MagicStats where to find plugins and themes...
#
Resources               : [[RESOURCES_PATH, RESOURCES_URL]];
# Tell MagicStats how to filter your accesses... this is described in
# detail in the User Guide.
#
Filters                 : [ ["UnEscapeURL" ],
                            ["RemoveIndexFilename", "index.html",
                                                    "index.shtml",
                                                    "index.htm",
                                                    "index.cgi",
                                                    "/"]
                          ];
#----------------------------------------------------------------------------
[[Fancy]]
#-------=
#
# Start of a theme section... duplicate this once for every set of pages you 
# would like to monitor...
#
# Define some filters... SectionFilter specifies what hits you want to 
# look at... here just stuff that falls on your webpage...
#
$SectionFilter          : ["/~{user-name}*", ""];
# PageFilter specifies what you want to be considered as a "page", as in 
# not graphic or other thing.  This list is stuff to filter out...
#
$PageFilter             : ($SectionFilter) + "*.GIF;*.JPG;*.gif;*.jpg;*.class";
# Set this to something personal...
$PageName               : "Chris's Web Creations";
$OutputPrefix           : "Stats";
# Set PathPrefix to be the directory you want stats files to go into:
#
$PathPrefix             : "~/public_html/stats/";
# These symlinks are links to "current" pages...
#
$DailyLink              : ($PathPrefix) + "index.html";
$MonthlyLink            : ($PathPrefix) + "Monthly.html";
#=======================================================================#
#                            END MagicStats.cfg                         #
#=======================================================================#
    Okay now, once you have that set up, you are ready to try everything out. If the MagicStats binary is in your path, try typing this at the command line (which runs MagicStats in "verbose" mode, and asks it to processes at most 100 accesses):

    prompt> MagicStats2 -v -N 100
MagicStats v2.0pr8...   By: Chris Lattner (sabre@nondot.org)
Loaded plugin: PPErrors
Loaded plugin: FSGZipped
Loaded plugin: AFRewrite
Loaded plugin: PPBreakdown
Loaded plugin: TestPlugin
Loaded plugin: AFDomainify
  Creating all html pages for: 10/15/2000........
Processed 100 accesses in 0.0 seconds: 980.0 Accesses/Second
  Parsed 100 accesses from /var/log/httpd/access_log
prompt>
    If you get something similar to this, then congratulations, it works (try looking in the directory you told it to put stats into with your web browser (for example http://www.nondot.org/~sabre/stats)! Now go to either "Final Steps for Unix" or "Final Steps for Win32"...

    If you feel like poking around a little bit, try typing "MagicStats -T -P" to get a list of themes and plugins that are available...

    Final Steps for Unix:

    The last thing you need to do for unix is make MagicStats run periodically. The best way to do this is to use a utility called "cron" (look at the manpages for more info). I like to have MagicStats run every half hour, so my crontab looks like this:

    # CRONTAB
5,35 * * * * /usr/local/bin/MagicStats2 -N 4000
# END CRONTAB
    Which says to to run at 5 and 35 minutes past the hour, and to only processes a maximum of 4000 hits at a time. This can obviously be tweaked. If you want to add something similar to this to your crontab, try doing something like this:

    prompt> crontab -l > cron
prompt> echo '3,35 * * * * BINARY_PATH -N 4000' >> cron
prompt> crontab cron
prompt> rm cron
prompt>
    and you are all set to go! Go to     the conclusion.

    Final Steps for Windows NT:

    The last thing you need to do for Windows is make MagicStats run periodically. The best way to do this is to use an NT utility called "at" (look in help for more info). I like to have MagicStats run every half hour, so I use:

    prompt> at /every:M,T,W,Th,F,S,Su BINARY_PATH -N 4000
    Which says to to run at 5 and 35 minutes past the hour, and to only processes a maximum of 4000 hits at a time. This can obviously be tweaked. Now you're all ready to go! (Thanks to James Beam for helping me with this information!)

    Conclusion:

    This document explains how to get MagicStats going in a pretty short amount of time. If you would like to customize MagicStats more, try looking at the User Guide for more configuration info, or the Architecture Guide for information about the internals. If you have any problems getting MagicStats set up, let me know so that I can improve this document and solve your problem!

    -Chris

    • Copyright © 2000 Chris Lattner