User documentation for this release

To view a complete list of documentation relevant to this release, see BIG-IP PSM 11.1.0 Documentation.

Supported platforms

To view a list of supported platforms, see SOL10288: BIG-IP software and platform support matrix.

If you are unsure which platform you have, look at the sticker on the back of the chassis to find the platform number.

Installation overview

The following instructions explain how to install Protocol Security Module version 11.1.0 onto existing systems running version 9.4.5 or later.

This section lists only the very basic steps for installing the software. The BIG-IP^® Systems: Getting Started Guide contains details and step-by-step instructions for completing an installation. F5 recommends that you consult the getting started guide for all installation operations.

Installation checklist

Before you begin, ensure that you have completed the following:

• The license and service contract are already updated for this release, if applicable.
• You downloaded the .iso file from F5 Downloads to /shared/images on the source for the operation.
  Note: You might need to create this directory. If so, use this exact name, including capitalization.
  Note: This step is only needed if you will run the tmsh or bigpipe commands to install (performing a live install). This is not needed if you will run the image2disk command to install.
• There is at least minimal partitioning on the system drives.
• You have already configured a management port.
• You are logged on to the management port of the system you want to upgrade.
• You are logged on to the non-active partition if you are upgrading from version 10.2.x. If you are upgrading from version 9.4.3, you can install on the active partition.
• You logged on using an account with administrative rights.
• You have saved the user configuration set (UCS) in the /var/local/ucs directory on the source installation location, if applicable.
• You are logged on to the standby unit in a redundant system, if applicable, and that you will synchronize the configuration to the active unit.
• You turned off mirroring, if applicable.
• If you are upgrading from 9.4.5 and later, you ran im <downloaded_filename.iso> to copy over the new installation utility.

Installing the software

How you install the software differs depending on the software version installed and whether your BIG-IP uses the partitions or volumes disk-formatting scheme.

• If you are upgrading from version 10.2.x and your BIG-IP uses the volumes disk-formatting scheme, see Upgrading from version 10.2.x if your BIG-IP uses volumes.
• If you are upgrading from version 10.0.x or 10.1.x and your BIG-IP uses the volumes disk-formatting scheme, see Upgrading from version 10.0.x or 10.1.x if your BIG-IP uses volumes.
• If you are upgrading from version 10.x and your BIG-IP uses the partitions disk-formatting scheme, see Upgrading from version 9.4.5 or later 9.x versions.
• If you are upgrading from version 9.4.5 or later 9.x versions, see Upgrading from version 9.4.5 or later 9.x versions.

The upgrade process installs the software on the inactive installation location that you specify. This process usually takes between three minutes and seven minutes. During the upgrade process, you see messages posted on the screen. For example, you might see a prompt asking whether to upgrade the End User Diagnostics (EUD), depending on the version you have installed. To upgrade the EUD, type yes, otherwise, type no.

Upgrading from version 10.2.x if your BIG-IP uses volumes

If you are currently running version 10.2.x and your BIG-IP uses the volumes disk-formatting scheme, use one of the following upgrade methods:

• Run the command bigpipe software desired HD<volume_number>version 11.1.0 build <nnnn.n> product BIG-IP
• Run the command tmsh install sys software image BIGIP-11.1.0.XXXX.0.iso volume HD1.X
  

  Note: The [create-volume] option is not supported on 10.2.x. If the volume does not exist, the system automatically creates the missing volume.

• Use the Software Management screens in the browser-based Configuration utility.

You can check the status of an active installation operation by running the command bigpipe software status or tmsh show sys software. If the installation fails, you can view the log file. The system stores the installation log file as /var/log/liveinstall.log.

Upgrading from version 10.0.x or 10.1.x if your BIG-IP uses volumes

If you are currently running version 10.0.x or 10.1.x and your BIG-IP uses the volumes disk-formatting scheme, use one of the following upgrade methods:

• Run the command bigpipe software desired HD<volume_number> version 11.1.0 build <nnnn.n> product BIG-IP
• Use the Software Management screens in the browser-based Configuration utility.

You can check the status of an active installation operation by running the command bigpipe software status. If the installation fails, you can view the log file. The system stores the installation log file as /var/log/liveinstall.log.

Upgrading from version 9.4.5 or later 9.x versions

If you are currently running version 9.4.5 or later 9.x versions, you must perform a one-time upgrade procedure to make your system ready for the new installation process. When you update from software version 9.4.5 or later 9.x versions to version 11.x, you cannot use the Software Management screens in the Configuration utility. Instead, you must run the command line.

Important: You cannot install version 11.x to a partitioned system. This means that, for example, you cannot have both 9.x and 11.x products coexisting on the same system.

Installation consists of the following steps:

1. Run the command bigpipe config save <your .ucs file> to save the .ucs file.
2. Since version 9.x uses the partitions disk-formatting scheme and version 11.x uses the volumes disk-formatting scheme, you must use the image2disk utility to install the <downloaded_filename.iso> as follows:
   
   image2disk - - format=volumes [OPTIONS] full_path_to_the_downloaded_filename.iso

   Tip: Type image2disk --help to view the available options.

3. Wait for the system to automatically reboot to the newly installed location.
4. If you are notified to relicense, do it now.
5. Run the command bigpipe config install <your .ucs file> to install the .ucs file.

Post-installation tasks

After the installation finishes, you must complete the following steps before the system can pass traffic. Each of these steps is covered in detail in the BIG-IP^® Systems: Getting Started Guide, and we recommend that you reference the guide to ensure successful completion of the installation process.

1. Reboot to the new installation location.
2. Log on to the browser-based Configuration utility.
3. Run the Setup utility.
4. Provision the module.

Changing the Resource Provisioning level of the Protocol Security Module

After upgrading or installing a new version, before you can use the Protocol Security Module, you must set the Protocol Security Module resource provisioning level to Nominal. You can do this from the command line, or using the Configuration utility.

To set the Protocol Security Module resource provisioning level to Nominal from the command line

Open the command-line interface utility, and run the following commands:
      tmsh modify sys provision psm level nominal
      tmsh save sys config

To set the Protocol Security Module resource provisioning level to Nominal using the Configuration utility

1. Using the Configuration utility, on the Main tab of the navigation pane, expand System, and click Resource Provisioning.
   The Resource Provisioning screen opens.
2. Set the Protocol Security (PSM) option to Nominal.
3. Click Update.
   The screen refreshes, and the resource provisioning level of the Protocol Security Module is set to Nominal.

Important: Wait 5 minutes after you set the resource provisioning level before making any configuration changes to the Protocol Security Module. The system overrides all configuration changes made before this process is completed. The system informs you when the process is not completed by displaying, in the Configuration utility, the following message: ASM is not ready. The system informs you when the process completed by indicating in the log (/var/log/asm) the following message: ASM started successfully.

New items and fixes in this release

This release includes the following new items and fixes.

New in this release

Route Domain Support
In the Configuration utility, when you enter the SMTP disallowed sender IP address, we now support the following syntax: IP_address%route_domain_id, where the IP address can (optionally) be followed by a percent sign (%) and the numeric ID of a route domain configured in the system (Network > Route Domains).

Note: If not specified, the route domain of an IP address entered in the configuration will default to the default route domain for the partition/path that is selected or current in the Configuration utility (and displayed in the drop-down list at the upper right-hand corner of any screen). The default route domain of the selected or current partition/path is not shown in the configuration screens.

IPv6 Support
ASM now supports IPv6 addresses in all parts of the product where you can configure an IP address. Any place where IP addresses are displayed, whether in the GUI or in internal/external logging capabilities, both IPv4 and IPv6 addresses are shown in their normal string representations.

Changes to Advanced Configuration System Variables
We removed the system variable OverviewEnabled.

Fixes in this release

This release includes the following fixes.

Non-RFC FTP command display on Statistics screen (ID 309852)
We fixed the reporting, on the Statistics screen, of the non RFC FTP command FTP protocol compliance failed violation.

Logging slow POST DoS attack events (ID 350683)
When the system detects a slow POST DoS attack, it now adds the event to the following logs: /var/log/ts/bd.log and /var/log/asm.

Features and fixes introduced in prior releases

New features introduced in 11.0.0

Antivirus enhancements
With this release, the system can inspect email and email attachments before releasing the content to the SMTP server. As a result, the Virus detected violation was added to the list of SMTP violations. To enable this feature, perform the following steps:

1. Enable at least one of the Alarm or Block check boxes of the Virus Detection setting, found on the SMTP Security Profile Properties screen (navigate to Protocol Security > Security Profiles > SMTP and click Create).
2. Configure an anti-virus protection server by configuring PSM to act as an ICAP client. Navigate to Protocol Security > Options > Anti-Virus Protection.
3. Navigate to Protocol Security > Options > Advanced Configuration and ensure that the values of the internal parameters icap_uri and virus_header_name correspond to the ICAP server's settings.

Note: The system's default value of the parameters icap_uri and virus_header_name are correct for the McAfee^® ICAP server. If you are using a different ICAP server, change these parameters' values to the appropriate values used by that ICAP server.

Note: F5 Networks^® tested the anti-virus feature on the following ICAP servers: McAfee^®, Trend Micro^™ InterScan^™ Web Security, and Kaspersky.

Multiple Remote Logging
With this release you can create one logging profile to log PSM messages to multiple remote servers. To configure multiple remote logging, navigate to Protocol Security > Options > Remote Logging and in the Server Addresses area of the screen add different IP addresses.

Bypass PSM
With this version, you can now configure whether or not web application traffic should bypass the Protocol Security Module, and if so, under which circumstances.

Note: Bypass is only for HTTP traffic, and not for FTP and SMTP traffic.

Warning: When you enable bypass, you permit users to continue accessing the web application even during extreme loads and failover. However, web application traffic is directed to the web server without passing through PSM. As a result, your PSM security profiles will not protect your web application. This puts your web application at risk of security threats.

There are three new parameters used to configure bypassing PSM; two are available from the Configuration utility, and one from the command line only. The following parameters are available in the Configuration utility:

• bypass_upon_asm_down: Specifies whether traffic bypasses PSM when PSM is stopped. The possible values are 1 (bypass enabled) or 0 (bypass disabled). The default value is 0 (bypass disabled). If you set this parameter value to 1, web traffic bypasses PSM if any of the following occur:
  • If you stop running PSM.
  • If you restart PSM, traffic bypasses PSM from the time PSM is stopped until the Security Enforcer reloads.
  • If the Security Enforcer performs a core dump, traffic bypasses PSM until the Security Enforcer reloads.

  Note: When enabling bypass_upon_asm_down, we recommend you set running to disabled in the "daemon-ha bd" section of /config/daemon.conf and then load the configuration using tmsh.

• bypass_upon_load: Specifies whether traffic bypasses PSM when there are not enough system resources for the Security Enforcer. The possible values are 1 (bypass enabled), and 0 (bypass disabled). The default value is 0 (bypass disabled). If you set this parameter value to 1, web traffic bypasses PSM if there is not enough memory for the Enforcer, or not enough system resources.

To change these parameters' default values, from the Configuration utility, navigate to Protocol Security > Options > Advanced Configuration.

The parameter that is available from the command line but not from the Configuration utility is bypass_under_high_cpu. This parameter’s value specifies whether traffic bypasses PSM when your system is consuming a large amount of CPU, indicated by the small amount of idle CPU available. The default is 90 percent, meaning that if the system’s idle CPU is 10 percent, traffic bypasses PSM.

To add and change the default value of this parameter, open the command line, and use the add_del_internal script, in the following format:
/usr/share/ts/bin/add_del_internal add <param_name> <param_value>.

To delete an internal parameter from your configuration, from the command line, type the following command:
/usr/share/ts/bin/add_del_internal del <param_name>.

After adding or deleting an internal parameter, you must enter and run the command bigstart restart asm in order for the changes to take effect.

User interface enhancements
In this release we made the following user interface enhancements.

• For the Data Guard configuration, we changed the options Enforce All URLs and Enforce URLs from the list to Ignore URLs in List and Enforce URLs in list, respectively. This allows you to fine tune the Data Guard operation.
• On the HTTP Security Profile Properties screen, XML Defense tab, in the XML Data Format Settings length settings, select Any to configure no limit. In previous releases, Any was not an option, and you had to set the number to 0.
• There are new parameters available in the Configuration utility:
  • virus_header_name: The ICAP response header containing detected virus name, whose default value is X-Virus-Name (McAfee’s).
  • icap_uri: The URI of an ICAP request, whose default is /reqmod.
• There are new internal parameters available from the command line and not from the Configuration utility:
  • max_slow_transactions: Specifies the maximum number of slow transactions per core before the system drops slow transactions. Slow transactions are defined in slow_transaction_timeout. The default value is 25 transactions.
  • slow_transaction_timeout: Specifies the number of seconds after which a transaction is considered slow. The system tracks the number of slow transactions that have occurred and drops slow transactions after max_slow_transactions is reached. The default value is 10 seconds.

  To change the default settings of these parameters, open the command line, and use the add_del_internal script, in the following format:
  /usr/share/ts/bin/add_del_internal add <param_name> <param_value>.

  To delete an internal parameter from your configuration, from the command line, type the following command:
  /usr/share/ts/bin/add_del_internal del <param_name>.

  After adding and changing the values of internal parameters, you must type and run the command bigstart restart asm in order for the changes to take effect.

Fixes introduced in version 11.0.0

This release includes the following fixes from version 11.0.0.

Ctrl+C does not stop recovery program (ID 222670, CR 122942)
Pressing the control and C keys simultaneously on the keyboard now correctly stops the recovery program recover_db.pl. In previous releases, it did not.

GUI Preferences saved upon upgrade (ID 222710)
GUI preferences (configured on the Options > Preferences screen) are now saved in the UCS file. As a result, if you upgrade your system, these settings are now saved on your new system.

Application Editor role enhancement (ID 223316, CR 128834)
The role Application Editor now has read-only access to Protocol Security Module profiles, and not just to the statistics screen.

Trusted XFF feature (ID 222734)
The Trusted XFF header feature is now enabled in Protocol Security Module.

Data Guard improvement (ID 223660)
We improved the functionality of the Data Guard feature with regard to the enforcement of custom patterns and exception patterns.

Logging of Disallowed senders IP address statistics (ID 224176)
When the system detects the SMTP Disallowed Senders Domain/IP Address violation, the system now logs in the Statistics screen not only the IP address, but also the domain name.

Viewing dropped requests statistics (ID 224545, ID 225277)
You can now view statistics regarding dropped requests on the Overview screen in the Protocol Security Statistics chart.

Logging of Illegal method statistics (ID 224602)
When the system detects the SMTP Illegal Method violation and the system is configured to log this violation, the system now logs it correctly in the Statistics screen. In the previous release, the system blocked the request.

Updating HTTP Profile when a lot of XML requests are sent (ID 224608)
Sending a lot of XML requests while updating a PSM HTTP profile no longer causes the system to core.

Lengthy storing of old session files (ID 224913)
To improve system performance, the PHP session files (in the /shared/tmp folder) are now aged out more quickly than before.

Sending traffic to a blade with PSM disabled (ID 225205)
Using the VIPRION^® platform, the aggregator no longer sends traffic to a blade when PSM is offline (either because the system is disabled or crashed). In such scenarios, the aggregator now redirects traffic to the primary blade. Note that the Enforcer must run at least once for this to work.

Renaming SMTP methods as commands (ID 225285)
On the SMTP Profile Properties screen, we renamed SMTP Methods to SMTP Commands, for accuracy.

Profile assignment errors (ID 225465)
Errors no longer occur when creating and assigning profiles.

Uncompressing GZIP data in responses (ID 225545)
There are no longer issues when the Enforcer fails to uncompress gzip data in responses.

Incorrect message in log upon upload of large file (ID 227039)
After a large request is sent that exceeds the Enforcer’s buffer limit of 10M (for example, uploading a 13M file), the system no longer sends an incorrect error message to /ts/log/bd.log.

Upgraded PHP version (ID 309780)
We upgraded the system’s version of PHP to the 5.3.x branch.

Correct detection of the Host header contains IP address violation (ID 319749)
The system no longer detects the HTTP Protocol Compliance sub violation Host header contains IP address when the request’s Host header contains a number value, or the request’s Host header is empty, or illegal. The system only detects this violation when the request’s host header value is an IP address.

Errors when performing multiple UCS operations simultaneously (ID 332374)
The system prevents errors from occurring if you unintentionally run two or more UCS operations simultaneously.

ArcSight date and time field (ID 336660)
When Remote Logging Profile is configured for an ArcSight^® server, the system now correctly logs the date and time when the event occurred. In previous releases there was a formatting error in the rt field.

Request storage improvement (ID 345505)
To improve the performance of storing requests, we changed the temporary storage location of requests from /var/ts/dms/uploaded_files to /shared/tmp. This is an internal enhancement made to increase system efficiency.

Reaping process changed (ID 351291 and ID 353526)
The Enforcer does not accept new transactions when they reach the Enforcer’s memory limit. The Enforcer does also not accept more transactions than the configured number of the new internal parameter max_allowed_trans is reached. The internal parameter number_jobs_to_abort was removed since it is no longer relevant.
When the value of max_allowed_trans is reached, if bypass is disabled, the system logs the message: trans_open: Not enough UMU memory to start a new trans. If bypass is enabled, the system logs the message: trans_open: Not enough UMU memory to start a new trans --> Bypassing ASM.

Handling requests that exceed the system maximum buffer length (ID 358360)
When a request exceeds the system's buffer length (generating the Request length exceeds defined buffer size violation), the system now either terminates or bypasses the request, depending on the value of the internal parameter EnableASMByPass.

Enforcer allocating memory (ID 360593)
There are additional tests at the beginning of each transaction to reduce the chances of the Enforcer allocating more memory resources that it has, and possibly producing a core dump.

Known issues

The following items are known issues in the current release.

File extension no_ext (CR51421)
The Protocol Security Module does not support the file type file extension named no_ext, because it is a reserved name. If you add a file type named no_ext, the Protocol Security Module considers it an file type with no file extension (for example, like the URL /, which has no file extension).

User roles and iControl (CR90671)
iControl^® does not support any user roles other than Administrator.

Protocol Security Module requests displayed unescaped (CR98148)
On the Protocol Security Module Statistics violation screens, the system displays escaped characters in requests as unescaped. For example, if a request contains the characters %3c the system displays them as <.

FTP logs and port numbers (CR109905)
In the FTP Remote Logging and Statistics logs, the port numbers are represented as a combination of 2 bytes instead of the real port number. For example 108, 108 is displayed to represent port number 27756 since 108*256+108=27756.

Null characters in HTTP request headers (CR112823)
If a virtual server running both the Protocol Security Module and the WebAccelerator system receives an HTTP request that contains a null character, the WebAccelerator system replaces the null character with a space. The null character is removed from the HTTP request header, so this request does not trigger the HTTP Protocol Checks violation Null in request. This behavior has no other effect on how the request is processed.

Installation may create a UCS file without database configuration (CR120190, CR127965)
If you try to install this version by running the command image2disk --nomoveconfig, or liveinstall with the database variable LiveInstall.MoveConfig set to disabled, and you have WebAccelerator, Application Security Manager, or Protocol Security Module provisioned or enabled in the target install slot, the system does not save the database configuration in the UCS file. To correctly install the current version and save your database configuration and installation, see Installing the current version and saving the database configuration and installation in the Workarounds for known issues section of this release note.

mysql database volume and deprovisioning (CR120943)
If you deprovision the WebAccelerator system, Application Security Manager, or Protocol Security Module, the system retains the mysql database volume. Because the database might contain important configuration data for the deprovisioned modules, you must determine whether or not to retain the mysql database volume. For information on locating and removing an unneeded mysql database volume, see the associated Solution in the AskF5 Knowledge Base.

Errors generated when resetting ICAP server configuration (ID 343418, ID 358256)
If you reset the ICAP server configuration while the system is processing traffic (by clicking Reset and Save on the Protocol Security > Options > Anti-Virus Protection screen), the system deletes the ICAP server configuration, but the system does not end the ICAP connections. As a result, the system logs errors in the BD log (/var/log/ts/bd.log).

Virus detection if system out of memory (ID 346498)
If the system runs out of memory resources, the system does not perform virus inspection even when it should. To inform you of this issue, the system logs in the BD log (/var/log/ts/bd.log) the error message ASM out of memory error.

Virtual machine CPU minimum requirement (ID 368121)
On a virtual machine, you need at least 2 CPUs to configure PSM.

Workarounds for known issues

The following sections describe workarounds for the corresponding known issues listed in the previous section.

Installing the current version and saving the database configuration and installation (CR120190-2, CR127965-2)

This workaround describes how to correctly install the current version and save your database configuration and installation. For information about the known issue, see Installation may create a UCS file without database configuration.

To correctly install the current version and save your database configuration and installation

1. Boot into the target installation slot.
2. Run the command tmsh save sys ucs <file location/filename.ucs>.
3. Save the UCS file in a safe, remote location.
4. Run the command tmsh reboot volume HD1.X to boot into the slot you want to install from.
5. Install your image on the target installation slot.
6. Run the command tmsh load sys ucs <filename.ucs> to restore the UCS file in the target installation slot.

Contacting F5 Networks

For additional information, please visit http://www.f5.com.

Copyright © 2011, F5 Networks, Inc., Seattle, Washington. All rights reserved. 

For a current list of F5’s trademarks and service marks, click here. All other product and company names herein may be trademarks of their respective owners.