Miva Empresa (Virtual Machine), README.txt
$Id$

Thank you for downloading this release version of Miva Empresa (Virtual Machine).

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 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 <VirtualHost> 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 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 Virtual Machine certificates (included in the distribution)
   or a "cafile" directive containing the path to the system's root
   certificate file.
3. The MySQL database library must be installed and properly referenced
   in the Miva 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 <vhost-user>.<vhost-group> mivavm
		# chmod 0755 mivavm

3. Copy "lib/config/env.so" to the virtual host's private cgi-bin directory
   as "libmivaconfig.so", with the ownership and permissions the same as
   the "mivavm" binary in step 2.

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 <vhost-user>.<vhost-group> mivadata
		# chmod 0750 mivadata

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

	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_FILE_CA /path/to/root_certificate_file.crt
	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

	AddHandler mivascript .mvc
	Action mivascript /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".

7. 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 <vhost-user>.<vhost-group> 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 <vhost-user>.<vhost-group> 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
		cafile=/path/to/root_certificate_file.crt
		usecookies=0
		builtindir=/path/to/mivavm/distribution/lib/builtins

		<DATABASE-LIB METHOD="MivaSQL" LIBRARY="/path/to/mivavm/distribution/lib/databases/mivasql.so">
		<DATABASE-LIB METHOD="MySQL" LIBRARY="/path/to/mivavm/distribution/lib/databases/mysql.so">

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

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

	AddHandler mivascript .mvc
	Action mivascript /cgi-bin/mivavm

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 4755 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

	AddHandler mivascript .mvc
	Action mivascript /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
   <VirtualHost> 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:

<BUILTIN-LIB LIBRARY="path">
		
		Register the builtin function library <LIBRARY>.

<DATABASE-LIB METHOD="type" LIBRARY="path">

		Register the database library <LIBRARY> with database type <METHOD>.

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_USER			Analagous to Apache "UserDir" directive
MvCONFIG_DIR_USERDATA		Identical to 3.x "authuserdir" setting
MvCONFIG_DIR_CA				Directory containing SSL certificate files
MvCONFIG_DIR_FILE			File path to system's root certificate file
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_<method>
	MvCONFIG_COMMERCE_<method>

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

IIS 7 AND NEWER INSTALLATION
----------------------------
1. You will need the IIS Admin Pack installed in order to edit the MivaScript
   configuration.  It may be obtained from Microsoft.

2. Copy "doc/MivaVMIIS7_schema.xml" to your IIS7 schema directory and rename it to
   "MivaVMIIS7.schema.xml".  The IIS schema directory is usually
   "C:\WINDOWS\SYSTEM32\inetsrv\config\schema".

3. Add the following to applicationHost.config
   (usually in C:\WINDOWS\SYSTEM32\inetsrv\config), as a child of the
   <configSections> tag:
		
		<section name="MivaScript" overrideModeDefault="Allow"
		         allowDefinition="Everywhere" />

4. Perform the following steps in the IIS Manager:

	a. Register MivaVMIIS7.dll as a Native Module.
	b. Add a Handler Mapping for *.mvc to the Module registered above.
	c. Using the Configuration Editor, select section MivaScript and configure
	   all settings as required, including registering all builtin function,
	   database and commerce libraries.
