# 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 `RFC 3875`) and adds variables declared in the Custom Environment Variables table 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`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, or `TLSv1.3`.

- `SSL_CIPHER` and `HTTPS_CIPHER`: The SSL cipher used to encrypt the current connection.

- `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.

If the current request is served over a HTTP/2 connection, the following variables are also available:

- `HTTP2`: It is set to `on`.

- `H2_STREAM_ID`: A number uniquely identifying the stream within the HTTP/2 connection on which the current request is being served.

- `H2_STREAM_TAG`: A tag uniquely identifying current stream within all HTTP/2 connections of the server. The tag is made of two numbers separated by a hyphen character.

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 also includes bad requests not targeting a specific host and which resulted in an error.

- `X_ABYSS_STATS_SERVER_H2`: The number of processed HTTP/2 requests for all the hosts.

- `X_ABYSS_STATS_SERVER_HTTPS`: The number of processed requests for all the hosts that were made over a secure HTTPS connection.

- `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_H2`: The number of HTTP/2 requests processed by the current host.

- `X_ABYSS_STATS_HOST_HTTPS`: The number of requests targeting the current host which were made over a secure HTTPS connection.

- `X_ABYSS_STATS_HOST_ERROR`: The number of requests targeting the current host which 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.