You use environment variables to pass descriptive information about the server and the current request to a CGI program. Some of these variables are set for all requests; others are set only for particular requests. Passing environment variables is described in these three tables:
• “Environment Variables” (page 146)lists and describes the standard environment variables applicable to generic and Pathway CGI programs.
• “Pathway Specific Environment Variables” (page 150)lists and describes additional environment variables available in the iTP Secure WebServer environment.
• “Environment Variable Access Methods” (page 152)describes how to use environment variables from specific programming languages.
NOTE: The CGI environment changes on each invocation of CGI_main. To access your
environment variables, use CGI_initialize(), as described under“Design Guidelines” (page 162). The SSL, session identifier, and Secure HTTP environment variables apply only to secure versions of the iTP Secure WebServer.
Table 16 Environment Variables
Description Environment Variable
The following environment variables are not
request-specific. These variables are set for all requests.
The name and version of the server software answering the request and running the gateway.
Format: SERVER_SOFTWARE
name/version
Example:
Tandem iTP Secure WebServer/7.2
The IP address of the virtual host that accepted the connection. Format:/dir1/dir2/program_name
Example: SERVER_ADDR
/search/name.cgi
The server host name, DNS alias, or IP address as it would appear in self-referencing URLs.
Format: SERVER_NAME
fully-qualified-domain-nameorip-address
Example:
www.company.comor199.170.183.2
The CGI specification to which this server complies. Format:
GATEWAY_INTERFACE
CGI/revision
Example:
CGI/1.1
Table 16 Environment Variables (continued)
Description Environment Variable
These environment variables are request specific.
The name and revision of the information protocol this request came in with.
Format: SERVER_PROTOCOL
protocol/revision
Example:
HTTP/1.0
The port number to which the request was sent. Format:
SERVER_PORT
number-between-1-and-65535
Example:
80
Extra path information given by the Web client. CGI programs can be accessed by their virtual path name PATH_INFO
followed by extra information. This extra information is contained in the PATH_INFO variable. If this information comes through a URL, it is decoded by the server before it is passed to the CGI program.
Format:
/dir1/dir2/dir3.../file
Example:
/images/logo.gif
The translated version of PATH_INFO, after the server applies a virtual-to-physical mapping to it.
Format: PATH_TRANSLATED
/dir1/dir2/dir3.../file
Example:
The partial path /images/logo.gif becomes the full path name:/root/server/images/logo.gif
The method by which the request was made. For HTTP, this is GET, HEAD, POST, and so on.
Format: REQUEST_METHOD
method
A virtual path to the CGI program being executed, used for self-referencing URLs.
Format: SCRIPT_NAME
/dir1/dir2/program_name
Example:
/search/name.cgi
The information following the question mark (?) in the URL referencing this CGI program. This information is not QUERY_STRING
decoded by the server. This variable is set whenever there is query information, regardless of command-line decoding (see“HTML Forms” (page 156)).
The name of the host making the request. If the iTP Secure WebServer does not know this name, it leaves this variable REMOTE_HOST
unset. To use this feature, you must enable DNS lookups by including the ReverseLookup directive, with a value of yes, in your configuration file.
Format:
machine.domain.category
Example:
www.company.com
Table 16 Environment Variables (continued)
Description Environment Variable
The IP address of the remote host making the request. If IPv4 address is used:
REMOTE_ADDR
n.n.n.n
Example:
199.170.183.2
If IPv6 address is used:
n:n:n:n:n:n:n:n
Example:
2001:0:0:0:0:FFD3:0:57ab
The request is sent by using this Port number. Format:
REMOTE_PORT
number-between-1-and-65535
Example:
80
If the server supports user authentication, and the CGI program is protected, this is the protocol-specific authentication method used to validate the user. Example:
AUTH_TYPE
basic
This variable is not supported. REMOTE_IDENT
If the server supports user authentication, and the CGI program is protected, this is the authenticated user name. Example:
REMOTE_USER
sandeman
For queries with attached information, such as HTTP POST, this is the content type of the data.
Format: CONTENT_TYPE
type/subtype
Example:
text/html
The length of the content (in bytes) as given by the Web client.
Example: CONTENT_LENGTH
768
These TLS and SSL environment variables are request specific.
Contains the number of bits in the session key used to encrypt this session.
Example: HTTPS_KEYSIZE
128
Contains the name of the issuer of this server's certificate. Example:
HTTPS_SERVER_ISSUER
CN=Capulet, O=Capulet's House of Keys, C=Italy
Contains the DN for this server's certificate. Example:
HTTPS_SERVER_SUBJECT
CN=Juliet, O=Capulet's House of Keys, C=Italy
Indicates whether the request is using TLS or SSL. The values are: ON, OFF
Example: HTTPS
off
Table 16 Environment Variables (continued)
Description Environment Variable
If TLS or SSL client authentication is used, this variable contains the certificate that is presented by the Web client. HTTPS_CLIENT_CERT
It is encoded in ASCII using radix-64. If SSL 3.0 was used, the value stored in this variable is the Web client's certificate, extracted from the certificate chain that was received from the Web client.
If TLS or SSL client authentication is used, this variable contains the type of certificate used. Possible values are X509 and X509V3.
Example: HTTPS_CLIENT_CERTTYPE
X509V3
If TLS or SSL client authentication is used with the
-requestauthoption, and the iTP Secure WebServer HTTPS_CLIENT_ERROR_DN
discovers an error while verifying the client certificate, this variable contains the DN of the certificate in error. If TLS or SSL client authentication is used, this variable contains the DN of the direct issuer of the client certificate. HTTPS_CLIENT_ISSUER
The DN is taken from the issuer field within the client certificate.
Example:
OU=PersonalCertificate,0="RSA Data Security,Inc.",C=US
If TLS or SSL client authentication is used, this variable contains the verification status of the client certificate. For HTTPS_CLIENT_STATUS
descriptions of possible status values, see“Using the -requestauth Option” (page 73).
Example:
VALID
If TLS or SSL client authentication is used, this variable contains the DN of the Web client.
Example: HTTPS_CLIENT_SUBJECT
CN=Juliet,O=Capulet's House of Keys
Indicates the port number used for the TLS or SSL request. Example:
HTTPS_PORT
443
Indicates the protocol used. Possible values are TLS and SSL.
Example: HTTPS_PROTOCOL
SSL
Indicates the version of the security protocol used. Possible values are: 3 - (SSL 3.0) 1.0 - (TLS 1.0) 1.1 - (TLS 1.1) 1.2 - (TLS 1.2)
Example: HTTPS_PROTOCOL_VERSION
3.0
These environment variables pertain to session identifiers.
The department ID, in ASCII. SI_DEPARTMENT
The group number embedded in the ticket. The group ID is taken from a user database. You can use this variable SI_GROUP
to present customized Web pages to particular groups of users.
Example:
45
The SI_GROUP variable is present only if a valid ticket is presented.
Table 16 Environment Variables (continued)
Description Environment Variable
The entire Session Identifier. SI_SI
The 2-bit user context field from the ticket. This field is used by the ticketing agent.
SI_UCTX
The user ID of the user accessing the content. This value is extracted from the ticket. Except for anonymous ticketing, SI_UID
the user ID is taken from a user database. You can use this variable to present customized Web pages to particular users.
Example:
967845
The SI_UID variable is present only if a valid ticket is presented.
Table 17 Pathway Specific Environment Variables
Description Environment Variable
Causes form-encoded data and name-value pairs in the QUERY_STRING environment variable to be stored in environment variables.
AUTOMATIC_FORM_DECODING1
This feature is only applicable to CGI objects with a MIME type of application/x-httpd-guardian. The parsing automatically decodes the form encoded data from the stdin file (or pseudo stdin in the case of Pathway servers). The parsing mechanism also decrements the
CONTENT_LENGTH environment variable accordingly. Format:
Region /* {AddCGI AUTOMATIC_FORM_DECODING ON | OFF}
Example:
To retrieve the value of the form entry:
<INPUT SIZE=30 NAME="First_Name"> <b> Your First Name</b><br>
Use the following:
getenv ("First_Name");
In this example, the environment variables are made with the same names as the name portion of the name value pair.
This URL:
http://www.yourserver.com/samples/Scripts/env.cgi?name=value&x=y
has the QUERY_STRING environment variable decoded into two extra environment variables: name=value and x=y. If these namevalue pairs were passed to the env.cgi program found in /samples/Scripts, the following would be returned:
Env CGI Script
Environment info follows SERVER_PORT 80
name value
SERVER_PROTOCOL HTTP/1.0
SERVER_NAME comm.loc201.company.com HTTP_USER_AGENT Mozilla/1.1N (Macintosh; I; PPC)
SERVER_SOFTWARE iTP Secure WebServer/1.1- SSL/1.1
HTTPS OFF
REMOTE_ADDR 155.186.131.240
Table 17 Pathway Specific Environment Variables(continued) Description Environment Variable QUERY_STRING=name=value name=value=y AUTOMATIC_FORM_DECODING ON HTTP_ACCEPT */*, image/gif, image/x-xbitmap, image/jpeg PATH /bin:/usr/bin:/usr/ucb:/usr/bsd:/usr/local/bin x y GATEWAY_INTERFACE CGI/1.1 REQUEST_METHOD GET SCRIPT_NAME /samples/Scripts/env.cgi
This environment variable is used to attach a prefix to the environment variables that are created when the value of FORM_DECODING_PREFIX
the AUTOMATIC_FORM_DECODING environment variable is set to ON.
Format:
Region /* {
AddCGI AUTOMATIC_FORM_DECODING ON
AddCGI FORM_DECODING_PREFIX your_prefix_ }
Example:
To retrieve the value of the form entry:
<INPUT SIZE=30 NAME="First_Name"> <b> Your First Name</b><br>
Use the following:
getenv ("your_prefix_First_Name");
In this example, the names of all environment variables have the prefixyour_prefix_. The prefix option can be useful if you expect duplication of names between the names in your form and the names of predefined environment variables.
If set toyes, causes the Pathway CGI server to abort when the dialog between HTTPD and CGI server is aborted. Format:
TANDEM_CGI_CONNECTION_ABORT_EXIT
Server path { Env
TANDEM_CGI_CONNECTION_ABORT_EXIT=value}
The valid values for this variable areYES/yesandNO/no. If you write your own copy of CGI_connection_abort() routine that does not stop the Pathway CGI server, the CGI server is aborted if
TANDEM_CGI_CONNECTION_ABORT_EXIT is set toyes. In all other cases, this variable has no effect.
This environment variable is not used in case of NSJSP. Example:
Server $root/bin/SampleServer.pway { Eval $DefaultServerAttributes
Env TANDEM_CGI_CONNECTION_ABORT_EXIT=YES}
This environment variable determines the number of seconds that the CGI process will retain buffered data TANDEM_CGI_ FFLUSH_TIMER
before flushing the data to the httpd process (which, in turn, sends the data to the client). You can include this variable in the configuration of your server class or set it by using the CGI_set_fflush_timer procedure.
Format:
Table 17 Pathway Specific Environment Variables(continued)
Description Environment Variable
Serverpath {Env
TANDEM_CGI_FFLUSH_TIMER=value}
The valid values for this variable are from 0 to 3600. The default value, 0, causes the CGI process to retain buffered data until the buffer is full. Any other value causes the process to wait the specified number of seconds before flushing the buffer.
Example:
Server /dir5/flush.pway {Env TANDEM_CGI_FFLUSH_TIMER=1}
The flush timer uses an OSS signal handling routine that catches a SIGALARM signal. When the alarm signal is delivered to a process, it can interrupt long I/O operations and cause an error. In this case, the errno variable is set to 4004 (interrupted system call).
If you want your program to do its own SIGALARM processing, set the value ofTANDEM_CGI_FFLUSH_TIMER
to 0.
This environment variable maps the current working directory to the CGI script directory when its value is set to YES.
Format: TANDEM_CGI_ RELATIVE_PATH_ SUPPORT
Server path {
Env TANDEM_CGI_RELATIVE_PATH_SUPPORT=value}
The valid values for this variable are YES/yes and NO/no. The default value, NO, causes the current working directory to be mapped to the directory specified by the CWD attributes of the server directive. If a directory is not specified by the CWD attributes, the current working directory, by default, will be mapped to the directory in which the generic-cgi.pway is located.
Example:
Server $root/bin/generic-cgi.pway { Eval $DefaultServerAttributes
Env TANDEM_CGI_RELATIVE_PATH_SUPPORT=YES}
Generic CGI will move the current working directory to the location of the script file. You can specify a relative path inside a cgi script by using this feature.
1 When AUTOMATIC_FORM_DECODING is used, only the last value in a multiple selection will be returned if the POST
method is used along with the multiple tag. To see all values, use the GET method and the QUERY_STRING variable.
Table 18 Environment Variable Access Methods
Variable Access Method Language
This access method makes a getenv library call Format: C/C++ #include stdlib.h char *variable = getenv("environment_variable_name") Example: char *sname=getenv("SERVER_NAME")
This access method accesses an environment variable Format:
Tcl
$env(environment_variable_name)
Example:
Table 18 Environment Variable Access Methods(continued)
Variable Access Method Language
$env(cgi_dump.cgi)
This access method accesses environment variables as normal shell variables
Format: Bourne Shell
variable=$environment_variable_name
Example:
SNAME=$SERVER_NAME
This access method accesses environment variables as normal shell variables
Format: Korn Shell
variable=$environment_variable_name
Example:
SNAME=$SERVER_NAME
You access environment variables through the HttpServletRequest class
Java