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