Httpd conf/texis.ini Section

The [Httpd] section of conf/texis.ini controls the Texis Monitor Web Server. This is a minimal web server primarily intended for certain standalone Windows applications. Most environments (e.g. Unix) should use the vhttpd web server instead.

Run Level
Default: 0
Whether to run the Texis Monitor Web Server or not. Integer; bits are flags:

  • 0x1 Run web server

  • 0x2 Exit monitor nonzero if web server startup error
Added in version 4.02.1036450486 Nov 4 2002.

Listen
Default: *:80 (port 443 if [Httpd] SSL Engine is on)
Local port and optional IP address to listen to for web requests. The address, if given, is separated from the port with a colon; an IPv6 address (but not the port-separator colon) must be in square brackets. If only a port is given, the default address is * for all local IPv4 and IPv6 (if version 8+ and OS supports IPv6) addresses. The default port, if no Listen setting(s) are given, is 80, unless [Httpd] SSL Engine is on, in which case the default port is 443 (both default ports require running as root).

This setting may be given multiple times to listen on multiple ports and/or addresses. Added in version 8.

Bind Address
Default: unset

Note: This setting is deprecated and will be removed in a future release; use Listen instead, which overrides Bind Address and Port.

The local IP address to bind to. There is no default; the Listen default applies instead.

Port
Default: 80 in version 7 and earlier (443 if [Httpd] SSL Engine is on); unset in version 8 and later

Note: This setting is deprecated and will be removed in a future release; use Listen instead, which overrides Bind Address and Port.

The TCP port to listen to. There is no default; the Listen default applies instead.

Document Root
Default: %INSTALLDIR%/htdocs
The document root directory to server documents from. Must be an absolute path. Added in version 4.02.1036450486 Nov 4 2002.

Transfer Log
Default: %LOGDIR%/transfer.log in version 8 and later, %INSTALLDIR%/logs/transfer.log in version 7 and earlier Path to log file for transfers. Must be absolute. Added in version 4.02.1036450486 Nov 4 2002.

Log Format
Default: %h %l %u %t "%r" %>s %b "%{Referer}i" "%{User-Agent}i" (the standard Combined format)
Format for entries in Transfer Log. The value is a printf-like format string containing %-codes for certain special values. The codes are based on Apache 2.4's LogFormat directive format codes, with some codes unsupported.

Note that conf/texis.ini setting values normally have certain %-variables replaced (e.g. %INSTALLDIR%); such var replacement may unexpectedly alter the Log Format value, as it is likely to also contain % codes that have meaning only in Log Format. To avoid this conflict, assign Log Format with the ":=" operator instead of the usual "=": the former disables variable substitution.

Some Log Format codes can take a {varName} prefix - e.g. "%{Referer}i" - as a parameter; these are noted in the list of codes below:

  • %% A percent sign

  • %a Client (remote) IP address

  • %A Local IP address

  • %B The response size in bytes, not including headers

  • %b The response size in bytes, not including headers, or "-" (dash) if unknown/empty

  • %{varName}C The value of cookie varName in the request, or dash if unset

  • %D Elapsed time for the transaction, in microseconds

  • %{varName}e Environment variable varName; unimplemented, always a dash

  • %f The request's filename path

  • %h The client hostname; reverse-DNS lookups are not currently performed so this is always the IP address

  • %H The request protocol

  • %{varName}i The request header named varName, or dash if unset; for security the value is escaped as if a C literal string

  • %k Number of Keep-Alives performed on this socket; i.e. one less than the number of transactions performed

  • %l Remote logname via identd; unimplemented, always a dash

  • %m Request method (e.g. "GET")

  • %{varName}n Apache module note named varName; unimplemented, always a dash

  • %{varName}o Reply header named varName; unimplemented, always a dash

  • %{varName}p Canonical server port; varName is optional and may be "canonical" for canonical server port (e.g. 80), "local" for local port (same as canonical), or "remote" for remote port

  • %{varName}P PID of process servicing the transaction; varName is optional and may be "pid" for PID, "tid" for thread ID, or "hextid" for the thread ID in hexadecimal

  • %q Request query string (with "?"), or empty if none

  • %r Request line; escaped as C literal string for security

  • %R Handler-generated request; unimplemented, always a dash

  • %s Status code (e.g. 200)

  • %>s Final status code (e.g. 200); same as %s

  • %{varName}t Timestamp when request started; varName may be a strftime() date format; the default is "[%d/%b/%Y:%H:%M:%S %z]". The prefix "begin:" may be prepended for the time the transaction began, or "end: for the time the transaction ended.

  • %T Length of time in seconds for transaction

  • %u Remote user; unimplemented, always a dash

  • %U URL path of request, without query string; URL-decoded

  • %v Canonical server name

  • %V Same as %v

  • %X Connection status: "X" if connection error/aborted, "+" if connection is reusable (via Keep-Alive), "-" if not reusable

  • %I Number of bytes received (including request line and headers); unimplemented, always a dash

  • %O Number of bytes sent (including request line and headers); unimplemented, always a dash

  • %S Number of bytes received and sent (including request line and headers); unimplemented, always a dash

  • %{varName}/ Non-Apache extension: print the resource statistic varName; one of the following:

    • UserTime

    • SystemTime

    • RealTime

    • MaxResidentSetSize

    • IntegralSharedMemSize

    • IntegralUnsharedDataSize

    • IntegralUnsharedStackSize

    • MinorPageFaults

    • MajorPageFaults

    • Swaps

    • BlockInputOps

    • BlockOutputOps

    • MessagesSent

    • MessagesReceived

    • SignalsReceived

    • VoluntaryContextSwitches

    • InvoluntaryContextSwitches
    The value is scaled, i.e. it may have a size suffix such as "K" appended. The varName given may have one of the prefixes "self", "children", "both" or "thread" prepended, with a period between it and the rest of varName. Such a prefix alters which statistics group varName is printed from, as per the Unix getrusage() call; the default is children for the Monitor web server and self for vhttpd. Not all platforms support all groups, nor all statistic names. Unsupported statistics are printed as a dash.

Apache's status-code qualifier prefix syntax is supported: after the "%", a comma-separated list of status codes may be given, indicating that the format code is only to be printed if the response status matches one of the codes. E.g. "%404,500{User-Agent}i" only logs the user agent on 404 or 500 responses. An exclamation point preceding the list negates it, i.e. the format is printed if the response status does not match one of the codes. The Apache "<" and ">" modifiers are also supported (though essentially ignored, since there is only one request).

The Log Format setting was added in version 7.01.1384824000 20131118.

Types Config
Default: %INSTALLDIR%/conf/mime.types
Extension-to-Content-Type config file. Relative to install dir if not absolute path. Added in version 5.01.1251952000 20090903.

Encodings Config
Default: %INSTALLDIR%/conf/mime.encodings
Extension-to-Content-Encoding config file. Relative to install dir if not absolute path. Added in version 5.01.1251952000 20090903.

Max Backlog
Default: 0
The maximum backlog of pending connections the OS should keep. 0 indicates the OS default should be used. Added in version 4.02.1036450486 Nov 4 2002.

Timeout
Default: 30
The network timeout in seconds. Note that per-script Vortex timeout applies when Vortex scripts are running. Added in version 4.02.1036450486 Nov 4 2002. May be -1 for no timeout.

User
Default: unset
Windows only: local user to run CGI texis as. If unset, same user as the running monitor server process. See discussion of the Vortex <exec> option USER for caveats and permission requirements. Added in version 4.04.1071892000 20031219.

Pass
Default: unset
Windows only: password to login User. Required if User is set. Note: password is in plain text; use EncPass setting instead. Overrides EncPass. Added in version 4.04.1071892000 20031219.

EncPass
Default: unset
Windows only: encrypted password to login User. Create by running monitor -E from the command-line. Added in version 4.04.1071892000 20031219.

Fast Logon
Default: 0
Windows only: if nonzero, fast logon method for User. Not recommended; see discussion of the Vortex <exec> flag FASTLOGON for caveats and permission requirements. Added in version 4.04.1071892000 20031219.

Max Clients
Default: 32
The maximum number of simultaneous connections (clients) allowed. Added in version 4.02.1036450486 Nov 4 2002.

Max Header Size
Default: 4096
The maximum total HTTP header size to accept, in bytes. Added in version 4.02.1036450486 Nov 4 2002.

Live Output
Default: 1
If nonzero, propagate CGI texis output "live", i.e. do not delay until server buffer is full. Added in version 5.01.1172190000 20070222.

Vortex Path
Default: unset
The URL path prefix to interpret as Vortex scripts. Typically set to /texis. Added in version 4.02.1036450486 20021104. While the overall path is a prefix, each path component must match fully to requests: e.g. given the Vortex Path /texis, the URL request /texis/subdir/script will run the script subdir/script, but the URL request /texisation/subdir/script will not run a script (i.e. will be treated as a flat file request unless otherwise mapped). Note that currently scripts are run via a separate CGI process, not directly as vhttpd does. Amongst the standard CGI environment variables, in version 6 and later the variable HTTPS is set to on if SSL Engine is on. It is unset if SSL Engine is optional or off: this allows scripts that use HTTPS to compute the scheme (protocol) prefix to the request URL to work. If the response will be secure/SSL, i.e. SSL Engine is on, or optional and the connection was RFC 2817 upgraded, the variable SSL_PROTOCOL will be set to the SSL protocol in use: one of SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2, or TLSv1.3. Note that the request might have been insecure, e.g. if SSL Engine is optional and the connection was upgraded on the main request instead of an earlier (OPTIONS) request.

Vortex By Ext Path
Default: unset
The URL path to interpret as a Vortex script, by extension. A request in this path with a "subdirectory" component that ends in one of the non-empty Vortex Source Extensions or the Vortex Compiled Extension will be run as a Vortex script. Typically set to /; e.g. the request /dir/subdir/script.vs/func.html would run the script dir/subdir/script.vs in the ScriptRoot dir. Added in version 5.01.1182883000 20070626. Note that Vortex Source Extensions typically only contains non-empty values (e.g. .vs) in Version 6.

Texis Exe
Default: %BINDIR$/texis (with .exe appended if Windows)
The executable (and optional arguments) to run Vortex scripts. Added in version 4.02.1036450486 Nov 4 2002. Note that since the Texis Monitor web server runs Vortex scripts via a separate CGI process, and Vortex ignores command line arguments by default in CGI mode for security, any arguments will likely be ignored (unless permitted via [Texis] Allow Cgi Command Line Options).

Index Files
Default: index.html (and index.htm if Windows)
What files to send as a directory's contents, as a space-separated list. Added in version 4.02.1036450486 Nov 4 2002.

Directory Indexing
Default: 1
Nonzero: list a directory's contents and links when no index file is present. Added in version 4.02.1036450486 Nov 4 2002.

Directory Robots Index
Default: 0
Nonzero: the <meta> robots tag on automatic directory index pages should indicate (via index that the page should be indexed by web crawlers. Zero indicates (via noindex) that the page should not be indexed. Added in version 5.01.1225747000 20081103.

Directory Robots Follow
Default: 1
Nonzero: the <meta> robots tag on automatic directory index pages should indicate (via follow) that the pages' links should be followed by web crawlers. Zero indicates (via nofollow) that the links should not be followed. Added in version 5.01.1225747000 20081103.

Multi Views
Default: 0
If on or non-zero, allow content-negotiated variant files to be served. With this option enabled, if a requested file is not found as named, files with the same name but additional recognized file extensions (for MIME types and/or encodings) will be searched for. The files will be ranked according to the client's Accept-... header preferences, and the highest-ranked file will be served. Applies to implicit Index Files files too. For example, a request for "/dir/file" might return "/dir/file.html", "/dir/file.txt.gz" etc. If variant(s) are found but are not deemed acceptable according to the client's Accept-... headers, a 406 Not Acceptable response may result. Currently, only the Accept-Encoding client header is respected. Added in version 5.01.1251952000 20090903.

Allow File Mask
Default: o=r
Only allow access to files in Document Root with at least one of these permission bits set. Note that files must still be accessible by User (if set). Added in version 5.01.1147373599 20060511.

Allow Dir Mask
Default: o=r
Only allow access to directories in Document Root with at least one of these permission bits set. Note that directories must still be accessible by User (if set). Added in version 5.01.1147373599 20060511.

Pass Env
Default: unset
Space-separated list of environment variables to pass through from the web server's environment to the Vortex CGI environment. Default is none. Only a minimal CGI environment is normally set for security. This setting can be used to pass through variables like LD_LIBRARY_PATH if needed. Use with caution. Added in version 4.02.1047673208 Mar 14 2003.

In addition, all "settings" in the [Httpd Set Env] section are taken as environment variable assignments to pass to the CGI environment. This allows environment variables which aren't set in the web server's environment to be set in the CGI environment. Added in version 4.02.1047663381 Mar 14 2003.

Bad Content Length Work Around
Default: 1
If bit 0 is set, try to read any extra socket input after the request. This works around a Microsoft Internet Explorer bug that causes connection-reset browser errors. If bit 1 is set, log such events. Added in version 5.01.1159558662 20060929.

Trace Requests
Default: 0
Enable debug tracing of monitor web server requests to monitor.log. This is an integer combination of bit flags to determine what is logged; see the <urlcp verbose> documentation for details, as this is the same format.

This is generally only set at the request of tech support. Some flags currently unsupported (e.g. all document flags). Added in version 5.01.1184720000 20070717. Previous to version 7.07.1545428000 20181221 only the request/response lines/headers flags existed, and were 4x (2 bit positions) smaller.

Flags supported:

  • 0x0004: response lines sent

  • 0x0008: request lines read

  • 0x0010: response headers sent

  • 0x0020: request headers read

Trace Auth
Default: 0
Enable debug tracing of authorization in monitor web server requests. This is an integer combination of bit flags in the same format as the Vortex <urlcp traceauth> setting. Generally only set at the request of tech support. Added in version 5.01.1184720000 20070717.

Max Conn Requests
Default: 100
Maximum number of requests to service on a Keep-Alive connection to the monitor web server. -1 is unlimited. Added in version 6.

Max Conn Lifetime
Default: 60
Maximum lifetime of a Keep-Alive connection to the monitor web server, in seconds. -1 is unlimited. Added in version 6.

Max Conn Idle Time
Default: 5
Maximum idle (not-in-use) time of a Keep-Alive connection to the monitor web server, in seconds. -1 is unlimited. Added in version 6.

SSL Engine
Default: off
Whether to use secure sockets (SSL) for incoming monitor web server connections. One of three values:

  • off: Listen for HTTP requests, do not use SSL. None of the following SSL settings are used.

  • optional: Listen for HTTP requests, but upgrade to HTTPS (SSL) if client agrees via Upgrade header.

  • on: Listen for HTTPS requests (use SSL).

If set to on, the default port value becomes 443 instead of 80. Added in version 6. If there is a problem initializing the SSL layer, an error such as "SSL disabled for web server due to previous errors" may result in monitor.log, after other errors (e.g. failed to load certificate): the web server will continue to run, but as if SSL Engine was off.

SSL Pass Phrase Dialog
Default: off
How to prompt for passwords when needed for loading password-protected certificate keys for the monitor web server. Can be:

  • off: Do not prompt; password-protected keys will not be loaded

  • builtin: Use the built-in prompter: ask for password at Texis Monitor startup. This requires that the monitor be started interactively, i.e. from the command line.
The default is off, so that the monitor may always start unimpeded, even from the command line when password prompting might be possible.

If a server is started with a password-protected key, but SSL Pass Phrase Dialog is set to off, an error such as "Cannot obtain password to decrypt SSL certificate key `.../server.key': [Httpd] SSL Pass Phrase Dialog is `off'" may result in monitor.log. If SSL Pass Phrase Dialog is set to builtin and an incorrect password is given when the monitor server is started (and prompts the user), the error "Cannot parse SSL certificate key `.../server.key': Bad password" may result in the log and the error "Failed to load SSL certificate key .../server.key" may be output to the user starting the monitor.

Note: if builtin is set, the monitor must be started manually on the command line, so that it can prompt for any needed password(s). Setting added in version 6. See also the [Scheduler] SSL Pass Phrase Dialog setting for the schedule/license server, here.

SSL Certificate File
Default: %INSTALLDIR%/conf/ssl/certs/server.cert
The path to the SSL server certificate file (in PEM format) to use for the monitor web server. A certificate file is required if SSL Engine is not off. If SSL Certificate Key File is unset, the corresponding certificate key will also be loaded from this file. Can also be the same file as SSL Certificate Chain File (if the certificate is in there). Added in version 6.00.1317693000 20111003 (note that in earlier version 6 releases, SSL Certificate Chain File was used to load the server certificate, and the certificate key was never loaded from that file).

The server certificate file is provided by the administrator. One way to create a certificate and unencrypted private key if they do not exist is with the command: 

/usr/local/morph3/etc/openssl req -new -x509 -nodes -days 3653 \
    -out server.cert -keyout server.key
See http://www.openssl.org/ for more on the openssl command.

If the server certificate file is missing, an error such as "Cannot read SSL certificate .../server.cert: No such file or directory" may result in monitor.log.

SSL Certificate Key File
Default: unset (%INSTALLDIR%/conf/ssl/keys/server.key prior to version 6.00.1317693000 20111003)
The path to the SSL certificate private key file (in PEM format) that corresponds to the SSL Certificate File certificate set for the monitor web server. This file is provided by the administrator. A certificate key is required if SSL Engine is not off. If this setting is unset (the default), the certificate key is assumed to be concatenated into SSL Certificate File. Added in version 6. Note: This file should be accessible only to the Texis Monitor server, i.e. the monitor owner. See the openssl example above for an example of how to create this file if it does not exist.

If the SSL certificate key is password-protected, SSL Pass Phrase Dialog will need to be set to "builtin" to allow the monitor to prompt for the password at server start; otherwise an error such as "Cannot obtain password to decrypt SSL certificate key" will result.

If the certificate key file is missing, an error such as "Cannot read SSL certificate key `.../server.key': No such file or directory" may result in monitor.log.

SSL Certificate Chain File
Default: unset
Optional path to monitor web server certificate's CA (certificate authority) chain file, PEM format. This file contains the chain of CA certificates (if any) for the server certificate, in order, starting with the CA certificate that signed the server certificate, the CA certificate that signed that CA certificate, etc. up through the root/self-signed CA certificate. The server certificate itself may also optionally be combined into this file, if it is the first certificate listed and SSL Certificate File is also set to this file: this allows the server plus chain certificates to all be in one file. Added in version 6 (note that in versions prior to 6.00.1317693000 20111003, this setting also loaded the server certificate).

Setting a CA chain for the server certificate may be needed so that a web browser can trust the server. If the server certificate was not signed by a well-known CA that the browser already trusts, the browser might give an SSL/certificate/security error to the user. Supplying the CA chain - up through a well-known root CA certificate - lets the browser follow that chain to the well-known root CA that it trusts, avoiding the security error.

Note that this setting only sets the server certificate CA chain; it does not alter what CA certificates the server trusts for authentication of clients (see SSL CA Certificate File).

Note also that if further CA certificates are needed to finish the server certificate's chain (due to SSL Certificate Chain File being unset or incomplete), the server may automatically obtain them from the SSL CA Certificate File. Since SSL CA Certificate File certificates are trusted whereas SSL Certificate Chain File certificates are not, it is best to add all needed server certificate chain certificates directly via SSL Certificate Chain File, and not implicitly via SSL CA Certificate File. For example, say the server certificate's issuer is a well-known Thawte certificate, but the server also wants to do authentication of clients and only trust clients with certificates issued by a local issuer (say Acme Co.). The Acme certificate should be the only certificate in the SSL CA Certificate File file - so that the server trusts only client certificates issued by Acme. The well-known Thawte certificate should only be in SSL Certificate Chain File - so that browsers can verify the server. If the Thawte certificate were in SSL CA Certificate File, the server chain would still be completed correctly, but the server would start trusting all clients with Thawte certificates - which is not what is desired.

SSL CA Certificate File
Default: unset
Optional file with trusted CA certificates (PEM format), used by monitor web server for authentication of clients. When such authentication is enabled (see SSL Verify Client), clients are asked to present a certificate; the certificate is trusted only if its root certificate is signed by one of the CAs listed in this file. Note that this file may also possibly be used for automatic completion of the server certificate CA chain, if not all needed CA certificates are found in SSL Certificate Chain File; see the SSL Certificate Chain File setting discussion on why this is not usually the best practice.

Added in version 6.00.1318364000 20111011.

SSL CA DN Request File
Default: unset
Optional file with CA issuer certificates (PEM format) whose names are sent to the client when the client certificate is requested by the monitor web server, during authentication of clients (see SSL Verify Client). The client can choose the certificate it wishes to return based on these acceptable issuer CAs. Some browsers will show the user this list, as an aid in choosing which client certificate to return (i.e. preferably one signed by one of these issuers). If this setting is unset (the default), the list of CA issuer names sent to the client is obtained from SSL CA Certificate File instead.

Note that while this setting (SSL CA DN Request File) sets the list of requested CAs, it does not set the list of CAs that are actually trusted by the server - that is controlled by SSL CA Certificate File. Usually these lists are the same, and hence this setting may be left unset. But sometimes they differ, e.g. if client certificates are signed by intermediate CAs: the requested list may need to be set differently with this setting, to prompt the user more correctly. Added in version 6.00.1318364000 20111011.

SSL Verify Client
Default: off
Whether the monitor web server should ask for and verify SSL client certificates. Verification is enabled if on, disabled if off (the default).

If on and a client certificate cannot be obtained or verified, the connection will be terminated with a server error such as "Cannot verify certificate from host:port: reason at depth N". The specific reason may vary; see the SSL Client/Server Certificate Verification appendix of the Vortex manual for a full list. The client/browser may see an error such as "SSL peer was unable to negotiate an acceptable set of security parameters / ssl_error_handshake_failure_alert", or "Cannot complete SSL handshake: ... alert bad certificate".

The Apache-compatible setting values none and require are also permitted, as aliases for on and off, respectively. The Apache value optional is also permitted - client certificates will be requested and must be verified if presented, but if no certificate is presented the connection continues. (This is a less secure value but may be useful for debugging, development etc.)

When asking for the client certificate, the server will present a list of names of certificate authorities (CAs): the client may choose which certificate to return based on this list. This list is obtained from SSL CA DN Request File if set, or SSL CA Certificate File if the former is unset.

The SSL Verify Client setting was added in version 6.00.1318364000 20111011.

SSL Verify Depth
Default: 1
The max client certificate chain depth to verify, if client verification is performed (see SSL Verify Client).

SSL Protocol
Default: all -SSLv2 -SSLv3 (in versions before 7.02.1413403000 20141015: all -SSLv2)
Which SSL protocol(s) to use when SSL is active for the monitor web server. One or more of the space-separated protocols SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3, or all for all protocols. An action may optionally be prefixed to any protocol: + to add the protocol to the enabled list, - to remove, or = to set (enable just this protocol - this is the default action). Setting added in version 6. (Prior to version 7.02.1413403000 20141015, the default was all -SSLv2. Prior to version 7.03, TLSv1.1 and TLSv1.2 were unsupported. Prior to version 7.07, TLSv1.3 was unsupported.) Note that support for vulnerable protocols may end in some Texis versions, depending on the concurrent OpenSSL libs' support: e.g. SSLv2 is no longer supported in OpenSSL 1.1.0 and later (used in Texis version 7.06.1534958000 20180822 and later).

SSL Cipher Suite
Default: unset
Which SSL ciphers to use when SSL is active for the monitor web server. The syntax is the same as for the Apache SSLCipherSuite directive, which use the OpenSSL ciphers tool syntax for ciphers. Note that support for some (e.g. vulnerable) ciphers may end in some Texis versions, depending on the concurrent OpenSSL libs' support: e.g. 40- and 56-bit ciphers are no longer supported in OpenSSL 1.1.0 and later (used in Texis version 7.06.1534958000 20180822 and later). Also, the list of ciphers classified as LOW, EXPORT etc. may change. Setting added in Texis version 7.06.1534958000 20180822. May be given multiply to set ciphers for multiple protocols.

In version 7.07 and later, an optional cipher group may be given as the first space-separated token in the setting value, to set the cipher list for that protocol group. The group may be SSL (the default) for protocols TLSv1.2 and below, or TLSv1.3 for TLSv1.3 ciphers; the cipher lists for the two groups are independent.

Copyright © Thunderstone Software     Last updated: Apr 15 2024

 

Copyright © 2024 Thunderstone Software LLC. All rights reserved.