Miva Empresa
Unix Configuration File
Reference Manual

---

Revision 1.7

This document and the software described by this document are copyright 2000 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.

ME1014-08 (Miva Empresa 3.9x)

Configuring Miva Empresa on Unix

The Miva Empresa global configuration file provides Miva Empresa with startup information. Its primary purpose is to set the global operating environment and to set the location of other files. These instructions, intended for the System Administrator, include the following topics:

Global Configuration File Location

The Miva Empresa global configuration file is the same name as the Miva Empresa binary, with .conf appended. If you installed Miva Empresa following the Miva Empresa Unix Installation Guide, you should find the files located in the directories identified below:

• In server-safe mode, look in the /etc directory, for miva.conf.
• In standard mode, look in the/cgi-bin, for miva.conf for example:

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

Note: If the configuration file is not located in the /private_cgi-bin directory, look in the directory in which the Miva Empresa executable resides.

Global Configuration Option (Directives)

The general format for a configuration option is shown below. If the format for a specific configuration option varies, it is listed under that option.

 configuration option=value

authfile

Contains the full path from the root of the server to the Miva Empresa authorization file.

• value format: full path

Note: The Miva Empresa 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/empresa.

authuserdir

Authorizes all users (except root) to use Miva script applications. If the value starts with slash (/), then it is assumed to be an absolute path, and no other checking is done. If it does not start with a slash, the directory is appended to the user's home directory.

• value format: directory name or absolute path

Note: If you also specify an authfile, an entry for a user in the authfile will override the authuserdir setting for that specific user only.

cadir (new in 3.94)

Determines the directory in which Miva Empresa looks for the SSL certificate files.

• value format: directory path

callbuffersize

The allocated buffer size when acting on an MvCALL, where the Engine emulates a browser using HTTP protocol to contact a remote host and send and/or receive data.

• value format: bytes, default 8192 bytes

calltimeout

During a call operation, Miva Empresa opens a TCP/IP port to a Web host. This option sets the number of seconds that Miva Empresa will wait for communication from the remote host.

• value format: seconds, default is 30

commercedir

The commerce subdirectory that corresponds to the specific commerce service under Miva Empresa's data directory (installed as mivadata, but could be under another directory).

• value format: subdirectory

contentbuffersize

The allocated buffer size MvCALL uses for sending data to the remote server.

• value format: bytes, default 8192 bytes

defaultmacroencoding (new in 3.92)

Allows the system administrator to specify the default encoding used for macros which do not explicitly specify an encoding method. The default value is "none". Any unrecognized values will be treated as "none".

• value format:

  none

  entities|

  attribute

dnslookup

Toggles the behavior of the VirtualHost tag. When dnslookup is on, Miva Empresa will attempt to resolve virtual host names to IP addresses. When dnslookup is off, Miva Empresa will simply compare virtual host names to the value in the "virtualhostvariable" configuration option.

• value format:

  1 (on), defaults is 1 (on)

  2 (off)

filetimeout (new in 3.94)

Specify a file timeout to prevent infinite loops when globaltimeout is set to zero. Or, with an operation which requires looping for guaranteed completion, such as finishing an MvLOCKFILE block. Or, prevent

• value format: milliseconds, defaults to 30

filedelay (new in 3.94)

Specify a file delay for use with an operation which requires looping for guaranteed completion, such as finishing an MvLOCKFILE block. Or, to prevent infinite loops when globaltimeout is set to zero.

• value format: milliseconds, defaults to 100

globaltimeout

When Miva Empresa has completed processing the information in the global configuration file and begins to execute an active document, it sets a global timer for the number of seconds specified by this variable. After the set number of seconds has elapsed, Miva Empresa enters exit mode, closes all files, logs the exit, and terminates. This helps in preventing processes from running too long. Miva Empresa's default value is 90 seconds and can be overridden by setting this variable. Set this variable to 0 if you would like no global time-out to be set.

• value format: seconds, defaults to 90 seconds

importbuffersize

When reading files associated with the <MvIMPORT> tag, Miva Empresa allocates a buffer for the incoming data. This allows you to tune the performance of Miva Empresa import processing to optimize data read performance. (Reasonable numbers less than 100000 are a good idea on most systems and smaller numbers, such as 10000, should be used on heavily loaded systems without a lot of RAM.)

• value format: bytes

lockexpiration

Identifies the number of seconds old a lockfile must be before it is considered expired and is removed. This prevents stale lockfiles from causing subsequent processes to timeout waiting for a lock.

lockhostname

Controls the host name that is written to the lockfile. Used if there are multiple hosts writing lockfiles to the same directory, which is possible if using NFS or some other fileserver. Each system must have a unique value for lockhostname (which almost always occurs, since the network hostnames will be different).

logfile

This variable contains the name of the file where Miva Empresa should log its operations. Refer to Activity Logging File on page 13.

• value format: file name

loglevel

The level of verbosity for log reporting.

• value format:

  0 (off)

  1 (script requests)

  2 (script and file operations

mailtimeout

During sending and receiving mail operations, Miva Empresa opens a TCP/IP port to the SMTP or POP3 host. This variable sets the number of seconds Miva Empresa will wait for communication from the remote host.

• value format: seconds, default is 30

maxfiles

When set to a value greater than 0, this directive will control the maximum number of file handles opened by the engine (not including the handle for the executable file itself, standard input, standard output, and standard error). Scripts that need to access more than "maxfiles" files simultaneously will still execute, because the engine will create virtual file handles. The default value is 0, disabled.

maxfunctiondepth

Sets the maximum number of nested function references allowed.

• value format: whole number, default is 23

mivadefault

The file name of the default active document name, if no name is specified on the URL command line. This is usually set to "index.mv" (".mv" is the usual Miva Empresa suffix for active document names).

• value format: file name

mivaroot

Determines the directory in which Miva Empresa looks for the documents it will parse (active documents). (Use an absolute path for mivaroot or set up a macro for Apache's environment variable). This can be overridden with the ~login directive on the URL command line.

mivaroot=&[document_root]

mivaroot=/sites/sitename/public_html

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 the mivaroot configuration option (.../public_html/subdirectory).

• value format: absolute path (or macro)

nice

Changes the priority that Miva Script runs under UNIX. Values below 0 indicate a priority higher than normal; values under 0 indicate a priority lower than normal.

• value format: -20 to +20

openssl (new in 3.94)

Determines the directory in which Miva Empresa looks for the SSL file, libssl.so.

• value format: full path (including file name)

openssl_crypto (new in 3.94)

Determines the directory in which Miva Empresa looks for the SSL file, libcrypto.so.

• value format: full path (including file name)

packages

Makes the configured packages available to the domain. The codes of available packages are comma-delimited. Refer to <PACKAGE> on page 9 for additional information.

• value format: list of comma-delimited codes of available packages

redirectonly

When set to true, Miva Empresa will process scripts only when invoked by Apache CGI-redirect, and will reject standard CGI requests. (This prevents users from using CGI style URLs to circumvent Web server document security.)

value format:

yes (restricts script processing)

no (does not restrict processing)

securityoptions

The numeric value given to this variable allows you to enable configurations that may not be secure under all circumstances. The default value of 0 (zero) specifies that under no circumstances, will Miva Empresa be allowed to follow symbolic links from source code or data directories. A value of 0 (zero) here also disallows Miva Empresa from following an absolute path, that may be specified in an application, to read or write data.

Value	Description
0	Do not allow Miva Empresa to follow symbolic links or an absolute path (default).
1	Follow symbolic links in the source code directory.
2	Ignore symbolic link ownership in the source code directory.
4	Follow symbolic links in the data directory.
8	Ignore symbolic link ownership in the data directory.
16	Allow absolute paths for data files.

Working as a bitmask, you can combine the values to allow combinations of different options. For example, the following option would allow Miva Empresa to ignore symbolic link ownership in the source code directory (2), and follow symbolic links in the data directory (4).

 securityoptions=6

serveruserid

When specified, Miva Empresa will only process scripts when invoked by the UID specified. This prevents users with shell accounts from running Miva Empresa from a shell prompt.

• value format: UID number

Note: The value configured must be a numeric user id, and not a user name.

sitevars

Contains the name of the file that contains the variable names / value pairs which are automatically created when Miva Empresa begins execution. (See Site Variables File on page 14.)

• value format: file name

serveradmin

Set this variable to the email address to be shown when Miva Empresa encounters a system configuration or authorization error, or cannot find the specified active document.

• value format: email address

smtpbuffersize

The allocated buffer size the Miva Script tag MvSMTP uses when writing to the SMTP mail server.

• value format: bytes, default is 8192

stdmodedatadir

Used in standard mode installation, defines the directory in which Miva Merchant will store data files created by Miva Script applications. It is ignored in server safe mode installations.

• value format: directory name

tempdir

Location for the files that are temporarily created by Miva Empresa.

• value: directory path

templatebuffersize

Miva Empresa allocates a buffer for active documents and attempts to load as much of the active document in the buffer as it can before processing.

• value format: bytes, default is 8,000

usecookies

This value is available to Miva Empresa active documents in the Collared system variable. To disable the use of cookies, use no as the value.

• value format:

  no (to disable)

  yes (to enable)

userdir

One type of URL Miva Empresa processes, references a script file which is stored in a user's private HTML directory, and takes the form: http://www.mivasite.com/~mivauser/script.mv. Miva Empresa looks for the script file in the directory defined by the userdir configuration option. (Typically, userdir will be defined to be the same as the UserDir of the Web server.)

• value format: directory name/~mivauser/script

usersitevars

The usersitevars is a configuration variable that allows a sitevars file to be defined for each user.

filename is the path and name of the file relative to the Miva Empresa data directory. The default value is "sitevars."

The usersitevars file is subjected to the same path validation that all data files are. The sitevars file is read AFTER Miva Empresa has dropped root privileges, if it is running in server-safe mode. This means that the file must be readable by the user whose script is running.

The standard sitevars file is always processed, even if there is a usersitevars file. In the event of duplicate variables in the two files, the usersitevars file variable values overrides the system sitevars file variable values.

If the usersitevars file does not exist, or cannot be opened, no error message is displayed, but the user sitevars file is not processed.

If there is a path validation error (such as the file is a symbolic link to another file outside that data directory, etc.) an error is displayed.

• value format: filename

validextensions

Miva Empresa will execute only the scripts with the defined extension. (.mv for the Miva Empresa Engine.)

virtualhostvariable

Defines the environment variable that will be used to determine the name of the virtual host when Miva Empresa processes a request.

• value format: environment variable, default is "SERVER_NAME"

workdir

Miva Empresa has the ability to optimize configuration information by putting virtualhost and authorization information into an indexed database. If workdir is specified, Miva Empresa will use this directory to store its caching database.

• value format: directory name

Global Configuration Tags

The following global configuration tags can be entered in the Miva Empresa global configuration file. Each must have a starting tag <tag> and an ending tag </tag>.

<COMMERCE-LIB>

The Commerce Library tag identifies the type of commerce method and the location of its libraries. For example:

 <COMMERCE-LIB METHOD = "UPSCost" LIBRARY = "/usr/local/
miva/lib/upsonline.so">
    

      
  Where:
    
  

    
 METHOD is the commerce method which the library provides.
    
 LIBRARY identifies the location of the Miva Script application commerce libraries.
  

Starting with Miva Empresa version 3.6.4, the MvCOMMERCE tag uses dynamically loaded commerce libraries. Therefore, the METHOD value of the COMMERCE-LIB tag will be passed to the METHOD attribute of the MvCOMMERCE tag. You may add as many COMMERCE-LIB tags as needed to install different commerce protocols.

To obtain a list of the Methods and Libraries for the commerce protocols that are available from Miva Corporation, refer to the "Commerce Libraries Listing" at http://www.miva.com/support/docs/empresa.

Note: <COMMERCE-LIB> may not be used in a <VirtualHost> tag, and it must be specified before any <VirtualHost> tags in the Miva Empresa global configuration file.

<PACKAGE>

Configures the master list of available packages and controls which packages are available for a specific virtual domain. For example:

 <PACKAGE CODE = "merchant"
NAME = "Miva Merchant"
DESCRIPTION = "Storefront Development System"
VERSION = "1.23"
PATH = "/etc/miva/merchant.tar"
DEFAULTPATH = "Merchant/">

Where:

• CODE is a unique identifier used for the package.
• NAME is the name of the package.
• DESCRIPTION is a brief description of the package.
• VERSION is the version of the package.
• PATH is the *full* path to a .tar file containing the files required by the package.
• DEFAULTPATH is the default installation path. This path will be used as the default by the Miva Package Manager.

Once a package has been defined by the <PACKAGE> tag, it must be made available to a domain (or domains) via the packages configuration option: packages=merchant, order.

<VirtualHost>

Note: The <VirtualHost> tag must appear AFTER all global directives and tags. Otherwise, the global options will stop parsing.

The <VirtualHost> tag is used to define Miva Empresa settings for a given virtual host. Configuration options inside a virtual block apply only to the site defined by the ipaddress or hostname. There are two commonly used methods for Virtual Hosting.

The first method assigns a separate IP address for each virtual host. The Miva Empresa default settings assume this type of configuration.

The second method is sometimes called "software virtual domains." In this method, one or more virtual hosts share an IP address. The correct virtual host is determined by an additional header provided by the Web browser.

• If you are using software virtual domains, uncomment (remove the # from), or add if not present, the following lines in the global configuration file (miva.conf):

   dnslookup=off
   virtualhostvariable=HTTP_HOST
  

• If you are using software virtual domains, use the full hostname of the virtual host or the IP address in the <VirtualHost> tag.

   <VirtualHost (ipaddress or hostname)>
   mivaroot=/location of document root of virtual host 
   configuration option=value
   </VirtualHost>
      
  
        
    mivaroot determines the directory in which the Miva Empresa looks for the documents it will parse (active documents) for this Virtual Host. Typically, mivaroot will be defined to be the same directory as the DocumentRoot of the virtual host.
        
    The configuration option shows that you can enter specific configuration options that apply only to this Virtual Host.
      
  

Advanced Configuration

Apache: Redirection Configuration

1. If you wish to use redirection (short-style URLs), and are running the Apache Web server, add the following lines to your httpd.conf or srm.conf file. (As of Apache version 1.3.4, Apache recommends that all Apache configuration commands be stored in httpd.conf.)
   • AddType application/x-miva .mv
   • Action application/x-miva /cgi-bin/miva

     It is assumed your cgi-bin directory is ScriptAlias'ed to /cgi-bin, and the name of the Miva Empresa binary is miva.

     If you do not have a ScriptAlias for your cgi-bin, Apache will expect a directory called cgi-bin to exist in the document root of the web site.

2. To create a ScriptAlias for a global cgi-bin, add the following line to your httpd.conf or srm.conf file (whichever one you used in step 1, above).
   • ScriptAlias /cgi-bin /home/sites/home/cgi-bin

Note: If you are not using Apache, you will need to consult your Web server's documentation for information on setting up redirection.

Zeus: Aliases and Handlers

1. On Edit Server page, under Module Configurables, click the "Path Mapping" box.
   
2. Under "Aliases" (see following image).
   • Docroot path: enter the virtual path (such as /home/admin/cgi-bin/).
   • Filesystem directory: enter the true path (such as home/admin/cgi-bin)/
   • Alias type: select cgi
   • Click Update.

     

3. Under "Handlers"
   • File Extension: enter hts and mv (one at a time)
   • Handler: enter /cgi-bin/miva
   • Click Update.
     

Configuring Miva Empresa with Apache suexec

Apache suexec is a CGI wrapper program that enables the Web server to run CGI programs as a specific user.

To use Miva Empresa under Apache suexec, you will need to install a separate copy of the Miva Empresa binary in each user's private cgi-bin. Each binary should be owned by the owner of the cgi-bin directory. To ease the administration process, you may configure these binaries to share common configuration files.

Activity Logging File

When Miva Empresa begins execution, but has not yet opened the active document, it opens the logfile. The full path to this file is specified in the global parameter logfile. As with most Miva Empresa global configuration options, you can create a separate file for multiple virtual domains.

The logfile contains new line separated records with | (bar) delimited fields indicating the operations of Miva Empresa. The fields in this file are as follows (listed in the order they appear):

• operation - a mnemonic indicating the current state of Miva Empresa
• day - day of the month
• month - month of the year
• hour - hour of the day (GMT)
• minute - minute of the hour (GMT)
• second - second of the minute (GMT)
• year - the year
• login - login id of executing Miva Empresa file
• uid - numeric user id of executing Miva Empresa file
• gid - numeric group id of executing Miva Empresa file
• filename - full path to executing Miva Empresa file
• rootdir - full path to the root directory of executing Miva Empresa file
• version - current version of Miva Empresa's pre-processor
• loglevel - the log level setting (currently only 1 or 0)
• info - mnemonic indicating result of operation (can be useful when tracking problems with Miva support).

Note: The Miva Engine records the time (hour, minute, second) in Greenwich Mean Time (GMT) also known as Universal Time Coordinated (UTC).

Site Variables File

Miva Empresa provides a capability for you to set global data that will be available to all Miva Empresa active documents upon execution. As with all global options, the sitevars file may be set on a per domain basis if you are running multiple domains. If you are an ISP or hosting service, you will most likely want to locate this file within data space accessible by the virtual domain owner.

Sitevars are very powerful and can be used to store standard formats for the FMT operator, messages of the day, commonly referenced links, or even Miva code. There are many possibilities for this configuration option.

The format of the sitevars file is:

 variablename=any string of text
    

      
  The text immediately following the = sign is loaded into the variable at the time of Miva Empresa active document startup. If you would like the text to span more than one line in your sitevars file, then you can use the \ (backslash) character for continuation.
      
  For example: 
    
 variablename=this is a very long line of text and I would like\
 to span more than one line of text
 variableb=a shorter line of text

The \ (backslash) character cannot be (currently) stored in the variable because of its special meaning as the continuation character.