This chapter describes each server configuration directive. If you choose to configure the server by editing the httpd.cnf configuration file, use this chapter as a reference. If you choose to configure your server by using the Configuration and Administration forms, you do not need to refer to this chapter.
The directive descriptions are grouped according to function, similar to the way the Configuration and Administration forms are grouped. Within each group, the directives are in alphabetical order.
Each directive description includes:
Each configuration directive follows the same general syntax:
DirectiveName value
These are the original values coded in the default configuration file. (Change only the parts of the configuration file that you want to be different from the default settings.)
For a list of the new directives added in Version 4.2, see page reference #1.
Some directives (the value portion) contain templates for requests, path names, or host names. Except where otherwise indicated, you can use the asterisk (*) character in templates. For the template to be matched, an asterisk can be replaced by any character string or single character.
The examples and defaults in this chapter use the backslash (\) character when showing a path name. In the configuration file, you can actually use either the backslash or forward slash (/) character when specifying a path name. Always use the forward slash (/) when specifying a URL or request template.
Several configuration directives allow you to specify a positive string. You can enter any of the following words:
Several configuration directives allow you to specify a negative string. You can enter any of the following words:
Several configuration directives allow you to specify an amount of time. You can specify any combination of:
All of your entries will be converted to seconds and added together.
The server currently does not allow the use of blank characters within a filename specified in the configuration file. Blank spaces are treated as delimiters.
Use the directives described in this section to control your server's basic configuration settings.
Use this directive on a multi-networking system to run a different server on each IP address. All the servers may listen on the same port.
If you specify On, the server binds to the IP address specified in the HostName directive only, instead of binding to all local IP addresses.
If this directive has not been specified, the server binds to the default HostName.
If you change this directive, you must stop the server and then start it again. The server will not pick up the change if you only restart it.
BindSpecific On
None.
BindSpecific Off
Use this directive to specify whether you want your server to look up the host name of requesting clients.
The value you use affects the following things about how your server works:
DNS-Lookup On
DNS-Lookup Off
Use this directive to specify the domain name or an IP address returned to clients from document requests. If you specify a domain name, a domain name server must be able to resolve the name into an IP address. If you specify an IP address, the domain name server is not needed or accessed.
HostName name or IP address
The name you specified for Host name during installation. The installation default is the default host name defined in your domain name server. If you remove this directive, the default host name defined in your domain name server is used.
Use this directive to specify if you want server-side include processing to be performed for documents served from the file system, CGI programs, or both. Server-side include processing is done on documents with a content type of text/x-ssi-html. Optionally, you can specify that server-side include processing also be done for documents with a content type of text/html. For more information about content types, see "AddType - Specify the data type of files with particular extension".
You can use server-side includes to dynamically insert information, such as the date, the size of a file, the last change date of a file, CGI or server-side include environment variables, or text documents into the document being returned. For more information on using server-side includes, see "Using server-side includes to insert information into CGI programs and HTML documents".
Server-side include processing causes the server to search your documents for special commands each time they are served. This can affect the server's performance and slow down response time to clients.
The format of this directive is:
imbeds source [type]
source can be:
The server checks the content type of each file it retrieves and the output of each CGI program it processes.
Server-side include processing is normally done only for documents having a content type of text/x-ssi/html. However, you can specify that documents with a content type of text/html be processed for server-side includes.
type can be:
Important migration note: In previous releases, you could specify that documents with a specific extension, such as .html, .htm. or .shtml, be processed for server-side includes. In this release, the server treats html, .html, and .htm as html. Anything else is treated as SSIOnly.
Each extension must have an AddType directive defined with the correct content type. If you use extension other than .htm or .html, make sure an AddType directive is defined with a content type of text/x-ssi/html.
imbeds on SSIOnly
imbeds off SSIOnly
Use this directive to specify the port number the server should listen to for requests. The standard port number for HTTP is 80. Other port numbers less than 1024 are reserved for other TCP/IP applications and should not be used. Common ports used for proxy Web servers are 8080 and 8008.
When a port other than 80 is used, clients are required to include a specific port number on requests to the server. The port number is preceded by a colon and placed after the host name on the URL. For example, from the browser, the URL
http://www.turfco.com:8008/requests the default welcome page from a host named www.turfco.com that is listening on port 8008.
You can use the -p option on the httpd command to override this setting when starting the server.
If you change this directive, you must stop your server and then start it again for the change to take effect. The server will not pick up the change if you only restart it.
Port 8080
The number you specified for Port during installation. The installation default is 80.
Use this directive to specify the directory where the server program is installed.
ServerRoot d:\webserve\BIN
The directory name you specified for Executables directory during installation. The installation default is:
ServerRoot C:\WWW\BIN
Note: PASS and EXEC rules may be independent of this directory.
Use the directives described in this section to control how your server responds to requests containing a directory name. You can have the server search the directory for a welcome file to return, or you can have the server generate a directory listing.
By default, the server first looks for a welcome file. If no welcome file is present, the server displays a directory listing. Configuration settings control how directory listings appear and the icons that the listings use.
The server provides a set of default icons to use for directory listings. You can replace these icons with others using some of the directives described in this section.
Use this directive to specify an icon to use for aligning the heading on directory listings. This can either be a blank icon or another icon you want to appear on the headings of your directory listings. For proper alignment, the icon you use must be the same size as the other icons you are using on your directory listings. The format of the directive is:
AddBlankIcon icon-URL alternate-text
If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server.
AddBlankIcon logo.gif logo
AddBlankIcon blank.gif
The default does not specify alternative text since the icon is blank.
Use this directive to specify an icon for representing a directory on a directory listing. The format of the directive is:
AddDirIcon icon-URL alternate-text
If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server. You must map the URL to a local file and make sure that the mapping directives allow the URL to be passed.
AddDirIcon direct.gif DIR
AddDirIcon dir.gif DIR
Use this directive to specify icons for representing files with a specific MIME content-type or encoding-type. The server uses the icons on directory listings. The format of the directive is:
AddIcon icon-URL alternate-text type-template
If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server. You must map the URL to a local file and make sure that the mapping directives allow the URL to be passed.
AddIcon movie.gif video video/*
AddIcon binary.gif BIN binary AddIcon text.gif TXT text/* AddIcon image.gif IMG image/* AddIcon movie.gif MOV video/* AddIcon sound.gif AU audio/* AddIcon tar.gif AR multipart/*tar AddIcon compress.gif MP x-compress x-gzip
Use this directive to specify an icon for representing a parent directory on a directory listing. The format of the directive is:
AddParentIcon icon-URL alternate-text
If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server. You must map the URL to a local file and make sure that the mapping directives allow the URL to be passed.
AddParentIcon parent.gif UP
AddParentIcon back.gif UP
Use this directive to specify an icon for representing files with an unknown file type on a directory listing. The format of the directive is:
AddUnknownIcon icon-URL alternate-text
If you are using the server as a proxy, the complete request must be a fully qualified URL pointing to your server. You must map the URL to a local file and make sure that the mapping directives allow the URL to be passed.
AddUnknownIcon saywhat.gif huh
AddUnknownIcon unknown.gif ???
Use this directive to specify if you want your server to always handle directory requests by first searching the directory for a welcome file.
The default value is On, which means that the server always searches the directory for a welcome file. The Welcome directive specifies the names of the files that the server recognizes as welcome files.
If you change the value to Off, the server first checks the last character of directory requests for the slash (/) character. If a directory request ends with a slash, the server searches the directory for a welcome file. If a directory request does not end with a slash, the server attempts to return a directory listing.
If the server does not find a welcome file, or AlwaysWelcome is set to Off and the directory request does not end in a slash, the DirAccess directive controls whether or not the server responds to the request with a directory listing.
Note: Setting AlwaysWelcome to Off does not affect requests that contain only your server name without a directory name. The server will always handle these requests by looking in your document root directory for a welcome file. The server cannot generate a directory listing for the document root directory.
AlwaysWelcome Off
AlwaysWelcome On
Use this directive to specify whether you want your server to return directory listings when requested. The values on the Welcome and AlwaysWelcome directives determine when a request is interpreted as a request for a directory listing.
The default value is On, which means that the server can return directory listings for all directories and subdirectories. If you want to control which directories and subdirectories the server can return directory listings for, use:
DirAccess Selective
If you change the value to Off, the server will not return directory listings.
If you change the value to Selective, the server will return directory listings for any directory that contains a file named .www_browsable. The contents of the .www_browsable file are not important; the server only checks for its existence.
DirAccess Off DirAccess Selective
DirAccess On
Use this directive to specify if and where you want your server to display directory listing README files.
The default value is Top, which means that when the server returns a directory listing, it searches the directory for a file named README. If README is found, the server puts the contents of the file at the top of the directory listing.
If you change the value to Bottom, the server searches for a README file, but puts the contents at the bottom of the directory listing.
If you change the value to Off, the server does not search the directory for a README file.
DirReadme Bottom DirReadme Off
DirReadme Top
Use this directive to specify whether you want the server to put brackets around alternative text on directory listings. The directives that specify directory listing icons also contain alternate text. The alternate text is used in place of an icon if the requesting browser is not displaying graphics.
DirShowBrackets Off
DirShowBrackets On
Use this directive to specify whether directory listings should include the exact byte count for files smaller than 1 KB.
A value of Off means the directory listing shows a size of 1 KB for all files that are 1 KB or smaller.
DirShowBytes On
DirShowBytes Off
Use this directive to specify whether directory listings should distinguish between uppercase and lowercase letters when sorting file names.
A value of On means uppercase letters are placed before lowercase letters.
DirShowCase Off
DirShowCase On
Use this directive to specify whether directory listings should include the last modification date for each file.
DirShowDate Off
DirShowDate On
Use this directive to specify whether directory listings should include descriptions for HTML files. The descriptions are taken from the files' HTML <title> tags.
DirShowDescription Off
DirShowDescription On
Use this directive to specify whether directory listings should include any hidden files on the directory.
The server considers the following to be hidden files:
DirShowHidden Off
DirShowHidden On
Use this directive to specify whether you want your server to include icons in directory listings. Icons can be used to provide a graphic representation of the content type of the files in the listing. The icons themselves are defined by the AddBlankIcon, AddDirIcon, AddIcon, AddParentIcon, and AddUnknownIcon directives.
DirShowIcons Off
DirShowIcons On
Use this directive to set the maximum number of characters to show in the description field on directory listings.
DirShowMaxDescrLength 30
DirShowMaxDescrLength 25
Use this directive to set the maximum number of characters that will be used for file names on directory listings.
DirShowMaxLength 30
DirShowMaxLength 25
Use this directive to set the minimum number of characters that will always be reserved for file names on directory listings. File names in the directory can exceed this number. However, file names cannot be longer than the number specified on the DirShowMaxLength directive.
DirShowMinLength 10
DirShowMinLength 15
Use this directive to specify whether directory listings should include the size of each file.
DirShowSize Off
DirShowSize On
Use this directive to specify URL information to be added at the beginning of each icon-URL specified on an AddBlankIcon, AddDirIcon, AddParentIcon, AddUnknownIcon, or AddIcon directive. The value you specify on this directive is added to the icon-URL value on each of the other directives to form the full request for the icon. The full request can be mapped to a file on your server or it can be a request to another server.
Attention: This directive must be before any of the other icon directives (AddBlankIcon, AddDirIcon, AddParentIcon, AddUnknownIcon, and AddIcon).
IconPath http://icon.server.com:8080/httpd-internal-icons/
In the above example, each request for a directory list icon generates a request to a server named icon.server.com.
IconPath /icons/
With the default settings, each request for a directory list icon generates a request that begins with /icons/. The server uses its mapping rules to map the request to a local file.
Use this directive to specify the name of a welcome file the server should look for to respond to requests that do not contain a specific file name. You can build a list of welcome files by putting multiple occurrences of this directive in the configuration file.
For requests that do not contain a file name or a directory name, the server always looks in the document root directory for a file that matches a name specified on a Welcome directive. If a match is found, the file is returned to the requester.
For requests that contain a directory name but not a file name, the AlwaysWelcome directive controls whether the server looks in the directory for a welcome file to return. By default, AlwaysWelcome is set to a value of On. This means the server always looks in the requested directory for a file matching a name specified on a Welcome directive. If a match is found, the file is returned to the requester.
If the server finds more than one match between files in a directory and file names on Welcome directives, the order of the Welcome directives determines which file is returned. The server uses the Welcome directive closest to the top of the configuration file.
If the server does not find a welcome file in the directory, the DirAccess directive controls whether or not the server responds to the request with a directory listing.
The format of the Welcome directive is:
Welcome file-name [Server-IP-address or hostname]
You can specify an IP address (for example, 204.146.167.72) or you can specify a host name (for example, hostA.bcd.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URLs.
Important migration note: Beginning with Version 4.2, a wildcard character can no longer be specified for a server's IP address.
Welcome letsgo.html Welcome Welcome.html
The above example defines two welcome pages and assumes the AlwaysWelcome directive is set to its default of On. For requests that do not contain a file name, the server would try to return a welcome file from the directory specified on the request (or document root directory if the request does not specify a file name or a directory). The server would first look for a file named letsgo.html. If the directory does not have a letsgo.html file, the server would look for a file named Welcome.html.
Welcome CustomerA.html 9.67.106.79 Welcome CustomerB.html 9.83.100.45
Your server would look for different welcome files based on the IP address of the network connection the request comes in on. For requests coming in on 9.67.106.79 the server would look for welcome files named CustomerA.html. For requests coming in on 9.83.100.45, the server would look for welcome files named CustomerB.html. If the request comes in on a different IP address, the server looks for the default address.
Welcome CustomerA.html hostA.bcd.com Welcome CustomerB.html hostB.bcd.com
Your server would look for different welcome files based on the host name in the URL. For requests coming in for hostA, the server would look for welcome files named CustomerA.html. For requests coming in for hostB, the server would look for welcome files named CustomerB.html. If the request comes in for a different host, the server looks for the default host name.
Welcome Welcome.html Welcome welcome.html Welcome index.html Welcome Frntpage.html
The above default values are shown in the order used by the default configuration.
Use the directives described in this section to control whether individual users of your server can have their own private Web documents.
Use this directive to specify the name of a directory on which you want to allow individual users to have their own subdirectories. Each user can have a subdirectory off of the directory name you specify. URL requests to user subdirectories are in the format ~username. The server passes these requests to the appropriate user subdirectory on the HomeDir directory.
You can use the HomeDir directive either by itself or together with the UserDir directive. Whether or not you use UserDir determines how the server maps URL requests to the user subdirectories.
If you use HomeDir without UserDir, all files within the user subdirectories are accessible to clients. See the description of the UserDir directive for a description and example of using HomeDir with UserDir.
Note: By using this directive, you are telling the server to process all requests to user subdirectories. You do not need to put any additional Pass directives in the configuration file.
HomeDir c:\user
In the above example, the server would map URL requests containing /~username to the c:\user\username directory.
None. By default the server does not accept requests to user subdirectories.
Use this directive to specify the name of a subdirectory where individual users can keep the files they want to be accessible to clients of the server. This directive limits client access to just one subdirectory within each user subdirectory. Each individual subdirectory off of the HomeDir directory can have a subdirectory with the name you specify.
To use this directive, you must also use the HomeDir directive.
For example, you might want to use this directive if your server has access to a LAN server where users have home directories. You can use this directive to define one subdirectory off of each user directory where users could keep Web pages they want to be accessible.
HomeDir c:\user UserDir html_docIn the above example the server would map URL requests containing /~username to the c:\user\username\html_doc directory.
None
Use the directives described in this section to control your server's logs. You can have the server log incoming requests and server errors. If your server is running as a caching proxy server, you can log access requests for files from the proxy server's cache.
You can specify the path and file where you want these logs to be kept, how requests should be logged, and which requests you do not want to log.
You can view the access, error, and trace logs from the server window. Although by default the access log will not write to the server window by default to ensure better server performance, you can change this by setting the LogToGUI directive to On.
You most likely will want to use the common log format. This is the default format and it is the same format used by most other types of Web servers. If you plan to use the access log report function, you are required to use the common log format.
Use this directive to specify the path and file name where you want the server to log access statistics. By default, the server writes an entry to this log each time a client sends the server a request. You can use the NoLog directive if you do not want to log requests from certain clients. For a description of the NoLog directive, refer to "NoLog - Suppress log entries for specific hosts or domains matching a template".
The server starts a new log file each day at midnight if it is running. Otherwise, the server starts a new log file the first time you start it on a given day. When creating the file, the server uses the file name you specify and appends a date extension. The date extension is in the format Mmmddyyyy, where Mmm is the first three letters of the month; dd is the day of the month; and yyyy is the year.
It is a good idea to remove old log files, because they can take up a significant amount of space on your hard drive. For information about removing old log files, refer to "AccessLogArchive - Remove existing access, agent, or referer log files or run a user exit".
AccessLog c:\server\logs\accesslog
AccessLog c:\path\httpd-log
c:\path\ is the value you entered for Logs directory at installation. The installation default is c:\WWW\LOGS
Values specified on the AccessLogArchive directive apply to access, agent, and referer logs. The collective size includes the size of all access logs or all agent logs or all referer logs, not the collective size of all types of logs.
At midnight each night, the server closes the current log and creates a new log file for the coming day. You can choose to do one of the following actions with the closed logs:
To remove access, agent, or referer logs of a given age, specify this directive, in addition to the AccessLogExpire directive. To remove logs when their collective size exceeds a certain amount of storage, specify this directive, in addition to the AccessLogSizeLimit directive.
To allow closed logs to remain on your hard drive, you can accept the default, which is AccessLogArchive none.
To branch to a user exit, specify the path to the user exit and any parameters for the user exit on the AccessLogArchive directive. The server will append to this directive the path to the access, agent, or referer log.
The AccessLogArchive directive can be specified in any of the following formats:
AccessLogArchive purge AccessLogArchive none AccessLogArchive userexit path_to_the_user-exit_program [parameters for the user-exit]
AccessLogArchive purge AccessLogArchive none AccessLogArchive userexit c:\accback\backup.exe -d -a
For the AccessLogArchive userexit example, the user exit invocation is:
AccessLogArchive userexit c:\accback\backup.exe -d -a c:\www\logs\httpd-log
AccessLogArchive none
None.
Use this directive to specify that you do not want to log access requests made for specific files or directories that match a given URL template. For example, you might not want to log access requests for GIF files or you might not want to log access requests to a particular file or directory on your server.
You can have multiple occurrences of this directive in your configuration file. You can also put multiple entries for the same directive if you separate them by one or more spaces.
AccessLogExcludeURL *.gif AccessLogExcludeURL /Freebies/*
None. The server includes in the access log requests for all files and directories.
None.
Use this directive to specify that you do not want to log access requests made for files or directories by using a specific method. For example, you might not want to log DELETE requests for files or directories.
You can have multiple occurrences of this directive in your configuration file. You can also put multiple methods on the same directive if you separate them by one or more spaces.
AccessLogExcludeMethod GET AccessLogExcludeMethod PUT AccessLogExcludeMethod POST AccessLogExcludeMethod DELETE
None. The server includes in the access log the files and directories requested by all types of methods.
None.
Use this directive to specify that you do not want to log access requests made for directories or files of a given MIME type. (Examples of MIME types are text/html, image/gif, and image/jpeg.) For example, you might not want to log access requests for GIF images.
You can have multiple occurrences of this directive in your configuration file. You can also put multiple MIME types on the same directive if you separate them by one or more spaces.
AccessLogExcludeMimeType image/gif
None. The access log includes requests to the server for files and directories of all MIME types.
None.
Use this directive to specify that you do not want to log access requests that fall within a given range of error code numbers. These error code numbers are httpd status codes. You cannot specify individual codes. Specifying 300 indicates that you want to exclude access requests with redirection return codes (301, 302, 303, and 304). To exclude these requests, you would specify:
AccessLogExcludeReturnCode 300
You can have multiple occurrences of this directive in your configuration file. You can also put multiple return codes on the same directive if you separate them by one or more spaces.
AccessLogExcludeReturnCode 300
None. The access log includes all requests to the server, regardless of the code.
None.
Use this directive to specify that you want to remove access log files when they reach a certain age (in days).
This directive requires that you also specify the AccessLogArchive directive, described under "AccessLogArchive - Remove existing access, agent, or referer log files or run a user exit". You can have only one occurrence of this directive in your configuration file.
The format of the AccessLogExpire directive is:
AccessLogExpire number-of-days
The file creation date, as reported by the operating system, is used to determine the age of the access log file. The suffix of the filename, such as httpd-log.Mar221996.extension, is not used to determine file age. (extension is the file extension.)
AccessLogExpire 10
AccessLogExpire 0
None.
Use this directive to specify that you want to remove access log files when they reach a collective size (in megabytes).
This directive requires that you also specify the AccessLogArchive directive, described under "AccessLogArchive - Remove existing access, agent, or referer log files or run a user exit". You can have only one occurrence of this directive in your configuration file.
The format of the AccessLogSizeLimit directive is:
AccessLogSizeLimit number-of-megabytes
This directive takes effect after the AccessLogExpire directive has taken effect.
AccessLogSizeLimit 4
AccessLogSizeLimit 0
None.
Use this directive to include a short description of the report to be created with this template.
AccessReportDescription Report on Web page accesses
None.
None.
Use this directive to specify that you do not want to include in the access report requests made for specific files or directories that match a given URL template. For example, you might not want to include in the report access requests for GIF files or you might not want to include access requests to a particular file or directory on your server.
You can have multiple occurrences of this directive in your configuration file.
AccessReportExcludeURL *.gif AccessReportExcludeURL oldfiles*
None.
None.
Use this directive to specify that you want to include in the access report only access requests made for specific files or directories that match a given URL template. For example, you might want to include in the report only access requests for HTML files or you might want to include access requests to a particular file or directory on your server.
You can have multiple occurrences of this directive in your configuration file.
AccessReportIncludeURL /*.html
None.
None.
Use this directive to specify that you do not want to include in the access report requests made by host names or IP addresses that match a given template.
You can have multiple occurrences of this directive in your configuration file.
Note: To exclude host names, you must set the DNS-Lookup directive to On. If the DNS-Lookup directive is set to Off (the default), you can exclude IP addresses only.
AccessReportExcludeHostName 9.85.*.* AccessReportExcludeHostName *.edu
None.
None.
Use this directive to specify that you want to include in the access report requests made by host names or IP addresses that match a given template.
You can have multiple occurrences of this directive in your configuration file.
Note: To include host names, you must set the DNS-Lookup directive to On. If the DNS-Lookup directive is set to Off (the default), you can include IP addresses only.
AccessReportIncludeHostName 9.9.99.* AccessReportIncludeHostName *.com
None.
None.
Use this directive to specify that you do not want to include in the access report requests of a given method type.
You can have multiple occurrences of this directive in your configuration file.
AccessReportExcludeMethod GET AccessReportExcludeMethod PUT AccessReportExcludeMethod POST
None.
None.
Use this directive to specify that you do not want to include in the access report requests that fall within a given range of error code numbers. These error code numbers are httpd status codes. You cannot specify individual return codes. Specifying 300 indicates that you want to exclude from the report access requests with redirection return codes (301, 302, 303, and 304). To exclude these requests from the report, you would specify AccessReportxcludeReturnCode 300
You can have multiple occurrences of this directive in your configuration file.
AccessReportExcludeReturnCode return code
AccessReportExcludeReturnCode 200 AccessReportExcludeReturnCode 400
None.
None.
Use this directive to specify the path and file name where you want the server to store access log reports and summary databases. We recommend that you accept the default path. If you choose to specify a different path, you will need to create the new directory with all the appropriate permissions and add a PASS directive to enable the server to honor requests for reports in that directory.
If you are running with workload management enabled, you should have unique AccessReportRoot directives for each instance of httpd based on the subsystem name. If you specify -SN system1, you should have AccessReportRoot /usr/lpp/internet/server_root/pub/reports/system1 and a corresponding Pass directive.
AccessReportRoot C:\WWW\BIN\REPORTS
None.
Use this directive to specify the name of the report template. There is a default template named "Top50". For more information, see "Tailoring the reports your server creates".
The format of the AccessReportTemplate is:
AccessReportTemplate report_title
AccessReportTemplate PageHits
AccessReportTemplate Top50 {
AccessReportDescription Top 50 most frequently requested files
and most frequent visitors
AccessReportTopList 50
}
None.
Use this directive to specify the top number of items on which to report.
The format of the AccessReportTopList is:
AccessReportTopList top_number|all
AccessReportTopList 10
None.
None.
Use this directive to specify the path and file name where you want the server to log statistics about which Web browser was used to access a Web page. By default the server writes an entry to this log each time a client sends the server a request. For every entry made in the access log, the agent log has a corresponding entry that indicates the browser used to display the page or file requested by the client.
The server starts a new agent log file each day at midnight if it is running. Otherwise, the server starts a new log file the first time you start it on a given day. When creating the file, the server uses the file name you specify and appends a date extension. The date extension is in the format Mmmddyyyy, where Mmm is the first three letters of the month; dd is the day of the month; and yyyy is the year.
AgentLog c:\server\logs\agent-log
AgentLog c:\path\agent-log
c:\path\ is the value you entered for Logs directory at installation. The installation default is c:\WWW\LOGS
None.
If the server is running as a proxy, you can log requests to the cache separately from other requests. Use the CacheAccessLog directive to specify the path and file name where you want the server to put access requests for cached files. To enable logging of requests to the proxy cache, the following directives must be defined:
The value of CacheAccessLog can either be an absolute path or a path relative to ServerRoot (one example is shown of each).
Note: If you choose to use CacheAccessLog, access requests for cached files are logged, but they are not included in the access reports. Access reports contain only information from access logs, not from cache access logs. Therefore, if you want access reports to contain access requests for cached files, do not specify the CacheAccessLog directive.
The server starts a new log file each day at midnight if it is running. Otherwise, the server starts a new log file the first time you start it on a given day. When creating the file, the server uses the file name you specify and appends a date extension. The date extension is in the format Mmmddyyyy, where Mmm is the first three letters of the month; dd is the day of the month; and yyyy is the year.
Note: It is a good idea to occasionally check the path that contains your log files. If your server has a large amount of activity, your log files could grow to the point that they cause your server to run out of disk space. Make sure the files are not taking up too much space and delete the log files you no longer need.
The format of this directive is
CacheAccessLog <file_path>
CacheAccessLog c:\absolute\path\logfile CacheAccessLog c:\logs\logfile
None. The server does not log cache access requests unless you include this directive in your configuration file.
None.
The server does not write error information to the cgi_error log for 16-bit CGI programs, only for 32-bit CGI programs. Therefore, to get cgi_error log information, you must recompile your 16-bit programs as 32-bit.
The server starts a new CGI error file each day at midnight if it is running. Otherwise, the server starts a new log file the first time you start it on a given day. When creating the file, the server uses the file name you specify and appends a date extension. The date extension is in the format Mmmddyyyy, where Mmm is the first three letters of the month; dd is the day of the month; and yyyy is the year.
CgiErrorLog c:\server\logs\cgi-error
CgiErrorLog c:\path\cgi-error
c:\path\ is the value you entered for Logs directory at installation. The installation default is c:\WWW\LOGS
None.
Use this directive to specify the path and file name where you want the server to log internal errors.
The server starts a new log file each day at midnight if it is running. Otherwise, the server starts a new log file the first time you start it on a given day. When creating the file, the server uses the file name you specify and appends a date extension. The date extension is in the format Mmmddyyyy, where Mmm is the first three letters of the month; dd is the day of the month; and yyyy is the year.
Note: If your server has a large amount of activity, your log files could grow to the point that they cause your server to run out of disk space. To prevent the files from taking up too much space, you can specify the ErrorLogArchive directive described under "ErrorLogArchive - Remove existing error or CGI error log files or run a user exit".
ErrorLog c:\server\logs\errorlog
ErrorLog c:\path\httpd-error
c:\path\ is the value you entered for Logs directory at installation. The installation default is c:\WWW\LOGS
None.
Values specified on the ErrorLogArchive directive apply to error and CGI error logs. The collective size includes the size of all error logs or all CGI logs, not the collective size of both types of logs.
At midnight each night, the server closes the current error and CGI error logs and creates a new log files for the coming day. You can choose to do one of the following actions with the closed error logs:
To remove logs of a given age, specify this directive, in addition to the ErrorLogExpire directive. To remove logs when their collective size exceeds a certain amount of storage, specify this directive, in addition to the ErrorLogSizeLimit directive.
To allow closed logs to remain on your hard drive, you can accept the default, which is ErrorLogArchive none.
To branch to a user exit, specify the path to the user exit and any parameters for the user exit on the ErrorLogArchive directive. The server will append to this directive the path to the error or CGI error log.
The ErrorLogArchive directive can be specified in any of the following formats:
ErrorLogArchive purge ErrorLogArchive none ErrorLogArchive userexit path_to_the_user-exit program [parameters for the user-exit]
ErrorLogArchive purge ErrorLogArchive none ErrorLogArchive userexit c:\errback\backup.exe -d -a
For the ErrorLogArchive userexit example, the user exit invocation is:
ErrorLogArchive userexit c:\errback\backup.exe -d -a c:\www\logs\httpd-error
ErrorLogArchive none
None.
Use this directive to specify that you want to remove error log files when they reach a certain age (in days).
This directive requires that you also specify the ErrorLogArchive directive, described under "ErrorLogArchive - Remove existing error or CGI error log files or run a user exit". You can have only one occurrence of this directive in your configuration file.
The format of the ErrorLogExpire directive is:
ErrorLogExpire number-of-days
The file creation date, as reported by the operating system, is used to determine the age of the error log file. The suffix of the filename, such as httpd-log.Mar221996, is not used to determine file age.
ErrorLogExpire 10
ErrorLogExpire 0
None.
Use this directive to specify that you want to remove error log files when they reach a collective size (in megabytes).
This directive requires that you also specify the ErrorLogArchive directive, described under "ErrorLogArchive - Remove existing error or CGI error log files or run a user exit". You can have only one occurrence of this directive in your configuration file.
The format of the ErrorLogSizeLimit directive is:
ErrorLogSizeLimit number-of-megabytes
This directive takes effect after the ErrorLogExpire directive has taken effect.
ErrorLogSizeLimit 4
ErrorLogSizeLimit 0
None.
Use this directive to specify whether you want your server to write log files in the common format or old format.
If you plan to use the reporting functions described under "Tailoring the reports your server creates", you must accept the default file format, common.
The common format is the one used by most Web servers. The old format was used with early versions of Web servers from CERN. You most likely will want to use the common format, which is the default.
LogFormat Old
LogFormat Common
Common.
Use this directive to specify whether your logs should record entries using local time or Greenwich Mean Time (GMT).
LogTime GMT
LogTime LocalTime
LocalTime.
Use this directive to specify whether you want your server to write access log files to the server window (also known as graphical user interface or GUI). The default setting of OFF improves server performance.
LogToGUI On
LogToGUI Off
Off.
Use this directive to specify that you do not want to log access requests made from specific hosts or domains that match a given template. For example, you may not want to log access requests from local hosts.
You can have multiple occurrences of this directive in your configuration file. You can also put multiple templates on the same directive if you separate them by one or more spaces. You can use host names or IP number addresses on the templates.
Note: To use host name templates, you must set the DNS-Lookup directive to On. If the DNS-Lookup directive is set to Off (the default), you can use IP address templates only.
NoLog 128.141.* *.edu localhost.*
None
None.
Use this directive to specify the path and file name where you want the server log the identity of the Web page that referred to (linked to) the requested Web page. By default the server writes an entry to this log each time a client sends the server a request. For every entry made in the access log, the referer log has a corresponding entry that indicates which page referred to the page that was requested by the client. If no page referred to the requested page, the entry is two quotation marks (" ").
The server starts a new referer log file each day at midnight if it is running. Otherwise, the server starts a new log file the first time you start it on a given day. When creating the file, the server uses the file name you specify and appends a date extension. The date extension is in the format Mmmddyyyy, where Mmm is the first three letters of the month; dd is the day of the month; and yyyy is the year.
RefererLog c:\server\logs\referer-log
RefererLog c:\path\referer-log
c:\path\ is the value you entered for Logs directory at installation. The installation default is c:\WWW\LOGS
None.
Use this directive to specify the path to the compression program (such as PKZIP2, GZIP, or compress) and any program parameters for the compression program. Include any command line parameters on the same line. This compression program is to be used to compress access data log files.
ReportDataCompressionProgram c:\bin\pkunzip
ReportDataCompressionProgram
None.
Use this directive to specify the path to the uncompression program (such as UNZIP, GZIP, or uncompress) and any program parameters for the uncompression program. Include any command line parameters on the same line. This uncompression program is to be used to uncompress access data log files.
ReportDataUnCompressionProgram c:\bin\pkunzip
ReportDataUnCompressionProgram
None.
Use this directive to specify the suffix appended to the compressed file.
ReportDataCompressionSuffix .zip
ReportDataCompressionSuffix
None.
Use this directive to indicate that you want the server to check for old access logs in the log directory that are not listed in the list of log files that have been processed into reports. With this directive, you can process old access log files by:
The format of the ReportProcessOldLogs directive is:
ReportProcessOldLogs append|force|last
Note: The only way to erase reports named access.mmddyyyy files is to archive them with the ReportDataArchive directive, described under "ReportDataArchive - Specify whether to remove existing accessdata files".
ReportProcessOldLogs append ReportProcessOldLogs force ReportProcessOldLogs last
ReportProcessOldLogs append
None.
Use this directive to specify that you want to remove access data files when they reach a collective size (in megabytes).
This directive requires that you also specify the ReportDataArchive directive, described under "AccessLogArchive - Remove existing access, agent, or referer log files or run a user exit". You can have only one occurrence of this directive in your configuration file.
The format of the ReportDataSizeLimit directive is:
ReportDataSizeLimit number-of-megabytes
This directive takes effect after the ReportDataExpire directive has taken effect.
ReportDataSizeLimit 4
ReportDataSizeLimit 0
None.
Use this directive to specify whether you want to remove existing access data log files.
If you want to remove access data files, you also need to specify the ReportDataExpire directive, described under "ReportDataExpire - Remove existing access data files when they reach a given age in days". You can have only one occurrence of this directive in your configuration file.
Even after you remove access data files, the data from these files is still available for reports to use, until you specify the ReportProcessOldLogs directive with the force option.
The ReportDataArchive directive can be specified in any of the following formats:
ReportDataArchive purge ReportDataArchive none ReportDataArchive userexit path_to_the_user-exit_program [parameters for the user-exit]
ReportDataArchive purge ReportDataArchive none ReportDataArchive userexit c:\accback\backup.exe -d -a
For the ReportDataArchive userexit example, the user exit invocation is:
ReportDataArchive userexit c:\accback\backup.exe -d -a c:\www\logs\httpd-log
ReportDataArchive purge
ReportDataArchive none
None
None.
Use this directive to specify that you want to remove access log data files when they reach a certain age (in days).
This directive requires that you also specify the ReportDataArchive directive, described under "ReportDataArchive - Specify whether to remove existing accessdata files". You can have only one occurrence of this directive in your configuration file.
ReportDataExpire number-of-days
The file creation date, as reported by the operating system, is used to determine the age of the error log file. The suffix of the filename, such as httpd-log.Mar221996, is not used to determine file age.
ReportDataExpire 10
ReportDataExpire 0
None.
Use the directives described in this section to control access to your server's resources.
You link protection setups to groups of files based on the requests that are used to access those files. Use the DefProt and Protect directives to define the requests you want to protect.
You can define the actual protection setup in a separate protection statement or directly in the configuration file. Within the configuration file, you can define and label a protection setup using the Protection directive. You can also define a protection setup directly on a DefProt or Protect directive.
This section also describes the subdirectives that define a protection setup.
See Chapter 7. "Protecting your server" for step-by-step instructions on protecting your server resources.
Use this directive to associate a default protection setup with requests that match a template.
Attention: For protection to work properly, you must put your DefProt and Protect directives before any Pass or Exec directives in your configuration file.
The format of the directive is:
DefProt request-template setup [FOR Server-IP-address or hostname]
Protection is not actually activated for requests matching the template unless the request also matches a template on a subsequent Protect directive. See the description of the Protect directive for an explanation of how it is used with DefProt.
You can specify an IP address (for example, FOR 204.146.167.72) or you can specify a host name (for example, FOR hostA.bcd.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.
Notes:
Important migration note: Beginning with Version 4.2, a wildcard character can no longer be specified for a server's IP address.
DefProt /secret/* d:\server\protect\setup1.acc
DefProt /secret/* SECRET-PROT
The above example uses a label name to point to the protection subdirectives. The label name must match a label name on a Protection directive. The Protection directive must come before the DefProt directive.
DefProt {
AuthType Basic
ServerID restricted
PasswdFile d:\docs\WWW\restrict.pwd
GroupFile d:\docs\WWW\restrict.grp
GetMask authors
PutMask authors
}
The above example includes the protection subdirectives as part of the DefProt directive.
DefProt /secret/* CustomerA-PROT 9.67.106.79 DefProt /secret/* CustomerB-PROT 9.83.100.45
The above examples use the optional IP address parameter. If your server receives requests that begin with /secret/, it associates a different default protection setup with the request based on the IP address of the network connection the request comes in on. For requests coming in on 9.67.106.79, the server associates the request with default protection defined on a Protection directive with a label of CustomerA-PROT. For requests coming in on 9.83.100.45, the server associates the request with default protection defined on a Protection directive with a label of CustomerB-PROT.
DefProt /secret/* CustomerA-PROT hostA.bcd.com DefProt /secret/* CustomerB-PROT hostB.bcd.com
The above examples use the optional host name parameter. If your server receives requests that begin with /secret/, it associates a different default protection setup with the request based on the host name in the URL. For requests coming in for hostA, the server associates the request with default protection defined on a Protection directive with a label of CustomerA-PROT. For requests coming in on hostB, the server associates the request with default protection defined on a Protection directive with a label of CustomerB-PROT.
None.
None.
Use this directive to activate protection setup rules for requests that match a template.
Attention: For protection to work properly, you must put your DefProt and Protect directives before any Pass or Exec directives in your configuration file.
The format of the directive is different depending upon whether you want to point to a label or file containing the protection subdirectives or you want to include the protection subdirectives as part of the Protect directive.
If you want to point to a label or file containing the protection subdirectives, the format is as follows:
Protect request-template [setup-file/label[FOR Server-IP-address or hostname ]]
If you want to include the protection subdirectives as part of the Protect directive, the format is as follows:
Protect request-template [Server-IP-address or hostname] {
subdirective value
subdirective value
.
.
.
}
This parameter is optional. If it is omitted, the protection setup is defined by the most recent DefProt directive that contains a matching template.
Protection setup is defined with protection subdirectives. See "Protection Subdirectives" for descriptions of the protection subdirectives. If present, this parameter can take one of three forms:
See "Protection Subdirectives" for descriptions of the protection subdirectives.
You can specify an IP address (for example, FOR 204.146.167.72) or you can specify a host name (for example, FOR hostA.bcd.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.
Notes:
Important migration note: Beginning with Version 4.2, a wildcard character can no longer be specified for a server's IP address.
Protection BUS-PROT {
AuthType Basic
ServerID restricted
PasswdFile d:\docs\WWW\restrict.pwd
GroupFile d:\docs\WWW\restrict.grp
GetMask authors
PutMask authors
}
DefProt /secret/* d:\server\protect\setup1.acc
Protect /secret/scoop/*
Protect /secret/business/* BUS-PROT
Protect /topsecret/* {
AuthType Basic
ServerID restricted
PasswdFile d:\docs\WWW\restrict.pwd
GroupFile d:\docs\WWW\restrict.grp
GetMask topbrass
PutMask topbrass
}
Pass /secret/scoop/* d:\WWW\restricted\*
Pass /secret/business/* d:\WWW\confidential\*
Pass /topsecret/* d:\WWW\topsecret\*
In the above example, the server activates protection as follows:
Protect /secret/* CustomerA-PROT FOR 9.67.106.79
Protect /secret/* CustomerB-PROT FOR 9.83.100.45
Protect /topsecret/* 9.67.106.79 {
AuthType Basic
ServerID restricted
PasswdFile /docs/WWW/customer-A.pwd
GroupFile /docs/WWW/customer-A.grp
GetMask A-brass
PutMask A-brass
}
Protect /topsecret/* 9.83.100.45 {
AuthType Basic
ServerID restricted
PasswdFile /docs/WWW/customer-B.pwd
GroupFile /docs/WWW/customer-B.grp
GetMask B-brass
PutMask B-brass
}
The above examples use IP addresses. If your server receives requests that begin with /secret/ or /topsecret/, it activates a different protection setup for the request based on the IP address of the network connection the request comes in on.
For /secret/ requests coming in on 9.67.106.79, the server activates the protection setup defined on a Protection directive with a label of CustomerA-PROT. For /topsecret/ requests coming in on 9.67.106.79, the server activates the protection setup defined inline on the Protect directive for /topsecret/.
For /secret/ requests coming in on 9.83.100.45, the server activates the protection setup defined on a Protection directive with a label of CustomerB-PROT. For /topsecret/ requests coming in on 9.83.100.45, the server activates the protection setup defined inline on the Protect directive for /topsecret/.
Protect /secret/* CustomerA-PROT FOR hostA.bcd.com
Protect /secret/* CustomerB-PROT FOR hostB.bcd.com
Protect /topsecret/* hostA.bcd.com {
AuthType Basic
ServerID restricted
PasswdFile /docs/WWW/customer-A.pwd
GroupFile /docs/WWW/customer-A.grp
GetMask A-brass
PutMask A-brass
}
Protect /topsecret/* hostB.bcd.com {
AuthType Basic
ServerID restricted
PasswdFile /docs/WWW/customer-B.pwd
GroupFile /docs/WWW/customer-B.grp
GetMask B-brass
PutMask B-brass
}
The above examples use virtual hosts. If your server receives requests that begin with /secret/ or /topsecret/, it activates a different protection setup for the request based on the host name in the URL.
For /secret/ requests coming in for hostA.bcd.com, the server activates the protection setup defined on a Protection directive with a label of CustomerA-PROT. For /topsecret/ requests coming in for hostA.bcd.com, the server activates the protection setup defined inline on the Protect directive for /topsecret/.
For /secret/ requests coming in for hostB.bcd.com, the server activates the protection setup defined on a Protection directive with a label of CustomerB-PROT. For /topsecret/ requests coming in for hostB.bcd.com, the server activates the protection setup defined inline on the Protect directive for /topsecret/.
Protection is provided for the Configuration and Administration forms by a Protect directive with a request template of /admin-bin/*.
Use this directive to define a protection setup within the configuration file. You give the protection setup a name and define the type of protection using protection subdirectives.
Note: In the configuration file, you must place Protection directives before any DefProt or Protect directives that point to them.
The format of the directive is:
Protection label-name {
subdirective value
subdirective value
.
.
.
}
See "Protection Subdirectives" for descriptions of the protection subdirectives.
Protection NAME-ME {
AuthType Basic
ServerID restricted
PasswdFile d:\WWW\password.pwd
GroupFile d:\WWW\group.grp
GetMask groupname
PutMask groupname
}
Protection PROT-ADMIN {
PasswdFile C:\TCPIP\ETC\ADMIN.PWD
Mask All@(*)
PostMask All@(*)
PutMask All@(*)
GetMask All@(*)
AuthType Basic
ServerID Private_Authorization
}
Following are descriptions of each of the protection subdirectives that can be used in a protection setup. The subdirectives are in alphabetical order.
Protection setups can either be in separate files or within the configuration file as part of DefProt, Protect, or Protection directives.
See "Protection example (without SSL client authentication)" and the previous descriptions of the DefProt, Protect, and Protection directives for examples of using protection setups.
Use this subdirective with a value of On if you want Access Control List files (ACL) to override the masks specified in the protection setup. If a directory being protected by the protection setup has an ACL file, the mask subdirectives in the protection setup are ignored. (The mask subdirectives are DeleteMask, GetMask, Mask, PostMask, and PutMask.)
See "Using Access Control List (ACL) files" for more information on ACL files.
ACLOverride On
Use this subdirective when limiting access based on user names and passwords. Specify the type of authentication to use when the client sends a password to the server. With basic authentication (AuthType Basic), passwords are sent to the server as plain text. They are encoded, but not encrypted.
AuthType Basic
Use this subdirective to specify user names, groups, and addresses templates authorized to make DELETE requests to a protected directory. See "Rules for specifying user names, group names, and address templates".
DeleteMask authors,(niceguy,goodie)@96.96.3.1,128.141.*.*
Use this subdirective to specify user names, groups, and address templates authorized to make GET requests to a protected directory. See "Rules for specifying user names, group names, and address templates".
GetMask authors,(niceguy,goodie)@96.96.3.1,128.141.*.*
Use this subdirective to specify the path and file name of the server group file that you want this protection setup to use. The groups defined within the server group file can then be used by:
See "Using server group files" more information about server group files.
GroupFile d:\docs\WWW\restrict.group
Use this subdirective to specify user names, groups, and address templates authorized to make HTTP requests not covered by other mask subdirectives. See "Rules for specifying user names, group names, and address templates". See "Methods - Set method acceptance" for descriptions of the HTTP methods supported by the server.
Mask authors,(niceguy,goodie)@96.96.3.1,128.141.*.*
Use this subdirective when limiting access based on user names and passwords. Specify the path and name of the password file that you want this protection setup to use.
Because some browsers such as NetScape cache userid/password by security realm (ServerId) within host, follow these guidelines when specifying ServerId and password files:
PasswdFile c:\WWW\restrict.password
For a secure server, use this subdirective to specify users, groups, and address templates authorized to make POST requests to a protected directory. See "Rules for specifying user names, group names, and address templates".
PostMask authors,(niceguy,goodie)@96.96.3.1,128.141.*.*
Use this subdirective to specify users, groups, and address templates authorized to make PUT requests to a protected directory. See "Rules for specifying user names, group names, and address templates".
PutMask authors,(niceguy,goodie)@96.96.3.1,128.141.*.*
Use this subdirective when limiting access based on user names and passwords. Specify a name you want to associate with the password file being used. The name does not need to be a real machine name.
The name is used as an identifier to the requester. Since different protection setups can use different password files, having a name associated with the protection setup can help the client decide which password to send. Most clients display this name when prompting for a user name and password.
Because some browsers such as NetScape cache userid/password by security realm (ServerId) within host, follow these guidelines when specifying ServerId and password files:
ServerID restricted
If you implement SSL client authentication, the server requests the client's certificate when the client makes an https request. The server establishes a secure connection whether or not the client has a valid certificate.
You can restrict who can access documents by using password files and/or user or group authentication in protection setups as described in Chapter 7. "Protecting your server". You can further restrict who can access documents by coding SSL client authentication parameters on protection setups, ACL files, or both. Coding SSL client authentication parameters on protection setups is described in "Creating protection setups for SSL client authentication"; coding them in ACL files is described in "Step 5. Limiting access to individual files".
Using SSL client authentication parameters as subdirectives, you can specify that the client certificate is valid or you can specify all or part of the Distinguished Name (DN) of a client or of the certification authority (CA) who issued the client's certificate.
When you use SSL client authentication parameters, the server first checks to see if the client certificate is valid, as is. If not, it compares any DN information in a protection setup and then compares any DN information in an ACL file with the DN information in the client's certificate. If the DN information matches, the server serves the document.
The following can be specified on the Protection or Protect directive:
Protect /topsecret/* {
CommonName "Dr Sheila A. Jones"
Organization "RTP Quick Care Center"
Mask Anybody@(*)
}
In the above example of an inline Protect directive, any https request beginning with /topsecret/ causes the server to request the client's certificate. If the client's common name is Dr Sheila A. Jones and the client's organization is RTP Quick Care Center, then the server returns the document to the client.
For a secure server, use the directives described in this section to control how your server uses network security functions.
If you change these directives, you must stop your server and then start it again for the changes to take effect. The server will not pick up the changes if you only restart it. If you change any of the security directives and then plan to uninstall the current server and reinstall a new one, it's a good idea to first back up the server configuration file. Then you should compare any security settings you had changed to the settings after you reinstall the server to be sure they were retained.
Use this directive to set the name for the key ring file.
If you change this directive, you must stop your server and then start it again for the change to take effect. The server will not pick up the change if you only restart it.
KeyFile keyfile.kyr
None
Use this directive to turn on or off the port defined by the Port directive.
Set NormalMode on for an HTTP connection. If you also want an SSL connection, set SSLMode on.
Note: You should have either this directive or the SSLMode directive turned on. However, if both NormalMode and SSLMode are turned off, the server will start in normal mode, and you won't have a secure network connection.
If you change this directive, you must stop your server and then start it again for the change to take effect. The server will not pick up the change if you only restart it.
NormalMode on
NormalMode on
Use this directive to enable SSL client authentication.
When this directive is enabled, the server requests a certificate from each client that makes an https request. Only enable client authentication if you need to authenticate clients; SSL client authentication increases network traffic.
If you change this directive, you must stop your server and then start it again for the change to take effect. The server will not pick up the change if you only restart it.
SSLClientAuth off
SSLClientAuth on
Use this directive to turn on or off the port defined by the SSLPort directive.
Set SSLMode on for an SSL connection. If you also want an HTTP connection, set NormalMode on.
Note: You should have either this directive or the NormalMode directive turned on. However, if both NormalMode and SSLMode are turned off, the server will start in normal mode, and you won't have a secure network connection.
If you change this directive, you must stop your server and then start it again for the change to take effect. The server will not pick up the change if you only restart it.
SSLMode on
SSLMode off
Use this directive to set the port for SSL security. The server will use this port only for HTTPS requests. (Requests for HTTP will still come on the port that you set with the Port directive.)
If you want to use a port other than 443, specify a port above 1024.
If you change this directive, you must stop your server and then start it again for the change to take effect. The server will not pick up the change if you only restart it.
SSLPort 443
SSLPort 443
Use the directives described in this section to associate files with particular extensions to the meta-information found in the headers of incoming requests. Based on the file extension (suffixes) specified in these directives, the server binds files to a content type, content encoding, content language, character set, or to a browser sending a request.
The resource mapping directives, AddType, AddEncoding, AddLanguage, AddCharSet, and AddClient, are used to associate meta-information from request headers with file suffixes or extensions. Meta-information can consist of MIME type, encoding, quality, charset, language, and browser (agent) type.
The following table identifies meta-information that is
associated with each directive.
Table 2. Meta-information and Associated Directive
+==========+=======+=======+========+==========+==========+=======+=======+ | Directiv | Suffi | MIME | Encodi | Quality | Charset | Langu | Agent | | e | x | | ng | | | age | | +==========+=======+=======+========+==========+==========+=======+=======+ | AddType | X | X | X | X | X | | | | | | | | (Optiona | (Optiona | | | | | | | | l) | l) | | | +----------+-------+-------+--------+----------+----------+-------+-------+ | AddEncod | X | | X | X | | | | | ing | | | | (Optiona | | | | | | | | | l) | | | | +----------+-------+-------+--------+----------+----------+-------+-------+ | AddLangu | X | | | X | | X | | | age | | | | (Optiona | | | | | | | | | l) | | | | +----------+-------+-------+--------+----------+----------+-------+-------+ | AddCharS | X | | | X | X | | | | et | | | | (Optiona | | | | | | | | | l) | | | | +----------+-------+-------+--------+----------+----------+-------+-------+ | AddClien | X | | | 2.0 | | | X | | t | | | | (Implied | | | | | | | | | ) | | | | +----------+-------+-------+--------+----------+----------+-------+-------+
There are two pieces to multi-format processing:
The browser sends accept-headers containing acceptable values (content-type, content-encoding, language, charset) that you can associate to file suffixes with the configuration directives. The browser also sends a user-agent header that identifies its browser type that you can associate with file suffixes in the same manner.
The server finds all files with any extension that matches the directory and file name and uses multi-format processing to choose the best file to return.
Multi-format processing computes the quality of a file based on the set of suffixes in the directory for the requested file name and sends the highest quality it finds. A perfect match is always the highest quality.
Quality is a floating point number between 0.0 and 1.0 that represents the relative desirability of a file. For example, if the file abc.html is requested and cannot be found, the server searches the directory for all files that match abc.*. Multi-format processing adds the * and finds all that may qualify.
When computing file quality, each file is given the value of 1.0 and this is multiplied by the quality of each suffix. The quality of a suffix is based on the quality value specified in the directive which is multiplied by the quality value specified in the accept-header. This can be shown as:
fileQ = (1.0 X ((suffixQ1) X (suffixQ2)...))or
fileQ = (1.0 X ((directiveQ X headerQ) X (directiveQ X headerQ)...))
The quality value is optional on many of the directives. If one is not specified, then the value of 1.0 is assumed. Also, if the accept-header does not specify a quality value, 1.0 is assumed.
If the server is processing a file and suffix that is defined in the list of AddClient directives, and the requester agent matches the defined string, the server doubles the file quality (implying a value of 2.0). If no match is found, this does not happen.
If you have HTML source files in different languages,
myfile.du.html myfile.uk.htmlyou could use these directives for multi-format processing:
AddLanguage .du du AddLanguage .uk en_UK AddType .html text/html 8bit
Then, if a browser sends a request for myfile.multi and sends the header Accept-Language: du, the server returns myfile.du.html. The server provides defaults for most commonly used extension. Use the extension definition directives only if you need to add new definitions or change the default definitions.
Use this directive to bind files with a particular extension to a language. The format of the directive is:
AddLanguage .extension language
AddLanguage .en en_US
This example defines files with a .en extension as being in American English.
AddLanguage .uk en_UK
This example defines files with a .uk extension as being in United Kingdom English.
None.
Use this directive to bind files with a particular extension to a MIME-encoding type. This directive is seldom used.
The format of the directive is:
AddEncoding .extension encoding
AddEncoding .qp quoted_printable
AddEncoding .Z x-compress 1.0 AddEncoding .gz x-gzip 1.0
Use this directive to specify the character set (code page) documents are stored in. (You can also specify character set on the AddType directive.)
The format of the directive is:
AddCharSet .extension character-set
AddCharSet .932 IBM-932
Use this directive to bind files with a particular extension to a MIME type/subtype. You can have multiple occurrences of this directive in your configuration file. The server provides defaults for most commonly used extension. The format of the directive is:
AddType .extension type/subtype encoding [quality[ character-set]]
Any other value of encoding receives the same treatment as binary and is passed in MIME headers as a content encoding MIME header. 7bit and 8bit is not sent in MIME headers.
AddType .ps application/postscript 8bit 1.0 AddType *.* application/binary binary 0.3the server would use the application/postscript line because its quality number is higher.
AddType .bin application/octet-stream binary 0.8
AddType .class application/octet-stream binary 1.0 AddType .mime www/mime binary 1.0 AddType .bin application/octet-stream binary 1.0 AddType .oda application/oda binary 1.0 AddType .pdf application/pdf binary 1.0 AddType .ai application/postscript 8bit 0.5 AddType .PS application/postscript 8bit 0.8 AddType .eps application/postscript 8bit 0.8 AddType .ps application/postscript 8bit 0.8 AddType .rtf application/x-rtf 7bit 1.0 AddType .csh application/x-csh 7bit 0.5 AddType .dvi application/x-dvi binary 1.0 AddType .hdf application/x-hdf binary 1.0 AddType .latex application/x-latex 8bit 1.0 AddType .nc application/x-netcdf binary 1.0 AddType .cdf application/x-netcdf binary 1.0 AddType .sh application/x-sh 7bit 0.5 AddType .tcl application/x-tcl 7bit 0.5 AddType .tex application/x-tex 8bit 1.0 AddType .texi application/x-texinfo 7bit 1.0 AddType .texinfo application/x-texinfo 7bit 1.0 AddType .t application/x-troff 7bit 0.5 AddType .roff application/x-troff 7bit 0.5 AddType .tr application/x-troff 7bit 0.5 AddType .man application/x-troff-man 7bit 0.5 AddType .me application/x-troff-me 7bit 0.5 AddType .ms application/x-troff-ms 7bit 0.5 AddType .src application/x-wais-source 7bit 1.0 AddType .bcpio application/x-bcpio binary 1.0 AddType .cpio application/x-cpio binary 1.0 AddType .gtar application/x-gtar binary 1.0 AddType .shar application/x-shar 8bit 1.0 AddType .sv4cpio application/x-sv4cpio binary 1.0 AddType .sv4crc application/x-sv4crc binary 1.0
The following are neutral CAE formats:
AddType .igs application/iges binary 1.0 AddType .iges application/iges binary 1.0 AddType .IGS application/iges binary 1.0 AddType .IGES application/iges binary 1.0 AddType .stp application/STEP 8bit 1.0 AddType .STP application/STEP 8bit 1.0 AddType .step application/STEP 8bit 1.0 AddType .STEP application/STEP 8bit 1.0 AddType .dxf application/dxf binary 1.0 AddType .DXF application/dxf binary 1.0 AddType .vda application/vda binary 1.0 AddType .VDA application/vda binary 1.0 AddType .set application/set 8bit 1.0 AddType .SET application/set 8bit 1.0 AddType .stl application/SLA 8bit 1.0 AddType .STL application/SLA 8bit 1.0
The following are vendor-specific CAD-formats commonly used by CERN and in HEP institutes:
AddType .dwg application/acad binary 1.0 AddType .DWG application/acad binary 1.0 AddType .SOL application/solids binary 1.0 AddType .DRW application/drafting binary 1.0 AddType .prt application/pro_eng binary 1.0 AddType .PRT application/pro_eng binary 1.0 AddType .unv application/i-deas binary 1.0 AddType .UNV application/i-deas binary 1.0 AddType .CCAD application/clariscad binary 1.0 AddType .snd audio/basic binary 1.0 AddType .au audio/basic binary 1.0 AddType .aiff audio/x-aiff binary 1.0 AddType .aifc audio/x-aiff binary 1.0 AddType .aif audio/x-aiff binary 1.0 AddType .wav audio/x-wav binary 1.0 AddType .gif image/gif binary 1.0 AddType .ief image/ief binary 1.0 AddType .jpg image/jpeg binary 1.0 AddType .JPG image/jpeg binary 1.0 AddType .JPE image/jpeg binary 1.0 AddType .jpe image/jpeg binary 1.0 AddType .JPEG image/jpeg binary 1.0 AddType .jpeg image/jpeg binary 1.0 AddType .tif image/tiff binary 1.0 AddType .tiff image/tiff binary 1.0 AddType .ras image/cmu-raster binary 1.0 AddType .pnm image/x-portable-anymap binary 1.0 AddType .pbm image/x-portable-bitmap binary 1.0 AddType .pgm image/x-portable-graymap binary 1.0 AddType .ppm image/x-portable-pixmap binary 1.0 AddType .rgb image/x-rgb binary 1.0 AddType .xbm image/x-xbitmap 7bit 1.0 AddType .xpm image/x-xpixmap binary 1.0 AddType .xwd image/x-xwindowdump binary 1.0 AddType .html text/html 8bit 1.0 AddType .htm text/html 8bit 1.0 AddType .htmls text/html 8bit 1.0 AddType .c text/plain 7bit 0.5 AddType .h text/plain 7bit 0.5 AddType .C text/plain 7bit 0.5 AddType .cc text/plain 7bit 0.5 AddType .hh text/plain 7bit 0.5 AddType .java text/plain 7bit 0.5 AddType .m text/plain 7bit 0.5 AddType .f90 text/plain 7bit 0.5 AddType .txt text/plain 7bit 0.5 AddType .rtx text/richtext 7bit 1.0 AddType .tsv text/tab-separated-values 7bit 1.0 AddType .etx text/x-setext 7bit 0.9 AddType .MPG video/mpeg binary 1.0 AddType .mpg video/mpeg binary 1.0 AddType .MPE video/mpeg binary 1.0 AddType .mpe video/mpeg binary 1.0 AddType .MPEG video/mpeg binary 1.0 AddType .mpeg video/mpeg binary 1.0 AddType .qt video/quicktime binary 1.0 AddType .mov video/quicktime binary 1.0 AddType .avi video/x-msvideo binary 1.0 AddType .movie video/x-sgi-movie binary 1.0 AddType .gz multipart/x-gzip binary 1.0 AddType .zip multipart/x-zip binary 1.0 AddType .tar multipart/x-tar binary 1.0 AddType .ustar multipart/x-ustar binary 1.0 AddType *.* www/unknown binary 0.2 AddType * www/unknown binary 0.2 AddType .cxx text/plain 7bit 0.5 AddType .for text/plain 7bit 0.5 AddType .mar text/plain 7bit 0.5 AddType .log text/plain 7bit 0.5 AddType .com text/plain 7bit 0.5 AddType .sdml text/plain 7bit 0.5 AddType .list text/plain 7bit 0.5 AddType .lst text/plain 7bit 0.5 AddType .def text/plain 7bit 0.5 AddType .conf text/plain 7bit 0.5 AddType . text/plain 7bit 0.5
Use this directive to specify whether you want your server to distinguish between uppercase and lowercase letters when comparing file extension to the extension patterns on AddClient, AddCharSet, AddType, AddEncoding, and AddLanguage directives. By default, the server does not distinguish between uppercase and lowercase.
SuffixCaseSense On
SuffixCaseSense Off
Use this directive to bind files with particular extensions to the type and version of client that is sending the request. This is often referred to as automatic browser detection.
All HTTP requests contain a User-Agent header that identifies the browser sending the request. The Internet Connection Secure Server enables you to detect which browser was used to send a request and, based on this information, respond with a version of a Web page, a document, or other file that is appropriate for that browser.
For example, your server can send a page written in HTML 3.0 only to browsers that are known to support it and send a version of the same page written in HTML 2.0 to all other browsers.
Automatic browser detection is only effective for multi-format processing; that is when a requesting URL specifies a file without an extension and no file with that name exists, or it specifies a file with the extension .multi. For example, a link from this HTML anchor tag initiates multi-format processing:
<A HREF="http://www.raleigh.ibm.com/cjjd/tscores.multi>
As a result, the server will evaluate the values passed in the request headers (such as User-Agent), along with the extensions of all the tscores files and the associations specified in the directives. Based on this, it will try to find the file that is the 'best match' to send in its response.
You can have multiple occurrences of this directive in your configuration file. The sequence of AddClient directives is important. The first AddClient directive that matches a client's User-Agent value is the one that will be used to determine the file extension.
If a client's User-Agent is not matched in an AddClient directive, the server looks for a generic file extension (.htm or .html) to send. If the server cannot find a generic file extension, it uses an algorithm to calculate the quality of all the extensions for that file and sends the file whose extension yields the highest quality, considering it to be the 'best match'.
The format of the directive is:
AddClient .extension user-agent
You cannot use any wildcard characters in this pattern. This extension can be one of a string of suffixes used to qualify a file. For example, the extension .Mozilla can apply to a file named TxtSample.UK.Mozilla.html or TxtSample.html.Mozilla.eng.
This field is case-sensitive. You can use an asterisk (*) as a wildcard character in this field. For example, IBM* applies to all versions of IBM's browser, WebExplorer.
AddClient .Mozilla Mozilla/2.*
AddClient .OldMozilla Mozilla/1.*
AddClient .Webex IBM*
If a client's User-Agent is not matched in an AddClient directive, the server looks for a generic file extension (.htm or .html) to send. If the server cannot find a generic file extension, it uses an algorithm to calculate the quality of all the extensions for that file and sends the file whose extension yields the highest quality, considering it to be the 'best match'.
None
Using automatic browser detection for sending various welcome pages requires additional considerations. Follow these steps to enable browser detection and multi-format processing for your welcome pages. As an example, they show how to serve different versions of the index.html file (in a fictitious webhome directory) but this also works for Welcome.html, welcome.html, or Frontpage.html files.
Welcome index.multi
AddClient .Mozilla Mozilla/2.*
AddClient .OldMozilla Mozilla/1.*
AddClient .Webex IBM*
http://www.web4hire.com/webhome/
Use the directives described in this section to control which requests your server accepts and where the server looks for resources.
Use the mapping directives (Exec, Fail, Map, Pass, and Redirect) to control which requests your server accepts and to map URL requests to your actual files.
You can use the mapping directives to create a virtual hierarchy of Web resources. You can then change the physical location of files or directories without affecting the virtual layout. Even if your server sends documents from different file systems, it can present a virtual layout.
The server applies the mapping directives in the order they appear in the configuration file until a request has been accepted, rejected, or there are no more directives that apply to the request.
Use this directive to specify a template for requests you want to accept and respond to by running a CGI program. Once a request matches a template on an Exec directive, the request is not compared to request templates on any subsequent directives.
The format of the directive is:
Exec request-template program-path [Server-IP-address or hostname]
You must use an asterisk as a wildcard in both the request-template and program-path. The part of the request that matches the request-template wildcard must begin with the name of the file that contains the CGI program.
The request can also contain additional data that is passed to the CGI program in the PATH_INFO environment variable. The additional data follows the first slash character that comes after the CGI program file name on the request. The data is passed according to CGI specifications.
Important migration note: The Exec directive is now recursive and applies to all subdirectories. You no longer need a separate Exec directive for each directory under cgi-bin and admin-bin.
You can specify an IP address (for example, 204.146.167.72) or you can specify a host name (for example, hostA.bcd.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.
Important migration note: Beginning with Version 4.2, a wildcard character can no longer be specified for a server's IP address.
Exec /idd/depts/* d:\depts\bin\*
In the above example, if your server receives a request of /idd/depts/plan/c92, it runs the CGI program in d:\depts\bin\plan.exe or d:\depts\bin\plan.cmd with c92 passed to the program as input.
Exec /cgi-bin/* C:\CGI-BIN\customerA\* 204.146.167.72 Exec /cgi-bin/* C:\CGI-BIN\customerB\* 9.83.100.45
The above example uses the optional IP address parameter. If your server receives requests that begin with /cgi-bin/, it serves the request from a different directory based on the IP address of the network connection the request comes in on. For requests coming in on 9.67.106.79, the server uses the C:\CGI-BIN\customerA directory. For requests coming in on any connection with an address of 9.83.100.45, the server uses the C:\CGI-BIN\customerB directory.
Exec /cgi-bin/* C:\CGI-BIN\customerA\* hostA.bcd.com Exec /cgi-bin/* C:\CGI-BIN\customerB\* hostB.bcd.com
The above example uses the optional host name parameter. If your server receives requests that begin with /cgi-bin/, it serves the request from a different directory based on the host name in the URL. For requests coming in for hostA.bcd.com, the server uses the C:\CGI-BIN\customerA directory. For requests coming in on any connection for hostB.bcd.com, the server uses the C:\CGI-BIN\customerB directory.
Exec /admin-bin/* d:\path\* Exec /cgi-bin/* d:\path\*
d:\path\ is replaced by a directory you entered at installation. If you used the installation defaults, your default Exec directives would be:
Exec /admin-bin/* C:\WWW\ADMIN\* Exec /cgi-bin/* C:\WWW\CGI-BIN\*
Use this directive to specify a template for requests you do not want to process. Once a request matches a template on a Fail directive, the request is not compared to request templates on any subsequent directives.
The format of the directive is:
Fail request-template [Server-IP-address or hostname]
You can use an asterisk as a wildcard in the template. The tilde character just after a slash (/~) has to be explicitly matched; a wildcard cannot be used to match it.
You can specify an IP address (for example, 204.146.167.72) or you can specify a host name (for example, hostA.bcd.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.
Important migration note: Beginning with Version 4.2, a wildcard character can no longer be specified for a server's IP address.
Fail /usr/local/private/*
In the above example, the server rejects any requests beginning with /usr/local/private/.
Fail /customerB/* 204.146.167.72 Fail /customerA/* 9.83.100.45
The above example uses the optional IP address parameter. The server rejects any requests beginning with /customerB/ if the request comes in on a network connection with IP address 204.146.167.72 The server rejects any requests beginning with /customerA/ if the request comes in on a network connection with an IP address of 9.83.100.45.
Fail /customerB/* hostA.bcd.com Fail /customerA/* hostB.bcd.com
The above example uses the optional host name parameter. The server rejects any requests beginning with /customerB/ if the request comes in for hostA. The server rejects any requests beginning with /customerA/ if the request comes in for hostB.
None.
Use this directive to specify a template for requests you want to change to a new request string. After your server changes the request, it takes the new request string and compares it to the request templates on subsequent directives.
The format of the directive is:
Map request-template new-request [Server-IP-address or hostname]
You can use an asterisk as a wildcard in the template. The tilde character just after a slash (/~) has to be explicitly matched; a wildcard cannot be used to match it.
You can specify an IP address (for example, 204.146.167.72) or you can specify a host name (for example, hostA.raleigh.ibm.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.
Important migration note: Beginning with Version 4.2, a wildcard character can no longer be specified for a server's IP address.
Map /stuff/* /good/stuff/*
In the above example, your server would take any requests starting with /stuff/ and change the /stuff/ portion of the request to /good/stuff/. Anything that followed /stuff/ on the original request would also be included in the new request string. So /stuff/whatsup/ would change to /good/stuff/whatsup/. Your server would take the new request string and continue to compare it to request templates on subsequent directives.
Map /stuff/* /customerA/good/stuff/* 204.146.167.72 Map /stuff/* /customerB/good/stuff/* 9.83.104.45
The above examples use the optional IP address parameter. If your server receives requests that begin with /stuff/, it changes the request to a different request string based on the IP address of the network connection the request comes in on. For requests coming in on 204.146.167.72 the server changes the /stuff/ portion of the request to /customerA/good/stuff/. For requests coming in on any connection with an address of 9.83.100.45, the server changes the /stuff/ portion of the request to /customerB/good/stuff/.
Map /stuff/* /customerA/good/stuff/* hostA.bcd.com Map /stuff/* /customerB/good/stuff/* hostB.bcd.com
The above examples use the optional host name parameter. If your server receives requests that begin with /stuff/, it changes the request to a different request string based on the host name in the URL. For requests coming in for hostA, the server changes the /stuff/ portion of the request to /customerA/good/stuff/. For requests coming in for hostB, the server changes the /stuff/ portion of the request to /customerB/good/stuff/.
Use this directive to specify a template for requests you want to accept and respond to with a document from your server. Once a request matches a template on a Pass directive, the request is not compared to request templates on any subsequent directives.
The format of the directive is:
Pass request-template [file-path [Server-IP-address or hostname]]
You can use an asterisk as a wildcard in the template. The tilde character just after a slash (/~) has to be explicitly matched; a wildcard cannot be used to match it.
This parameter is optional. If you do not specify a path, the request itself is used as the path. The drive is assumed to be the drive where the server program is installed.
You can specify an IP address (for example, 204.146.167.72) or you can specify a host name (for example, hostA.raleigh.ibm.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.
Important migration note: Beginning with Version 4.2, a wildcard character can no longer be specified for a server's IP address.
Pass /updates/parts/* C:\WWW\HTML\catalog\updates\parts\*
In the above example, your server would respond to a request starting /updates/parts/ with a document from C:\WWW\HTML\catalog\updates\parts\. Anything that followed /updates/parts/ would also be used to identify the document. So your server would respond to the request /updates/parts/printers/ribbon.html with the document in file C:\WWW\HTML\catalog\updates\parts\printers\ribbon.html.
Pass /gooddoc/*
In the above example, your server would respond to a request starting with /gooddoc/ with a document from d:\gooddoc\ (where d: is the drive where you installed the server program). So your server would respond to the request /gooddoc/volume1/issue2/newsletter4.html with the document in file d:\gooddoc\volume1\issue2\newsletter4.html.
Pass /parts/* C:\customerA\catalog\* 204.146.167.72 Pass /parts/* C:\customerB\catalog\* 9.83.104.45
The above examples use the optional IP address parameter. If your server receives requests that begin with /parts/, it returns a file from a different directory based on the IP address of the network connection the request comes in on. For requests coming in on 204.146.167.72 the server returns a file from C:\customerA\catalog\. For requests coming in on any connection with an address of 9.83.104.45, the server returns a file from C:\customerB\catalog\.
Pass /parts/* C:\customerA\catalog\* hostA.bcd.com Pass /parts/* C:\customerB\catalog\* hostB.bcd.com
The above examples use the optional host name parameter. If your server receives requests that begin with /parts/, it returns a file from a different directory based on the IP address of the network connection the request comes in on. For requests coming in for hostA.bcd.com, the server returns a file from C:\customerA\catalog\. For requests coming in for hostB.bcd.com, the server returns a file from C:\customerB\catalog\.
Pass /reports/* d:\path\* Pass /Docs/* d:\path\* Pass /httpd-internal-icons/* d:\path\* Pass /icons/* d:\path\* Pass /Admin/*.html d:\path\* Pass /Admin/*.gif d:\path\* Pass /* d:\path\*
d:\path\ is replaced by a directory you entered at installation. If you used the installation defaults, these Pass directives would be:
Pass /Docs/* C:\WWW\DOCS\* Pass /httpd-internal-icons/* C:\WWW\ICONS\* Pass /icons/* C:\WWW\ICONS\* Pass /Admin/* C:\WWW\ADMIN\* Pass /* C:\WWW\HTML\*
Note: The path following Pass /* is your document root directory. See "Understanding the document root directory" for more information.
Use this directive to specify a template for requests you want to accept and send to another server. Once a request matches a template on a Redirect directive, the request is not compared to templates on any other directives in your configuration file.
The format of the directive is:
Redirect request-template URL [Server-IP-address or hostname]
You can use an asterisk as a wildcard in the template. The tilde character just after a slash (/~) has to be explicitly matched; a wildcard cannot be used to match it.
URL must contain a protocol specification and the name of the server to send the request to. It can also contain a path or file name. If request-template uses a wildcard, the path or file name on URL can also use a wildcard. The part of the original request that matches the wildcard on request-template is inserted in place of the wildcard on URL.
You can specify an IP address (for example, 204.146.167.72) or you can specify a host name (for example, hostA.bcd.com).
This parameter is optional. Without this parameter, the server uses the directive for all requests regardless of the IP address the requests come in on or the host name in the URL.
Important migration note: Beginning with Version 4.2, a wildcard character can no longer be specified for a server's IP address.
Redirect /chief/stuff/* http://www.other.org/wahoo/*
In this example, your server sends any requests beginning with /chief/stuff/ to the wahoo directory of the www.other.org server.
Redirect /stuff/* http://www.chief.org/wahoo/* 204.146.167.72 Redirect /stuff/* http://www.dawg.com/pound/* 9.83.100.45
The above examples use the optional IP address parameter. If your server receives requests that begin with /stuff/, it redirects the request to different servers based on the IP address of the network connection the request comes in on. For requests coming in on 204.146.167.72, the server sends the request to the wahoo directory of the www.chief.org server. For requests coming in on any connection with an address of 9.83.100.45, the server sends the request to the pound directory of the www.dawg.com server.
Redirect /stuff/* http://www.chief.org/wahoo/* hostA.bcd.com Redirect /stuff/* http://www.dawg.com/pound/* hostB.bcd.com
The above examples use the optional IP address parameter. If your server receives requests that begin with /stuff/, it redirects the request to different servers based on the host name in the URL. For requests coming in for hostA, the server sends the request to the wahoo directory of the www.chief.org server. For requests coming in for hostB, the server sends the request to the pound directory of the www.dawg.com server.
None.
Use this directive to specify which environment variables you want your CGI programs to inherit (other than the CGI environment variables that are specific to CGI processing).
If you do not include an InheritEnv directive, all environment variables are inherited by CGI programs. If you include any InheritEnv directive, only those environment variables specified on InheritEnv directives will be inherited along with the CGI-specific environment variables. The directive allows you to optionally initialize the value of the variables that are inherited.
Refer to the Web Programming Guide for a list of the CGI-specific environment variables.
InheritEnv PATH InheritEnv LANG=ENUS
In this example, only the PATH and LANG environment variables will be inherited by CGI programs.
None. The default is all environment variables are inherited by CGI programs.
Use this directive to specify which environment variables you do not want your CGI programs to inherit (other than the CGI environment variables that are specific to CGI processing).
By default, all environment variables are inherited by CGI programs. You can exclude individual environment variables from being inherited with the DisInheritEnv directive.
Refer to the Web Programming Guide for a list of the CGI-specific environment variables.
DisInheritEnv PATH DisInheritEnv LANG
In this example, all environment variables except PATH and LANG will be inherited by CGI programs.
None. The default is all environment variables are inherited by CGI programs.
Use this directive to customize the messages your server sends to the requesting client when it encounters an error condition. For example, you can change a message to include more information about the cause of the problem and suggest possible solutions to fix it. For internal networks, you might provide a contact person for your users to call.
Each error condition is identified by a key word. To decide which error messages you want to customize, first review the list of error conditions, their causes, and the default message that the server sends. Then, for each error message you want to change:
Note: The server does not parse your error files for imbeds, regardless of the file extensions or use of the Imbeds directive.
Use this directive to specify the name of a file that you want to send when the server encounters a particular error condition.
You can place this directive anywhere in the configuration file. When the error occurs, the file will be processed according to the mapping rules defined in your configuration file. Therefore, the file you want to send must be in a location that can be reached through the mapping rules as defined by the Fail, Map, NameTrans, Pass, Redirect, Service directives. At a minimum, you need a Pass directive that would allow the server to pass the error message file.
The format of this directive is:
ErrorPage keyword /path/filename.htm
ErrorPage scriptstart /errors/html/scriptstart.htm
In the above example, when a scriptstart condition is encountered, the server will send the scriptstart.htm file to the client.
This file might contain the following HTML text:
<HTML> <HEAD> <TITLE>Message for SCRIPTSTART condition</TITLE> </HEAD> <BODY> The CGI program could not be started. <P> <A HREF="mailto:admin@websvr.com">Notify the administrator</A> of this problem. </BODY> </HTML>
If the server's configuration file contains PASS /* d:\wwwhome\*, then the full path for this message file would be d:\wwwhome\errors\html\scriptstart.htm.
If you do not specify an ErrorPage directive for an error condition, the server's default error message for that condition will be sent.
The following list shows the HTTP response code and key word for each error condition, followed by the probable cause, and the default message the server sends.
Default message: Found.
Default message: Invalid request - completely unable to parse it.
Default message: The script execution request is not valid.
Default message: Host not found or not responding.
Default message: Host not found or not responding.
Default message: Proxy load failed.
Default message: The request is not valid or not recognized.
Default message: Not Authorized. Authentication failed.
Default message: Not authorized to access the document.
Default message: The user directory is not valid.
Default message: The redirection in the configuration file is not valid.
Default message: Forbidden by rule.
Default message: Directory browsing failed - access forbidden.
Default message: Forbidden - URL containing .. forbidden (don't try to break in).
Default message: Server will not serve to your IP address.
Default message: Proxy server will not serve to your IP address (at least with this HTTP method).
Default message: Method method is disabled on this server.
Default message: Access to this file is not allowed 'no ACL file'.
Default message: Access to this file is not allowed (no ACL entry).
Default message: The PUT and DELETE methods must be specified in the server's protection setup.
Default message: Can't browse selected file.
Default message: Server protection setup error occurred. Probably, the protection setup file was not found or it contained a syntax error.
Default message: The file was not found, even after searching on any extensions to the file name.
Default message: Not authorized. Proxy-Authentication failed (or your browser does not support it).
Default message: Not authorized for proxy access to the document.
Default message: Precondition failed: could not match entity tags.
Default message: Cannot read script output pipe.
Default message: The script request is not valid; none of <program> and <program>.pp is executable.
Default message: Starting the CGI program failed. Could not communicate with the CGI program.
Default message: Sorry, can't convert from mime-type-1 to mime-type-2.
Use the directives described in this section to control the amount of time the server spends processing requests. If you are using persistent connections, see "PersistTimeout - Specify time to wait for the client to send another request".
Use this directive to set the time allowed for a client to send a request after making a connection to the server. A client first connects to the server and then sends a request. If the client does not send a request within the amount of time on this directive, the server drops the connection. Specify the time value in any combination of hours, minutes (or mins), and seconds (or secs).
InputTimeout 3 mins 30 secs
InputTimeout 5 minutes 30 seconds
InputTimeout 2 minutes
Use this directive to set the maximum time allowed for your server to send output to a client. The time limit applies to requests for local files and requests for which the server is acting as a proxy. The time limit does not apply for requests that start a local CGI program.
If the server does not send the complete response within the amount of time on this directive, the server drops the connection. Specify the time value in any combination of hours, minutes (or mins), and seconds (or secs).
OutputTimeout 20 minutes
OutputTimeout 1 hour
OutputTimeout 20 minutes
Use this directive to set the time allowed for a program started by the server to finish. The server stops a program if it runs longer than the limit. Specify the time value in any combination of hours, minutes (or mins), and seconds (or secs).
ScriptTimeout 15 mins
ScriptTimeout 10 minutes
ScriptTimeout 5 minutes
Use the directives described in this section to control which HTTP methods are enabled for your server.
Client requests to the server include a method field that indicates the action the server is to perform on the specified object. The request identifies the object with a Uniform Resource Locator (URL).
Following is a list of methods that the server supports and a description of how the server would respond to a client request containing the method. The description assumes the method is enabled.
Use this directive to specify which HTTP methods you do not want your server to accept.
In the default configuration file, the GET, HEAD, OPTIONS, POST, and TRACE methods are enabled and all other supported HTTP methods are disabled. To disable a method that is currently enabled, change the Enable directive for the method to a Disable directive.
Note: The Configuration and Administration forms use the POST method to make updates to your server configuration. If you disable the POST method you will not be able to use the Configuration and Administration forms.
Disable HEAD
Disable PUT Disable DELETE
Use this directive to specify which HTTP methods you want your server to accept.
You can enable as many of the HTTP methods as you need. For each method you want the server to accept, enter a separate Enable directive followed by the name of the method.
Enable DELETE
If no Service directive exists for a particular URL, you can use the Enable directive to perform customized programming for any HTTP method. The program you specify on this directive will override the standard processing for that method.
The format is:
Enable method d:\path\fileDLL:function_name
Enable
Enable GET Enable HEAD Enable POST Enable TRACE Enable OPTIONS
Important migration notes
Use the directives described in this section to control where your server looks for meta-information files.
You can use a separate set of files to store meta-information about your server's documents. The server can include the meta-information with its HTTP responses. Meta-information describes the file containing a document, not the contents of the document. For example, meta-information for a file might give the date the file was created and the date it was last modified. You can include any valid response headers as described in the HTTP 1.1 specification.
HTTP recognizes MIME headers. Information that MIME header fields can include are the file type, subtype, encoding, and content length.
Each line of a meta-information file contains a header field, followed by a colon, and the value of the field. For example:
Last-Modified: Wednesday, 05-Apr-96 20:51:35 GMT Expires: Friday, 30-Jun-96 24:00:00 GMT MIME-Version: 1.0
Use this directive to specify the name you want to use for subdirectories that contain meta-information files. You can only have one instance of this directive, which means all your meta-information subdirectories have the same name.
Any directory from which your server retrieves files can have a subdirectory with the name specified on this directive. The files on the meta-information subdirectory contain meta-information about the files being retrieved. The meta-information files have the same file name and extension as the file they describe, plus an added extension. The name of the added extension is specified on the MetaSuffix directive.
For example, you might have the following two directives in your configuration file:
MetaDir look_here MetaSuffix .file_desc
If your server goes to retrieve this file:
d:/html/realcool/coolindex.htmlit looks for meta information to include with the response in this file:
d:/html/realcool/look_here/coolindex.html.file_desc
MetaDir mimeinfo
MetaDir .web
Note: The dot character (.) at the beginning of the default value is used as part of the subdirectory name.
Use this directive to specify the extension you want to use for meta-information files. You can only have one instance of this directive, which means all meta-information files end with the same extension. You must include the period character (.) as part of the value.
Any file your server retrieves can have a meta-information file associated with it. A meta-information file has the same file name and extension as the file it describes, plus the additional extension specified on the MetaSuffix directive. A meta-information file must be located on a subdirectory of the directory that contains the file being described. The name of the subdirectory must be the name specified on the MetaDir directive.
See the description of the MetaDir directive to see an example of how MetaDir and MetaSuffix work together.
MetaSuffix .head
MetaSuffix .meta
The Internet Connection Application Programming Interface (ICAPI) allows you to extend the Internet Connection Secure Server's base functions with your own customized processing routines. Use the directives described in this section to have the server call the application functions in your program at various points in its request processing cycle. You can find detailed information for writing the application functions and compiling your program in the Web Programming Guide.
Except for Service and NameTrans, these directives can be in any order in the configuration file and you do not need to include every directive. If you do not have a customized application function for a particular step, just omit the corresponding directive. The normal processing for that step will execute by default.
The Service and NameTrans directives behave like the other mapping directives and are sensitive to their placement in the configuration file. For example a rule for /cgi-bin/foo.dll must appear before the rule for /cgi-bin/*.
You can also have more than one configuration directive for a step. For example, you could include two NameTrans directives, each pointing to a different application function. When the server performs the name translation step, it will process your name translation functions in the order in which they appear within the configuration file.
Your application functions do not have to be executed for every request:
Use this directive to specify a customized application function you want the server to call during it's initialization routines. This code will be executed before any client requests are read and whenever the server is restarted.
If you are using the GoServe modules in the PreExit or Service steps, you need to call the gosclone module here.
The format of the directive is:
ServerInit d:\path\file:function_name
ServerInit d:\ics\api\bin\icsext05.dll:svr_init ServerInit d:\www\dll\gosclone.dll:init
None.
Use this directive to specify a customized application function you want the server to call during the PreExit step. This code will be executed after a client request has been read but before any other processing occurs. You can call the GoServe module during this step.
The format of the directive is:
PreExit d:\path\file:function_name
PreExit d:\ics\api\bin\icsext05.dll:pre_exit PreExit d:\www\dll\gosclone.dll:goserve
None.
Use this directive to specify a customized application function you want the server to call during the Authentication step. This code will be executed based on the authentication scheme. Currently, only Basic authentication is supported.
Note: Authentication is part of the authorization process; it only occurs when authorization is required.
The format of the directive is:
Authentication type d:\path\file:function_name
Authentication BASIC d:\ics\api\bin\icsextpgm.dll:basic_authen
None.
Use this directive to specify a customized application function you want the server to call during the Name Translation step. This code would supply the mechanism for translating the virtual path in the request to the physical path on the server, mapping URLs to specific objects.
Note: This is not a terminal mapping rule. The transformed URL still has to match one of the terminal mapping rule directives, such as Exec, Fail, Map, Pass, Redirect, and Service.
The format of the directive is:
NameTrans request-template d:\path\file:function_name [Server-IP-address or hostname]
Important migration note: Beginning with Version 4.2, a wildcard character can no longer be specified for a server's IP address.
NameTrans /index.html d:\api\bin\icsextpgm.dll:trans_url
None.
Use this directive to specify a customized application function you want the server to call during the Authorization step. This code would verify that the requested object can be served to the client.
The format of the directive is:
Authorization request-template d:\path\file:function_name
Authorization /index.html d:\api\bin\icsextpgm.dll:trans_url
None.
Use this directive to specify a customized application function you want the server to call during the Object Type step. This code would locate the requested object in the file system and identify its MIME type.
The format of the directive is:
ObjectType request-template d:\path\file:function_name
ObjectType /index.html d:\api\bin\icsextpgm.dld:obj_type
None.
Use this directive to specify a customized application function you want the server to call during the Service step. This code would service the client request. For example, it sends the file or runs the CGI program.
There is no default for this directive. If the request matches a Service rule (an application function specified on a Service directive is executed) but it returns HTTP_NOACTION, the server will generate an error and the request will fail.
The format of the directive is:
Service request-template d:\path\file:function_name [Server-IP_address or hostname]
Important migration note: Beginning with Version 4.2, a wildcard character can no longer be specified for a server's IP address.
Note: If you want full path translation, including query_string, you must have an asterisk (*) in both the request-template and in the d:\path\file:function_name as shown in the second example.
Service /index.html d:\ics\api\bin\icsext05.dll:serve_req Service /cgi-bin/htimage* \ics\api\htimage:Htimage*
None.
Use this directive to specify a customized application function you want the server to call to retrieve PICS labels for a specified URL. Your function can either dynamically create a PICS label for the requested document or to search for a PICS label in an alternative file or database.
The format of the directive is:
PICSDBLookup request-template d:\path\file:function_name
PICSDBLookup /index.html d:\ics\api\bin\icsext05.dll:get_pics
None.
Use this directive to specify a customized application function you want the server to call during the Data Filter step. This code would provide three application functions:
You can only have one DataFilter active for each instance of the server.
The format of the directive is:
DataFilter d:\path\file:function_name:function_name:function_name
DataFilter d:\ics\bin\icsext05.dll:open_data:write_data:close_data
None.
Use this directive to specify a customized application function you want the server to call during the Log step. This code would supply logging and other processing you want performed after the connection has been closed.
The format of the directive is:
Log request-template d:\path\file:function_name
Log /index.html d:\api\bin\icsextpgm.dll:trans_url
None.
Use this directive to specify a customized application function you want the server to call during the Error step. This code would execute only when an error is encountered to provide customized error routines.
The format of the directive is:
Error request-template d:\path\file:function_name
Error /index.html d:\ics\api\bin\icsext05.dll:error_rtns
None.
Use this directive to specify a customized application function you want the server to call during the PostExit step. This code will be executed regardless of the return codes from previous steps or other PostExit handlers. It allows you to clean up any resources allocated to process the request.
The format of the directive is:
PostExit d:\path\file:function_name
PostExit \ics\api\bin\icsext05.dll:post_exit
None.
Use this directive to specify a customized application function you want the server to call during the Server Termination step. This code would execute when an orderly shutdown occurs and whenever the server is restarted. It allows you to release resources allocated by a PreExit application function.
The format of the directive is:
ServerTerm d:\path\file:function_name
ServerTerm d:\ics\api\bin\icsext05.dll:shut_down
None.
Use this directive to configure your server to support Sun's Java servlet API. This will allow you to execute servlets that extend the Java servlet interface and it's classes, as defined in the java.servlet and java.servlet.http packages in Sun's Java Servlet API White Paper (http://java.sun.com/products/jeeves//CurrentRelease/doc/api.html). The servlet API classes you need to compile a Java servlet are included in the icsclass.zip file in the server's base CGI-BIN directory. If you enable Java servlet support, this file is added to your CLASSPATH.
A servlet is like a server-side applet that runs on a Java thread but does not have a user interface. Servlets are persistent. Although a servlet's service() method is executed for each request, servlets are instantiated and initialized just once when they are loaded. This allows servlets to create dynamic output similar to CGI programs.
Using the Java configuration directives, you have the ability to:
On the Internet Connection Secure Server, servlets cannot be loaded from the network; they must reside on the local system. Servlets run in a separate process than the one in which the Internet Connection Secure Server is running.
Note to servlet writers:
When writing your servlets, you can write your own code for the following servlet class methods (the service method is required and the others are optional):
Use this directive to specify whether or not you want your server to support Java servlets. If you specify no, the servlet support is turned off and all the other Java servlet directives are ignored. If you specify yes, the servlet support is turned on, the Java Virtual Machine (JVM) is started, and all the other Java servlet directives are implemented.
The format of this directive is:
EnableJavaServletSupport value
EnableJavaServletSupport yes
EnableJavaServletSupport no
Use this directive to specify the maximum number of Java threads that the server will use to process Java servlets.
The format of this directive is:
MaxActiveJavaThreads number
MaxActiveJavaThreads 25
MaxActiveJavaThreads 10
Use this directive to specify the name and location of the log file for Java servlet messages. All messages generated by the servlet log method will be written to this file. If you omit this directive, none of the messages generated by the servlet log method will be captured.
Note: This log is not automatically deleted on schedule like other server logs. You will have to monitor and control the size of this log yourself.
The format of this directive is:
ServletLog drive:\path\filename
ServletLog D:\WWW\ics\logs\js-log-12
ServletLog c:\path\logs\servlet-logc:\path is replaced by the drive and directory where you installed the server. The default directory is C:\WWW.
Use this directive to specify the name and location of the directory where you will keep all Java servlets.
The format of this directive is:
ServletDir drive:\path\directory
ServletDir D:\WWW\ics\servlets\v42\public
ServletDir c:\path\publicc:\path is replaced by the drive and directory where you installed the server. The default directory is C:\WWW.
Use this directive to specify the name and value of the parameters passed to a Java servlet when it is initialized. These must be listed one per line.
The format of this directive is:
Servlet servlet-name {
parm0=value0
parm1=value1
parm2=value2
....
parmn=valuen
}
Servlet MyServlet {
count=1
path=d:\w3\list
}
None
Use the directives described in this section to configure your server as a caching proxy. See "Running your server as a proxy" for more information on proxy servers.
Use this directive to set a default expiration time for files that the server did not give either an Expires or a Last-Modified header to. You specify a URL template and the expiration time for files with URLs that match the template. You can have multiple occurrences of this directive in the configuration file. Include a separate directive for each template. The URL template must include the protocol. Specify the time value in any combination of months, weeks, days, and hours.
CacheDefaultExpiry ftp:* 1 month CacheDefaultExpiry gopher:* 10 days
CacheDefaultExpiry ftp:* 1 day CacheDefaultExpiry gopher:* 1 day CacheDefaultExpiry http:* 0 days
Notice in the above defaults that the default expiration for HTTP is 0. HTTP should be kept at 0 because many script programs don't give an expiration date, yet their output expires immediately. (A value other than 0 may cause problems.)
Use this directive to specify whether you want the server to return cached files that have expired. Specify Off for the value if you want the server to be able to return expired files. Use the default value of On if you do not want the server to return expired files. Generally, you will not want the server to return expired files. An exception might be if you were demonstrating the server and do not particularly care about the content being returned.
CacheExpiryCheck Off
CacheExpiryCheck On
HTTP servers usually give the Last-Modified time for a file, but not the Expires date. Use this directive to have your server approximate the expiration date of these files based on the Last-Modified time. The server uses the Last-Modified date to determine how long it has been since the file was modified. The server multiplies that length of time by the value on the CacheLastModifiedFactor directive. The server uses the result of this calculation to assign the file an expiration date when it caches the file.
CacheLastModifiedFactor 0.2
The above example would cause files modified five months ago to expire after one month.
CacheLastModifiedFactor Off
The above example would turn this function off.
CacheLastModifiedFactor 1.5
The default of 1.5 causes files modified in the past week to be updated in one day.
The server uses an algorythm for garbage collection to determine which files to delete. The size of a file is part of the calculation. The size of small files is not taken into account in the calculation. The size of large files is taken into account; the larger the file, the more likely it is to be deleted.
Use this directive to tell the server what should be considered a small file. The value can be specified in bytes (B), kilobytes (K), megabytes (M), or gigabytes (G). It does not matter if you have a space between the number and the value (B, K, M, G).
CacheLimit_1 400 K
CacheLimit_1 20 K
Use this directive to specify the maximum size of files to be cached. Files larger than this size will not be cached. The value can be specified in bytes (B), kilobytes (K), megabytes (M), or gigabytes (G). It does not matter if you have a space between the number and the value (B, K, M, G).
CacheLimit_2 2000 K
CacheLimit_2 400 K
During retrieval, cache files are locked. If something goes wrong, a locked file may be left hanging. Use this directive to set the amount of time after which the lock on the file can be broken. Specify the time value in minutes (mins).
Note: Set CacheLockTimeOut to a value equal to or greater than OutputTimeOut. The default value of 20 minutes is the same as the default for OutputTimeOut.
CacheLockTimeOut 30 mins
CacheLockTimeOut 20 minutes
Use this directive to specify whether you want the proxy server to retrieve files from remote servers. Use the default value of Off if you want the server to be able to retrieve files from remote servers.
Specify On if you want the server to run in stand alone cache mode. This means that the server can return only files already stored in its cache. Typically, you would also set the CacheExpiryCheck directive to Off when running the server in this mode.
Running the server in stand alone cache mode can be useful if you are using the server for demonstrations. If you know all the files you want to use for a demonstration are stored in the cache, then you do not need a network connection.
CacheNoConnect OnIn the above example, the server returns only files stored in its cache.
CacheNoConnect Off
Use this directive to specify that only files with URLs that match the given template should be cached. You can have multiple occurrences of this directive in the configuration file. Include a separate directive for each template. The URL template must include the protocol.
CacheOnly http://realstuff/*
None
Use this directive to specify the top directory in the cache hierarchy. The server will create subdirectories within this directory for each cached protocol. It will also create subdirectories under each protocol subdirectory for each remote server.
CacheRoot /webcache
None
Use this directive to set the maximum amount of disk space you want the proxy cache to use. If you have plenty of disk space, you may want to substantially increase the 5 M default size. The size of the cache will usually stay below the maximum, but may occasionally grow slightly larger. When the maximum size is reached, the garbage collection process begins. The value can be specified in bytes (B), kilobytes (K), megabytes (M), or gigabytes (G). It does not matter if you have a space between the number and the value (B, K, M, G).
CacheSize 50 M
CacheSize 5 M
Use this directive to set the maximum amount of time for the server to keep unused cached files with URLs matching a given template. The server deletes unused files with URLs matching the template after they have been cached for the specified time, regardless of their expiration date. You can have multiple occurrences of this directive in the configuration file. Include a separate directive for each template. The URL template must include the protocol. Specify the time value in any combination of months, weeks, days, and hours.
CacheUnused ftp:* 3 weeks CacheUnused gopher:* 3 days 12 hours CacheUnused * 4 weeks
None
Use this directive to enable the caching of files. With caching turned on, the proxy server can store the files it retrieves from other servers in a local cache. The server can then respond to subsequent requests for the same files without having to retrieve them from another servers. This can improve response time.
Caching On
Caching Off
If your proxy server is part of a chain of proxies, use this directive to specify the name of another proxy that this server should contact for FTP requests.
ftp_proxy http://outer.proxy.server/
None.
If you have enabled caching, the server uses the garbage collection process to delete files that should no longer be cached. Files are deleted based on their expiration date and other proxy directive values. Use this directive to turn garbage collection on or off. Generally, you would not turn off garbage collection if you have enabled caching. If you do, your cache file could grow beyond the maximum size you set for it.
Assuming garbage collection is turned on, the garbage collection process runs when the cache reaches its maximum size (as specified on the CacheSize directive). The garbage collection process will also run at the time of day specified on the GcDailyGc directive.
Gc On
Gc Off
Use this directive to specify a particular time of day to run the garbage collection process. Garbage collection occurs automatically when the cache size limit is reached. By specifying a daily time for garbage collection you can also remove cached files before the cache reaches its maximum. Specify the time value in 24:00 hour format. Generally, you would want the garbage collection process to run when your server is not being used much for other things. This is why the default is 03:00.
GcDailyGc 22:00
The above example would start the garbage collection process at 10 PM.
GcDailyGc Off
The above example would disable daily garbage collection.
GcDailyGc 03:00
Garbage collection works best if it can read all cache information into memory at one time. It may not be able to read in the entire cache if your system does not have enough main memory.
Use this directive to specify how much memory garbage collection can use. The value you specify should be approximately the amount of virtual memory that the server may use while performing garbage collection. The amount of memory needed will vary based on dynamic changes such as the directory structure of cached files. Specify the value as a number that represents kilobytes, but do not put a K next to the number.
If garbage collection fails because there is not enough memory on your system, set this directive to a smaller value. If you have plenty of memory to spare, you may want to set this value above the default of 500.
GcMemUsage 100
The example above might be used for a machine with a small amount of memory.
GcMemUsage 1000
If your proxy server is part of a chain of proxies, use this directive to specify the name of another proxy that this server should contact for Gopher requests.
gopher_proxy gopher://outer.proxy.server/
None.
If your proxy server is part of a chain of proxies, use this directive to specify the name of another proxy that this server should contact for HTTP requests.
http_proxy http://outer.proxy.server/
None.
Use this directive to set the size of the buffer for dynamic data generated by the server. Dynamic data is output from CGI programs, server-side includes, and API programs. It is data that does not come from a proxy request.
The value can be specified in bytes (B), kilobytes (K), megabytes (M), or gigabytes (G). It does not matter if you have a space between the number and the value (B, K, M, G).
MaxContentLengthBuffer 2 M
MaxContentLengthBuffer 50 K
Use this directive to specify the domains that you want the server to directly connect to rather than going through a proxy.
Specify the value as a string of domain names or domain name templates. Separate each entry in the string with a comma. Do not put any spaces in the string.
You specify templates on this directive a bit differently than the way you specify templates on other directives. Most importantly, you cannot use the wildcard character (*). What you can do is specify a template by including only the last part of a domain name. The server connects directly to any domains that end with a string matching the templates you specify. The following example shows how this works.
no_proxy www.someco.com,.raleigh.ibm.com,.some.host.org:8080
In the above example the server would not go through a proxy for the following requests:
Use this directive to specify that the server should not cache files with URLs matching the given template. You can have multiple occurrences of this directive in the configuration file. Include a separate directive for each template. The URL template must include the protocol.
NoCaching http://joke/*
None.
Use this directive to specify the path and file name where you want the server to log access statistics that pertain to proxy requests. By default, the server writes an entry to this log each time it acts as a proxy for a client request. You can use the NoLog directive if you do not want to log requests from certain clients. For a description of the NoLog directive, refer to "NoLog - Suppress log entries for specific hosts or domains matching a template".
The server starts a new log file each day at midnight if it is running. Otherwise, the server starts a new log file the first time you start it on a given day. When creating the file, the server uses the file name you specify and appends a date extension. The date extension is in the format Mmmddyyyy, where Mmm is the first three letters of the month; dd is the day of the month; and yyyy is the year.
It is a good idea to remove old log files, because they can take up a significant amount of space on your hard drive.
ProxyAccessLog c:\server\logs\proxylog
ProxyAccessLog c:\path\proxy-log
c:\path\ is the value you entered for Logs directory at installation. The installation default is c:\WWW\LOGS
Use this directive to specify the IP address or host name of the Socks server through which this proxy will be passing requests.
SocksServer SocksServerwhere SocksServer is the IP address or the host name of the Socks server to which the proxy should be chained.
SocksServer socks.bcd.com
None.
If your proxy server is part of a chain of proxies, use this directive to specify the name of another proxy that this server should contact for WAIS requests.
wais_proxy wais://outer.proxy.server/
None.
Use the directives described in this section to control the performance of your server.
Each time your server receives a request from a client, it uses one or two threads to perform the requested action. (One thread if the server is not performing DNS lookup. Two threads if the server is performing DNS lookup.) If no threads are available, the server holds requests until more threads are available. The MaxActiveThreads directive specifies the maximum number of active threads.
If your server is running at maximum capacity on a sustained, non-stop basis, the amount of virtual memory used increases. This increase is temporary and is alleviated as the number of requests decline and the server catches up on servicing requests.
You can lower the amount of virtual memory used by lowering the MaxActiveThreads setting. A good starting point would be half of your current MaxActiveThreads setting. Keep in mind when you're lowering MaxActiveThreads that, when no threads are available, the server holds requests until more threads are available.
Use the ServerPriority directive to specify the priority your operating system gives to the server.
If you see a problem with your performance with your server being too slow, it could be related to any of the following:
Use the CacheLocalFile directive to load your most popular files into the servers memory at startup time. You can specify the maximum amount of memory and the maximum number of files for caching with the CacheLocalMaxBytes and CacheLocalMaxFiles directives.
Use the PersistTimeout and the MaxPersistRequest directives to specify the characteristics of a persistent connection. A persistent connection allows the server to accept multiple requests and to send responses over the same TCP/IP connection. Overall throughput is increased because the server does not have to establish a separate TCP/IP connection for each request and response. Also, the TCP/IP connection is used more efficiently because a client can make multiple requests without waiting for the response to each request.
Use this directive to specify the names of files you want to load into the server's memory each time you start the server. You can have multiple occurrences of this directive in the configuration file. Include a separate directive for each file you want to load into memory.
By keeping your most frequently requested files loaded in the server's memory, you can improve your server's response time for those files. For example, if you load your server's welcome page into memory at startup, the server can handle requests for the page much more quickly than if it had to read the file from a disk. Keep in mind that for each file you load into memory, you are making that amount of memory unavailable for other uses.
Before responding to a request for a file that is stored in memory, the server checks to see if the file has changed since the server was started. If the file has changed, the server responds to the request with the updated file and deletes the old version from its memory. To load the new file into memory, you need to restart the server.
Notes:
To cache a specific file
CacheLocalFile d:\www\html\index.html
To cache all .html files in the powerco directory
CacheLocalFile d:\www\powerco\*.html
The default configuration includes CacheLocalFile directives for the HTML and graphics files that make up the server's Front Page.
Use this directive to specify the maximum amount of memory you want to allow for file caching. You can specify the memory in kilobytes (K) or megabytes (M). You must still specify the files that you want cached with the CacheLocalFiles directive.
Note: CacheLocalMaxBytes can help limit your cache size when you are using the wildcard character to specify the files on the CacheLocalBytes directive.
CacheLocalMaxBytes 5K
CacheLocalMaxBytes 2M
Use this directive to specify the maximum number of files you want to be cached at one time. You must still use the CacheLocalFiles directive to indicate which files you want cached.
Note: CacheLocalMaxFiles can help limit your cache size when you are using the wildcard character to specify the files on the CacheLocalFiles directive.
CacheLocalMaxFiles 150
CacheLocalMaxBytes 200
Use this directive to specify whether or not the cache is updated when a cached file is modified. Specify ON if you want users requesting a cached file to get the file with the latest updates. OFF is the high performance setting.
LiveLocalCache off
LiveLocalCache off
Use this directive to set the maximum number of threads that you want to have active at one time. If the maximum is reached, the server holds new requests until another request finishes and threads become available. The recommended value is 40. Unpredictable results may occur if this value is exceeded.
MaxActiveThreads 35
MaxActiveThreads 40
Use this directive to specify a priority class for the Internet Connection Secure Server. The operating system uses priority classes to determine which processes have priority over others.
Valid values are:
You may want to use a value of 0 if the machine your server is running on is also processing other types of requests.
ServerPriority 0
ServerPriority 1
Use this directive to specify the maximum number of requests the server should receive on a persistent connection. When determining this number, be sure to consider the number of images used in your pages. Each image requires a separate request.
The format of this directive is:
MaxPersistRequest number
number is the number of requests the server should receive for a persistent connection.
MaxPersistRequest 5
MaxPersistRequest 5
Use this directive to specify the amount of time the server should wait between client requests before cancelling a persistent connection.
The server uses a different timeout, the input timeout, to determine how long to wait for the client to send the first request after the connection is established. For more information on the input timeout, see "InputTimeout - Specify input timeout setting".
After the server sends its first response, it uses the persistent timeout to determine how long it should wait for each subsequent request before cancelling the persistent connection.
The format of this directive is:
PersistTimeout time
time can be any valid time increment, but usually will be seconds or minutes
PersistTimeout 1 minutes
PersistTimeout 1 minutes
Use this directive to specify whether the ACL files with be checked for file protection. Set this directive to never or protect only for better server performance. The format of the directive is:
UseACLs setting
The setting can have a value of always, protect only, or never.
UseACLs protectonly
UseACLs always
Use this directive to specify whether the meta files used by the server. Set this directive to off for better server performance. The format of the directive is:
UseMetaFiles setting
The setting can have a value of on or off.
UseMetaFiles off
UseMetaFiles on
Use the directives described in this section to define settings used to monitor and manage the health, throughput, and activity of your servers.
Use this directive to enable or disable SNMP support. The form of the directive is:
SNMP setting
The setting can have a value of on or off.
SNMP on
SNMP off
SNMP off
Use this directive to define the password between the Internet Connection Secure Server DPI subagent and the SNMP agent. The SNMP community name authorizes a user to view the performance variables monitored by SNMP for a particular community of servers. The system administrator defines which variables from which servers can be viewed when a password is entered. If you change this value, you must also add the new community name to the SystemView Agent snmpcfg. For more information about creating a community name, refer to "Providing a security password for SNMP".
The form of the directive is:
SNMPCommunityName com_nam
SNMPCommunityName public
SNMPCommunityName public
SNMPCommunityName public
Use this directive to create an e-mail address to receive SNMP problem reports. The default mail address is webmaster.
The form of the directive is:
WebMasterEmail webmastermailaddress
WebMasterEmail webmaster@computer.com
WebMasterEmail webmaster