Web Server Mode or CGI Mode?
Before you install Sawmill you will need to decide which mode you want to run it in. Sawmill will run as a stand-alone in web server mode or in CGI mode. If you plan to run Sawmill in web server mode, please see the section below called Web Server Mode Installation. If you plan to run it as a CGI program, under an existing web server, please see the section below, called CGI Mode Installation. If you don't know which way you want to install it, this section will help you with that decision.
In web server mode, Sawmill runs its own web server, and serves statistics using it. In CGI mode, Sawmill runs as a CGI program under another web server. In both modes, you access Sawmill through a web browser on your desktop.
In brief, web server mode is ideal if you want installation to be as easy as possible. CGI mode is the better choice if you want to run Sawmill on a shared web server system, or a system where you have limited access.
Here are the specific details of the advantages and disadvantages of web server mode vs. CGI mode:
The advantages of Web Server Mode:
Sawmill uses its own web server in this mode-- there does not need to be an already existing web server on the computer where it is running.
Sawmill is extremely simple to install in web server mode. You just run it, point your browser at it, choose a password, and you're ready to start using it. In CGI mode, the installation and startup process is considerably more involved, though still fairly easy.
The Sawmill Scheduler is available in web server mode. In CGI mode, the Scheduler is not easily available; an external scheduler must be used to schedule database builds/updates/etc.
Advantages of CGI mode:
Sawmill only uses memory and other resources while it's actively in use in CGI mode. In web server mode, Sawmill uses memory even when it isn't being actively used.
At system boot time there is no extra configuration required to start Sawmill -- it is always available.
In CGI mode, Sawmill can use the services of the web server that's running it. This makes it possible to use HTTPS, server authentication, and other powerful server features with Sawmill.
In some environments, web server mode may not be possible or permissible, due to restrictions of the server, firewall limitations, and other considerations. For instance, if you have only FTP access to your web server, and you want to run Sawmill on the server, you must use CGI mode.
Please continue your installation with either Web Server Mode Installation or CGI Mode Installation depending upon your choice.
Web Server Mode Installation
Sawmill needs to be installed according to the platform you intend to run it on:
Windows: Sawmill is a standard Windows installer. Just double-click the program to start the installer, and follow the instructions.
Once Sawmill is installed, it will be running as a Windows service. You can access it at http://127.0.0.1:8988/ with a web browser. Sawmill runs as the SYSTEM user by default, which is the most secure approach, but restricts access to network shares or mapped drives. See Can't See Network Drives with Sawmill as Service for instructions for running Sawmill as a different user, to get access to that user's mapped drives and network privileges.
MacOS: Sawmill is a disk image. Mount the image, and drag the Sawmill folder to the Applications folder. Once Sawmill is installed, you can start using it by double-clicking the Sawmill application icon (in the Applications/Sawmill folder). Once it's running, click Use Sawmill to start using it.
UNIX: Sawmill is a gzipped tar archive file. You need to transfer that to the UNIX machine where you'll be running Sawmill, if it's not already there. Then you'll need to open a "shell" prompt using telnet, ssh, or the way you normally get to the UNIX command line. Next, gunzip and untar the file using the following command:
gunzip -c (sawmill.tgz) | tar xf -
You will need to change (sawmill.tgz) to match the name of the file you have downloaded.
Once the archive is uncompressed and extracted, you can run Sawmill by changing to the installation directory, and typing the name of the executable file from the command line:
cd (installation-directory) ./sawmill
You may need to change the filename to match the actual version you downloaded. Sawmill will start running, and it will start its own web server on the UNIX machine (using port 8988, so it won't conflict with any web server you may already be running there). To start using Sawmill, copy the URL printed by Sawmill in your window, and paste it into the URL field of your web browser, and press return. You should see Sawmill appear in your web browser window.
Note: You can add a single ampersand (&) to the end of the command line that starts Sawmill, to run Sawmill "in the background," which allows you to close your terminal window without killing Sawmill. On some systems, you may also need to add
nohupto the beginning of the command line for this to work properly.
If you have any problems installing Sawmill in web server mode, please see the Troubleshooting Web Server Mode section.
CGI Mode Installation
To install Sawmill in CGI mode, you will need to extract the Sawmill program, and copy it to your web server's CGI directory.
IMPORTANT: There are different versions of Sawmill for each platform (e.g. Windows, Macintosh, Linux, etc.), and a version designed for one platform will not work on another. In CGI mode, you must install the version of Sawmill that matches your server's platform, not the version that matches your desktop computer. For instance, if you're running Windows at home, and you install Sawmill on your ISP's web server, and the web server is running Linux, you need to install the Linux version of Sawmill on the web server, not the Windows version. If you don't know what platform your web server is running, you can find out by asking your ISP or system administrator, if it's a UNIX system, you can also find out by logging in by telnet and typing "uname -a".
Make sure you understand the previous paragraph! And now download the correct version of Sawmill, the one that matches your web server platform. Make sure you do the FTP download in BINARY mode, or Sawmill will not work.
You install Sawmill in CGI mode differently depending on the type of your web server. See Web Server Information if you need help finding your cgi-bin directory.
UNIX or MacOS with SSH access. If your server is UNIX or similar, and you have SSH access to your server, then download the file to your server and gunzip/untar it according to the instructions above (in the web server mode installation section). Then copy the executable file and LogAnalysisInfo directory from the installation directory to your cgi-bin directory, using this command:
cp (installation-directory)/sawmill (cgi-bin)/sawmill.cgi cp -r (installation-directory)/LogAnalysisInfo (cgi-bin)
You may need to change the name of sawmill to match the version you downloaded, and you will definitely need to change the (cgi-bin) part to match your web server's cgi-bin directory.
You can access Sawmill now using the URL http://(yourserver)/cgi-bin/sawmill.cgi replacing (yourserver) with the actual name of your server. Sawmill should appear in the web browser window.
Make the Sawmill executable file and LogAnalysisInfo directory accessible by the CGI user. The CGI user depends on the configuration of the web server, but it is often a user like "web" or "apache" or "www". If you have root access you can use this command, after cd'ing to the cgi-bin directory, to change ownership of the files:
chown -R apache (PRODUCT_EXECUTABLE_DOCS).cgi LogAnalysisInfo
If you do not have root access, you may need to open up permissions completely to allow the root user to access this:
chmod -R 777 (PRODUCT_EXECUTABLE_DOCS).cgi LogAnalysisInfo
However, please note that using chmod 777 is much less secure than using chown--anyone logged on to the server will be able to see or edit your Sawmill installation, so in a shared server environment, this is generally not safe. If possible, use chown as root instead.
For more information, see Troubleshooting CGI Mode below.
UNIX with only FTP access. If you have a UNIX server, and you have only FTP access to your server (you cannot log in and run commands by ssh, or in some other way), then you need to do things a bit differently. Here's how you do it:
Download the file to your desktop system, remember you need the version that matches your server, not the version that matches your desktop system. Download in BINARY mode.
Rename the sawmill file to sawmill.cgi.
Upload sawmill.cgi to your server's cgi-bin directory. Make sure you use BINARY mode to do the transfer, otherwise it won't work.
Upload the entire LogAnalysisInfo directory including all the files and directories in it, to your server's cgi-bin directory. In order to do this conveniently, you will need to use an FTP client which supports recursive uploads of directories, including all subdirectories and files. Make sure you use BINARY mode to do the transfer, or it won't work.
Make sawmill.cgi executable in your web server using "chmod 555 sawmill.cgi" if you're using a command-line FTP program, or using your FTP program's permission-setting feature otherwise.
You can now access Sawmill using the URL http://(yourserver)/cgi-bin/sawmill.cgi replacing (yourserver) with the actual name of your server. Sawmill should appear in the web browser window. For more information, see the section on Troubleshooting CGI Mode below.
Windows. If the web server is IIS, this is a difficult installation due to the security features of IIS, which make it difficult to run a binary CGI program -- consider using web server mode instead. If you need CGI mode, then it is possible, but it's not as easy as on other platforms. See Installing Sawmill as a CGI Program Under IIS for more information on installing in CGI mode under IIS.
You need to upload the Sawmill.exe file and the LogAnalysisInfo folder to your server's cgi-bin directory (Windows may hide the .exe part of the filename, but that is its actual full filename). The easiest way to get this file and this folder is to install the Windows version of Sawmill on a local Windows desktop machine, and then look in the Sawmill installation directory (C:\Program Files$PRODUCT_NAME\ by default); the Sawmill.exe file and LogAnalysisInfo folder will be there. If you don't have access to a Windows machine locally, please contact firstname.lastname@example.org and we will send you this file and folder. Make sure you do the upload in BINARY mode, or Sawmill will not work! Once you've uploaded it to your cgi-bin directory, you can access it using the URL http://(yourserver)/cgi-bin/Sawmill.exe (replace yourserver with the name of your domain). Sawmill should appear in the web browser window. If it still doesn't work, see Troubleshooting CGI Mode below.
Troubleshooting Web Server Mode
If Sawmill is not working in web server mode (if you're not getting a page back when you enter the URL, or if you're getting an error page), try these suggestions:
Make sure you installed the version of Sawmill that matches the computer you're running Sawmill on (for instance, you can't run the Solaris version of Sawmill on Windows). If there were several choices available for your platform (e.g. Old and New, static and dynamic), try all of them.
Make sure you downloaded Sawmill in BINARY mode.
In UNIX, make sure the Sawmill program is executable.
There are more troubleshooting suggestions in Troubleshooting.
Troubleshooting CGI Mode
If Sawmill is not working in CGI mode (if you're not getting a page back when you enter the URL), try these suggestions:
Make sure you installed the version of Sawmill that matches your server, not your desktop system. If there were several choices available for your platform (e.g. Old and New, static and dynamic), try all of them.
Make sure you uploaded the Sawmill program in BINARY mode.
On UNIX, make your cgi-bin directory writable, using "chmod a+w (cgi-bin)" if you have telnet access, or using your FTP client's "change permissions" feature if you have only FTP access.
Create a directory called LogAnalysisInfo in your cgi-bin directory, using "mkdir (cgi-bin)/LogAnalysisInfo" on UNIX with telnet access, or by using your FTP client's "make directory" feature if you don't have telnet access. If your server is UNIX, also make it writable using "chmod -R a+rwx (cgi-bin)/LogAnalysisInfo" if you have telnet access, or by using your FTP client's "change permissions" feature if you have only FTP access.
Contact email@example.com. If you're having trouble, we will install Sawmill for you at no cost, even if it's just the trial version.
There are more troubleshooting suggestions in Troubleshooting.