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

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

<h4>Installation Modes</h4>

<p>$PRODUCT_NAME can run either in web server mode (stand-alone) or in CGI mode. In both modes, you can access $PRODUCT_NAME through a web browser on your desktop.</p>

<p>This section will help you decide whether you want to run $PRODUCT_NAME in "web server mode," or in "CGI mode." In web server mode the installation is easy, $PRODUCT_NAME runs its own web server,  and serves statistics using it. CGI mode is better if you want to run $PRODUCT_NAME on a shared web server system, or a system you have only limited access to.</p>

<p>Here are the advantages and disadvantages of web server mode vs. CGI mode:</p>
<b>Advantages of Web Server Mode:</b>
<ul> 
  <li> $PRODUCT_NAME uses its own web server -- there does not need to be an existing web server on the computer where it is running.</li>
  <li> $PRODUCT_NAME 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. </li>
  <li> $PRODUCT_NAME Scheduler is available.</li>
</ul> </p>
<b>Disadvantages of the Web Server Mode:</b>
<ul>  
<li>Memory is being used, even when $PRODUCT_NAME isn’t being used.
<li>Server features, like HTTPS, authentication and other features can not be used in this mode.
<li>May not be possible to use because of firewall limitations and other restrictions.
</ul>

<b>Advantages of CGI Mode:</b>
<ul>
<li>In CGI mode, $PRODUCT_NAME only uses memory and other resources while it's actively in use. 
<li>There is no extra configuration required to start $PRODUCT_NAME at system boot time -- it is always available.
<li>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.
<li>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.
</ul>
<b> Disadvantages of CGI Mode:</b>
<ul>
<li>In CGI mode, the installation and startup process is more involved, although fairly easy.
<li>The $PRODUCT_NAME Scheduler is not easily available, an external scheduler must be used to schedule builds/updates/etc.
</ul>
<b>The two different installations are described below:</b>

<p><h3><b>Web Server Mode Installation</h3></b>
<p>$PRODUCT_NAME needs to be installed differently depending on 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:8987/ 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 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 8987, 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 <b>Troubleshooting Web Server Mode</b> </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.
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>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)CL.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)CL.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)CL.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>

<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 to 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></p>

<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() =}