CGI environment (CGI Scope) variables
When a browser makes a request to a server, the web server and the browser create environment variables. In ColdFusion, these variables are referred to as CGI environment variables. CGI Environment variables contain data about the transaction between the browser and the server, such as the IP Address, browser type, and authenticated username. The available CGI variables depend on the browser and server software.
The CGI variables are available to ColdFusion pages in the CGI scope. They take the CGI prefix regardless of whether the server uses a server API or CGI to communicate with the ColdFusion server. You can reference CGI environment variables for a given page request anywhere in the page. CGI variables are read-only.
By default, when you use the cfdump tag to display the CGI scope, or when you request debug output of the CGI scope, ColdFusion attempts to display a fixed list of standard CGI environment variables. Because the available variables depend on the server, browser, and the types of interactions between the two, not all variables are normally available, and are represented by empty strings in the debug output. You can request any CGI variable in your application code, including variables that are not in the list variables displayed by dump and debug output.
ColdFusion checks for the following variables for the cfdump tag and debug output:
AUTH_PASSWORD AUTH_TYPE AUTH_USER CERT_COOKIE CERT_FLAGS CERT_ISSUER CERT_KEYSIZE CERT_SECRETKEYSIZE CERT_SERIALNUMBER CERT_SERVER_ISSUER CERT_SERVER_SUBJECT CERT_SUBJECT CF_TEMPLATE_PATH CONTENT_LENGTH CONTENT_TYPE CONTEXT_PATH GATEWAY_INTERFACE HTTPS HTTPS_KEYSIZE HTTPS_SECRETKEYSIZE HTTPS_SERVER_ISSUER HTTPS_SERVER_SUBJECT HTTP_ACCEPT HTTP_ACCEPT_ENCODING HTTP_ACCEPT_LANGUAGE HTTP_CONNECTION HTTP_COOKIE HTTP_HOST HTTP_REFERER HTTP_USER_AGENT QUERY_STRING REMOTE_ADDR REMOTE_HOST REMOTE_USER REQUEST_METHOD SCRIPT_NAME SERVER_NAME SERVER_PORT SERVER_PORT_SECURE SERVER_PROTOCOL SERVER_SOFTWARE WEB_SERVER_API (This value is always blank; retained for compatibility.)
The following sections describe how to test for CGI environment variables and provide information on some of the more commonly used CGI environment variables
Testing for CGI variables
Because some browsers do not support some CGI variables, ColdFusion always returns true when it tests for the existence of a CGI variable, regardless of whether the browser supports the variable. To determine if the CGI variable is available, test for an empty string, as the following example shows:
<cfif CGI.varname IS NOT "">
CGI variable exists
<cfelse>
CGI variable does not exist
</cfif>
CGI server variables
The following table describes common CGI environment variables that the server creates (some of these are not available with some servers):
|
CGI server variable |
Description |
|---|---|
| SERVER_SOFTWARE |
Name and version of the information server software answering the request (and running the gateway). Format: name/version. |
| SERVER_NAME |
Server's hostname, DNS alias, or IP address as it appears in self-referencing URLs. |
| GATEWAY_INTERFACE |
CGI specification revision with which this server complies. Format: CGI/revision. |
| SERVER_PROTOCOL |
Name and revision of the information protocol this request came in with. Format: protocol/revision. |
| SERVER_PORT |
Port number to which the request was sent. |
| REQUEST_METHOD |
Method with which the request was made. For HTTP, this is Get, Head, Post, and so on. |
| PATH_INFO |
Extra path information, as given by the client. Scripts can be accessed by their virtual pathname, followed by extra information at the end of this path. The extra information is sent as PATH_INFO. |
| PATH_TRANSLATED |
Translated version of PATH_INFO after any virtual-to-physical mapping. |
| SCRIPT_NAME |
Virtual path to the script that is executing; used for self-referencing URLs. |
| QUERY_STRING |
Query information that follows the ? in the URL that referenced this script. |
| REMOTE_HOST |
Hostname making the request. If the server does not have this information, it sets REMOTE_ADDR and does not set REMOTE_HOST. |
| REMOTE_ADDR |
IP address of the remote host making the request. |
| AUTH_TYPE |
If the server supports user authentication, and the script is protected, the protocol-specific authentication method used to validate the user. |
|
REMOTE_USER AUTH_USER |
If the server supports user authentication, and the script is protected, the username the user has authenticated as. (Also available as AUTH_USER.) |
| REMOTE_IDENT |
If the HTTP server supports RFC 931 identification, this variable is set to the remote username retrieved from the server. Use this variable for logging only. |
| CONTENT_TYPE |
For queries that have attached information, such as HTTP POST and PUT, this is the content type of the data. |
| CONTENT_LENGTH |
Length of the content as given by the client. |
CGI client variables
The following table describes common CGI environment variables the browser creates and passes in the request header:
|
CGI client variable |
Description |
|---|---|
| HTTP_REFERER |
The referring document that linked to or submitted form data. |
| HTTP_USER_AGENT |
The browser that the client is currently using to send the request. Format: software/version library/version. |
| HTTP_IF_MODIFIED_SINCE |
The last time the page was modified. The browser determines whether to set this variable, usually in response to the server having sent the LAST_MODIFIED HTTP header. It can be used to take advantage of browser-side caching. |
CGI client certificate variables
ColdFusion makes available the following client certificate data. These variables are available when running Microsoft IIS 4.0 or Netscape Enterprise under SSL if your web server is configured to accept client certificates.
|
CGI client certificate variable |
Description |
|---|---|
| CERT_SUBJECT |
Client-specific information provided by the web server. This data typically includes the client's name, e-mail address, and so on, for example: O = "VeriSign, Inc.", OU = VeriSign Trust Network, OU = "www.verisign.com/repository/RPA Incorp. by Ref.,LIAB.LTD(c)98", OU = Persona Not Validated, OU = Digital ID Class 1 - Microsoft, CN = Matthew Lund, E = mlund@.com |
| CERT_ISSUER |
Information about the authority that provided the client certificate, for example: O = "VeriSign, Inc.", OU = VeriSign Trust Network, OU = "www.verisign.com/repository/RPA Incorp. By Ref.,LIAB.LTD(c)98", CN = VeriSign Class 1 CA Individual Subscriber-Persona Not Validated |