Module mod_cgi

Important: Information for this topic supports the latest PTF levels for HTTP Server for i5/OS . It is recommended that you install the latest PTFs to upgrade to the latest level of the HTTP Server for i5/OS. Some of the topics documented here are not available prior to this update. See http://www.ibm.com/servers/eserver/iseries/software/http/services/service.htm Link outside Information Center for more information.

Summary

The module mod_cgi provides for execution of CGI scripts. This module will process any file with mime type application/x-httpd-cgi. Any file that has the mime type application/x-httpd-cgi or handler cgi-script will be treated as a CGI script, and run by the server, with its output being returned to the client. Files acquire this type either by having a name containing an extension defined by the AddType directive, or by being in a ScriptAlias directory.

When the server invokes a CGI script, it will add a variable called DOCUMENT_ROOT to the environment. This variable will contain the value of the DocumentRoot configuration variable.

CGI Environment variables

The server will set the CGI environment variables as described in the CGI specification Link outside Information Center with the following provisions. See Environment variables on HTTP Server for a list of environment variables.

REMOTE_HOST
This will only be set if HostNameLookups is set to double (it is off by default), and if a reverse DNS lookup of the accessing hosts address indeed finds a host name.
REMOTE_IDENT
This will only be set if IdentityCheck is set to on and the accessing host supports the ident protocol.
Note: The contents of this variable cannot be relied upon because it can easily be faked. If there is a proxy between the client and the server, the variable is not useful.
REMOTE_USER
This will only be set if the CGI script is subject to authentication.

CGI Debug

Debugging CGI scripts has traditionally been difficult, mainly because it has not been possible to study the output (standard output and error) for scripts which are failing to run properly. However, the iSeries™ runs CGI programs in previously started jobs (not prestart jobs) and it also reuses these jobs to run many CGI program invocations. Therefore, debugging your CGI program is simple. You simply need to find the job that runs CGI programs. It will have a jobname the same as the server instance name. The joblog will contain either HTP2001 or HTP2002 indicating whether it is a CGI single threaded only job, or a CGI multi-thread capable job. If you use a dedicated server instance, when you invoke your CGI from a browser, the first job in the WRKACTJOB list for CGI, will be the job chosen to run the CGI request. Therefore, you can use STRSRVJOB against this job and STRDBG against your CGI program. From here, you have full debug capabilities provided with the iSeries debugger. You can also use standard error (stderr) for debug information. The debug information written to STDERR is written to the ScriptLog if one is configured or to the ErrorLog if a ScriptLog is not configured. The ScriptLog and ErrorLog are both created with CCSID 1208 UTF-8. For CGI conversion mode EBCDIC, debug information is assumed to be in the CCSID of the CGI job. The logging process handles the conversion from CGI job CCSID to UTF-8. For CGI converison mode BINARY, debug information is written as is.

ScriptLog Format

When configured, the ScriptLog logs any CGI that does not execute properly. Each CGI script that fails to operate causes several lines of information to be logged. The first two lines are always of the format: 

%% [time] request-line %% HTTP-status CGI-script-filename

If the error is that CGI script cannot be run, the log file will contain an extra two lines: 

%%error error-message

Alternatively, if the error is the result of the script returning incorrect header information (often due to a bug in the script), the following information is logged: 

%request All HTTP request headers received POST or PUT entity (if any) %response 
All headers output by the CGI script %stdout CGI standard output %stderr CGI standard error
Note: The %stdout and %stderr parts may be missing if the script did not output anything on standard output or standard error

Directives

CGIConvMode

Module: mod_cgi
Syntax: CGIConvMode mode
Default: CGIConvMode EBCDIC
Context: server config, virtual host, directory, .htaccess, Not in Limit
Override: FileInfo
Origin: iSeries
Example: CGIConvMode BINARY

The CGIConvMode directive is used to specify the conversion mode that your server will use when processing CGI programs.

Parameter: mode
  • Valid modes include the following:
    Mode Description
    EBCDIC The server converts everything into the EBCDIC CCSID of the CGI job. If the directive CGIJobCCSID exists, it has precedence in its context over the job CCSID of the server. The server assumes the header output and encoded characters "%xx" are in the EBCDIC CCSID of the CGI job. The server assumes that the body output is in the EBCDIC CCSID of the CGI job unless specified otherwise using the Content-type header.
    EBCDIC_JCD The server will use the Japanese Codepage Detection utility to determine which Japanese ASCII CCSID to convert from. Otherwise, this option is the same as the EBCDIC option.
    BINARY The server performs no conversion on QUERY_STRING or STDIN data. Environment variables are encoded in the CGI job's EBCDIC CCSID.

    The server expects the header output and encoded characters "%xx" in ASCII. The server assumes that the body output is in ASCII unless specified otherwise using the Content-type header. This differs from no parse header CGI in that the server will still build the HTTP headers and perform conversion on the body output if necessary.

CgiInitialUrl

Module: mod_cgi
Syntax: CgiInitialUrl url userid
Default: none
Context: server config
Override: none
Origin: iSeries
Example: CgiInitialUrl /qsys.lib/qsyscgi.lib/db2www.pgm/mymacros/macro.ndm/initial *
Example: CgiInitialUrl /qsys.lib/cgi.lib/mycgi.pgm QTMHHTP1
Example: CgiInitialUrl /QOpenSys/mypacedir/pacecgi USER1
Example: CgiInitialUrl /qsys.lib/cgi.lib/mycgi.pgm?init=yes

This directive is used to load and initialize CGI programs when the server starts. At server startup, when we are processing the StartCgi directive, we are starting jobs to run CGI programs in. This new directive will enable the server to run a CGI request to the CGI job enabling the CGI program to be loaded and initialized. This is beneficial for Net.Data® users and other CGI programs built to use "named" activation groups. The initialization of the "named" activation group is a performance issue that the first user of the CGI job has to endure. This function will enable the performance issue to be moved to when the server starts, so the first user does not have to pay the performance penalty.

If there are no StartCgi directives, an error will be posted and the server will not start.

Parameter One: url
  • The url parameter value is actually the physical path URL, not the logical path URL. It should not be fully qualified (do not use http://system:port/). It must start with a / and contains the physical path to the CGI program and any path info needed by the CGI program, including query-string. If a URL is specified that is not valid, the server will not start.
Parameter Two: userid
  • The userid parameter value is either a valid iSeries userid or * where * means all of the userids specified on the StartCgi directive. To check for valid values, follow the rules for iSeries user profiles. The userid is optional.

CGIJobCCSID

Module: mod_cgi
Syntax: CGIJobCCSID cgi-job-character-set-identification-number
Default: CGIJobCCSID Dependent upon server-character-set-identification-number
Context: server config, virtual host, directory, not in limit, .htaccess
Override: none
Origin: iSeries
Example: CGIJobCCSID 37
Example: To run one CGI program in CCSID 37 (English):
ScriptAlias /cgi-english/ /QSYS.LIB/ENGLISH.LIB/
<Directory  /QSYS.LIB/ENGLISH.LIB/>
   Allow From all                              
   Options +ExecCGI   
   DefaultNetCCSID 819
   CGIJobCCSID  37    
  CGIConvMode EBCDIC     
</Directory>
Example: To run a different CGI program in CCSID 284 (Spanish):
ScriptAlias /cgi-spanish/ /QSYS.LIB/SPANISH.LIB/
<Directory /QSYS.LIB/SPANISH.LIB/>
   Allow From all                              
   Options +ExecCGI   
   DefaultNetCCSID 819
   CGIJobCCSID  284      
   CGIConvMode EBCDIC 
</Directory>
Example: For GET and POST – Use the URI to determine the language of the user:
Enter: http://www.mydomain.com/cgi-bin/ENG/819/...  
The configuration file would have this container configuration:    
<Location  /cgi-bin/ENG/819/>
   DefaultNetCCSID 819
   CGIJobCCSID  37
</Location>
ScriptAlias /cgi-bin/ /QSYS.LIB/CGI.LIB/
<Directory  /QSYS.LIB/CGI.LIB/>
    Allow From all                              
    Options +ExecCGI   
    CGIConvMode EBCDIC   
</Directory>
	    
The same configuration can handle this URI for a Japanese speaking user.
Enter: http://www.mydomain.com/cgi-bin/JAP/942/

The configuration file would also have this container configuration: 
<Location /cgi-bin/JAP/942/>
    DefaultNetCCSID 942
    CGIJobCCSID  5035
    CGIConvMode EBCDIC_JCD
</Location>
ScriptAlias /cgi-bin/ /QSYS.LIB/CGI.LIB/
<Directory /QSYS.LIB/CGI.LIB/>
    Allow From all
   	Options +ExecCGI   
   	CGIConvMode EBCDIC
</Directory>
The CGIJobCCSID directive specifies the CCSID under which CGI jobs run, the CGI job character set environment, and the EBCDIC CCSID that is used when the server converts:
  • Input request data for user CGI programs
  • Output response data from user CGI programs to be sent back to the requester (client browser)
If this directive is not specified, the default behavior is to have the CGI job run under the same CCSID as the main server jobs. See the DefaultFsCCSID directive for detailed information on how this is determined.

CGIJobLocale

Module: mod_cgi
Syntax: CGILocale locale_path_name
Default: none
Context: server config, virtual host, directory, not in limit, .htaccess
Override: none
Origin: iSeries
Example: CGIJobLocale /QSYS.LIB/LOCALELIB.LIB/EN_US.LOCALE
Example: To run one CGI program in CCSID 37 with an English based locale (English):
ScriptAlias /cgi-english/ /QSYS.LIB/ENGLISH.LIB/

<Directory /QSYS.LIB/ENGLISH.LIB/>
   Allow From all                              
   Options +ExecCGI   
   DefaultNetCCSID 819
   CGIJobCCSID  37    
           CGIJobLocale /QSYS.LIB/LOCALELIB.LIB/EN_US.LOCALE
  CGIConvMode EBCDIC  
</Directory>
Example: To run a different CGI program in CCSID 273 and with a German based locale (German):
ScriptAlias /cgi-german/ /QSYS.LIB/GERMAN.LIB/
<Directory /QSYS.LIB/GERMAN.LIB/>
   Allow From all                              
   Options +ExecCGI   
   DefaultNetCCSID 819
   CGIJobCCSID  273    
           CGIJobLocale /QSYS.LIB/LOCALELIB.LIB/DE_DE.LOCALE
  CGIConvMode EBCDIC  
</Directory>

Applications can be created independent of language, cultural data, or specific characters. Locales can be accessed to provide this type of support to any integrated language environment-based application. The CGIJobLocale directive allows a locale to be set globally or for a specific CGI job. After the locale is set, country 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. The environment variable CGI_JOB_LOCALE is set from the CGIJobLocale directive.

CGIMultiThreaded

Module: mod_cgi
Syntax: CGIMultiThreaded on | off
Default: CGIMultiThreaded off
Context: server config, virtual host, directory, .htaccess, Not in Limit
Override: FileInfo
Origin: iSeries
Example: CGIMultiThreaded on

The CGIMultiThreaded directive is used to specify whether your CGI programs should be run in a job that is multiple thread capable. HTTP Server uses a pool of pre-started jobs for handling CGI requests. Multiple threaded programs must run in a multiple thread-capable job. The job pool that the job runs in is specified at job startup time. Once the job has started, it cannot be changed to another job pool. Not all iSeries APIs are thread safe, some will issue an error if used in a multiple thread-capable job. This happens even if the program does not actually have multiple threads running. Because of this, HTTP Server must default to non-multiple thread capable jobs for CGI programs for compatibility reasons. If your CGI program uses multiple threads, it must run in a multiple thread capable job. If your CGI does not need multiple threads, you should run it in the single threaded CGI job for performance reasons.

CGIRecyclePersist

Module: mod_cgi
Syntax: CGIRecyclePersist on | off
Default: CGIRecyclePersist off
Context: server config, virtual host, directory, .htaccess, Not in Limit
Override: FileInfo
Origin: iSeries
Example: CGIRecyclePersist on

The CGIRecyclePersist directive instructs the server what should be done with the job that was being used by a persistent CGI when the persistent CGI exits persistence normally.

Parameter: on | off
  • The on value indicates that the server can reuse this job for other CGI requests. When this is used, the persistent CGI program is responsible for cleaning up any static data from the persistent CGI transaction. The server will not perform any action other than to remove all environment variables, to clean up any static data. Before using this setting, the CGI programmer need to verify that it does indeed clean up its static data.
  • The off value indicates that the server will not reuse this job for other CGI requests. This is the default behavior.

DefaultNetCCSID

Module: mod_cgi
Syntax: DefaultNetCCSID client-character-set-identification-number
Default: DefaultNetCCSID 819
Context: server config, virtual host, directory, .htaccess
Override: none
Origin: iSeries
Example: DefaultNetCCSID 819
The DefaultNetCCSID directive specifies the client character set environment and defines the ASCII or UTF-8 CCSID that is used when converting:
  • Input request data for user CGI programs or Apache modules.
  • When serving EBCDIC documents and no ASCII CCSID can be deduced from the file CCSID.
  • Output response data from user CGI programs, or Apache modules, to be sent back to the requester (client browser).
A configuration file can contain more than one DefaultNetCCSID directive, but the last directive in the configuration file determines the CCSID. Starting in i5/OS™ V5R4, the use of this directive is expanded to help you configure a single server to handle requests in more than one language. The directive is now allowed in a virtual host container and in directory containers. This directive is supported in the global scope.

MaxCGIJobs

Module: mod_cgi
Syntax: MaxCGIJobs number
Default: MaxCGIJobs 40 or value of the ThreadsPerChild directive
Context: server config
Override: none
Origin: iSeries
Example: MaxCGIJobs 50

The MaxCGI directive is used to set the maximum number of CGI jobs that the server will concurrently use. The server will only run CGI programs in jobs where the user profile for the CGI job matches the user profile that the request is to run under. If you protect your CGI programs with many different dummy iSeries profiles ( profiles with no password) or use %%CLIENT%% (each user has their own iSeries profile and it is used to run the CGI program), then you may want to use this directive to allow the server to start more CGI jobs to handle the CGI programs. The server does reuse the CGI jobs, but only when the profile for the CGI program matches the profile for the CGI job. If you see the server ending and starting CGI jobs regularly, then you may want to use this directive to allow the server to use more CGI jobs. This would improve the capacity and performance of your system and server.

Parameter: number
  • The number parameter accepts any positive number. If an invalid value is used, or the number is smaller than the value of the ThreadsPerChild directive, then the server will use a default of (value of ThreadsPerChild). If ThreadsPerChild directive is not present, then the default of this directive will be set to 40.

MaxPersistentCGI

Module: mod_cgi
Syntax: MaxPersistentCGI number
Default: MaxPersistentCGI 40
Context: server config
Override: none
Origin: iSeries
Example: MaxPersistentCGI 50

The MaxPersistentCGI directive is used to set the maximum number of active persistent CGI jobs that you want to have active at one time.

Parameter: number
  • The number parameter sets the maximum number of active persistent CGI jobs that are active at any one time.

MaxPersistentCGITimeout

Module: mod_cgi
Syntax: MaxPersistentCGITimeout number
Default: MaxPersistentCGITimeout 1200
Context: server config
Override: none
Origin: iSeries
Example: MaxPersistentCGITimeout 1800

The MaxPersistentCGITimeout directive specifies the maximum number of seconds that a CGI program can use when overriding the PersistentCGITimeout directive.

Parameter: number
  • The number parameter value must be greater than 1 second.

MaxThreadedCGIJobs

Module: mod_cgi
Syntax: MaxThreadedCGIJobs number
Default: MaxThreadedCGIJobs 40 or the value of ThreadsPerChild directive
Context: server config
Override: none
Origin: iSeries
Example: MaxThreadedCGIJobs 50

The MaxThreadedCGIJobs directive is used to set the maximum number of multiple thread capable CGI jobs that the server will concurrently use. The server will only run multiple thread capable CGI programs in jobs where the user profile for the multiple thread capable CGI job matches the user profile that the request is to run under. If you protect your multiple thread capable CGI programs with many different dummy iSeries profiles (profiles with no password) or use %%CLIENT%% (each user has their own iSeries profile and it is used to run the multiple thread capable CGI program), then you may want to use this directive to allow the server to start more multiple thread capable CGI jobs to handle the multiple thread capable CGI programs. The server does reuse the CGI jobs, but only when the profile for the multiple thread capable CGI program matches the profile for the multiple thread capable CGI job. If you see the server ending and starting multiple thread capable CGI jobs regularly, then you may want to use this directive to allow the server to use more multiple thread capable CGI jobs. This would improve the capacity and performance of your system and server.

Parameter: number
  • The number parameter value can be any positive number. If an invalid value is used, or the number is smaller than the value of the ThreadsPerChild directive, then the server will use a default of (value of ThreadsPerChild). If ThreadsPerChild directive is not present, then the default of this directive will be set to 40.

PersistentCGITimeout

Module: mod_cgi
Syntax: PersistentCGITimeout number
Default: PersistentCGITimeout 300
Context: server config
Override: none
Origin: iSeries
Example: PersistentCGITimeout 120

This directive specifies the number of seconds that your server waits for a client response before ending a persistent CGI session. The CGI program can override the value that you specify on a request-by-request basis.

Parameter: number
  • The number parameter can be any amount of time greater than 1 second.

ScriptLog

Module: mod_cgi
Syntax: ScriptLog filename
Default: none
Context: server config
Override: none
Origin: Modified
Example: ScriptLog /QIBM/userdata/httpa/(instance name)

The ScriptLog directive sets the Common Gateway Interface (CGI) script error logfile. If no ScriptLog is given, no CGI error log is created. If a ScriptLog is given, any CGI errors are logged into the filename given as the argument. If this is a relative file or path, it is taken relative to the server root.

This log will be opened as the user the child processes run as, for example the user specified in the main User directive. This means that either the directory the script log is in needs to be writable by that user or the file needs to be manually created and set to be writable by that user. If you place the script log in your main logs directory, do not change the directory permissions to make it writable by the user the child processes run as.

Note: The script logging is meant to be a debugging feature when writing CGI scripts, and is not meant to be activated continuously on running servers. It is not optimized for speed or efficiency, and may have security problems if used in a manner other than that for which it was designed.

Behavior

If the filename does not begin with a slash ('/') then it is assumed to be relative to the ServerRoot.

If the path ends with a '/' character, then the path is considered to be the directory that will contain the log file.

The ScriptLog file will be created with CCSID 1208 (UTF8). Customer data written to the script log is assumed to be in the CGI job CCSID and will automatically be converted to CCSID 1208. The data will be written to the log file in binary. Therefore, the customer's data will be written to the ScriptLog without conversion. Information from the CGI request will not need to be translated, as the data will already be in the defaultFSCCSID.

ScriptLogBuffer

Module: mod_cgi
Syntax: ScriptLogBuffer size
Default: ScriptLogBuffer 1024
Context: server config
Override: none
Origin: Apache
Example: ScriptLogBuffer 512

The ScriptLogBuffer directive limits the size of any PUT or POST entity body that is logged to the file. This prevents the log file from growing too big too quickly (the case if large bodies are being received).

Parameter: size
  • The size parameter is measured in bytes and consists of any positive integer. By default, up to 1024 bytes are logged, but the value can be changed with this directive.

ScriptLogLength

Module: mod_cgi
Syntax: ScriptLogLength size
Default: ScriptLogLength 10385760
Context: server config
Override: none
Origin: iSeries
Example: ScriptLogLength 1024000

The ScriptLogLength directive can be used to limit the size in bytes of the Common Gateway Interface (CGI) script log file. Since the log file logs a significant amount of information per CGI error (all request headers, all script output) it can grow to be quite large. To prevent problems due to unbounded growth, this directive can be used to set a maximum file-size for the CGI logfile. If the file exceeds this size, no more information will be written to it.

Parameter: size
  • The size parameter is measured in bytes. This is any positive number.

StartCGI

Module: mod_cgi
Syntax: StartCGI number userid
Default: none
Context: server config
Override: none
Origin: iSeries
Example: StartCGI 5 USER1

The StartCGI directive specifies the number of CGI jobs that are spawned by the server when it starts up and the iSeries user profile to use in these jobs. This allows you to have the server prestart CGI jobs when the server starts so the users do not incur the performance hit of starting a new job. It also allows you to start up jobs for different user profiles. The userid is optional and should only be used to protect your CGI programs so that they run under the %%CLIENT%% profile or under a dummy iSeries profile (a profile with no password).

The cumulative number from all occurrences of this directive cannot exceed MaxCGIJobs, if it does, the server will not start. If the user profile parameter is not specified, the default server profile (QTMHHTP1) or the value from the global ServerUserID directive is used.

If you are using %%CLIENT%% as the profile in the protection of the CGI programs (meaning that each user authenticates with an iSeries user profile), then it should be noted that %%CLIENT%% is not a valid value on this directive. Using iSeries profiles like this should only be done in an intranet or highly secure server because you would not want to give just anyone an iSeries user profile. Therefore, you would know how many users and also their user profile name, thus you would need to decide how many users will be doing CGI requests and how many concurrent CGI requests you want each user to be able to do. Then you could specify multiple StartCGI directives, one for each user, specifying the number of concurrent CGI requests you expect that user to do.

Note: This will NOT limit the number of concurrent CGI requests. This will simply allow CGI jobs to be started at server startup time so the user does not have to incur the performance hit of starting up a new job when they run their first CGI program.

StartThreadedCGI

Module: mod_cgi
Syntax: StartThreadedCGI number userid
Default: none
Context: server config
Override: none
Origin: iSeries
Example: StartThreadedCGI 3
Example: StartThreadedCGI 5 USER1

The Start ThreadedCGI directive specifies the number of multiple thread capable CGI jobs that are spawned by the server when it starts up and the iSeries user profile to use in these jobs. This allows you to have the server prestart CGI jobs when the server starts so the users do not incur the performance hit of starting a new job. It also allows you to start up jobs for different user profiles. The userid is optional and should only be used to protect your multiple thread capable CGI programs so that they run under the %%CLIENT%% profile or under a dummy iSeries profile (a profile with no password).

The cumulative number from all occurrences of this directive cannot exceed MaxThreadedCGIJobs, if it does, the server will not start. If the user profile parameter is not specified, the default server profile (QTMHHTP1) or the value from the global ServerUserID directive is used.

If you are using %%CLIENT%% as the profile in the protection of the multiple thread capable CGI programs (meaning that each user authenticates with an iSeries user profile), then it should be noted that %%CLIENT%% is not a valid value on this directive. Using iSeries profiles like this should only be done in an intranet or highly secure server because you would not want to give just anyone an iSeries user profile. Therefore, you would know how many users and also their user profile name, thus you would need to decide how many users will be doing CGI requests and how many concurrent multiple thread capable CGI requests you want each user to be able to do. Then you could specify multiple StartThreadedCGI directives, one for each user, specifying the number of concurrent multiple thread capable CGI requests you expect that user to do.

Note: This will NOT limit the number of concurrent multiple thread capable CGI requests. This will simply allow multiple thread capable CGI jobs to be started at server startup time so the user does not have to incur the performance hit of starting up a new job when they run their first multiple thread capable CGI program.

ThreadedCgiInitialUrl

Module: mod_cgi
Syntax: ThreadedCgiInitialUrl url userid
Default: none
Context: server
Override: none
Origin: iSeries
Example: ThreadedCgiInitialUrl /qsys.lib/cgi.lib/mycgi.pgm QTMHHTTP
Example: ThreadedCgiInitialUrl /QOpenSys/mypacedir/pacecgi
Example: ThreadedCgiInitialUrl /qsys.lib/cgi.lib/mycgi.pgm?init=yes USER1

This directive is used to load and initialize threaded CGI programs when the server starts. At server startup, when processing the StartThreadedCgi directive, jobs are started to run CGI programs in. This directive enables the server to run a CGI request to the CGI job enabling the CGI program to be loaded and initialized. This function enables performance issues to be moved to when the server starts, so the first user does not have diminished performance.

If there are no StartThreadedCgi directives, an error is posted and the server does not start.