{=
  include("docs.util");
  start_docs_page(docs.technical_manual.page_titles.installation);
=}

<h3>Web Server Mode or CGI Mode?</h3>

<p>Before you install $PRODUCT_NAME you will need to decide which mode you want to run it in. $PRODUCT_NAME will run as a stand-alone in web server mode  
or in CGI mode.  If you plan to run $PRODUCT_NAME in web server mode, please see the section below 
called <b>Web Server Mode Installation</b>.  If you plan to 
run it as a CGI program, under an existing web server, please see the section 
below, called <b>CGI Mode Installation</b>.  If you don't know which way you want to install it, 
this section will help you with that decision.</p> 

 

<p>In web server mode, $PRODUCT_NAME runs its own web server, and 
serves statistics using it.  In CGI mode, $PRODUCT_NAME runs as a CGI program under another web server. 
In both modes, you access $PRODUCT_NAME through a web browser on your desktop.</p>

<p>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 $PRODUCT_NAME on a shared web server system,
or a system where you have limited access.</p>

<p>Here are the specific details of the advantages and disadvantages of web server mode vs. CGI mode:</p>
<p>The advantages of Web Server Mode:</p>
<ul> 
  <li> <p>$PRODUCT_NAME 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.</p>
  <li> <p>$PRODUCT_NAME is <i>extremely</i> 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.</p> 
  <li> <p>The $PRODUCT_NAME 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.</p>
</ul> 
<p>Advantages of CGI mode:</p> 
<ul> 
  <li> <p>$PRODUCT_NAME only uses memory and other resources while it's actively in 
       use in CGI mode.  In web server mode, $PRODUCT_NAME uses memory even 
       when it isn't being actively used.</p> 
  <li> <p>At system boot time there is no extra configuration required to start $PRODUCT_NAME  -- it is always available.</p>
  <li> <p>In CGI mode, $PRODUCT_NAME 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 $(PRODUCT_NAME).</p>
  <li> <p>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 $PRODUCT_NAME 
       on the server, you <i>must</i> use CGI mode.</p> 
</ul>

<p>Please continue your installation with either 
<b>Web Server Mode Installation</b> or <b>CGI Mode Installation</b> 
depending upon your choice.</p>


<h3>Web Server Mode Installation</h3>
<p>$PRODUCT_NAME needs to be installed 
according to the platform you intend to run it on: </p>
<ul> 
  <li> <p><b>Windows</b>: $PRODUCT_NAME is a standard Windows installer.  Just 
       double-click the program to start the installer, and follow the 
       instructions.</p>
       <p>Once $PRODUCT_NAME 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.
       $PRODUCT_NAME runs as the SYSTEM user by default, which is the most secure
       approach, but restricts access to network shares or mapped drives.  See
       {=docs_faq_link('mappeddrivewithservice')=} for instructions for running $PRODUCT_NAME
       as a different user, to get access to that user's mapped drives and network privileges.
       </p>

  <li> <p><b>MacOS</b>: $PRODUCT_NAME is a disk image.  Mount the image,
       and drag the Sawmill folder to the Applications folder.
       Once $PRODUCT_NAME is installed, you can start using it by double-clicking the $PRODUCT_NAME 
       application icon (in the Applications/Sawmill folder).
       Once it's running, click Use $PRODUCT_NAME to start using it.</p> 

  <li> <p><b>UNIX</b>: $PRODUCT_NAME is a gzipped tar archive file. 
       You need to transfer that to the UNIX machine where you'll be running $PRODUCT_NAME, 
       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:</p>
       <pre>  gunzip -c ($(PRODUCT_EXECUTABLE_DOCS).tgz) | tar xf -</pre> 
       <p>You will need to change ($(PRODUCT_EXECUTABLE_DOCS).tgz) to match the name 
       of the file you have downloaded.</p> 
       <p>Once the archive is uncompressed and extracted, you can 
       run $PRODUCT_NAME by changing to the installation directory, and 
       typing the name of the executable file from the command line:</p> 
       <pre>  cd (installation-directory)
  ./$PRODUCT_EXECUTABLE_DOCS</pre> 
       <p>You may need to change the filename to match the actual version you downloaded. 
       $PRODUCT_NAME 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 $PRODUCT_NAME, copy the URL 
       printed by $PRODUCT_NAME in your window, and paste it into the URL field of your 
       web browser, and press return.  You should see $PRODUCT_NAME appear in your web browser window.</p>
       <p>Note: You can add a single ampersand (&) to the end of the command line that starts $PRODUCT_NAME, 
       to run $PRODUCT_NAME "in the background," which allows you to close your terminal window 
       without killing $(PRODUCT_NAME).  On some systems, you may also need to add <code>nohup</code> to the beginning 
       of the command line for this to work properly.</p>
</ul> 
<p>If you have any problems 
installing $PRODUCT_NAME in web server mode, please see the <b>Troubleshooting Web Server Mode</b> section.</p>


<h3>CGI Mode Installation</h3>

<p>To install $PRODUCT_NAME in CGI mode, you will need to extract the $PRODUCT_NAME program, 
and copy it to your web server's CGI directory.</p>

<p>IMPORTANT: There are different versions of $PRODUCT_NAME 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 $PRODUCT_NAME that matches your <b>server's</b> 
platform, <i>not</i> the version that matches your desktop computer.
For instance, if you're running Windows at home, and you install $PRODUCT_NAME 
on your ISP's web server, and the web server is running Linux, you need to install the 
Linux version of $PRODUCT_NAME 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".</p>

<p>Make sure you understand the previous paragraph!  And now download the correct version 
of $PRODUCT_NAME, the one that matches your <b><i>web server</b></i> platform.  Make sure you do
the FTP download in BINARY mode, or $PRODUCT_NAME will not work.</p>

<p>You install $PRODUCT_NAME in CGI mode differently depending on the type of your web server. 
See {=docs_chapter_link('webservers')=} if you need help finding your cgi-bin directory.</p>
<ul>
  <li> <p><b>UNIX or MacOS with SSH access</b>.  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:</p>
       <pre>  cp (installation-directory)/$PRODUCT_EXECUTABLE_DOCS (cgi-bin)/$(PRODUCT_EXECUTABLE_DOCS).cgi
  cp -r (installation-directory)/LogAnalysisInfo (cgi-bin)</pre>
       <p>You may need to change the name of $PRODUCT_EXECUTABLE_DOCS 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.</p>
       <p>You can access $PRODUCT_NAME now using the URL http://(yourserver)/cgi-bin/$(PRODUCT_EXECUTABLE_DOCS).cgi 
       replacing (yourserver) with the actual name of your server.  $PRODUCT_NAME should 
       appear in the web browser window.
       <p>Make the $PRODUCT_NAME 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:</p>
       <pre>  chown -R apache (PRODUCT_EXECUTABLE_DOCS).cgi LogAnalysisInfo</pre>
       <p>If you do not have root access, you may need to open up permissions completely to allow the root user to access this:</p>
       <pre>  chmod -R 777 (PRODUCT_EXECUTABLE_DOCS).cgi LogAnalysisInfo</pre>
<p>However, please note that using chmod 777 is <i>much</i> 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.</p>
       <p>For more information, see <b>Troubleshooting CGI Mode</b> below.</p>

  <li> <p><b>UNIX with only FTP access</b>.  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:</p>
       <ol>
         <li> <p>Download the file to your desktop system, 
              remember you need the version that matches your <b><i>server</b></i>, not the version that matches your 
              desktop system.  Download in BINARY mode.</p>
         <li> <p>Use a gunzipping and untarring utility on your desktop system to decompress 
              the file, <a href=http://www.winzip.com/>WinZip</a> on Windows, 
              <a href=http://www.aladdinsys.com/expander/>StuffIt Expander</a> on Mac,
              or gunzip/tar if your desktop is also UNIX.</p>
         <li> <p>Rename the $PRODUCT_EXECUTABLE_DOCS file to $(PRODUCT_EXECUTABLE_DOCS).cgi.</p>
         <li> <p>Upload $(PRODUCT_EXECUTABLE_DOCS).cgi to your server's cgi-bin directory.  Make sure you 
              use BINARY mode to do the transfer, otherwise it won't work.</p>
         <li> <p>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.</p>
         <li> <p>Make $(PRODUCT_EXECUTABLE_DOCS).cgi executable in your web server 
              using "chmod 555 $(PRODUCT_EXECUTABLE_DOCS).cgi" if you're using a command-line FTP program, or using your 
              FTP program's permission-setting feature otherwise.</p>
       </ol>
       <p>You can now access $PRODUCT_NAME using the URL http://(yourserver)/cgi-bin/$(PRODUCT_EXECUTABLE_DOCS).cgi 
       replacing (yourserver) with the actual name of your server.  $PRODUCT_NAME should 
       appear in the web browser window.
       For more information, see the section on <b>Troubleshooting CGI Mode</b> below.</p>

  <li> <p><b>Windows</b>.  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 <i>is</i> possible, but it's not as easy as on other platforms.  See
       {=docs_chapter_link('iiscgi')=} for more information on installing in CGI mode under IIS.<p>
       <p>You need to upload the $(PRODUCT_NAME).exe file and the LogAnalysisInfo folder
       to your server's cgi-bin directory (Windows may hide the .exe part of the filename, but 
       that <i>is</i> its actual full filename).  The easiest way to get this file and this folder is to install 
       the Windows version of $PRODUCT_NAME on a local Windows desktop machine, and then look in the $PRODUCT_NAME 
       installation directory (C:\Program Files\$PRODUCT_NAME\ by default); the $(PRODUCT_NAME).exe file and
       LogAnalysisInfo folder
       will be there.  If you don't have access to a Windows machine locally, please contact 
       <a href=mailto:$SUPPORT_EMAIL>$SUPPORT_EMAIL</a> and we will send you this file and folder.
       Make sure you do the upload in BINARY mode, or $PRODUCT_NAME will not work! 
       Once you've uploaded it to your cgi-bin directory, you can access it using 
       the URL http://(yourserver)/cgi-bin/$(PRODUCT_NAME).exe (replace yourserver with the name of 
       your domain).  $PRODUCT_NAME should appear in the web browser window.
       If it still doesn't work, see <b>Troubleshooting CGI Mode</b> below.</p>

</ul>


<h3>Troubleshooting Web Server Mode</h3>

<p>If $PRODUCT_NAME 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:</p>
<ol>
  <li> <p>Make sure you installed the version of $PRODUCT_NAME that matches the computer you're running $PRODUCT_NAME on
       (for instance, you can't run the Solaris version of $PRODUCT_NAME on Windows).
       If there were several choices available for your platform (e.g. Old and New, static and dynamic), 
       try all of them.</p>
  <li> <p>Make sure you downloaded $PRODUCT_NAME in BINARY mode.</p>
  <li> <p>In UNIX, make sure the $PRODUCT_NAME program is executable.</p>
  <li> <p>Contact <a href=mailto:$SUPPORT_EMAIL>$SUPPORT_EMAIL</a>.</p>
</ol>
<p>There are more troubleshooting suggestions in {=docs_chapter_link('troubleshooting')=}.</p>


<h3>Troubleshooting CGI Mode</h3>

<p>If $PRODUCT_NAME is not working in CGI mode (if you're not getting a page back 
when you enter the URL), try these suggestions:</p>
<ol>
  <li> <p>Make sure you installed the version of $PRODUCT_NAME 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.</p>
  <li> <p>Make sure you uploaded the $PRODUCT_NAME program in BINARY mode.</p>
  <li> <p>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.</p>
  <li> <p>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.</p>
  <li> <p>Contact <a href=mailto:$SUPPORT_EMAIL>$SUPPORT_EMAIL</a>.  If you're having trouble, 
       we will install $PRODUCT_NAME for you at no cost, even if it's just the trial version.</p>
</ol>
<p>There are more troubleshooting suggestions in {=docs_chapter_link('troubleshooting')=}.</p>

{= end_docs_page() =}