Altair EEvision Installation with CGI

Altair EEvision for CGI-based Web Server (compare with Standalone)

The EEvision software is delivered as a .zip or .tgz (tar ball) and after unpacking, the contents of its "web" directory is intended to be copied somewhere below the Web Server's document_root. Here, we use the keyword eevhome to refer to this installation directory. This directory serves the start URL for the EEvision GUI. Directly below that the EEvision GUI uses the data URL to access input data files and the srv/proxy.cgi URL for AJAX requests to provide interactive response. Here is an overview of these URLs and their corresponding physical locations in the Web Server's file system.

If the EEvision GUI is stated with an EDB file, e.g. with the URL "eevhome/main.html?edb=designdir/d.edb" or if a JSON request is started from an EDB file, like "eevhome/srv/json.cgi?edb=designdir/d.edb", then the EDB file, plus optional SVG image files, plus an optional eev.conf are read from these locations:

EEvision is proven to run under Apache, Tomcat and Jetty, but should run under any Web Server that provides a CGI interface. All configuration examples in this document below refer to Apache 2.4. The easiest installation is to keep the directory structure as it is and stay in sync with the URL structure. The software package includes "htaccess.sample" (at /document_root/eevhome/ and /document_root/eevhome/srv/) that stores Apache configuration rules that are required or useful to run on an Apache Web Server. For Web Servers other than Apache these configuration rules need to be translated. Please find the contents from the "htaccess.sample" in the gray boxes below.

Requirements for the Web Server configuration, (see Tomcat and Jetty configuration)

CGI-programs located in a dedicated directory

If the CGI-Programs are required to be located in a directory different to "/document_root/eevhome/srv", say, e.g., in "/var/www/cgi-bin", then all content of the srv directory must be moved to /var/www/cgi-bin (including srv/.htaccess on Apache). These URLs must correspond to physical locations as shown in the table below:

Alias for CGI programs

ScriptAlias /eevhome/srv/  "/var/www/cgi-bin/"
<Directory "/var/www/cgi-bin">
    SetEnv EEV_DATA /document_root/eevhome/data/
    …
</Directory>

Apache needs a "ScriptAlias" for this as shown in the box on the right side (to be put into the Apache main configuration file). Additionally, the environment variable EEV_DATA must be added to define the location of the input data (dataRoot) for the CGI-programs. Alternatively, the SetEnv EEV_DATA … can be added to the /var/www/cgi-bin/.htaccess".

Input Data (dataRoot) in a dedicated directory

If the Input Data (EDB files, SVG images, etc) is required to be located in a directory different to "/document_root/eevhome/data", say e.g. in "/extra/data", then the URLs below "data" must correspond to that physical location as shown in the table below:

Alias for dataRoot

Alias /eevhome/data/ "/extra/data/"
<Directory "/extra/data">
    Require all granted
</Directory>

Apache needs an "Alias" for this as shown in the box on the right side (to be put into the Apache main configuration file). Apache usually needs access rights explicitly specified by the "Require" keyword as shown in the gray box.

Additionally, the environment variable EEV_DATA must be added to define the location of the input data (dataRoot) for the CGI-programs.

<Directory "/document_root/eevhome/srv">
    SetEnv EEV_DATA  /extra/data/
</Directory>

If the CGI programs are still located in the default srv directory, then the gray box on the right side (to be put into the Apache main configuration file) defines the EEV_DATA relative to that srv directory. Alternatively, the SetEnv EEV_DATA … can be added to the srv/.htaccess.

<Directory "/var/www/cgi-bin">
    SetEnv EEV_DATA  /extra/data/
</Directory>

If the CGI programs are located in the /var/www/cgi-bin directory, then the gray box on the right side (to be put into the Apache main configuration file) defines the EEV_DATA relative to that directory. Alternatively, the SetEnv EEV_DATA … can be added to the /var/www/cgi-bin/.htaccess".

Temp Directory

EEvision may need a directory to store temporary internal data, which is defined by the EEV_TEMPDIR environment variable. If EEV_TEMPDIR is undefined, then on UNIX "/tmp" and on Windows Temp or TMP or "C:/tmp" is used; this directory should exist with write permissions for the service process.

Logging

On Unix environments, EEvision uses syslog facility "local0" to print notices, warnings and other messages. Please consult the Unix systems /etc/syslog.conf or /etc/rsyslog.conf how to configure them. The environment variable EEV_SYSLOG can be set to ERR, WARNING, NOTICE, INFO or DEBUG, to control the severity level of the logging. The default is NOTICE. For compatibility, the numbers 3, 4, 5, 6, or 7 can be used respectively. The EEV_SYSLOG variable must be set for the CGI-program analogous to the EEV_DATA variable.

On Windows environments, EEvision logs to a file defined by the EEV_LOGFILE environment variable – or to "eev.log" in the CGI directory, if EEV_LOGFILE is not defined. The environment variable EEV_SYSLOG is also supported on Windows to control the severity of the logging (which actually defines the verbosity).

Overview on environment variables

These environment variables should be set for the CGI programs, on Apache in the srv/.htaccess file (see srv/htaccess.sample in the release package). Non-ASCII characters won't work on Windows (but may work on UNIX if UTF-8 encoded).

Notes for LM_LICENSE_FILE:

In the table above, the "default" values apply in addition to LM_LICENSE_FILE. The exedir stands for the directory of the executable, which is "/document_root/eevhome/srv". This means, after checking the locations in the environment variables LM_LICENSE_FILE (and DCONCEPT_LICENSE_FILE), EEvision will also check for /document_root/eevhome/srv/license.dat, then for /document_root/eevhome/license.dat, and finally for /usr/local/flexlm/license.dat (on UNIX) or for C:/flexlm/license.dat (on Windows).

Debug the Installation

Environment:
        EEV_DATA
        EEV_TEMPDIR
        EEV_SYSLOG   = 7
        EEV_LOGFILE
        EDB_PASSWD
        LM_LICENSE_FILE
getcwd()          --> /var/www/html/eevision/srv
GetDataRoot()     --> ../data
SyslogPrio()      --> 7=DEBUG
GetTempDir()      --> /tmp
MakeTempDir('D')  --> /tmp/eev.DKndjWT []
MakeTempFile('F') --> /tmp/eev.FNAxSrx []
                      [Sun, 06 Oct 2019 21:14:37 GMT]
tmpfile()         --> OK

a HTML GET request to /eevhome/srv/debug.cgi displays the relevant environment variables with values and performs some checks and displays their results (in plain/text), as e.g. in the gray box on the right.

Cleanup Temp Files

Reading temp directory /tmp
Statistics:
      6 files/dirs older than  0 weeks
     48 files/dirs older than  1 weeks
    357 files/dirs older than  2 weeks
     35 files/dirs from other programs

a HTML GET request to /eevhome/srv/cleanup.cgi displays some hints about temp files and temp directories created by EEvision on the Web Server. These hints are displayed (in plain/text), as e.g. in the gray box on the right. If this Cleanup program is invoked with a parameter "weeks", then all EEvision temp files or directories older than the given number of weeks are deleted. E.g. /eevhome/srv/cleanup.cgi?weeks=2 will delete the 357 files/dirs older than 2 weeks.

Architecture

Each Browser tab that loads the EEvision main GUI from "https://server/eevhome/main.html" also starts a "guard" process on the Web Server. The life-time of the "guard" process is bound to the life-time of the main.html page in the Browser. This is also the life-time of the interactive session. Such a session is bound to one dedicated EDB file (that defines the borders for interactive exploration within such session). The small and lightweight CGI-program proxy.cgi creates and terminates the "guard" process and performs all communication to it via AJAX POST requests to https://server/eevhome/srv/proxy.cgi.

Altair License checker

The new EEvision packages come with Altair License Units. They require an Altair License Manager to run; please check out the corresponding Altair License documentation. The "guard" process in the srv directory usually needs the environment variable ALTAIR_LICENSE_PATH pointing to the Altair License Server. Each interactive EEvision session requires Altair License Units for the life-time of the session (which is the time, the Browser tab with main.html is open).

FlexNet License checker

The legacy EEvision packages still support the FlexNet License mechanism. They require an License Manager (lmgrd) to run; please check out the corresponding FlexNet documentation. For FlexNet related installation notes, please read The FlexNet Installation Guide. The "guard" process in the srv directory usually needs the environment variable LM_LICENSE_FILE pointing to the FlexNet License Manager. Each interactive EEvision session requires a FlexNet floating license for the life-time of the session (which is the time, the Browser tab with main.html is open).

Trust-based Customer-Specific License checker

In certain cases, an alternative license checker can be established by the EEvision customer. If so, then the eev.conf's "license" entry must define the URL path to the customer's license web service to provide license cookies. EEvision will add two URL parameters "salt" and "widget" and will access the customer's license web service via a HTTP GET, like:

https://server/path_to_customer_license_service?salt=123456789&widget=nlvEq7