Applies To:

Show Versions Show Versions

Manual Chapter: Administrator Guide for the BIG-IP WebAccelerator Module: 5 - Changing Configuration Options
Manual Chapter
Table of Contents   |   << Previous Chapter   |   Next Chapter >>


5

Changing Configuration Options


Changing default settings

Once the WebAccelerator system is installed and running, you can change the default settings for certain configuration options by modifying the following files:

  • /config/wa/pvsystem.conf
  • /config/wa/globalfragment.xml

Modifying the pvsystem.conf file

You can modify the /config/wa/pvsystem.conf file to change options for:

  • Log file creation
  • Compile queues
  • Assembly queue
  • System TTL parameters
  • Socket tunnels
  • Cookie encryption
  • HDS prune
Important

F5 Networks recommends that you create a backup copy of the /config/wa/pvsystem.conf file using the cp /config/wa/pvsystem.conf /config/wa/pvsystem.conf.back command before you make changes. This enables you to easily restore the modified configuration in case of a system failure.

To modify the pvsystem.conf file

  1. Log into the BIG-IP system as root.
  2. Edit the /config/wa/pvsystem.conf file as required.
    The parameters for these options are specified on the following pages.
  3. Save the file.
  4. Restart the process that you modified, using the command specified in the following sections.

Managing log file creation

The WebAccelerator system generates change logs, which contain information about page requests, and hit logs, which contain the same type of information as in the web server log files. The WebAccelerator system buffers change and hit log information in memory until the specified threshold is reached. Once the threshold is reached, the WebAccelerator system writes the information to the hard drive.

The threshold at which the WebAccelerator system writes hit and change data to disk is based on a size limit and a time limit. The WebAccelerator system resets log file Time-to-Live (TTL) values each time it writes the change or hit log to disk. For example, if the WebAccelerator system writes a change log at 3 minutes because a file size has reached the limit, it resets the TTL counter to 0 and does not write the hit log again until either 5 minutes has elapsed or 1MB of data is collected, whichever comes first.

You can change the threshold limits for the following parameters by editing the /config/wa/pvsystem.conf file. After you change a parameter, restart the process using the bigstart restart pvac command.

Important

Do not change the default values unless instructed to do so by F5 Networks Technical Support.
Figure 5.1 Log file parameters
Parameter
Description
changeLogFileSize
The WebAccelerator system writes change log data to disk if the amount of change log data buffered in memory meets the threshold defined by this parameter.
Default is 1000000 (1MB).
hitLogFileSize
The WebAccelerator system writes hit log data to disk if the amount of hit log data buffered in memory meets the threshold defined by this parameter.
Default is 1000000 (1MB).
changeLogFileTTL
The WebAccelerator system writes change log data to disk on the interval specified by this parameter regardless of how much change data is buffered in memory.
Default is 5 minutes.
hitLogFileTTL
The WebAccelerator system writes hit log data to disk on the interval specified by this parameter regardless of how much hit log data is buffered in memory.
Default is 5 minutes.

Managing the compile queues

The WebAccelerator system compiles all responses that it caches, and puts the responses in one of two compile queues, depending on whether the response contains Edge-Side Includes (ESI). Once in a compile queue, the WebAccelerator system uses special threads to parse the responses.

The compile queues are:

  • Normal compile queue for non-ESI responses.
  • ESI compile queue for responses that contain ESI data.
Note

If a Surrogate-Control header is located in a response, the WebAccelerator system categorizes the response as containing ESI data. For additional information about ESI support and the Surrogate-Control header, see the Policy Management Guide for the BIG-IP WebAccelerator Module.

The default values for the compile queues work well, and you should not change these values unless monitoring suggests that some tuning is required. (See Monitoring the ESI compile queue , located in Chapter 6, for more information.)

If you determine that you need to modify the thresholds for the compile queues, you can make changes to the following parameters in the /config/wa/pvsystem.conf file. It is important to make only small changes to these parameters to see if it helps overall performance. Adding threads and tasks to the compile queues can actually result in slowing the WebAccelerator system's performance.

After you change a parameter, restart the process using the bigstart restart pvac command.

Table 5.1 Compile queue parameters
Parameter
Description
maxParserThreads
Number of threads that the WebAccelerator system uses to parse responses found in the normal compile queue.
Default is 1.
maxParserTasks
Maximum number of responses allowed in the normal compile queue.
Default is 1000.
maxEsiParserThreads
Number of threads that the that the WebAccelerator system uses to parse responses found in the ESI compile queue.
Default is 1.
maxEsiParserTasks
Maximum number of responses allowed in the ESI compile queue at any given time. Set this number to 2 times the number of front-end connections allowed for the system.
Default is 1000.

Managing the assembly queue

When the WebAccelerator system receives an HTTP request that it can service from its cache, it places that request in an assembly queue. The WebAccelerator system then uses special threads to run the compiled response (including any related ESI-compiled response) and assembles the content required to respond to the request. The process of running a compiled response, in order to respond to an HTTP request, is called assembly.

The default values for the assembly queues work well, and you should not change these values unless you determine through monitoring that some tuning is required. (See Monitoring the assembly queue , located in Chapter 6, for more information.)

If you determine that you need to modify the thresholds for the assembly queues, you can make changes to the following parameters in the /config/wa/pvsystem.conf file. It is important to make only small changes to these parameters to see if it helps overall performance. Adding threads and tasks to the assembly queues can actually result in slowing the WebAccelerator system's performance.

After you change a parameter, restart the process using the bigstart restart pvac command.

Table 5.2 Assembly queue parameters
Parameter
Description
maxAssembleThreads
Number of threads used to assemble compiled responses.
Default is 1.
maxAssembleTasks
Maximum number of requests allowed in the assembly queue. You must set this number to 2 times the number of front-end connections allowed for the WebAccelerator system.
Default is 1000.
maxNumInclude
Maximum number of esi:include statements the that the WebAccelerator system processes before giving up. If this limit is reached, the WebAccelerator system returns HTTP status 404 (Page not found) to the requesting client. Default is 50.

Managing system TTL parameters

The WebAccelerator system assigns a Time-to-Live (TTL) value to every compiled response that it caches. This value defines the time that is allowed to elapse before the compiled response expires and the WebAccelerator system sends a request to the origin server for fresh content. This length of time is called the content's lifetime and can vary for each compiled response.

For most compiled responses, you can define the TTL values using acceleration policies. (See the Policy Management Guide for the BIG-IP WebAccelerator Module for more information.) Another option is to adjust the TTL values using the various lifetime mechanisms available in the HTTP and ESI protocols. However, in either case you cannot set TTL values to exceed the system limits that are controlled with the parameters that are defined in the /config/wa/pvsystem.conf file.

To modify the system limit TTL values for compiled responses, you can make changes to the following parameters in the /config/wa/pvsystem.conf file. After you change a parameter, restart the process using the bigstart restart pvac command.

Table 5.3 TTL parameters
Parameter
Description
staticMinTTL
The system-wide minimum TTL value for static content like images.
Default is 0 seconds.
staticMaxTTL
The system-wide maximum TTL value.
Default is 86400 seconds (24 hours).
staticLastModFactor
A system-wide default value for the HTTP last mod factor. This value is used in an equation that determines TTL values based on information found in HTTP headers. You can use acceleration policies to override this default value.

Note

Content lifetime and TTL values are described in further detail in the Policy Management Guide for the BIG-IP WebAccelerator Module.

Managing socket tunnels

Socket tunnels are a mechanism by which you can identify traffic that the WebAccelerator system should pass on to an identified host and port. You can use socket tunnels to configure the WebAccelerator system to handle traffic that should not or cannot be managed by a cache, such as SSL or FTP sessions.

You create socket tunnels by adding one or more socketTunnel parameters to the /config/wa/pvsystem.conf file. The parameter format is:

<socketTunnel listenPort=[port] remoteHost=[host:port] />

Where:

  • port
    Is the port on the WebAccelerator system that receives the traffic that you want tunneled.
  • host:port
    Is the host name and port to which you want the traffic tunneled.

For example:

<socketTunnel listenPort="444" remoteHost="secure1.siterequest.com:443" />

After you change a parameter, restart the process using the bigstart restart pvac command.

Managing cookie encryption

The WebAccelerator system is capable of encrypting cookies that it sets on a client. When the client presents the cookie back to the WebAccelerator system, the WebAccelerator system decrypts it and processes it. Further, if the WebAccelerator system must send a request to the origin servers, it decrypts the cookie before it sends a response to the client.

By using encrypted cookies, you ensure that the client cannot examine the information contained in the cookie. This can prevent malicious users from examining the contents of your cookies and gaining knowledge about how your site works.

You can manage cookie encryption by changing the following parameters in the /config/wa/pvsystem.conf file. After you change a parameter, restart the process using the bigstart restart pvac command.

Table 5.4 Cookie encryption parameters
Parameter
Description
encryptCookieNames
When set to true, the WebAccelerator system encrypts cookie names.
encryptCookieValues
When set to true, the WebAccelerator system encrypts cookie values.
encryptCookieVerifyIP
When set to true, the WebAccelerator system examines the IP address of the client presenting the cookie before decrypting the cookie.
Using this feature can reduce performance slightly, however, it ensures that the WebAccelerator system decrypts a cookie only if it is presented by the client to which the cookie was originally set.
encryptCookieMatching
When used, the WebAccelerator system only encrypts cookies with a name that matches the provided regular expression. You must include the start of line (^) and end of line ($) expressions. For example, to encrypt all cookies that begin with myDomain, use:
^myDomain.*$

Managing hds_prune

The WebAccelerator system uses a shell script called hds_prune to clear compiled responses, that are no longer needed, from the WebAccelerator system's on-disk cache.

The script works by periodically checking the current capacity of the on-disk cache. If the amount of available free space for the on-disk cache is less than, or equal to, the minimum amount specified by the hdsPruneStartLevel parameter, the script prunes the cache. In doing so, the script removes enough data from the on-disk cache to satisfy the maximum amount specified by the hdsPruneStopLevel parameter. That is, when the script is done, the amount of free space in the on-disk cache partition is as big as the maximum specified by the hdsPruneStopLevel parameter.

You can modify the default values for the hds_prune script, by changing the following parameters in the /config/wa/pvsystem.conf file. After you change a parameter, restart the process using the bigstart restart hds_prune command.

Table 5.5 hds_prune parameters
Parameter
Definition
hdsDiskScanInterval
The length of time that passes before the script starts checking the current amount of free space available in the on-disk cache partition.
Default is 300 seconds (5 minutes).
hdsPruneStartLevel
The smallest amount of free space allowed in the on-disk cache partition. If hds_prune finds that the on-disk cache partition has a free space value that is less than or equal to this value, then it prunes the on-disk cache. Values are expressed as a percentage of free space.
The default is to start pruning when there is less than 20% of the disk free.
hdsPruneStopLevel
The amount of free space that must be available in the partition when hds_prune is finished pruning the on-disk cache. Values are expressed as a percentage of free space.
The default is to stop pruning when there is at least 40% of the disk free.
hdsLocation
The location of the on-disk cache.
Default is /var/wa/hds.

Modifying the globalfragment.xml file

The /config/wa/globalfragment.xml configuration file contains options for:

  • Managing object types
  • Managing URL normalization
  • Redirecting browsers
  • Selectively disabling content-based identity

To edit the globalfragment.xml file

  1. Log into the BIG-IP system as root.
  2. Edit the /config/wa/globalfragment.xml file as required.
    The parameters for these options are specified in the following sections.
  3. Save the file.
  4. Restart the process that you modified, using the command specified in the following sections.
Important

We recommend that you create a backup copy of the /config/wa/globalfragment.xml file after you make changes. This enables you to easily restore the modified configuration in the event of a system failure.

Managing object types

The WebAccelerator system classifies, by object type, every response it receives from the origin servers. This classification can be more accurate than deriving an object type based on the request. To classify the object type, the WebAccelerator system reviews the response headers, and classifies the responses based on the first information it finds, in the following order:

  • File extension in the Content-Disposition header's file name field
  • File extension in the Content-Disposition header's extension field
  • Content-Type header in the response, unless it is an ambiguous MIME type
  • Extension of the path in the request

For example, if the extension in the Content-Disposition header's file name field is empty, then the WebAccelerator system looks at the file extension in the Content-Disposition header's extension field. If Content-Disposition header's field has an extension, the WebAccelerator system attempts to match it to an object type in the /config/wa/globalfragment.xml file. If there is no match, the WebAccelerator system assigns an object type of other and uses the settings for other. The WebAccelerator system looks at the information in the Content-Type header only if there is no extension in the Content-Disposition header's file name or extension fields.

The WebAccelerator system contains a set of predefined object types in the /config/wa/globalfragment.xml file. You can modify the options for these types, or add new object types. For each object type you create, you can specify the following options in the /config/wa/globalfragment.xml file.

Table 5.6 Object type options
Object type option
Description
type
A short name that you can use to identify the object type. This name is displayed in the X-PvInfo header for each response.
This option is required.
group
A short, arbitrary name that you can use to identify groups. This name is displayed in the X-PvInfo header for the response. This allows you to organize object types into groups.
This option is required.
category
An arbitrary category name that you can use to create a super set of groups. We recommend that you set a value for category that helps you differentiate between the predefined object types and the custom types that you create.
This option is required.
displayName
A longer, more descriptive name for the object type.
This option is required.
ext
The values for extension define this object type. When the WebAccelerator system finds a file extension in the file name or extension field in the Content-Disposition header of the response, it attempts to match that to one of the values that you specify in the extension. If there is a match, the WebAccelerator system classifies the response as this object type. Specify as a single value or as a comma-separated list. For example:
ext="jpg, jpeg"
This option is required.
mimeType
The values for MIME type that define this object type. If the WebAccelerator system does not find an extension in the file name or extension fields of the Content-Disposition header, it looks in the Content-Type header of the response to attempt to match that to one of the MIME types you specify here. If there is a match, it classifies the response as this object type. Specify as a single MIME type or as a comma-separated list of MIME types. For example:
mimeType="application/excel, application/msexcel, application/ms-excel"
compressToClient
Specifies in which cases the WebAccelerator system should use gzip for the response. The values you can specify are:
none
Never compress the response.
wa
Compress the response only if the client is another WebAccelerator system.
policyControlled
Use the compression setting specified in the assembly rule that is in effect for this response
Setting this option to none or wa overrides any compression settings in the assembly rule for the node to which the response matched. If you use an object type definition to control compression (set to none or wa) or run rewrite scripts, use caution and keep the following in mind:
An object type definition applies across the entire WebAccelerator system, regardless of an application or acceleration policy. The object type setting overrides settings in all assembly rules.
Use object type for compression or rewriting only if you want the setting used for any response matching that object type across the entire system, and you do not want an assembly rule to ever affect this setting.
This option is required.
transformFile
Specifies the name of the rewrite script that the WebAccelerator system should run against the response.
This option is not required and should only be used for very unusual cases, because it overrides any rewrite settings in the assembly rule for the node to which the response matched. You need this option only when you want the WebAccelerator system to run a particular rewrite script against responses for the specified content type, regardless as to what rules are set for the acceleration policy.
For most cases, you define the matching rules so that any response with this content type matches to it. Then you create an assembly rule that specifies the rewrite script that you want to run.
Contact your F5 Networks Consultant for information about how to use this option.

To see the current classification for an object type in a response, look for the type option that is displayed in the X-PvInfo header of the response string that begins with OT/.

Following is an object type example, as it appears in the /config/wa/globalfragment.xml file:

<objType

type="mspowerpoint"

group="documents"

category="common"

displayName="Microsoft Powerpoint"

ext="ppt"

mimeType="

application/powerpoint,

application/mspowerpoint,

application/ms-powerpoint,

application/x-powerpoint,

application/x-mspowerpoint,

application/vnd.powerpoint,

application/vnd.mspowerpoint,

application/vnd.ms-powerpoint"

compressToClient="wa"

/>

Managing URL normalization

To better identify content, the WebAccelerator system analyzes the contents of a response and creates an object ID based on that specific content. The WebAccelerator system then inserts the object ID into the response returns it to the client. This process, called URL normalization, enables the WebAccelerator system to recognize content independent of the URL.

Once the WebAccelerator system performs URL normalization, it can send the normalized URL in a redirect to the browser client that sent the request. The browser can use the normalized URL to search its own cache, in case it has a copy of the content that it could not recognize based on the request URL. If the browser finds the content in its cache, the WebAccelerator system does not have to send the content. This reduces bandwidth usage and speeds up the response time for the end user.

By default, the WebAccelerator system:

  • Performs URL normalization when responding to a client browser.
  • Performs URL normalization only for responses that are classified in a documents group. A documents group consists of objects or files that are 20KB or larger and size and contain Microsoft Word, Microsoft Excel, and Microsoft Power Point objects, or Adobe PDF files.
  • Has the authorization and authentication security feature disabled and the virtual base path, where the normalized objects appear to come from, is /pv_obj_cache.

You can manage URL normalization, defining whether the WebAccelerator system uses redirects and the type of content that the WebAccelerator system redirects, by modifying the contentBasedIdentity section of the /config/wa/globalfragment.xml file.

Following is an example of the contentBasedIdentity section of the /config/wa/globalfragment.xml file:

<contentBasedIdentity

enableNormalization="true"

enableNormalizationToBrowsers="false"

types=""

groups="documents"

sizeThresholdKB="20"

basePath="pv_obj_cache"

normalizationMethod="redirect"

requireAuth="false"

authMethod="cookie"

addDefaultExt="true"

/>

Some of the options in the /config/wa/globalfragment.xml file currently support only one value, and cannot be changed.

The options that you can change are specified in the following table.

Table 5.7 URL normalization options
Option
Description
enableNormalization
Set to true or false.
true enables normalization for this WebAccelerator system.
false disables normalization.
enableNormalizationToBrowsers
Set to true or false.
true enables normalization to browser clients if enableNormalization is also true. Before setting this to true, read Redirecting to browsers .
false disables normalization to browser clients.
types
Specifies the object types for which normalization can occur, in addition to the object types that are part of any groups specified in groups. See Managing object types . Specify the values in a comma-separated list. For example:
types="jpeg, pdf, text"
groups
Specifies the object groups for which normalization can occur, in addition to the object types specified in types. See Managing object types . Specify the values in a comma-separated list. For example:
groups="documents, images"
sizeThresholdKB
Specifies the minimum size, in kilobytes, that the object must be before the WebAccelerator system can normalize it.
basePath
Specifies the virtual path on your web site from which normalized objects appear to originate. You can change this value for consistency with other URLs on your web site, so that objects appear to come from specific parts of your application.
requireAuth
Set to true or false.
true enables authorization and authentication. The object ID is combined with user identifier that WebAccelerator system generates it is encrypted before being used on the redirect. The user and requested document must match before the document can be retrieved using the redirect.
false disables this feature.

Redirecting to browsers

If you set enableNormalizationToBrowsers to true, in the contentBasedIdentity section of the /config/wa/globalfragment.xml file, you enable redirects to client browsers. It is important to be aware of the following restrictions and security considerations associated with this setting.

  • If your web site contains frame sets imbedded using JavaScript, it is possible that the redirects to a browser will fail. Although this is not typically an issue if you specify documents as the only object group, it can occur.
  • For browser bookmarks, only bookmark the original URL. Normalized URL bookmarks are not valid.
  • When you enable redirects to browsers, you should enable the security feature, to restrict access to secure documents. You can do this by setting requireAuth to true. This prevents other users from finding and using the normalized URL to access content they normally would not be able to access.

Selectively disabling content-based identity

You can enable content-based identity and normalization for the WebAccelerator system, and then disable it for particular nodes in the Request Type Hierarchy. The WebAccelerator system does not normalize redirects for any request or response that matches to a node with content-based identity disabled, and it does not perform content-based cache routines for those nodes.

By default, disableContentBasedIdentity is set to false, meaning that this setting does not override any other content-based identity system-wide options.

You cannot use the disableContentBasedIdentity setting to enable content-based identity. You can only disable it when content-based identity is turned on for the WebAccelerator system. You enable content-based identity by setting enableNormalization to true in the /config/wa/globalfragment.xml file.

To disable content-based identity for a node

  1. In the navigation pane, click Policies.
    The Policies screen opens in a separate window.
  2. Click the Edit button next to the application policy name that you want to modify.
  3. On the menu bar, click Assembly.
    The content assembly options display.
  4. In the Advanced Assembly box, type:
  5. disableContentBasedIdentity=true
  6. Click the Save button.



Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Was this resource helpful in solving your issue?




NOTE: Please do not provide personal information.



Incorrect answer. Please try again: Please enter the words to the right: Please enter the numbers you hear:

Additional Comments (optional)