================================================================================
                  MxRemotePreview Installation Instructions
================================================================================


--------------------------------------------------------------------------------
   Document Info
--------------------------------------------------------------------------------

   Publisher:                  MOBOTIX AG

   Authors:                    Bernd Wilhelm
                               Thilo Schüller

   Date:                       2010-03-26

   Confidentiality:            public
--------------------------------------------------------------------------------


Contents
--------

(0) Introduction
(1) System Requirements
(2) Installation Basics
(3) Installation on Apache Web Server
(4) Installation on Microsoft Internet Information Server 7
(5) Testing the Web Server Installation
(6) Testing the CGI
(7) Notes on Security



================================================================================
(0)   Introduction
================================================================================

"MxRemotePreview" is a software component to improve the MxControlCenter's
direct access to file servers via low bandwidth connections - e.g. via the
Internet and a VPN tunnel. It is installed as a CGI program within a web
server environment.

MxControlCenter then does not retrieve the original stored audio/video data
directly from the file server but sends a data request to the web server, which
in turn calls MxRemotePreview for certain file types.

MxRemotePreview reads the original large data files, REDUCES them by recoding
the video content with a reduced frame rate, resolution and/or JPEG quality and
delivers only the reduced data back to MxControlCenter.

=> Instead of the original large audio/video data files, only the reduced, much
smaller ones have to be transmitted via the network. MxControlCenter thus gets
the requested files fast enough to build up its event list and to play back the
audio/video data.

To use MxRemotePreview, you need a Windows web server with Apache or IIS
installed. The recordings can be stored on the same server (i.e. the cameras are
using this server as a file server) or on a different server/NAS system. If two
different servers are used, the MxRemotePreview web server needs a fast access
(high bandwidth) to the file server/NAS system with the camera recordings.

If you need MxRemotePreview to run on a different operating system, please send
an e-mail to software-feedback@mobotix.com, describing the desired operating
system.



================================================================================
(1)   System Requirements
================================================================================

* The processor speed should be higher than 1 GHz.
* This version requires Windows XP SP3 or higher.



================================================================================
(2)   Installation Basics
================================================================================

The basic idea behind all installation variants is:

(a) Install the CGI in the server's standard way to install CGIs.

(b) Specify to call the CGI for either all JPEG files or just certain ones.
    You can use "[MEAPC][0-9]+\.jpg$" as a regular expression.
    Don't call the CGI for any other file type.

(c) Set the document root to the path of the recordings. Make this root
    available as "http://<server name>/".

(d) Optionally pass default recoding parameters using the following
    environment variables:

    MXRECODER_FRAMERATE - desired frame rate (default: 1 frame per second)
    MXRECODER_WIDTH     - image size, aspect ration will be kept
    MXRECODER_HEIGHT    - image resolution will stay inside these values
    MXRECODER_QUALITY   - desired JPEG quality in percent
    MXRECODER_AUDIO     - enable (1) or disable (0) audio, saving 64 kbit/s



================================================================================
(3)   Installation on Apache Web Server
================================================================================

(3a)   Install Apache Web Server
--------------------------------------------------------------------------------

If you don't have a web server running already, do this:

 * Run installer apache_xxx-win32-xxx.msi.
 * Follow the instructions.
 * Install Apache as a Windows service, listening to port 80 (default).
   (Note: you can use a different port than 80 - just remember to enter/change
   that port in your MxControlCenter configuration.)


(3b)   Install MxRemotePreview.cgi
--------------------------------------------------------------------------------

 * Copy MxRemotePreview.cgi.exe to the Apache installation folder:
     C:/Program Files/Apache.../cgi-bin


(3c)   Configure Apache
--------------------------------------------------------------------------------

 * Copy configuration file httpd.conf to the Apache installation folder:
     C:/Program Files/Apache.../conf

 * Open httpd.conf and edit the following lines:

   DocumentRoot                 "C:/<folder with camera recordings>"

   ScriptAlias  /cgi-bin/       "C:/<apache installation folder>/cgi-bin/"
   Action       mxremotepreview /cgi-bin/MxRemotePreview.cgi.exe

   <Directory "C:/<folder with camera recordings>">
      <FilesMatch [MEAPC][0-9]+\.jpg$>
         SetHandler mxremotepreview
      </FilesMatch>
   </Directory>

 * Add desired default MxRemotePreview settings
   (Note: These will usually be overridden by MxCC)

    # desired frame rate (default: 1 frame per second)
    SetEnv MXRECODER_FRAMERATE   1

    # image size, aspect ration will be kept
    SetEnv MXRECODER_WIDTH     320
    SetEnv MXRECODER_HEIGHT    240

    # JPEG quality [1..100]
    SetEnv MXRECODER_QUALITY    40

    # enabled audio output, 0 to disable
    SetEnv MXRECODER_AUDIO       1


 * Other Apache configuration settings may be edited as necessary.
      See http://httpd.apache.org/docs/2.2/

 * Restart the Apache service



================================================================================
(4)   Installation on Microsoft Internet Information Server 7
================================================================================


(4a)   Install IIS
--------------------------------------------------------------------------------

 * Open Server Manager and select "Add roles".

 * Select "Web Server (IIS)" from the list and continue to press the "Next"
   button until the "Role services" selection window is reached.

 * When the "Role services" selection is presented, in addition to what is
   already selected,
     (1) select "CGI" under "Application Development".
     (2) ensure that the "IIS Management Console" is also selected (on Windows
         7 it is not, but on Windows Server 2008 it is).
   Continue to press the "Next" button until you complete the installation.

 * Open a web browser and enter "http://localhost" to verify that the web server
   is running.


(4b)   Install MxRemotePreview.cgi
--------------------------------------------------------------------------------

* Create a folder named cgi-bin in C:\inetpub
* Copy the MxRemotePreview.cgi.exe to that folder.


(4c)   Configure IIS
--------------------------------------------------------------------------------

 * Open "Control Panel", "Administrative Tools" and double-click on "Internet
   Information Services (IIS) Manager"

 * Navigate in the "Connections" pane to the "Default Web Site" and click on it
   to select it.

 * Click on "Advanced Settings..." in the right pane.

 * When the "Advanced Settings" dialog opens, change the "Physical Path" to the
   shared folder where the cameras are storing their recordings and click on
   the "OK" button.

 * Double-click on the "Directory Browsing" icon in the center pane. When it
   opens, click on "Enable" under "Actions" in the right pane.

 * Click again on the "Default Web Site" in the "Connections" pane.

 * Double-click on the "Handler Mappings" icon in the center pane. When it
   opens, click on "Add Module Mapping..." under "Actions" in the right pane.

 * When the "Add Module Mapping" dialog opens in the center pane, enter these
   values in the following fields:
     - Request path: *.jpg
     - Module: CgiModule
     - Executable (optional): C:\inetpub\cgi-bin\MxRemotePreview.cgi.exe
     - Name: MxRemotePreview service
   Then click on the "OK" button.

 * When the "Add Module Mapping" dialog asks you "Do you want to allow this
   ISAPI extension?", click on the "Yes" button.

 * Right-click on "Default Web Site" in the "Connections" pane and select
   "Add Virtual Directory".

 * When the "Add Virtual Directory" dialog opens, enter these values in the
   following fields:
      - Physical Path: <folder with camera recordings>
        (the physical path can also point to a share on a different computer/NAS
        if this share has been mapped as a network drive on the local computer).
   Then click on the "OK" button.

 * Click on the name of the server in the "Connections" pane.

 * Double-click on the "MIME Types" icon in the center pane and when it opens,
   click on "Add..." under "Actions" in the right pane.

   Note: although you can perform exactly the same operation in the "Default
   Web Site", loading the following address produces an http error 500.19:
   http://<server name>/<camera-ip>/.erdinfo

   Hence, the MIME Type for the ".erdinfo" file has to be defined globally (for
   the whole web server, see below).

 * When the "Add MIME Type" dialog opens, enter these values in the following
   fields:
    - File name extension: erdinfo
    - MIME Type: application/octet-stream
   Then click on the "OK" button.



================================================================================
(5)   Testing the Web Server Installation
================================================================================

 * Open a web browser

 * Navigate to "http://127.0.0.1/";
   the web page should list available file server folders for each camera

 * Navigate into a file server folder and note how .jpg files are displayed.

 * Change the URL by adding "?previewsize=320x240&quality=20". If you see
   the image changing accordingly, you have everything set up correctly and
   the CGI is also working.



================================================================================
(6) Testing the CGI
================================================================================

You can test the CGI via the web server. The parameters for recoding are
specified in the URL:

 * previewsize=<h>x<v>  : maximum dimension in pixels ("320x240" = 320px
                          horizontally x 240px vertically)
 * framerate=<fps>      : frames per second, can be decimal, e.g. 1.5
 * quality=<percent>    : quality to use for JPEG encoding, 1..100
 * noaudio              : do not include the audio stream

Sample:

http://mxcam.mycompany.net/10_0_0_1/000/000/E00001.jpg?previewsize=320x240
   &framerate=1.0&quality=20&noaudio

Note: Copy this command into one line of your web browser's address bar (the
parameters can be in any sequence). Make sure that there are NO blanks in the
address!



================================================================================
(7) Notes on Security
================================================================================

Please make sure that you observe the following notes on security:

 * Make sure that you are protecting the Windows computer and shared folder by
   assigning special user names and passwords for the cameras. When recording,
   the cameras need full access to the sahred folder(s). Other users should not
   be able to access these folders at all or - if this is unavoidable - they
   should have read rights at maximum.
   
 * Protect your web server installation and the recordings by assigning a user
   name and password to the corresponding folders. You may even consider
   encrypting the entire traffic to and from the web server using SSL (access
   requires using "https://...). For more information on these settings, please
   refer to the Apache documentation on your computer by accessing
   "http://localhost/manual/" or online under
   "http://httpd.apache.org/docs-project/".

================================================================================
March 26, 2010                  MOBOTIX AG                http://www.mobotix.com
