Setting up Multiple Users (ISP Setup)

One of the most common ways of using Sawmill is to publish statistics for many sites to the users who own them. This is the standard mode of operation for an ISP -- you want to provide all of your customers with statistics, with each customer seeing only statistics for their own site, and no other sites. Non-ISP users of Sawmill may also need a similar setup, to provide statistics for different sites, or sections of the same site, to several different people. Sawmill makes this easy.

In a nutshell, what you'll do is create a profile for each user (possibly using the Create/Update Many Profiles feature). Then in the Users Editor, you create a separate user for each user who will access statistics, and set it up so that user can access only those profiles (often, just one profile) that belongs to them. You'll set up each profile to process only the relevant log data (that user's log data). Finally, you'll deliver the statistics to the users as a URL, pointing to an active copy of Sawmill, and they'll use a browser to view their statistics.

Creating the First Profile

The first thing you'll need to do is create a profile for each user. Start by creating one profile and setting it up the way you like. From the profiles list, click Create New Profile, and follow the instructions to create the profile. For an ISP, you may want to use the domain name as the profile name. In this example, we'll assume that you're an ISP setting up a site for mysite.com, so you'll name the profile mysite.com.

If each user has separate log files, point this profile's Log Source to the appropriate log files. Otherwise, point the Log Source at the combined log data; you can skip over all the information about filters below.

If all the users' log data is combined into a single file, you'll need to create a log filter to separate out the hits for just this user. For instance, if you're logging 100 web sites to a single file, then you'll need to create a log filter to reject all hits except those from mysite.com. Exactly how this is done depends on how your server indicates which site each hit was on, but usually it's logged in a "server domain" field. The filter in that case is:

if (!ends_with(server_domain, "mysite.com")) then "reject"

If your server logs the server domain information as part of the page field instead, you can use a similar filter:

if (!starts_with(page, "/mysite.com/")) then "reject"

For more information about log filters, see Using Log Filters.

If your server logs each domain to a separate log file, then you're in luck-- you don't need to do anything with filters. Just point your profile to the proper log files. In addition to being simpler to set up, this is also more efficient, because Sawmill will only have to read each log file once. Because of these advantages, it may be worth reconfiguring your web server to log each domain to a separate location.

At this point, you've done the most important steps in creating the first profile. All your other profiles will be based on this one, so if you have some options that you know you're going to use in every profile (for instance, a custom header or footer), you can set them now. You'll also be able to change options later, if you want.

Creating the Rest of the Profiles

Now you need to set up the Create/Update Many Profiles feature to automatically create all the rest of your profiles. Start by editing the file create_many_profiles.cfg in the miscellaneous directory of the LogAnalysisInfo directory. In this file you can specify the names and labels of each profile you wish to create, the name of the profile which should be duplicated to create them (the template you created above), and any other options you want to differ from the rest of the profiles. For instance, it is common for each profile to have its own log source, so you might override log.source.0.pathname to pull log data from a different pathname. Or you might override a particular log filter to filter the data differently for this profile. Any profile option can be overridden in the "changes" group of the profile group in the create_many_profiles.cfg file.

When you're done setting up the create_many_profiles.cfg file, you can create all the profiles in a single step with the following command line:

  sawmill -dp util.create_many_profiles

and the following command line (Windows):

  Sawmill.exe -dp util.create_many_profiles

This will create all the profiles you've specified, and apply the changes you indicated to them, and save them to the profiles list.

In the future, if you want to make a change to affect all profiles, Modify the template profile, and rerun the command above to recreate the profiles.

Sending the Statistics to your Users

There are many ways of sending statistics to your users, but the main one is to send them a URL pointing to an active installation of Sawmill. The URL will allow them to view their statistics, but will not allow them to do anything else--they will not have access to other profiles, or to the administrative menu. For instance, if the profile name is mysite.com and Sawmill is running in CGI mode on the server stats.isp.com, then you can send your user the following URL:

http://stats.isp.com/cgi-bin/sawmill.cgi?dp=reports&p=mysite_com

In web server mode, the URL would be

http://stats.isp.com:8988/?dp=reports&p=mysite_com

There are also ways to let them select their profile from a list; see Security for complete details.

You can also send any view by email to your users. The single-page summary view is a good choice, but you can send any view, or create your own. The view will be sent as HTML with embedded images, viewable in any modern graphical mail client, and it can contain links to a live version of Sawmill if you wish. You can set Sawmill to send views regularly using the Scheduler (see Using the Sawmill Scheduler).

Sawmill can also generate "static" HTML pages, which can then be uploaded to a web server, to provide statistics without a running copy of Sawmill. However, these pages are much less powerful than Sawmill's normal dynamic statistics, take up more space, and require an extra upload step, so it is usually a better idea to use the dynamic statistics. If you need static statistics, you can profile Sawmill to generate them regularly using the Scheduler.

Keeping the Statistics Up to Date

Sawmill will keep the databases up to date even if you never explicitly set it up. If someone views the statistics when the database hasn't been built yet, Sawmill builds it; if they view the statistics when the database hasn't been updated for more than a day, Sawmill updates it. But there are some advantages to updating the databases manually. Most importantly, the build/update step can take a long time, especially for large sites, and that delay may not be acceptable every time a user wants to see their statistics. You can eliminate the delay by updating the database regularly (usually once daily, in the middle of the night) so that the statistics are never more than a day old. You can do this with the Scheduler (see Using the Sawmill Scheduler); Sawmill can be configured to automatically update all databases every night. The Scheduler only works in web server mode, though; if you're using Sawmill in CGI mode (often a good choice for multi-user environments), you'll need to use an external scheduler like cron or Windows Scheduler to do the updates. You can update a database from the command line (or a scheduler) using a command line this:

  sawmill -p config-name -a ud

Or you can set up the schedules in the Sawmill Scheduler, and call Sawmill like this every minute to run any necessary schedules:

  sawmill -scheduler

Or you can leave a copy of Sawmill running in web server mode as well, just to handle the schedules.

Maintaining the Profile

Once you've set up the multi-user environment, it will run without any maintenance on your part. However, if you want to change something about the profiles (change the header, add a new report, add new cross-references, etc.), you'll need to regenerate your profiles. The easiest way to do this is to continue to treat one of your profiles as a "template" profile -- make all your changes to that profile, and never change any other profile directly. Then, you'll only have to make each change once, to the template. Once your template is working the way you like, you can go back to the Create/Update Many Profiles field, paste in the profiles list you saved from the first time you used it, and click the button to recreate all the profiles from the template. Create/Update Many Profiles does not change or delete the databases for the profiles; it only changes the profile options. So you can safely Create/Update Many Profiles to create profiles even if the databases exist; the data will not be lost.