Environment variables set by HTTP Server
The IBM® HTTP Server for i supports the standard environment variables in addition to environment variables that are unique to the IBM i server.
When using application programming interfaces to retrieve the value
of an environment variable, you need to handle the case in which there
is no value for the environment variable. For example, when a CGI
program is trying to do a getenv(″CONTENT_LENGTH″) and
the request method is GET, the value returned is NULL.
The reason NULL is returned for the value is because CONTENT_LENGTH is
only defined for POST request methods (to describe
the length of standard input).
The following table lists the environment variables supported by HTTP Server. The environment variables have been divided into two groups: Non-SSL and SSL.
Notes:
- All headers sent by a client (such as Set-Cookie) are prefixed
by "
HTTP_". To access the value of a header, prefix the header name with "HTTP_". - In the following table, long variable names are shortened by the insertion of a blank character within the name. This is done for display purposes only.
| Variable Name | Type | Description |
|---|---|---|
| AUTH_TYPE | Non-SSL | If the server supports client authentication
and the script is a protected script, this environment variable contains
the method that is used to authenticate the client. Example: Cert_Or_Basic |
| CGI_ASCII_CCSID | Non-SSL | Contains the ASCII CCSID the server used when
converting CGI input data. If the server did not perform any conversion,
(for Example, in %%BINARY%% mode), the server sets this value to the
DefaultNetCCSID configuration directive value. Example: 819 |
| CGI_EBCDIC_CCSID | Non-SSL | Contains the EBCDIC CCSID under which the current
CGI job is running (DefaultFsCCSID or CGIJobCCSID configuration directive).
It also represents the job CCSID that is used during server conversion
(if any) of CGI input data. Example: 37 |
| CGI_JOB_LOCALE | Non-SSL | Allows a locale to be set globally or for a
specific CGI job. After the locale is set, region specific information
such as date or time format can be accessed. Some ILE C/C++ run-time
functions such as ctime() and localtime() are locale sensitive. Example: CGIJobLocale /QSYS.LIB/LOCALELIB.LIB/EN_US.LOCALE |
| CGI_MODE | Non-SSL | Contains the CGI conversion mode the server
is using for this request. The program can use this information to
determine what conversion, if any, was performed by the server on
CGI input data and what format that data is currently in. Example: EBCDIC |
| CGI_OUTPUT_MODE | Non-SSL | Determines which output conversion mode the
server is using. Example: EBCDIC |
| CONTENT_LENGTH | Non-SSL | When the method of POST is used to send information,
this variable contains the number of characters. Servers typically
do not send an end-of-file flag when they forward the information
by using stdin. If needed, you can use the CONTENT_LENGTH value to
determine the end of the input string. Example: 7034 |
| CONTENT_TYPE | Non-SSL | When information is sent with the method of
POST, this variable contains the type of data included. You can create
your own content type in the server configuration file and map it
to a viewer. Example: Application/x-www-form-urlencoded |
| DATE_GMT | Non-SSL | The current date and time in Greenwich Mean
Time. Example: 2000/12/31:03:15:20 |
| DATE_LOCAL | Non-SSL | The current date and time in the local time
zone. Example: 2000/08/14:15:40:10 |
| DOCUMENT_NAME | Non-SSL | The file name of the document requested by the
user. Example: /www/myserver/htdocs/html/hello.html |
| DOCUMENT_PATH_INFO | Non-SSL | Contains the additional path information as
sent by the Web browser for SSI. Example: /wizard |
| DOCUMENT_ROOT | Non-SSL | Sets the directory from which the HTTP Server
will serve files. The server appends the path from the requested URL
to the document root and makes the path to the document. Example: /www/myserver/htdocs |
| DOCUMENT_URI | Non-SSL | The URI of the document requested by the user.
Example: /html/hello.html Note: The DOCUMENT_URI and DOCUMENT_URL
environment variables are identical
|
| DOCUMENT_URL | Non-SSL | The URL of the document requested by the user. Example: /html/hello.html Note: The DOCUMENT_URI
and DOCUMENT_URL environment variables are identical.
|
| FSCP | Non-SSL | The EBCDIC CCSID used to translate the data.
Example: 37 |
| GATEWAY_INTERFACE | Non-SSL | Contains the version of CGI that the server
is using. Example: CGI/1.1 |
| HTTP_ACCEPT | Non-SSL | Contains the list of MIME types the browser
accepts. Example: image/gif,image/x-xbitmap,image/jpeg,image/pjeg,image/pgn,*/* Note: The
header lines received from the client, if any, are placed into the
environment variable with the prefix HTTP_* followed by the header
name. The header returns the environment variable.
|
| HTTP_ACCEPT_CHARSET | Non-SSL | Contains the list of character sets the browser
accepts. Example: iso-8859-1,*,utf-8 Note: The header lines
received from the client, if any, are placed into the environment
variable with the prefix HTTP_* followed by the header name. The header
returns the environment variable.
|
| HTTP_ACCEPT_ENCODING | Non-SSL | Contains the list of encoding protocols the
browser accepts. Example: gzip Note: The header lines received
from the client, if any, are placed into the environment variable
with the prefix HTTP_* followed by the header name. The header returns
the environment variable.
|
| HTTP_ACCEPT_ LANGUAGE | Non-SSL | Contains the list of languages the browser accepts.
Example: de,fr,en Note: The header lines received from the
client, if any, are placed into the environment variable with the
prefix HTTP_* followed by the header name. The header will return
the environment variable.
|
| HTTP_CONNECTION | Non-SSL | The header lines received from the client, if
any, are placed into the environment variable with the prefix HTTP_*
followed by the header name. The header returns to the environment
variable. Example: Keep-Alive |
| HTTP_COOKIE | Non-SSL | User-defined cookie for the response. Example: w3ibmTest=true |
| HTTP_HOST | Non-SSL | Contains the HTTP host URL. Example: IBM.COM Note: The
header lines received from the client, if any, are placed into the
environment variable with the prefix HTTP_* followed by the header
name. The header returns the environment variable.
|
| HTTP_USER_AGENT | Non-SSL | Contains the name of your browser (web client).
It includes the name and version of the browser, requests that are
made through a proxy, and other information. Example: Mozilla/4.72 [en ](WinNT;U) Note: The header lines received from the client,
if any, are placed into the environment variable with the prefix HTTP_*
followed by the header name. The header returns the environment variable.
|
| IBM_CCSID_VALUE | Non-SSL | The CCSID under which the current server job
is running. Example: 37 |
| NETCP | Non-SSL | The default ASCII CCSID used to translate the
data. Example: 819 |
| PATH_INFO | Non-SSL | Contains the additional path information as
sent by the web browser. Example: /wizard |
| PATH_TRANSLATED | Non-SSL | Contains the decoded or translated version of
the path information that is contained in PATH_INFO, which takes the
path and does any virtual-to-physical mapping to it. Example: /wwwhome/wizard |
| QIBM_CGI_LIBRARY_LIST | Non-SSL | This variable is used to set the CGI jobs' library list. The variable can be set using the SetEnv directive. See the SetEnv directive for more information. |
| QUERY_STRING | Non-SSL | When information is sent using a method of GET,
this variable contains the information in a query that follows the
"?". The string is coded in the standard URL format of changing spaces
to "+" and encoding special characters with "%xx" hexadecimal encoding.
The CGI program must decode this information. Example: NAME=Eugene+T%2E+Fox=etfox%7Cibm.net=xyz Note: The
supported maximum size of QUERY_STRING is 8K for HTTP Server.
|
| QZHBHA_MODEL | Non-SSL | Model of the highly available Web server. Example: PRIMARYBACKUP |
| QZHBIS_FIRST_REQUEST | Non-SSL | This environment variable indicates to a CGI
program if this is a subsequent request of some session. The Web server
sets this variable to 1 if this is not a subsequent request of any
session (this is potentially the first request of a new session).
The Web server sets this variable to 0 if this is a subsequent request
of some session. Example: 0 |
| QZHBIS_CLUSTER_ENABLED | Non-SSL | This environment variable indicates to the CGI
program that the CGI program is allowed to be cluster-enabled if the
request does not belong to any existing session (QZHBIS_FIRST_REQUEST
is set to 1). This environment variable indicates to the CGI program
that the CGI program is cluster-enabled (QZHBIS_FIRST_REQUEST set
to "0"). When the Web server receives a first request to a CGI, it
decides if the CGI program is allowed to be cluster-enabled. If the
CGI program is allowed to be cluster-enabled, the Web server sets
the QZHBIS_CLUSTER_ENABLED environment variable to 1; otherwise the
Web server does not define the QZHBIS_CLUSTER_ENABLED environment
variable. When the Web server receives a subsequent request to a CGI,
it looks to see if the session is cluster-enabled. If the session
is cluster-enabled, the Web server sets the QZHBIS_CLUSTER_ENABLED
environment variable to 1; otherwise the Web server does not define
the QZHBIS_CLUSTER_ENABLED environment variable. Example: 1 |
| QZHBNEXT_SESSION_HANDLE | Non-SSL | This environment variable contains a new session
handle for a CGI program to use. If the CGI program is cluster-disabled,
it may ignore this session handle. The Web server generates a session
handle and sets the QZHBNEXT_SESSION_HANDLE environment variable to
this value. If the CGI program decides to be cluster-enabled, it must
use the passed session handle in the URLs of subsequent requests;
otherwise, the Web server will not associate subsequent requests with
this session. Example: 8B739003AB741824899F0004AC009021 |
| QZHBRECOVERY | Non-SSL | Contains whether the highly available Web server has gone through a recovery (primary to backup or backup to primary). If this environment variable is present, recovery has occurred. If it is not present, then recovery has not occurred |
| REDIRECT_QUERY_STRING | Non-SSL | Contains QUERY_STRING from a re-directed request.
Example: NAME=Eugene+T%2E+Fox=etfox%7Cibm.net=xyz |
| REDIRECT_QUERY_URL | Non-SSL | This environment variable is used in the primary/backup
models only. This environment variable is used to indicate to a cluster-enabled
CGI program that it should perform a recovery operation (for example,
restore its state). The Web server passes a session handle to the
CGI program through the QZHBRECOVERY environment variable. The Web
server passes the CGI's state to the CGI program. If there is no recovery,
this environment variable is undefined. In the primary/backup model,
the high availability CGI is also treated as a persistent CGI. The
high availability CGI state information can also be retained in the
CGI job. The next request for the next step in the CGI is automatically
run in the same job. Therefore, the CGI program can skip reading its
state unless this environment variable is defined. Example: 4D868803AB731824899F0004AC009021 |
| REFERER | Non-SSL | Contains the referrer. Example: http://www.myserver.com/cgi-bin/ |
| HTTP_REFERER | Non-SSL | Contains the referrer. Example: http://www.myserver.com/cgi-bin/ |
| REFERER_URL | Non-SSL | Contains the referrer URL. Example: http://WWW.MYSERVER.COM:8080/perlSetEnv/ |
| REMOTE_ADDR | Non-SSL | Contains the IP address of the remote host (web
browser) that is making the request, if available. Example: 10.10.2.3 |
| REMOTE_PORT | Non-SSL | Contains the remote user port number. Example: 3630 |
| REMOTE_IDENT | Non-SSL | Contains the user ID of the remote user. Example: MyIdentityx |
| REMOTE_USER | Non-SSL | If you have a protected script and the server
supports client authentication, this environment variable contains
the user name that is passed for authentication. Example: SMITH |
| REQUEST_METHOD | Non-SSL | Contains the method (as specified with the METHOD
attribute in an HTML form) that is used to send the request. Example: GET |
| REQUEST_URI | Non-SSL | Specifies URI to be requested. Example: /cgi-bin/hello.pgm |
| RULE_FILE | Non-SSL | Specifies rule file to be used. Example: /www/myserver/conf/httpd.conf |
| SCRIPT_FILENAME | Non-SSL | The file name of the document requested by the
user. Example: /QSYS.LIB/CGI.LIB/HELLO.PGM |
| SCRIPT_NAME | Non-SSL | A virtual path to the program being run. Use
this for self-referring URLs. Example: /cgi-bin/hello.pgm |
| SERVER_ADDR | Non-SSL | Contains the address of the server. Example: 10.10.2.3 |
| SERVER_ADMIN | Non-SSL | Contains information about the server administrator.
Example: [no address given ] |
| SERVER_NAME | Non-SSL | Contains the server host name or IP address
of the server. Example: 10.9.8.7 |
| SERVER_PORT | Non-SSL | Contains the port number to which the client
request was sent. Example: 2001 |
| SERVER_PROTOCOL | Non-SSL | Contains the name and version of the information
protocol that is used to make the request. Example: HTTP/1.0 |
| SERVER_SIGNATURE | Non-SSL | Allows configuration of a trailing footer line
under server generated documents like error messages, mod_proxy ftp
directory listings, and mod_info output. Enabling the footer line
allows the user to tell which chained servers in a proxy chain produced
a returned error message. Example: On |
| SERVER_SOFTWARE | Non-SSL | Contains the name and version of the information
server software that is answering the request. Example: IBM-HTTP-SERVER/1.0 |
| SSI_DIR | Non-SSL | The path of the current file relative to SSI_ROOT.
If the current file is in SSI_ROOT, this value is "/". Example: ssi_child_dir/ |
| SSI_FILE | Non-SSL | The file name of the current file. Example: ssi_parent.shtml |
| SSI_INCLUDE | Non-SSL | The value that is used in the include command
that retrieved this file. This is not defined for the topmost file.
Example: ssi_child_dir/ssi_child.shtml |
| SSI_PARENT | Non-SSL | The path and file name of the include, relative
to SSI_ROOT. Example: ssi_parent.shtml |
| SSI_ROOT | Non-SSL | The path of the topmost file. All include requests
must be in this directory or a child of this directory. Example: #echo var=SSI_DIR -> Note: You can use echo to display a value
set by the set or global directives.
|
| UNIQUE_ID | Non-SSL | Provides a unique magic token and acts as the
identifier across all requests under very specific conditions. Example: aK8YOAkFBZkAABsuEC4AAACB |
| HTTPS | SSL | Returns ON if the system has completed
an SSL handshake. It returns OFF if the exchange of signals
to set up communications between two modems has failed. Example: OFF |
| HTTPS_CIPHER | SSL | This is the cipher that is used to negotiate
with the client on the SSL handshake. Example: SSL_RSA_WITH_RC4_128_MD5 |
| HTTPS_CLIENT_CERT | SSL | The entire certificate passed to the server
from the client browser when SSL client authentication is enabled.
The format of the certificate is a BASE64 encoded string that represents
the DER format of the X.509 certificate. As an environment variable
the BASE64 encoded string has been converted to EBCDIC and must be
converted back to ASCII before it can be used for typical digital
certificate API's. Example: MIIC0DCCAbigAwIBAgIHOL2Yx... |
| HTTPS_CLIENT_ CERT_COMMON_NAME | SSL | The common name from the client certificate's
distinguished name. Example: SMITH |
| HTTPS_CLIENT_CERT_COUNTRY | SSL | The region code from the client certificate's
distinguished name. Example: US |
| HTTPS_CLIENT_CERT_DN | SSL | The client certificate's distinguished name.
Example: :cn=CAPTAIN,ou=downtown,o=fire fighters,l=Minot,st=North Dakota,c=US |
| HTTPS_CLIENT_CERT_EMAIL | SSL | The email of the client owning the certificate.
Example: me@mycompany.com |
| HTTPS_CLIENT_CERT_ISSUER_ COMMON_NAME | SSL | The common came of the certificate authority
that issued the client's certificate. Example: SMITH |
| HTTPS_CLIENT_CERT_ISSUER_ COUNTRY | SSL | The region code of the certificate authority
that issued the client's certificate. Example: US |
| HTTPS_CLIENT_CERT_ISSUER_DN | SSL | The distinguished name of the certificate authority
that issued the client's certificate. Example: :cn=testsystem.ibm.com CA,ou=Test Organization Unit,o=System test, l=Rochester,st=Minnesota,c=US |
| HTTPS_CLIENT_CERT_ISSUER_ EMAIL | SSL | The e-mail address of the certificate authority
that issued the client's certificate. Example: me@mydomain.net |
| HTTPS_CLIENT_CERT_ISSUER_ LOCALITY | SSL | The locality or city of the certificate authority
that issued the client's certificate. Example: New York |
| HTTPS_CLIENT_CERT_ISSUER_ ORG_UNIT | SSL | The organizational unit of the certificate authority
that issued the client's certificate. Example: bird watchers |
| HTTPS_CLIENT_CERT_ISSUER_ ORGANIZATION | SSL | The organization name of the certificate authority
that issued the client's certificate. Example: dove |
| HTTPS_CLIENT_CERT_ISSUER_ POSTAL_CODE | SSL | The postal code of the certificate authority
that issued the client's certificate. Example: 12344-6789 |
| HTTPS_CLIENT_CERT_ISSUER_ STATE_OR_PROVINCE | SSL | The state or province of the certificate authority
that issued the client's certificate. Example: North Dakota |
| HTTPS_CLIENT_CERT_LEN | SSL | The length of the certificate passed in HTTPS_CLIENT_CERT.
Example: 968 |
| HTTPS_CLIENT_CERT_LOCALITY | SSL | The locality or city of the client certificate's
distinguished name. Example: New York |
| HTTPS_CLIENT_CERT_ORG_UNIT | SSL | The organization unit name from the client certificate's
distinguished name. Example: Pack234 |
| HTTPS_CLIENT_CERT_ ORGANIZATION | SSL | The organization name from the client certificate's
distinguished name. Example: Scouts |
| HTTPS_CLIENT_CERT_ POSTAL_CODE | SSL | The postal code assigned by the issueing certificate
authority. Example: 80525 |
| HTTPS_CLIENT_CERT_ SERIAL_NUM | SSL | The serial number assigned by the issuing certificate
authority. Example: 3F:E4:83:81:02:D5:58 |
| HTTPS_CLIENT_CERT_ STATE_OR_PROVINCE | SSL | The state or province from the client certificate's
distinguished name. Example: Alberta |
| HTTPS_CLIENT_ISSUER_EMAIL | SSL | Contains the email address of the Certificate
Authority that issued the certificate. Example: jones@mydomain.net |
| HTTPS_KEYSIZE | SSL | If a valid security product is installed and the SSLMode directive is SSLMode=ON, this will be set to the size of the bulk encryption key used in the SSL session. Example: [ 128 ] |
| HTTPS_SESSION_ID | SSL | Set to NULL by default when used with HTTP Server. |
| HTTPS_SESSION_ID_NEW | SSL | If the value is TRUE, it indicates that
a full handshake was performed for this SSL session. If the value
is FALSE, it indicates that an abbreviated handshake was performed
for this SSL session. Example: True |
| SSL_CIPHER | SSL | This is the cipher that is used to negotiate
with the client on the SSL handshake. Example: SSL_RSA_WITH_RC4_128_MD5 |
| SSL_CLIENT_C | SSL | The region code from the client certificate's
distinguished name. Example: USA |
| SSL_CLIENT_CERTBODY | SSL | The entire certificate passed to the server
from the client browser when SSL Client authentication is enabled.
The format of the certificate is a BASE64 encoded string that represents
the DER format of the X.509 certificate. As an environment variable
the BASE64 encoded string has been converted to EBCDIC and must be
converted back to ASCII before it can be used for typical digital
certificate API's. Example: MIIC0DCC big IB gIHOL2Yx... |
| SSL_CLIENT_CERTBODYLEN | SSL | The length of the certificate passed in SSL_CLIENT_CERT.
Example: 828 |
| SSL_CLIENT_CERT_EMAIL | SSL | The email of the client owning the certificate.
Example: me@mycompany.com |
| SSL_CLIENT_CN | SSL | The common name from the client certificate's
distinguished name. Example: SMITH |
| SSL_CLIENT_DN | SSL | The client's distinguished name. Example: :cn=CAPTAIN,ou=downtown,o=fire fighters,l=Minot,st=North Dakota,c=US HTTPS_CLIENT_CERT_DN :cn=CAPTAIN,ou=downtown,o=fire fighters,l=Minot,st=North Dakota,c=US |
| SSL_CLIENT_ICN | SSL | The common name of the certificate authority
that issued the client's certificate. Example: SMITH |
| SSL_CLIENT_IC | SSL | The region code of the certificate authority
that issued the client's certificate. Example: CA |
| SSL_CLIENT_IDN | SSL | The distinguished name of the certificate authority
that issued the client's certificate. Example: :cn=testsystem.ibm.com CA,ou=Test Organization Unit,o=System test, l=Rochester,st=Minnesota,c=US |
| SSL_CLIENT_EMAIL | SSL | The e-mail of the certificate authority that
issued the client's certificate. Example: me@mycompany.com |
| SSL_CLIENT_IL | SSL | The locality of the certificate authority that
issued the client's certificate. Example: New York |
| SSL_CLIENT_IO | SSL | The organization name of the certificate authority
that issued the client's certificate. Example: bird watchers |
| SSL_CLIENT_IOU | SSL | The organizational unit of the certificate authority
that issued the client's certificate. Example: bird watchers |
| SSL_CLIENT_IPC | SSL | The postal code of the certificate authority
that issued the client's certificate. Example: 55901 |
| SSL_CLIENT_IST | SSL | The state or province of the certificate authority
that issued the client's certificate. Example: MNA |
| SSL_CLIENT_L | SSL | The locality or city of the client certificate's
distinguished name. Example: New York |
| SSL_CLIENT_NEWSESSIONID | SSL | If the value is TRUE, it indicates that
a full handshake was performed for this SSL session. If the value
is FALSE, it indicates that an abbreviated handshake was performed
for this SSL session. Example: True |
| SSL_CLIENT_O | SSL | The organization name from the client certificate's
distinguished name. Example: bird watchers |
| SSL_CLIENT_OU | SSL | The organizational unit name from the client
certificate's distinguished name. Example: bird watchers |
| SSL_CLIENT_PC | SSL | The postal code from the client certificate's
distinguished name. Example: 58401 |
| SSL_CLIENT_SERIALNUM | SSL | The serial number assigned by the issuing certificate
authority. Example: 3F:E4:83:81:02:D5:58 |
| SSL_CLIENT_SESSIONID | SSL | If the value is TRUE, it indicates that
a full handshake was performed for this SSL session. If the value
is FALSE, it indicates that an abbreviated handshake was performed
for this SSL session. Example: True |
| SSL_CLIENT_ST | SSL | The state or province from the client certificate's
distinguished name. Example: North Dakota |
| SSL_PROTOCOL_VERSION | SSL | The SSL protocol version negotiated on the SSL
handshake with the client. Example: SSLV3 |
| SSL_SERVER_C | SSL | The region where the server is located in.
Example: Denmark |
| SSL_SERVER_CN | SSL | The common name from the server certificate's
distinguished name. Example: WWW.MYDOMAIN.COM |
| SSL_SERVER_DN | SSL | The server's distinguished name. Example: :cn=TESTSYSTEM.IBM.COM,ou=MyTestOrganizationUnit, o=Software test, l=Rochester,st=Minnesota,c=US |
| SSL_SERVER_EMAIL | SSL | The e-mail address of the server certificate.
Example: me@mydomain.net |
| SSL_SERVER_L | SSL | The locality of the server certificate's distinguished
name. Example: New York |
| SSL_SERVER_OU | SSL | The organization unit name from the server certificate's
distinguished name. Example: bird watchers |
| SSL_SERVER_O | SSL | The organization name from the server certificate's
distinguished name. Example: bird watchers |
| SSL_SERVER_ST | SSL | The state or province from the server certificate's
distinguished name. Example: North Dakota |
| SSL_UNKNOWNREVOCATION_SUBJECT | SSL | The SSL_UNKNOWNREVOCATION_SUBJECT variable is set whenever a message is logged for SSLUnknownRevocationStatus directive. |
| HTTP_AS_AUTH_PROFILETKN | SSL, Non-SSL | A 32-bit value used to identify or authenticate the user. See the ProfileToken directive for more information. |