CGI environment variables

Before running a CGI application or interpreter, Abyss Web Server sets its environment variables in conformity with the CGI/1.1 specification (as described in http://hoohoo.ncsa.uiuc.edu/cgi) and adds variables declared in the Custom Environment Variablestable as well as the system environment variables. Some Abyss Web Server specific variables are also set.

The following list contains the variables documented in the CGI/1.1 specification and some variables commonly set by web servers:

• PATH_INFO: The extra path information, as given in the requested URL. In fact, scripts can be accessed by their virtual path, followed by extra information at the end of this path. The extra information is sent in PATH_INFO.

• PATH_TRANSLATED: The virtual-to-real mapped version of PATH_INFO.

• SCRIPT_NAME: The virtual path of the script being executed.

• SCRIPT_FILENAME and REQUEST_FILENAME: The real path of the script being executed.

• SCRIPT_URI: The full URL to the current object requested by the client.

• URL: The full URI of the current request. It is made of the concatenation of SCRIPT_NAME and PATH_INFO (if available.)

• SCRIPT_URL and REQUEST_URI: The original request URI sent by the client.

• REQUEST_METHOD: The method used by the current request; usually set to GET or POST.

• QUERY_STRING: The information which follows the ? character in the requested URL.

• CONTENT_TYPE: The MIME type of the request body; set only for POST or PUT requests.

• CONTENT_LENGTH: The length in bytes of the request body; set only for POST or PUT requests.

• AUTH_TYPE: The authentication type if the client has authenticated itself to access the script.

• AUTH_USER and REMOTE_USER: The name of the user as issued by the client when authenticating itself to access the script.

• ALL_HTTP: All HTTP headers sent by the client. Headers are separated by carriage return characters (ASCII 13 - \n) and each header name is prefixed by HTTP_, transformed to upper cases, and - characters it contains are replaced by _ characters.

• ALL_RAW: All HTTP headers as sent by the client in raw form. No transformation on the header names is applied.

• SERVER_SOFTWARE: The web server's software identity.

• SERVER_NAME: The host name or the IP address of the computer running the web server as given in the requested URL.

• SERVER_ADDR: The IP address of the computer running the web server.

• SERVER_PORT: The port to which the request was sent.

• GATEWAY_INTERFACE: The CGI Specification version supported by the web server; always set to CGI/1.1.

• SERVER_PROTOCOL: The HTTP protocol version used by the current request.

• REMOTE_ADDR: The IP address of the computer that sent the request.

• REMOTE_PORT: The port from which the request was sent.

• DOCUMENT_ROOT: The absolute path of the web site files. It has the same value as Documents Path.

• INSTANCE_ID: The numerical identifier of the host which served the request. On Abyss Web Server X1, it is always set to 1 since there is only a single host.

• APPL_MD_PATH: The virtual path of the deepest alias which contains the request URI. If no alias contains the request URI, the variable is set to /.

• APPL_PHYSICAL_PATH: The real path of the deepest alias which contains the request URI. If no alias contains the request URI, the variable is set to the same value as DOCUMENT_ROOT.

• IS_SUBREQ: It is set to true if the current request is a subrequest, i.e. a request not directly invoked by a client. Otherwise, it is set to true. Subrequests are generated by the server for internal processing. XSSI includes for example result in subrequests.

If the current request is served by an SSL enabled host, the following SSL related variables are also available:

• SSL_PROTOCOL: The SSL protocol version. It could be SSLv2, SSLv3, or TLSv1.

• SSL_CIPHER and HTTPS_CIPHER: The SSL protocol version. It could be SSLv2, SSLv3, or TLSv1.

• SSL_CIPHER_EXPORT: It is set to true if the cipher is conforming to US export restrictions (i.e. it is limited to 56 bit symmetric keys and 1024 asymmetric keys).

• SSL_CIPHER_USEKEYSIZE and HTTPS_SECRETKEYSIZE: The number of cipher bits currently used.

• SSL_CIPHER_ALGKEYSIZE and HTTPS_KEYSIZE: The maximum number of cipher bits that could be used.

• SSL_SERVER_M_VERSION: The version of the server's certificate.

• SSL_SERVER_M_SERIAL: The serial number of the server's certificate.

• SSL_SERVER_V_START: The date corresponding to the start of the validity the server's certificate.

• SSL_SERVER_V_END: The date corresponding to the end of the validity the server's certificate.

• SSL_SERVER_A_SIG: The algorithm used to sign the server's certificate.

• SSL_SERVER_A_KEY: The encryption type of the private key of the server's certificate.

• SSL_SERVER_S_DN and HTTPS_SERVER_SUBJECT: The value of the subject's DN (distinguished name) of the server's certificate.

• SSL_SERVER_S_DN_component: The value of the component of the subject's DN (distinguished name) of the server's certificate. component can be CN (Common Name), C (Country), ST or SP (State/Province), L (Locality), O (Organization), OU (Organization Unit), T (Title), I (Initials), G (Given Name), S (Surname), D (Description), Email (Contact Email).

• SSL_SERVER_I_DN and HTTPS_SERVER_ISSUER: The value of the issuer's DN (distinguished name) of the server's certificate.

• SSL_SERVER_I_DN_component: The value of the component of the issuer's DN (distinguished name) of the server's certificate.

The Abyss Web Server specific variables provide a means to access to server and host statistics. They are listed below:

• X_ABYSS_STATS_SERVER_UPTIME: The total time in seconds during which the server was up.

• X_ABYSS_STATS_SERVER_CURRENT_UPTIME: The total time in seconds during which the server was up since the last start or restart.

• X_ABYSS_STATS_SERVER_TOTAL: The total number of processed requests for all the hosts. It includes also bad requests that were not targeting a specific host and that resulted in an error.

• X_ABYSS_STATS_SERVER_ERROR: The number of requests for which the server replied by an error.

• X_ABYSS_STATS_SERVER_HTML: The number of requests the server replied to by a document which MIME type was text/html.

• X_ABYSS_STATS_SERVER_IMAGE: The number of requests the server replied to by a document which MIME type starts with image/.

• X_ABYSS_STATS_SERVER_NOTMODIFIED: The number of requests for which the server detected that the requested document has not changed.

• X_ABYSS_STATS_SERVER_OUTPUT: The total size in bytes of the payload sent by the server to the clients.

• X_ABYSS_STATS_SERVER_COMPRESS_TOTAL: The total number of compressed responses for all the hosts.

• X_ABYSS_STATS_SERVER_COMPRESS_OUTPUT_TOTAL: The total size in bytes of the payload sent by the server to the clients in compressed responses.

• X_ABYSS_STATS_SERVER_COMPRESS_ORIGINAL_OUTPUT: The total original uncompressed size in bytes of the payload sent by the server to the clients in compressed responses.

• X_ABYSS_STATS_HOST_UPTIME: The total time in seconds during which the current host was up.

• X_ABYSS_STATS_HOST_CURRENT_UPTIME: The time in seconds during which the current host was up since the last server start or restart.

• X_ABYSS_STATS_HOST_TOTAL: The total number of requests processed by the current host.

• X_ABYSS_STATS_HOST_ERROR: The number of requests targeting the current host that resulted in an error.

• X_ABYSS_STATS_HOST_HTML: The number of requests the current host replied to by a document which MIME type was text/html.

• X_ABYSS_STATS_HOST_IMAGE: The number of requests the current host replied to by a document which MIME type starts with image/.

• X_ABYSS_STATS_HOST_NOTMODIFIED: The number of requests for which the current host detected that the requested document has not changed.

• X_ABYSS_STATS_HOST_OUTPUT: The total size in bytes of the payload sent by the current host to the clients.

• X_ABYSS_STATS_HOST_COMPRESS_TOTAL: The total number of compressed responses for the current host.

• X_ABYSS_STATS_HOST_COMPRESS_OUTPUT_TOTAL: The total size in bytes of the payload sent by the current host to the clients in compressed responses.

• X_ABYSS_STATS_HOST_COMPRESS_ORIGINAL_OUTPUT: The total original uncompressed size in bytes of the payload sent by the current host to the clients in compressed responses.

In addition to these variables, all header lines received in the request are added to the environment with the prefix HTTP_ followed by the header name in upper cases. All - characters in the header name are changed to underscore _ characters. For example, User-Agent is translated to HTTP_USER_AGENT.

If the request results from an internal redirection (from an XSSI document or if it is used as a custom error page for example), the environment variables of the parent request are also added and each variable name is prefixed by REDIRECT_. The parent request's status code is stored in the special variables REDIRECT_STATUS and REDIRECT_STATUS_CODE. The cookies of the parent request are also passed to the redirected request in the COOKIES environment variable. REDIRECT_STATUS_CODE may seem redundant but it is actually useful when with PHP scripts as some PHP configurations require setting REDIRECT_STATUS to a fixed value.

Example 6-1. Using the redirection information in scripts

If a script is invoked after an internal redirection, it can retrieve some interesting information from the environment about its parent request such as:

• REDIRECT_SCRIPT_NAME: The virtual path of the parent document.

• REDIRECT_STATUS_CODE: The status code of the parent request. It is useful when writing scripts that generate custom error pages.

Note: The CGI environment variables are not only useful for CGI applications and interpreters. They are also available and used in XSSI pages and ISAPI interpreters and applications.