Setting Access Log Preferences

During installation, an access log file named access is created for the server. You can customize access logging for any resource by specifying whether to log accesses, what format to use for logging, and whether the server should spend time looking up the domain names of clients when they access a resource.

You can specify logging preferences using the Set Access Log Preferences page in the Server Manager, or you can manually configure directives in the obj.conf file. In obj.conf, the server calls the function flex-init to initialize the flexible logging system and the function flex-log to record request-specific data in a flexible log format. To log requests using the common log file format, the server calls init-clf to initialize the Common Log subsystem which is used in obj.conf, and common-log to record request-specific data in the common log format used by most HTTP servers.

Once an access log for a resource has been created, you cannot change its format unless you archive it or create a new access log file for the resource.

Table 9–2 Log File Formats for the Administration Server

Log Format Item	Description
Client Hostname	The hostname (or IP address if DNS is disabled) of the client requesting access.
Authenticate User Name	If authentication is necessary, you can list the authenticated user name in the access log.
System Date	The date and time of the client request.
Full Request	The exact request the client made.
Status	The status code the server returned to the client.
Content Length	The content length, in bytes, of the document sent to the client.
HTTP Header, “referer”	The referer specifies the page from which the client accessed the current page. For example, if a user is looking at the results from a text search query, the referer would be the page from which the user accessed the text search engine. Referers enable the server to create a list of backtracked links.
HTTP Header, “user-agent”	The user-agent information, which includes the type of browser the client is using, its version, and the operating system on which it is running. This information comes from the User-agent field in the HTTP header information that the client sends to the server.
Method	The HTTP request method used, such as GET, PUT, or POST.
URI	Universal Resource Identifier. The location of a resource on the server. For example, for http://www.a.com:8080/special/docs, the URI is special/docs.
Query String Of The URI	Any text after the question mark in a URI. For example, for http://www.a.com:8080/special/docs?find_this, the query string of the URI is find_this.
Protocol	The transport protocol and version used.

When changing the format of an existing log file, you should first delete/rename the existing log file OR use a different file name.

To Set the Access Log Preferences for the Administration Server

1. Access the Administration Server and click the Preferences tab.

2. Click the Set Access Log Preferences link.

   The Set Access Log Preferences page is displayed.

3. Select the resource from the drop-down list or click the Regular Expression button, type a regular expression, and click OK.

4. Specify whether to log client accesses.

   This setting requires Domain Name Service (DNS) to be enabled.

5. Specify the absolute path for the access log file.

   As a default, the log files are kept in the logs directory in the server root. If you specify a partial path, the server assumes the path is relative to the logs directory in the server root.

   If you are editing the entire server, the default value for this field is $accesslog, the variable that denotes the access log file for the server in the configuration file.

6. Choose whether record domain names or IP addresses of the systems accessing the server in the access log.

7. Choose the type of log file format to use in the access log.

   The following options are available:

   • Use Common LogFile Format. Includes client’s host name, authenticated user name, date and time of request, HTTP header, status code returned to the client, and content length of the document sent to the client.

   • Only Log. Enables you to determine which information will be logged. You can choose from the flexible log format items listed in Table 9–2.

   • If you choose a custom format, type it in the Custom Format field.

8. Click OK.

9. Click Restart Required.

   The Apply Changes page is displayed.

10. Click the Restart Proxy Server button to apply the changes.

Setting Access Log Preferences for the Server Instance

The flexible log formats that you can use to set the access log preferences for the server instance are listed in the following table.

Table 9–3 Log File Formats for the Server Instance

Log Format Item	Description
Client Hostname	The hostname (or IP address if DNS is disabled) of the client requesting access.
Authenticate User Name	If authentication was necessary, you can have the authenticated user name listed in the access log.
System Date	The date and time of the client request.
Full Request	The exact request the client made.
Status	The status code the server returned to the client.
Content Length	The content length, in bytes, of the document sent to the client.
HTTP Header, “referer”	The referer specifies the page from which the client accessed the current page. For example, if a user is looking at the results from a text search query, the referer would be the page from which the user accessed the text search engine. Referers enable the server to create a list of backtracked links.
HTTP Header, “user-agent”	The user-agent information, which includes the type of browser the client is using, its version, and the operating system on which it is running. This information comes from the User-agent field in the HTTP header information that the client sends to the server.
Method	The HTTP request method used such as GET, PUT, or POST.
URI	Universal Resource Identifier. The location of a resource on the server. For example, for http://www.a.com:8080/special/docs, the URI is special/docs.
Query String Of The URI	Any text after the question mark in a URI. For example, for http://www.a.com:8080/special/docs?find_this, the query string of the URI is find_this.
Protocol	The transport protocol and version used.
Cache Finish Status	This field specifies whether the cache file was written, refreshed, or returned by an up-to-date check.  The cs field can hold one of the following:  - means that the resource was not cacheable.  WRITTEN means that the cache file was created.  REFRESHED means that the cache file was updated or refreshed.  NO-CHECK means that the cache file was returned without an up-to-date check.  UP-TO-DATE means that the cache file was returned with an up-to-date check  HOST-NOT-AVAILABLE means that the remote server was not available for an up-to date check, so the cache file was returned without a check.  CL-MISMATCH means that the cache file write was aborted due to a content-length mismatch  ABORTED means that caching was aborted due to a particular reason. For eg. the absense of a valid Last-Modified header.
Remote Server Finish Status	This field specifies if the request to the remote server was successfully carried out to completion, interrupted by the client clicking the Stop button in the browser, or aborted by an error condition.
Status Code From Server	The status code returned from the server.
Route To Proxy (PROXY, SOCKS, DIRECT)	The route used to retrieve the resource. The document can be retrieved directly, through a proxy, or through a SOCKS server.
Transfer Time	The length of time of the transfer, in seconds or milliseconds.
Header-length From Server Response	The length of the header from the server response.
Request Header Size From Proxy To Server	The size of the request header from the proxy to the server.
Response Header Size Sent To Client.	The size of the response header sent to the client.
Request Header Size Received From Client	The size of the request header received from the client.
Content-length From Proxy To Server Request.	The length, in bytes, of the document sent from the proxy to the server.
Content-length Received From Client	The length, in bytes, of the document from the client.
Content-length From Server Response	The length, in bytes, of the document from the server.
Unverified User From Client	The user name given to the remote server during authentication.

To Set the Access Log Preferences for the Server Instance

1. Access the Server Manager and click the Server Status tab.

2. Click the Set Access Log Preferences link.

   The Set Access Log Preferences page is displayed.

3. Select the resource from the drop-down list or click the Regular Expression button, type a regular expression, and click OK.

4. Specify whether to log client accesses.

   This setting requires Domain Name Service (DNS) to be enabled.

5. Specify the absolute path for the access log file.

   The log files by default are kept in the logs directory in the server root. If you specify a partial path, the server assumes the path is relative to the logs directory in the server root.

   If you are editing the entire server, the default value for this field is $accesslog, the variable that denotes the access log file for the server in the configuration file.

6. Choose whether to record domain names or IP addresses of the systems accessing the server in the access log.

7. Choose the format the log file should be: common, extended, extended-2, only specified information (“Only log” radio button), or custom.

   If you click Only log, the following flexible log format items are available:

8. Choose the type of log file format to use in the access log.

   Server access logs can be in Common Logfile Format, Extended Logfile Format, Extended2 Logfile format, flexible log format, or your own customizable format. The Common Logfile Format is a commonly supported format that provides a fixed amount of information about the server. The flexible log format enables you to choose (from Proxy Server) what to log. A customizable format uses parameter blocks that you specify to control what gets logged.

   • Use Common LogFile Format. Includes client’s host name, authenticated user name, date and time of request, HTTP header, status code returned to the client, and content length of the document sent to the client.

   • Use Extended LogFile Format. Includes all of the fields of the common log file format as well as some additional fields such as remote status, proxy to client content length, remote to proxy content length, proxy to remote content length, client to proxy header length, proxy to client header length, proxy to remote header length, remote to proxy header length and transfer time.

   • Use Extended2 LogFile Format. Includes all of the fields of the extended logfile format as well as some additional fields such as client status, server status, remote status, cache finish status, and actual route.

   • Only Log. Allows you to choose which information will be logged. You can choose from the flexible log format items listed in Table 9–3.

   • If you choose a custom format, type it in the Custom Format field.

9. If you do not want to log client access from certain host names or IP addresses, type them in the host names and IP Addresses fields.

   Type a wildcard pattern of hosts from which the server should not record accesses. For example, *.example.com does not log accesses from people whose domain is example.com. You can type wildcard patterns for host names, IP addresses, or both.

10. Choose whether to include the format string in the log file.

    If you are using the Proxy Server’s log analyzer, you should include a format string. If you are using a third-party analyzer, you may not want to include a format string in your log file.

11. Click OK.

12. Click Restart Required.

    The Apply Changes page appears.

13. Click the Restart Proxy Server button to apply the changes.

Easy Cookie Logging

Proxy Server has an easy way to log a specific cookie using the flexlog facility. Add Req->headers.cookie.cookie_name to the line that initializes the flex-log subsystem in the configuration file obj.conf. This instruction logs the value of the cookie variable cookie_name if the cookie variable is present in the request’s headers, and logs - if it is not present.