CONFIGURATION AND INSTALLATION
------------------------------
The Miva Virtual Machine for UNIX is a cgi-bin application that is designed to
be executed by a webserver, such as Apache or Zeus. Installation is fairly
simple and anyone who has installed a previous version of the Miva Engine
should have no difficulty.

The configuration system in the Miva Virtual Machine has been modularized, so
that hosting providers with custom provisioning systems can develop custom
configuration engines. A configuration library is a DSO that is loaded by the
Miva Virtual Machine and then queried for configuration values.

This release of the Miva Virtual Machine ships with two configuration
libraries: "lib/config/3x.so" and "lib/config/env.so". "3x.so" is a
configuration library that provides compatibility with the configuration file
used by v3.x of Miva Empresa. "env.so" is a configuration library that
obtains configuration values from environment variables.

The Miva Virtual Machine first looks for its configuration library as
"libmivaconfig.so" in the current directory. If this file is not found,
then the engine tries to load the DSO identified by the environment variable
MvCONFIG_LIBRARY (if set). For security reasons, the owner of the
configuration library must be either the same as the user executing the Miva
Virtual Machine, or root.

APACHE INSTALLATION FOR PCI COMPLIANCE
--------------------------------------
Our PA-DSS certification requires that your Apache server use suEXEC. This
places the following additional restrictions on the installation of the
Miva Merchant Virtual machine:

1. Each virtual host must have its own private cgi-bin directory
2. Each virtual host must have a unique user and group, and suEXEC
must be configured to use the correct user/group with a SuexecUserGroup
directive for each tag.
3. If using the environment variable based configuration, the configuration
must be modified to pass through suEXEC by prepending "HTTP_" to all
names. For example, MvCONFIG_DIR_MIVA becomes HTTP_MvCONFIG_DIR_MIVA.

In addition, for a PA-DSS certified installation of Miva Merchant, the
Miva Merchant Virtual Machine configuration must also include:

1. Correct "openssl" and "openssl_crypto" directives containing the
paths to OpenSSL libraries.
2. A "cadir" directive containing the path to the current version of
the Miva Merchant Virtual Machine certificates (included in the
distribution)
3. The MySQL database library must be installed and properly referenced
in the Miva Merchant Virtual Machine configuration file.
4. While not required for Miva Merchant, we recommend that the engine
"htscallerid" cookie be disabled.

STEP BY STEP INSTALLATION ON APACHE WITH suEXEC AND ENVIRONMENT CONFIGURATION:
------------------------------------------------------------------------------
1. Place the file "cgi-bin/mivavm" in the virtual host's private cgi-bin
directory.

2. Change the ownership and permissions of the "mivavm" binary with the
following commands:

# chown . mivavm
# chmod 0755 mivavm

3. Create a "mivadata" directory parallel to the virtual host's HTML
document root. This directory *MUST NOT* be contained in a web
accessible location.

4. Change the ownership and permissions of the "mivadata" directory with
the following commands:

# chown . mivadata
# chmod 0750 mivadata

5. Add the following lines to your "httpd.conf" (or "srm.conf", if using
an older version of Apache) within the appropriate tag for
the site being configured.

SetEnv HTTP_MvCONFIG_LIBRARY /path/to/mivavm/distribution/lib/config/env.so
SetEnv HTTP_MvCONFIG_DIR_MIVA /path/to/vhost/document_root
SetEnv HTTP_MvCONFIG_DIR_DATA /path/to/vhost/mivadata
SetEnv HTTP_MvCONFIG_DIR_BUILTIN /usr/local/miva/lib/builtins
SetEnv HTTP_MvCONFIG_DIR_CA /path/to/mivavm/distribution/certs/openssl-1.0
SetEnv HTTP_MvCONFIG_DATABASE_MIVASQL /path/to/mivavm/distribution/lib/databases/mivasql.so
SetEnv HTTP_MvCONFIG_DATABASE_MYSQL /path/to/mivavm/distribution/lib/databases/mysql.so
SetEnv HTTP_MvCONFIG_SSL_OPENSSL /lib/libssl.so.6
SetEnv HTTP_MvCONFIG_SSL_CRYPTO /lib/libcrypto.so.6
SetEnv HTTP_MvCONFIG_COOKIES 0

AddType application/x-miva-compiled .mvc
Action application/x-miva-compiled /cgi-bin/mivavm

NOTE: If your UNIX distribution uses OpenSSL v0.9.x, you must change the
value of HTTP_MvCONFIG_DIR_CA to end in "openssl-0.9".

6. Restart your Apache server.

STEP BY STEP INSTALLATION ON APACHE WITH suEXEC AND 3.x CONFIGURATION:
----------------------------------------------------------------------
1. Place the file "cgi-bin/mivavm" in the virtual host's private cgi-bin
directory.

2. Change the ownership and permissions of the "mivavm" binary with the
following commands:

# chown . mivavm
# chmod 0755 mivavm

3. Copy "lib/config/3x.so" to "libmivaconfig.so" in the virtual host's
private cgi-bin directory.

4. Create a "mivadata" directory parallel to the virtual host's HTML
document root. This directory *MUST NOT* be contained in a web
accessible location.

5. Change the ownership and permissions of the "mivadata" directory with
the following commands:

# chown . mivadata
# chmod 0750 mivadata

6. Create a 3.x configuration file with the name "mivavm.conf" in the
virtual host's private cgi-bin directory. An example configuration
file follows:

mivaroot=/path/to/vhost/document_root
stdmodedatadir=/path/to/vhost/mivadata
redirectonly=1
openssl=/lib/libssl.so.6
openssl_crypto=/lib/libcrypto.so.6
cadir=/path/to/mivavm/distribution/cadir/openssl-1.0
usecookies=0
builtindir=/path/to/mviavm/distribution/lib/builtins




NOTE: If your UNIX distribution uses OpenSSL v0.9.x, you must change the
value of cadir to end in "openssl-0.9".

STEP BY STEP APACHE INSTALLATION - NOT PCI COMPLIANT
----------------------------------------------------
1. Place the file "cgi-bin/mivavm" in your Apache "cgi-bin" directory.

2. Change the ownership and permissions of the "mivavm" binary with the
following commands:

# chown root.root mivavm
# chmod 0755 mivavm

3. Add the following lines to your "httpd.conf" (or "srm.conf", if using
an older version of Apache).

SetEnv MvCONFIG_LIBRARY /usr/local/miva/lib/config/env.so
SetEnv MvCONFIG_DIR_MIVA /home/httpd/html
SetEnv MvCONFIG_DIR_DATA /home/httpd/mivadata
SetEnv MvCONFIG_DIR_BUILTIN /usr/local/miva/lib/builtins

AddType application/x-miva-compiled .mvc
Action application/x-miva-compiled /cgi-bin/mivavm

The above lines assume that you have extracted the Miva Virtual Machine
distribution file into /usr/local/miva, and that your Apache DocumentRoot
is /home/httpd/html

4. You may override any Miva Virtual Machine configuration directives for a
Virtual Host by placing "SetEnv MvCONFIG_..." directives inside the
block.

5. Restart your Apache server.

CONFIGURATION REFERENCE - 3x.so
-------------------------------
For the most part, 3x.so behaves identically to the Miva Empresa 3.x
configuration. As such, you may refer to the UNIX Empresa configuration
documentation on the Miva website for additional information.

The following additional configuration tags are supported:



Register the builtin function library .



Register the database library with database type .

CONFIGURATION REFERENCE - env.so
--------------------------------
env.so loads configuration values from environment variables. Please
note that the names of the environment variables are case sensitive.

Environment Variable Description
----------------------------------------------------------------------
MvCONFIG_DIR_MIVA Root directory for .mvc files
MvCONFIG_DIR_DATA Root data directory
MvCONFIG_DIR_CA Directory containing SSL certificate files
MvCONFIG_DIR_USER Analagous to Apache "UserDir" directive
MvCONFIG_DIR_USERDATA Identical to 3.x "authuserdir" setting
MvCONFIG_INFO_SERVERADMIN Email address of server administrator
MvCONFIG_SSL_OPENSSL Full path to libssl.so (if available)
MvCONFIG_SSL_CRYPTO Full path to libcrypto.so (if available)
MvCONFIG_TIMEOUT_GLOBAL Global application timeout (seconds)
MvCONFIG_TIMEOUT_MAIL MvPOP/MvSMTP network timeout (seconds)
MvCONFIG_TIMEOUT_CALL MvCALL network timeout (seconds)
MvCONFIG_COOKIES Output htscallerid cookie (boolean)
MvCONFIG_FLAGS_SECURITY Identical to 3.x "securityoptions" setting

env.so automatically loads all .so files contained in the directory
specified by the environment variable MvCONFIG_DIR_BUILTIN (if specified).

To register a commerce library or database library, create an environment
variable with the name in the following form:

MvCONFIG_DATABASE_
MvCONFIG_COMMERCE_

Where is the desired commerce method or database type. The value of
this environment variable should be the full path to the library file.