Miva Empresa
Unix Installation Guide

---

Revision 1.3

This document and the software described by this document are copyright 2001 by Miva Corporation. All rights reserved. Use of the software described herein may only be done in accordance with the License Agreement provided with the software. This document may not be reproduced in full or partial form except for the purpose of using the software described herein in accordance with the License Agreement provided with the software. Information in this document is subject to change without notice. Companies, names and data used in the examples herein are fictitious unless otherwise noted.

Miva is a registered trademark of Miva Corporation. Miva Script, Miva Order, Miva Merchant, Miva Mia, Miva Empresa, the Miva "blades" logo, and the Miva Engine are trademarks of Miva Corporation. Windows is the registered trademark of Microsoft Corporation. All other trademarks are the property of their respective owners. This document was developed and produced in San Diego, CA, USA.

MIVA CORPORATION WILL NOT BE LIABLE FOR (A) ANY BUG, ERROR, OMISSION, DEFECT, DEFICIENCY, OR NONCONFORMITY IN THE SOFTWARE OR THIS DOCUMENTATION; (B) IMPLIED MERCHANTIBILITY OF FITNESS FOR A PARTICULAR PURPOSE; (C) IMPLIED WARRANTY RELATING TO COURSE OF DEALING, OR USAGE OF TRADE OR ANY OTHER IMPLIED WARRANTY WHATSOEVER; (D) CLAIM OF INFRINGEMENT; (E) CLAIM IN TORT, WHETHER OR NOT ARISING IN WHOLE OR PART FROM MIVA CORPORATION'S FAULT, NEGLIGENCE, STRICT LIABILITY, OR PRODUCT LIABILITY, OR (F) CLAIM FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES, OR LOSS OF DATA, REVENUE, LICENSEES GOODWILL, OR USE. IN NO CASE SHALL MIVA CORPORATION'S LIABILITY EXCEED THE PRICE THAT LICENSEE PAID FOR MERCHANT.

ME1013-04, Rev.1.3, Miva Empresa Engine v.3.75 and above

Installing Miva Empresa on Unix

Installing the Miva Empresa Engine (3.9x) enables you to run uncompiled Miva Script (.mv) applications on your web site. These installation instructions provide only the basic information to allow you to get Miva Empresa up and running quickly. The instructions include the following topics:

Note: Use the following installation instructions if you want to install the Miva Empresa Engine (3.x) that interprets uncompiled Miva Script files (.mv).

If you want to install the Miva Empresa Virtual Machine (4.x), which executes compiled Miva Script files (.mvc), including compiled Miva Merchant (4.14 and above), refer to the Miva Empresa Virtual Machine 4.x publications, located at
http://www.miva.com/support/docs/empresa/.

• Upgrading From a Previous Version
• Installation Modes
• Server Safe Mode Installation
• Standard Mode Installation
• Distribution File Contents
• After Completing This Basic Installation

Upgrading From a Previous Version

In most cases, upgrading Miva Empresa from a previous version is as simple as replacing the old Miva Empresa binary file with the new one. However, you should be aware of the following items:

• Back up the Miva Empresa data and scripts before performing the upgrade.
• Upgrade the Miva Script application commerce libraries.
• Ensure the ownership and permissions on the new Miva Empresa binary file are identical to those on the old one.
• Review the Release Notes that contain descriptions of new features and/or program corrections that may require a configuration change.

Installation Modes

Miva Empresa provides two installation modes: Server Safe Mode (the preferred method); and Standard Mode. To determine which installation mode is best for your situation and requirements, review the following descriptions, advantages, and disadvantages for both modes.

Server-Safe Mode Installation: Advantages and Disadvantages

This mode (which requires root level privileges) is typically used when the System Administrator is configuring Miva Empresa for use by multiple users or virtual hosts on the Web server.

• Advantages of Server-Safe Mode
  • Miva Empresa data directories can be configured (by the Administrator) for each user/virtual host.
  • Miva Empresa data directories for multiple users can share a common configuration file.
  • Miva Script applications can be globally configured for redirection (also called short style URLs).
• Disadvantages of Server-Safe Mode
  • Requires root level privileges to perform the installation.

Standard Mode Installation: Advantages and Disadvantages

This mode can be used on a Web server to install Miva Empresa for private use, and there must be a private cgi-bin into which the installation can be performed.

• Advantages of Standard Mode
  • Installation can be performed by any user with telnet access.
  • It's easy to configure.
• Disadvantages of Standard Mode
  • Does not support ~user style URLs.
  • Does not support multiple data directories.
  • Cannot be configured for redirection (short style URLs) without administrative privileges.

Install Preparation (Standard and Server Safe Mode)

1. Place the Miva Empresa distribution file into a temporary directory and change to that directory.
2. If your file ends with .gz, gunzip the Miva Empresa distribution file.
3. Untar the Miva Empresa distribution file, for example:

   tar -xvf miva-vx.xx-platform.tar

   Where x.xx is the version of the program.

4. Refer to Distribution File Contents to view the content and untarred directory tree of the Miva Empresa distribution file,
   miva-vx.xx-cgi-platform.tar.gz (some files do not have the .gz).

Server Safe Mode Installation

1. Move the Miva Empresa binary, named miva (located in the cgi-bin subdirectory of the Miva Empresa distribution files), to the system-wide cgi-bin directory. (Refer to Distribution File Contents.)
2. Enter the following commands directly at the server or via telnet to change the Unix setuid permissions of the Miva Empresa binary file:

   chown root miva

   chmod 4755 miva

Note: Changing the Miva Empresa binary file's setuid to the root, allows it to downgrade its permissions to the owner of the Miva Script application file.

3. Create the global configuration file for Miva Empresa. (You can also refer to the conf/examples/serversafe.* in the Miva Empresa distribution file, for sample configuration files. See Distribution File Contents.)
   • Set the authfile configuration option. (This identities the location of the Miva Empresa Authorization file, which defines the location of Miva Empresa data files for each user.)

     authfile=/etc/miva-authfile

Note: You will create the authorization file later.

The mivaroot configuration option determines the directory in which Miva Empresa looks for the documents it will parse (active documents). If mivaroot=/sites/sitename/public_html, and the URL is http://mivasite.com/cgi-bin/miva?/diag.mv, Miva Empresa will look for the file in the directory assigned by the mivaroot configuration option (.../public_html). If the URL is http://mivasite.com/cgi-bin/miva?/subdirectory/file.mv, Miva Empresa will look for the file in the subdirectory of the path set by mivaroot
(.../public_html/subdirectory).

(Typically, mivaroot is defined as the same directory as the DocumentRoot of the Web server.)

• If you use Apache or Zeus: set the mivaroot configuration option. Use a macro to force Miva Empresa to use the server's environment variable, as follows:

  mivaroot=&[document_root]

• If you do not use Apache or Zeus: set mivaroot to the full path from the root of the server to the site's document root. The value must start with a slash, otherwise, set it to the path from a users home directory. For example:

  mivaroot=/sites/sitename/public_html

Note: You can also set mivaroot individually for each of many individual sites by placing the configuration option inside a VirtualHost tag block. Refer to the Miva Empresa Unix Configuration Reference Manual for details. The manual is located at http://www.miva.com/support/docs.

• Set the valid extensions configuration option as follows: (Miva Empresa will execute only the scripts with the defined extension.)

  validextensions=.mv

• If you want to set additional global configuration options, refer to the Miva Empresa Unix Configuration Reference Manual.
• Save the global configuration file in /etc, naming it the same name as the Miva Empresa binary, with .conf appended:

  /etc/miva.conf

4. Apache and Zeus Web Servers: refer to the Miva Empresa Unix Configuration Reference Manual for the following:
   • Redirection (short-style URLs)
   • Aliases and Handlers (must be configured on Zeus).
5. Refer to the Miva Empresa Unix Configuration Reference Manual for information on the following:
   • If you want to set up multiple Miva sites on one system, and set up independent configuration options, use Virtual Hosting.
   • If you plan to allow all users on your Web server to run Miva script applications, you can use the "authuserdir" configuration option.
6. Create the Miva Empresa Authorization File. (You can also refer to the conf/examples/authfile in the Miva Empresa distribution file, for a sample authfile.)

Note: If you do not plan to allow all users on your Web server to run Miva script applications, then you can use group mode or single user authorization. The Miva Empresa Unix Authorization File Reference Manual contains detailed instructions for all options available in the Miva Empresa Authorization File. The manual is located at http://www.miva.com/support/docs.

• Enter the user name, and the mivadata directory for that user. (If the directory does not begin with a slash, it is assumed to be relative to the user's home directory.) For example:

  joe=mivadata (or joe=/home/joe/mivadata)

  derek=mivadata

  burch=mivadata

  troy=mivadata

  If a user does not have an entry in the Miva Empresa Authorization File, that user will not be permitted to run Miva script applications. (Unless you use the authuserdir configuration option that allows all users access.)

• Save the authfile to /etc/miva-authfile or (if different), as defined in the Miva Empresa global configuration file.

Caution:

It is important that the data directories configured in the Authorization File are not accessible via the Web browser, to prevent unauthorized access to your Miva Empresa data files. Be sure the data directories are placed outside of the hierarchy accessible to the web browser.

7. Test the installation.
   • Place diag.mv into the HTML directory of a virtual host. (diag.mv is a test program included in the mivaroot/ directory of Miva Empresa distribution file.)
   • You may then run the application using a URL similar to the following:

     http://<virtual host>/cgi-bin/miva?/diag.mv

Standard Mode Installation

If your Internet Host Provider is Miva-enabled, you do not need to install Miva Empresa in your private cgi-bin.

If your Internet Host Provider or Service Provider is not Miva-enabled, you can install Miva Empresa only if you have a local private cgi-bin.

1. Locate your private cgi-bin directory. Your system administrator should be able to assist you.
2. Place the Miva Empresa binary (located in the cgi-bin subdirectory of the distribution files) in your private cgi-bin directory.
3. Enter the following commands directly at the server or via telnet to set the binary to be setuid root:

   chown <myuserid> miva

   chmod 4755 miva

   Making the Miva Empresa binary setuid to your user id will ensure that the data files created by Miva script applications will be owned by your user account.

You will create a global configuration file, which will be placed in your private cgibin directory, and will have the same name as the Miva Empresa binary, with .conf appended.

4. Create the global configuration file for Miva Empresa. (You can also refer to the conf/examples/standardmode.* in the Miva Empresa distribution file, for sample configuration files. See Distribution File Contents.)
   • Set the mivaroot command. (Defines the directory that contains the script files.) Two examples:

     mivaroot=/home/mivauser/public_html

     mivaroot=&[document_root]

   • Set the stdmodedatadir command. (Defines the directory in which Miva Empresa will store data files created by Miva script applications.) For example:

     stdmodedatadir=/home/mivauser/mivadata

   • Save the global configuration file in your /private_cgi-bin, naming it the same name as the Miva Empresa binary, with .conf appended:

     /home/mivauser/private_cgi-bin/miva.conf

Note: Refer to the Miva Empresa Unix Configuration Reference Manual for detailed information on all Miva Empresa configuration options. The manual is located at http://www.miva.com/support/docs.

5. Test the installation.

   diag.mv is a test program included in the mivaroot/ directory of the Miva Empresa distribution file. Place diag.mv into the directory specified by the mivaroot configuration option in your configuration file. You may then run the application using a URL similar to the following:

   http://<your site>/<your private_cgi-bin>/miva?diag.mv

Distribution File Contents

The contents and untarred directory tree of the Miva Empresa distribution file,
miva-vx.xx-cgi-platform.tar(.gz), is shown below.

After Completing This Basic Installation

After completing this installation, refer to the Unix Configuration Reference Manual at http://www.miva.com/support/docs/empresa/ to configure Miva Empresa for start-up information, set the global operating environment, and set the location of other files. It includes:

• Global Configuration Options (directives), including time-outs, logging, security options, setting global data, and others.
• Global Configuration Tags for a Commerce Library, Packages, and Virtuals Hosts.
• Apache and Zeus configurations (redirection or short-style URLs, aliases, handlers, and Apache suexec).
• Activity Logging File, and Site Variables File