Vortex texis.cnf Configuration Settings

Certain site-wide properties of Vortex can be set in the Texis configuration file texis.cnf. This plain ASCII text file resides in the install directory (usually ``/usr/local/morph3'' under Unix, or ``c:\morph3'' under Windows). The format of this file is similar to Windows .ini files, where a section is denoted by a name in brackets on one line, and settings for that section follow, one per line:

  [Section One]
  Setting One = value
  Setting Two = value

  [Section Two]
  Setting One = value
  Setting Two = value

For more details on other sections' settings that apply to other programs, see the ``Texis Configuration File'' section of the Texis manual. Also note that many of these settings can be overridden by the Texis Web Server (vhttpd) config file; see p. .

The following Vortex-specific settings appear under the [Texis] section of texis.cnf:

• Vortex Log  
    Sets the log file for errors. The default is texis/vortex.log in the install directory. When running the Texis Web Server (vhttpd), this value can be overridden in the vhttpd.conf file (p. ).

• Default Database  
    Sets the database that is used if no database is specified by the script. This is also the database used to store modules. The default is texis/testdb in the install directory.

• Default Script  
    Sets the script that is executed if none is specified in the URL, when Vortex is invoked from the web. The default is texis/testdb/index in the install directory.

• ErrorScript  
    Sets the Vortex script to run if the requested script cannot be started, when Vortex is invoked from the web. This script would be run if the requested script does not exist, cannot be compiled, or otherwise cannot be started normally. Any putmsg errors generated by the attempt to start the requested script are saved for capture by the ErrorScript's <putmsg> function. This enables the ErrorScript to control what errors are seen by the user, even for errors that other scripts can't capture. It can then take appropriate action such as generating a useful error page, redirecting to another page, notifying the site administrator, etc. Vortex is installed with the error script texis/scripts/errorscript configured as an example.

  Note that any errors generated by the requested script after it has started are capturable by that script's <putmsg>, not the ErrorScript. Hence the main script's <putmsg> function should be the first place to put error checking. ErrorScript is for fatal startup errors.

  The ErrorScript value is a file path to a Vortex script, typically /usr/local/morph3/texis/scripts/errorscript. If a relative path is specified, it is taken as relative to the web server's SERVER_ROOT directory. This allows multiple ErrorScripts to be specified across multiple web servers via the single texis.cnf file. (Note that the web server must set the environment variable SERVER_ROOT for relative paths to work.)

  When running the Texis Web Server (vhttpd), the ErrorScript value can be overridden in the vhttpd.conf file (p. ). Added in version 4.00.1018000000 20020405.

• ErrorFile  
    Sets the plain HTML file to send if ErrorScript is to be invoked but is unspecified or cannot be started. The string %errors% in the file is replaced with the text of any error messages. Note that this is a plain HTML file, intended as a last-ditch ``fallback'' if ErrorScript fails. Primary responsibility for handling errors should lie with the <putmsg> function in the main script first, then the ErrorScript script, then ErrorFile.

  The ErrorFile value is a file path to a plain HTML file, typically /usr/local/morph3/texis/scripts/errorfile. If a relative path is specified, it is taken as relative to the web server's SERVER_ROOT directory. This allows multiple ErrorFiles to be specified across multiple web servers via the single texis.cnf file. (Note that the web server must set the environment variable SERVER_ROOT for relative paths to work.)

  When running the Texis Web Server (vhttpd), the ErrorFile value can be overridden in the vhttpd.conf file (p. ). Added in version 4.00.1018000000 20020405.

• ScriptRoot  
    Sets the root file directory to look for Vortex scripts, when run from the web. The default in version 4 and earlier is the web server's document root (ie. the DOCUMENT_ROOT environment variable). In version 5 and later, the default changed to the texis/scripts directory in the install dir; this helps avoid permission problems with compiling scripts and prevents Web users from downloading the contents of the script. Specifying an alternate directory with this setting allows Vortex script files to be moved out of the web server document tree. This may be desirable for security reasons if the script source must be protected from download. It may also be useful to avoid permission issues, eg. where the CGI user does not have write permission to the document tree for writing the .vtx files: ScriptRoot can set another directory with the appropriate perms, possibly outside the document tree to avoid changing its perms.

  The ScriptRoot value is a file directory. If a relative path is specified, it is taken as relative to the web server's SERVER_ROOT directory. This allows multiple ScriptRoots to be specified across multiple web servers via the single texis.cnf file. (Note that the web server must set the environment variable SERVER_ROOT for relative paths to work.)

  When running the Texis Web Server (vhttpd), the ScriptRoot value can be overridden in the vhttpd.conf file (p. ). Added in version 4.00.1017300000 20020327.

• Ignore Env Script Name  
    When to ignore the SCRIPT_NAME environment variable when constructing the Vortex $url variable. In some CGI environments (particularly when the CGI mapping is by-file-extension and not by-directory), SCRIPT_NAME is set incorrectly or redundantly, and concatenating it with PATH_INFO (as per CGI/1.1 spec) would result in the wrong self-referential URL; in these instances it should be ignored. The Ignore Env Script Name setting controls when this occurs. It is a comma-separated list of any of the following:

  • ext-IIS-prefix
    When SCRIPT_NAME ends in one of the non-empty Vortex Source Extensions or ``.vtx'', and SERVER_SOFTWARE starts with ``Microsoft/IIS'', and SCRIPT_NAME is a prefix of PATH_INFO. This typically indicates a Microsoft IIS/6.0 application mapping, where both SCRIPT_NAME and PATH_INFO contain the Vortex script.

  • redirect_handler=action-name
    When the environment variable REQUEST_HANDLER is set to action-name. This may indicate an Apache 2.1+ Action/AddHandler by-file-extension mapping, where using SCRIPT_NAME would give a usable URL, but different from the request (and thus break cookies).

  • always
    Always ignore SCRIPT_NAME.
  The default value is ``ext-IIS-prefix,redirect_handler=texis-vortex'', which handles IIS/6.0, as well as Apache 2.1+ (if the Action is named ``texis-vortex''). Added in version 5.01.1182304953 20070619.

• Allow Cgi Command Line Options  
    Which Vortex command-line options to enable in CGI mode. This is a space-separated list of command-line options (each optionally double-quoted). The default is empty (none) for security, since the QUERY_STRING from the user may be mapped to the command line by the web server. However, it may contain the options --ignore-env-script-name or --, if for example the former must be set differently explicitly for different CGI environments (this is an unlikely situation). In such cases, -- (end of options) should also be allowed, and any server-configured command-line options should be configured and ended with -- before any user-supplied (QUERY_STRING) options are possible. Added in version 5.01.1182042673 20070616.

• Entropy Pipe  
    The path to the prngd daemon's Unix socket. This is only required for Unix systems, and only if using SSL (eg. in <fetch>) and there is no random device (eg. /dev/random). The default is %INSTALLDIR%/etc/egd-pool. Overridden by the entropypipe setting of urlcp (p. ). Added in version 4.01.1031693207 20020910.

• Charset Converter  
    The program and arguments to run for translating character sets (eg. when <fetch>ing pages.) It should take stdin in one charset and output stdout in another requested charset. The variables %CHARSETFROM% and %CHARSETTO% will be replaced with the input and output (requested) charsets, respectively. Embedded-space arguments may be double-quoted. The default is "%INSTALLDIR%/etc/iconv" -f %CHARSETFROM% -t %CHARSETTO% -c. Added in version 5.00.1089408421 20040709.

• Default Header Printif  
    The default value for the PRINTIF flag to <header> statements. Overridden by setting PRINTIF non-empty in a <header> statement (p. ). The default value is headers. Note that this default is a behavior change from prior versions (previous default was always). Added in version 5.01.1111422505 20050321.

• Cookies  
    Whether to URL-decode incoming cookie values when initializing Vortex variables or not. The value urldecode means URL-decode the values, and is the default. The value asis means leave values as-is, ie. do not decode. Can be overridden in a script with the <COOKIES> directive (p. ). Added in version 5.01.1121884376 20050720 (default urldecode in previous versions).

• CGI Debug  
    Controls whether to enable CGI debugging features, such as the -dump option, in CGI mode. Off (0) by default. Added in version 4.02.1047916696 20030317.

• Default Vortex Sort Shortest  
  Nonzero: the default for <sort>/<uniq> should be SHORTEST, not LONGEST. Default is 0 (ie. LONGEST). Added in version 5.01.1189552000 20070911. Previously all <sort>s were SHORTEST.