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:
  1. 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_".
  2. 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.
Table 1. Environment variables that may be set by the HTTP Server
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.