3.7.3-AdministratorsGuide

WebSphere® DataPower SOA Appliances

Administrators Guide

Version 3.7.3

��

NoteBefore using this information and the product it supports, read the information in “Notices and trademarks” on page 191.

First Edition (May 2009)

This edition applies to version 3, release 7, modification 3 of IBM WebSphere DataPower SOA Appliances and to allsubsequent releases and modifications until otherwise indicated in new editions.

© Copyright International Business Machines Corporation 2002, 2009.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Preface . . . . . . . . . . . . . . viiWho should read this document . . . . . . . viiHow this document is organized . . . . . . . viiPublications . . . . . . . . . . . . . . viii

Installation and upgrade documentation . . . viiiAdministration documentation . . . . . . viiiDevelopment documentation. . . . . . . . ixReference documentation . . . . . . . . . ixIntegration documentation . . . . . . . . ixProblem determination documentation . . . . xSupplemental documentation . . . . . . . . x

File naming guidelines . . . . . . . . . . . xObject naming guidelines . . . . . . . . . . xiTypeface conventions . . . . . . . . . . . xi

Part 1. Working with the WebGUI . . 1

Chapter 1. WebGUI basics . . . . . . . 3Objects on the appliance . . . . . . . . . . 3Working with objects . . . . . . . . . . . 3Accessing the WebGUI . . . . . . . . . . . 3Welcome screen . . . . . . . . . . . . . 3Common WebGUI conventions . . . . . . . . 4

Working with referenced objects . . . . . . . 4Working with lists of referenced objects . . . . 5

Viewing and editing local files during configuration 5Viewing local files . . . . . . . . . . . 6Editing local files . . . . . . . . . . . . 6

Common WebGUI tasks . . . . . . . . . . 6Applying and saving changes . . . . . . . 6Canceling changes . . . . . . . . . . . 6Resetting objects . . . . . . . . . . . . 7Deleting objects . . . . . . . . . . . . 7Exporting objects . . . . . . . . . . . . 7Viewing object-specific logs . . . . . . . . 7Viewing object status . . . . . . . . . . 8Cloning services . . . . . . . . . . . . 8Accessing probe captures . . . . . . . . . 9

Part 2. Controlling user access tothe appliance . . . . . . . . . . . 11

Chapter 2. Managing user access . . . 13Understanding RBM on the DataPower appliance 13Optimizing access on the DataPower appliance . . 14Capabilities of RBM . . . . . . . . . . . 14

Authenticating users . . . . . . . . . . 14Evaluating the access profile. . . . . . . . 15Authorizing access to resources. . . . . . . 15

Configuring RBM settings . . . . . . . . . 15RBM using custom authentication . . . . . . 16RBM using LDAP authentication . . . . . . 19RBM using local user authentication . . . . . 22RBM using RADIUS authentication . . . . . 24

RBM using SAF authentication . . . . . . . 26RBM using SPNEGO authentication . . . . . 28RBM using SSL user certificate . . . . . . . 31RBM using XML file authentication . . . . . 33

Defining the password policy . . . . . . . . 35Defining an LDAP Search Parameters object . . . 36Managing RBM access . . . . . . . . . . . 37

Defining the account policy . . . . . . . . 37Restoring RBM access from the command line. . 38Extending RBM access to the WebGUI only. . . 39Enabling the RBM admin-state from thecommand line . . . . . . . . . . . . 39Publishing an RBM XML file to anotherappliance . . . . . . . . . . . . . . 39Flushing the RBM cache . . . . . . . . . 40

Chapter 3. Using the builder to createan RBM policy file . . . . . . . . . . 41Using the RBM XML file . . . . . . . . . . 41RBM XML file for authentication and authorization 41RBM XML file for authentication . . . . . . . 43RBM XML file for authorization . . . . . . . 44

Chapter 4. Managing user groupaccounts . . . . . . . . . . . . . . 47Creating a group account . . . . . . . . . . 47Format of access policy . . . . . . . . . . 48Example of access policies . . . . . . . . . 48Controlling access to the command line . . . . . 48

Adding access to a command group . . . . . 49Removing access to a command group . . . . 49

Chapter 5. Using the Access Policybuilder . . . . . . . . . . . . . . . 51Elements of an access policy . . . . . . . . . 51Adding an access policy . . . . . . . . . . 52Example access profile that grants full access . . . 53Example access policy that uses wildcards . . . . 53Example access policy that grants user managementpermissions . . . . . . . . . . . . . . 53Editing an access profile . . . . . . . . . . 54Removing an access profile . . . . . . . . . 54

Chapter 6. Managing user accounts . . 55Creating a user account . . . . . . . . . . 55Resetting the admin password . . . . . . . . 56Migrating a user to a new group . . . . . . . 56Forcing a password change . . . . . . . . . 56Changing the password for the current user . . . 57Configuring SNMP V3 users. . . . . . . . . 57

Part 3. Managing the appliance . . . 61

© Copyright IBM Corp. 2002, 2009 iii

Chapter 7. Securing communication . . 63Supported cryptographic formats . . . . . . . 63Working with keys and certificates . . . . . . 63

Creating key-certificate pairs . . . . . . . 63Generating keys and certificates . . . . . . 64Exporting keys and certificates . . . . . . . 65Importing keys and certificates . . . . . . . 66

Working with certificate revocation lists . . . . . 67Enabling CRL retrieval . . . . . . . . . 67Configuring CRL update policies . . . . . . 67

Defining Certificate Monitor objects . . . . . . 68

Chapter 8. Managing the applianceitself. . . . . . . . . . . . . . . . 71Ethernet and VLAN interfaces . . . . . . . . 71

Failover configurations . . . . . . . . . 71Configuring Ethernet interfaces . . . . . . . 72Configuring VLAN interfaces . . . . . . . 72Defining static routes . . . . . . . . . . 73Defining standby controls . . . . . . . . 73Removing an Ethernet interface from the network 74Initiating a packet-capture session . . . . . . 74

Configuring appliance-wide network settings . . . 74DNS Settings . . . . . . . . . . . . . . 76

Configuring the DNS service . . . . . . . 76Flushing the DNS hosts cache . . . . . . . 76

Host Alias . . . . . . . . . . . . . . . 77Working with local host aliases . . . . . . . 77Migrating configuration data . . . . . . . 77

NTP Service . . . . . . . . . . . . . . 78Managing the time on the appliance . . . . . . 79

Setting the local time and date . . . . . . . 79Setting the local time zone . . . . . . . . 79Creating a custom time zone . . . . . . . 79

Selecting the reboot configuration . . . . . . . 80Configuring throttle settings . . . . . . . . . 81Shutting down the appliance . . . . . . . . 82Controlling the locate LED (Type 9235) . . . . . 82

Activating the locate LED . . . . . . . . 82Deactivating the locate LED . . . . . . . . 83

Generating an appliance certificate . . . . . . 83Configuring appliance settings . . . . . . . . 83Configuring NFS Settings. . . . . . . . . . 84

NFS Client Settings . . . . . . . . . . . 84NFS Dynamic Mounts . . . . . . . . . . 85NFS Static Mounts . . . . . . . . . . . 87

Using the iSCSI protocol (Type 9235) . . . . . . 89IQN and EUI formats . . . . . . . . . . 89Configuring and initializing an iSCSI volume . . 89Repairing an iSCSI volume . . . . . . . . 90Reference objects for iSCSI . . . . . . . . 91

Configuring SNMP Settings . . . . . . . . . 92Configuring global properties . . . . . . . 93Viewing MIBs . . . . . . . . . . . . 94Configuring subscriptions . . . . . . . . 94Configuring communities. . . . . . . . . 94Configuring recipients . . . . . . . . . . 95Configuring contexts . . . . . . . . . . 96

Chapter 9. Managing network access tothe appliance . . . . . . . . . . . . 97SSH access . . . . . . . . . . . . . . 97Telnet access . . . . . . . . . . . . . . 97WebGUI access . . . . . . . . . . . . . 98XML Management Interface . . . . . . . . 100

Services overview . . . . . . . . . . . 100Enabling interface services . . . . . . . . 101Changing default security and HTTP settings 102

SOAP interface . . . . . . . . . . . . . 102General structure of requests . . . . . . . 103General structure of responses. . . . . . . 103Available operations for requests . . . . . . 103Example request to view status . . . . . . 106Example request to compare configurations . . 107

WSDM interface . . . . . . . . . . . . 108Example request to view the number of clientrequests . . . . . . . . . . . . . . 110Example request to view active users . . . . 110Example request to view CPU usage. . . . . 111Example request to view appliance usage . . . 111Example request to view accepted connections 111

Chapter 10. Managing the firmwareimage. . . . . . . . . . . . . . . 113Applying a firmware image . . . . . . . . 113Rolling back an upgrade. . . . . . . . . . 113

Chapter 11. Managing files. . . . . . 115Directories on the appliance . . . . . . . . 115Launching the File Management utility . . . . . 117Displaying directory contents . . . . . . . . 117Creating a subdirectory . . . . . . . . . . 117Deleting a directory . . . . . . . . . . . 118Refreshing directory contents . . . . . . . . 118Uploading files from the workstation . . . . . 118Working with Java Key Stores . . . . . . . . 119

Required software . . . . . . . . . . . 119Granting permissions . . . . . . . . . . 119Types of key stores . . . . . . . . . . 119Uploading a file from a Java Key Store . . . . 119

Fetching files . . . . . . . . . . . . . 120Copying files . . . . . . . . . . . . . 120Renaming files . . . . . . . . . . . . . 121Moving files . . . . . . . . . . . . . . 121Viewing files . . . . . . . . . . . . . 122Editing files . . . . . . . . . . . . . . 122Deleting files . . . . . . . . . . . . . 122

Chapter 12. Managing auxiliary datastorage . . . . . . . . . . . . . . 123Configuring the compact flash. . . . . . . . 123Managing the file system on the compact flash . . 123

Initializing the file system . . . . . . . . 123Repairing the file system . . . . . . . . 124

Configuring the hard disk array . . . . . . . 124Managing the file system on the hard disk array 124


iv IBM WebSphere DataPower SOA Appliances: Administrators Guide

Managing the RAID volume . . . . . . . . 125Activating the volume . . . . . . . . . 125Initializing the volume . . . . . . . . . 125Rebuilding the volume . . . . . . . . . 125Deleting the volume . . . . . . . . . . 126

Chapter 13. Managing theconfiguration of the appliance . . . . 127Managing domains . . . . . . . . . . . 127

The default domain . . . . . . . . . . 127Application domains . . . . . . . . . . 127Visible domains . . . . . . . . . . . 128Creating application domains . . . . . . . 128Restarting application domains . . . . . . 129Resetting application domains . . . . . . . 130

Creating Include Configuration File objects . . . 130Creating Import Configuration File objects . . . 131Backing up and exporting configuration data. . . 133

Backing up the entire appliance . . . . . . 133Backing up domains . . . . . . . . . . 134Exporting select objects . . . . . . . . . 135Copying or moving select objects . . . . . . 136

Managing configuration checkpoints . . . . . 138Defining number configuration checkpoints toallow . . . . . . . . . . . . . . . 138Saving configuration checkpoints . . . . . . 138Listing configuration checkpoints. . . . . . 139Rolling back to a configuration checkpoint . . 139Deleting configuration checkpoints . . . . . 139

Importing configuration data . . . . . . . . 140Managing changes in configuration data . . . . 141

Comparing configurations . . . . . . . . 142Reading the change report . . . . . . . . 143Reverting changes . . . . . . . . . . . 143

Chapter 14. Configuring deploymentpolicies . . . . . . . . . . . . . . 145Creating a Deployment Policy object . . . . . 145Using the deployment policy builder . . . . . 146Specifying the matching statement . . . . . . 147

Chapter 15. Managing logs . . . . . 149Types of log targets . . . . . . . . . . . 149Configuring log categories . . . . . . . . . 150Configuring log targets . . . . . . . . . . 150Setting event filters . . . . . . . . . . . 150Setting object filters . . . . . . . . . . . 151Setting IP address filters . . . . . . . . . . 152Setting event subscriptions . . . . . . . . . 152Viewing log files . . . . . . . . . . . . 153Configuring an email pager . . . . . . . . 153Using a Load Balancer Group as the remote host 154

Part 4. Referenced objects . . . . 155

Chapter 16. Service objects . . . . . 157HTTP Service . . . . . . . . . . . . . 157SSL Proxy Service . . . . . . . . . . . . 158TCP Proxy Service. . . . . . . . . . . . 159

Chapter 17. Referenced objects . . . 161Access Control List . . . . . . . . . . . 161

Overview. . . . . . . . . . . . . . 161Creating an Access Control List object . . . . 162

Defining Certificate objects . . . . . . . . . 162Defining Identification Credentials objects . . . . 164Working with Kerberos objects . . . . . . . 164

Points to remember when using Kerberos . . . 165Kerberos KDC Server objects . . . . . . . 166Kerberos Keytab File objects . . . . . . . 166

Defining Key objects . . . . . . . . . . . 167Load Balancer Group . . . . . . . . . . . 168

Health of member servers . . . . . . . . 168Setting the health state with a variable . . . . 169Configuring Load Balancer Group objects . . . 169

Defining Profile objects . . . . . . . . . . 173RADIUS Settings . . . . . . . . . . . . 175

NAS-identifier . . . . . . . . . . . . 175Configuring RADIUS Settings . . . . . . . 175

Adding SSH known hosts . . . . . . . . . 176Defining SSL Proxy Profile objects . . . . . . 177

Creating a forward (or client) proxy . . . . . 177Creating a reverse (or server) proxy . . . . . 177Creating a two-way proxy . . . . . . . . 178

Working with Validation Credentials objects . . . 179Creating for non-expiring, non-password-protected certificates . . . . . . . . . . 179Creating for select certificates . . . . . . . 179

z/OS NSS Client . . . . . . . . . . . . 181Creating the z/OS NSS Client . . . . . . . 182

Appendix A. User interfacecustomization . . . . . . . . . . . 183Aspects that can be customized . . . . . . . 183Markup supported for the XML file . . . . . . 183Structure of the XML file . . . . . . . . . 185Command line prompt extension definition . . . 186Example messages for WebGUI sessions . . . . 186

Example pre-login message. . . . . . . . 186Example post-login message . . . . . . . 186Example appliance messages . . . . . . . 186

Example messages for command line sessions . . 187Example pre-login message. . . . . . . . 187Example post-login message . . . . . . . 187Example appliance message . . . . . . . 187

Template of the custom user interface file . . . . 188

Appendix B. Getting help andtechnical assistance . . . . . . . . 189Searching knowledge bases . . . . . . . . . 189Getting a fix . . . . . . . . . . . . . . 189Contacting IBM Support. . . . . . . . . . 190

Notices and trademarks . . . . . . . 191Trademarks . . . . . . . . . . . . . . 191

Index . . . . . . . . . . . . . . . 193

Contents v

vi IBM WebSphere DataPower SOA Appliances: Administrators Guide

Preface

IBM® WebSphere® DataPower® SOA Appliances are purpose-built, easy-to-deployNetwork appliances that simplify, help secure, and accelerate your XML and WebServices deployments while extending your SOA infrastructure. These appliancesoffer an innovative, pragmatic approach to harness the power of SOA whilesimultaneously enabling you to leverage the value of your existing application,security, and Networking infrastructure investments.

Who should read this documentThis document is intended for administrators of who are responsible for theconfiguration and maintenance of the DataPower appliance. Administrators shouldhave the following knowledge:v Network architecture and conceptsv Internet and transport protocolsv Lightweight Directory Access Protocol (LDAP) and directory servicesv Authentication and authorizationv XML and XSLT

Administrators should also be familiar with SSL protocol, key exchange (publicand private), digital signatures, cryptographic algorithms, and certificateauthorities.

The types of administrators who will work on the appliance include the followingbroad roles which are found in a typical Enterprise organization:v A single administrator with the admin account who manages day-to-day

operations.v System administrators who manage access to all objects except Network

interfaces.v Network administrators who manage Network connectivity and real time

operational data for the appliance.v Account administrators who manage users and user groups.v Access administrators who manage access to all resources, access policies, Role

Based Management (RBM), cryptographic keys, authentication, andauthorization.

v Lifecycle administrators who manage simple appliance and domain backups, aswell as lifecycle migration of primary objects.

How this document is organizedThis document is organized across the following broad concepts:v Part 1, “Working with the WebGUI”

Discusses basic access to the WebGUI and common tasks that are performedfrom the WebGUI.

v Part 2, “Controlling user access to the appliance”Focuses on user and group accounts, Role Based Management (RBM), remoteaccess to the appliance, access policies, SNMP V3 user accounts, and settings forRADIUS servers.

© Copyright IBM Corp. 2002, 2009 vii

v Part 3, “Managing the appliance”Details network connectivity and utilities, file management, general andadvanced configuration settings, log management, and the XML ManagementInterface, which manages lifecycle tasks.

v Part 4, “Referenced objects”This part details configuring primary and secondary service objects from theobject view. Configuring service objects in this view allows users to buildcomprehensive objects with the most granular control possible.

PublicationsThe IBM WebSphere DataPower library is organized into the following categories:v “Installation and upgrade documentation”v “Administration documentation”v “Development documentation” on page ixv “Reference documentation” on page ixv “Integration documentation” on page ixv “Problem determination documentation” on page xv “Supplemental documentation” on page x

Installation and upgrade documentationv IBM WebSphere DataPower SOA Appliances: 9003: Installation Guide

Provides instructions for installing and powering up the Type 7993 (9003)appliance, creating a startup configuration script, and placing the appliance inoperation.

v IBM WebSphere DataPower SOA Appliances: Type 9235: Installation Guide

Provides instructions for installing and powering up the Type 9235 appliance,creating a startup configuration script, and placing the appliance in operation.

v IBM WebSphere DataPower SOA Appliances: Type 9235: Hardware ProblemDetermination and Service Guide

Provides information about diagnosing and troubleshooting hardware problems,ordering consumable replacement parts, and replacing parts.

v IBM WebSphere DataPower SOA Appliances: Upgrade and Rollback Guide: Generation2 Firmware

Provides instructions for upgrading Generation 2 firmware and for rolling backfirmware upgrades.

Administration documentationv IBM WebSphere DataPower SOA Appliances: Appliance Overview

Provides an introduction and understanding of the IBM Websphere DataPowerSOA appliances.

v IBM WebSphere DataPower SOA Appliances: Administrators Guide

Provides instructions for using the DataPower GUI for managing user access,network access, appliance configuration and system configuration of theappliance.

v IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide

A user guide for using a Hardware Security Module (HSM) installed in theappliance.

viii IBM WebSphere DataPower SOA Appliances: Administrators Guide

Development documentationv IBM WebSphere DataPower SOA Appliances: XSL Accelerator Developers Guide

Provides instructions for using the WebGUI to configure XSL Proxy and XSLCo-Processor services.

v IBM WebSphere DataPower SOA Appliances: XML Firewall Developers Guide

Provides instructions for using the WebGUI to configure XML Firewall services.v IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers

Guide

Provides instructions for using the WebGUI to configure Web ApplicationFirewall services.

v IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway DevelopersGuide

Provides instructions for using the WebGUI to configure Multiple-ProtocolGateway services.

v IBM WebSphere DataPower SOA Appliances: Web Service Proxy Developers Guide

Provides instructions for using the WebGUI to configure Web Service Proxyservices.

v IBM WebSphere DataPower SOA Appliances: B2B Gateway Developers Guide

Provides instructions for using the WebGUI to configure B2B Gateway services.v IBM WebSphere DataPower SOA Appliances: Low Latency Messaging Developers

Guide

Provides instructions for using the WebGUI to configure a DataPower appliancefor low latency messaging.

Reference documentationv Product-specific documentation for using commands from the command line.

The documentation is specific to each of the following products. Each documentprovides an alphabetical listing of all commands with syntactical and functionaldescriptions.– IBM WebSphere DataPower XML Accelerator XA35: Command Reference

– IBM WebSphere DataPower XML Security Gateway XS40: Command Reference

– IBM WebSphere DataPower XML Integration Appliance XI50: Command Reference

– IBM WebSphere DataPower B2B Appliance XB60: Command Reference

– IBM WebSphere DataPower Low Latency Appliance XM70: Command Reference

v IBM WebSphere DataPower SOA Appliances: Extension Elements and FunctionsCatalog

Provides programming information about the usage of DataPower XSLTextension elements and extension functions.

Integration documentationThe following documents are available for managing the integration of relatedproducts that can be associated with the DataPower appliance:v Integrating with ITCAM

Provides concepts for integrating the DataPower appliance with IBM TivoliComposite Application Management for SOA.

v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphereTransformation Extender

Preface ix

Provides concepts for integrating the DataPower appliance with WebSphereTransformer Extender.

v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ

Explains the concepts and common use patterns for connecting DataPowerservices to WebSphere MQ systems.

Problem determination documentationv IBM WebSphere DataPower SOA Appliances: Problem Determination Guide

Provides troubleshooting and debugging tools.

Supplemental documentationv Understanding Web Services Policy

Provides conceptual information about how the DataPower appliance can useWeb Services Policy (WS-Policy).

v Understanding WS-Addressing

Provides conceptual information about how the DataPower appliance can useWS-Addressing.

v Understanding LTPA

Provides conceptual information about how the DataPower appliance can useLightweight Third Party Authentication.

v Understanding SPNEGO

Provides conceptual information about how the DataPower appliance can useSPNEGO.

v Optimizing through Streaming

Provides conceptual information about and procedures for optimizing theDataPower appliance through streaming.

v Securing the Last Mile

Provides conceptual information about and procedures for understanding theDataPower appliance while securing the last mile.

v Configuring the DoD PKI

Provides conceptual information about and procedures for configuring theDataPower appliance with Department of Defense Public Key Infrastructure.

File naming guidelinesThe maximum length for a file name can be approximately 4128 characters. Thename of the base file can be up to 128 characters in length. The base file is the partafter the name of the DataPower directory. Examples of directories are local:,store:, and temporary:.

If the directory (or domain) supports subdirectories, the path to the file can have alength of 4000 characters. When you create a domain, its name is the base filename in several DataPower directories when viewed from the default domain.

The following characters are valid in directory and file names:v a through z

v A through Z

v 0 through 9

v _ (underscore)

x IBM WebSphere DataPower SOA Appliances: Administrators Guide

v - (dash)v . (period)

Note: Names cannot contain two consecutive periods (..).

Object naming guidelinesThe object name must be unique in the object namespace. The following charactersare valid in when specifying the name for an object:v a through z

v A through Z

v 0 through 9

v _ (underscore)v - (dash)v . (period)

Note: Names cannot contain two consecutive periods (..).

Typeface conventionsThe following typeface conventions are used in the documentation:

bold Identifies commands, programming keywords, and GUI controls.

italics Identifies words and phrases used for emphasis and user-suppliedvariables.

monospacedIdentifies user-supplied input or computer output.

Preface xi

xii IBM WebSphere DataPower SOA Appliances: Administrators Guide

Part 1. Working with the WebGUI

Chapter 1. WebGUI basics . . . . . . . . . 3Objects on the appliance . . . . . . . . . . 3Working with objects . . . . . . . . . . . 3Accessing the WebGUI . . . . . . . . . . . 3Welcome screen . . . . . . . . . . . . . 3Common WebGUI conventions . . . . . . . . 4

Working with referenced objects . . . . . . . 4Working with lists of referenced objects . . . . 5

Viewing and editing local files during configuration 5Viewing local files . . . . . . . . . . . 6Editing local files . . . . . . . . . . . . 6

Common WebGUI tasks . . . . . . . . . . 6Applying and saving changes . . . . . . . 6Canceling changes . . . . . . . . . . . 6Resetting objects . . . . . . . . . . . . 7Deleting objects . . . . . . . . . . . . 7Exporting objects . . . . . . . . . . . . 7Viewing object-specific logs . . . . . . . . 7

Viewing log files from the catalog . . . . . 7Viewing log files from the configuration screen 7

Viewing object status . . . . . . . . . . 8Cloning services . . . . . . . . . . . . 8Accessing probe captures . . . . . . . . . 9

© Copyright IBM Corp. 2002, 2009 1

2 IBM WebSphere DataPower SOA Appliances: Administrators Guide

Chapter 1. WebGUI basics

The WebGUI is the primary interface for managing the appliance itself and forconfiguring objects.

Objects on the applianceObjects that can be configured on the appliance range from simple to complex. Anobject is any entity that you configure on the appliance. During configuration, anobject can reference another object that can, in turn, reference another object. Forexample, the configuration of a service references an instance of the XML Managerobject that references an instance of the User Agent object. The flexibility inconfiguration and association of referenced object allow you to meet yourbusiness-processing criteria and security requirements.

Working with objectsWhen configuring services on the appliance, the WebGUI provides an object viewand a service view. You can use either view to create or edit the service.

Service viewWorking in the service view allows less-than-expert level users to buildbasic, generic objects.

Object viewWorking in the object view allows expert-level users to build specific,complex and highly detailed objects.

Accessing the WebGUITo use the WebGUI, the Web Management Interface must be configured. Thisinterface was defined during the initial firmware setup (during applianceinstallation) or afterward with the web-mgmt command.

To access the WebGUI, use the following procedure:1. Direct your browser to the WebGUI login screen. Use the IP address and port

number assigned during the configuration of the Web Management interface.The address uses the HTTPS protocol and has the https://address:portformat.

2. In the login fields, specify an account name and password.3. From the Domain list, select the domain to which to log in.4. Click Login.

After verifying credentials, the WebGUI displays the Control Panel.

Welcome screenAfter successfully logging in, the WebGUI displays its Welcome screen. Visibility ofobjects in the WebGUI is controlled by a combination of the Role-basedmanagement (RBM) object and whether the administrator is in the default domainor an application domain.


This screen is separated into the following areas:v The banner shows details about the administrator who logged in to the

appliance and contains the following controls:– The Domain list that allows the administrator to switch domains.– The Save Config button that allows the administrator to persist configuration

changes.– The Logout button that allows the administrator to end the WebGUI session.

v The navigation bar along the left side provides access to related configurationsuites and to related management suites. This area contains the followingmenus:– The Control Panel returns the administrator to the Welcome screen.– The Status menu provides access to logs and status providers.– The Services menu provides access to service configuration objects and

objects referenced by service objects. When the administrator selects the item,the WebGUI displays the service view for the object.

– The Network menu provide access to network configuration objects. Theseobjects are to define the network in which the appliance connects. Many ofthese objects are available in the default domain.

– The Administration menu provides access to managing access to theappliance as well as general appliance settings. Many of these objects areavailable in the default domain.

– The Objects menu provides access to service configuration objects and objectsreferenced by service objects. When the administrator selects the item, theWebGUI displays the object view for the object.

v The dashboard that is separated into the following areas:– The top area contains icons to access top-level objects for the appliance.– The middle area contains icons to access monitoring and troubleshooting

utilities.– The bottom area contains icons to access file management and administration

utilities.When you click any icon on the dashboard or select any item from the menu,the WebGUI replaces the dashboard with the details for the selected item.

Common WebGUI conventionsIn addition to the standard interface controls, the WebGUI uses custom controls tohelp during the configuration of objects. These controls generally pertain todefining referenced objects.

Working with referenced objectsWhen using the WebGUI to create and modify objects, the configuration screenmight display an input field to select a referenced object. Figure 1 illustrates thistype of input field.

When the WebGUI displays this type of input field, you can specify the referencedobject in the following ways:v Select the name of an existing referenced object from the list.

Figure 1. Input field for referenced objects


v Use the + button to create a new referenced object. When created, the input fieldcontains the name of the newly created referenced object.

v Use the ... button to modify the referenced object whose name is in the inputfield. When modified, the input field retains the name of the referenced object.

When you click the + button or ... button, the WebGUI launches a new windowthat displays the configuration screen for that type of object.

Working with lists of referenced objectsWhen using the WebGUI to create or modify objects, the configuration screenmight display an input list to define a group of referenced objects. The input forthis configuration item is the list of referenced objects. Figure 2 illustrates this typeof input list.

When the WebGUI displays this type of list, you can manage referenced objects inthe following ways:v Select the name of an existing referenced object from the list. Click Add to add it

to the list of referenced objects.v Use the + button to create a new referenced object. When created, the input field

contains the name of the new referenced object. Click Add to add it to the list ofreferenced objects.

v Use the ... button to modify the referenced object whose name is in the inputfield. When modified, the input field retains the name of the referenced object.Click Add to add it to the list of referenced objects.

v Select the name of a referenced object from the list (either the input field or thelist of referenced objects). Click Delete to remove it from the list of referencedobjects.

When you click the + button or ... button, the WebGUI launches a new windowthat displays the configuration screen for that type of object.

Viewing and editing local files during configurationAs you use the WebGUI to select a local file during configuration, theconfiguration screen might display the View and Edit buttons beside the selectionlists.

Working with files in this way has the following advantages:v Ensure that the file is the one that you wantv Ability to edit the file to address errors found while defining a configurationv Use a single session instead of opening another session to manage files through

the File Management utility

You cannot view or edit remote files.

Figure 2. Input list for referenced objects

Chapter 1. WebGUI basics 5

Viewing local filesTo view a local file, use the following procedure:1. Select the file from the lists.2. Click View to open the file editor in view mode.3. Review the file.4. Click Cancel.

Editing local filesThe edited file overwrites the original file.

To edit a local file, use the following procedure:1. Select the file from the lists.2. Click Edit to open the file editor in edit mode.3. Edit the file as required.4. Click Submit to save changes.5. Click Close.

Common WebGUI tasksThe majority of objects provide the following common tasks. Not all of these tasksare available to all objects.v Applying and saving configuration changesv Canceling changes before saving to the running configurationv Resetting changes to an objectv Deleting an objectv Exporting the configuration of an objectv Viewing object-specific logsv Viewing object statusv Cloning a servicev Accessing probe captures

Applying and saving changesAs you use the WebGUI to manage object and service configurations, click Applyto save these changes to the running configuration. Changes that are made to therunning configuration take effect immediately, but are not persisted to the startupconfiguration. During an appliance restart these changes are lost.

To retain applied changes across an appliance restart, click Save Config. Thechanges are saved to the startup configuration. The startup or persistentconfiguration is persisted across an appliance restart. By default, the appliancereads the startup configuration from the auto-config.cfg file.

Canceling changesAs you use the WebGUI to manage objects, click Cancel to not save the currentchanges to the running configuration. If you click Cancel, you return to objectcatalog and lose all changes.


Resetting objectsIndependent of whether the settings are saved to the configuration, you can resetan object to its default configuration.

Use the following procedure to revert changes to a specific object:1. Display the catalog for the object. The catalog lists the available instances of

this object.2. Click the name of the object for which to reset to display the configuration

screen.3. Click Undo.4. Follow the prompts.

Deleting objectsYou might want to delete objects that are no longer needed. If no other objectdepends on the object to be deleted, you can delete it at any time. Because aDataPower service is a top-level object, you can delete it at any time. Conversely,you cannot delete an object that is active and that is in use by a higher-level object.

Use the following procedure to delete an object:1. Display the catalog for the object. The catalog lists the available instances of

this object.2. Click the name of the object to delete to display the configuration screen.3. Click Delete.4. Follow the prompts.

Deleting an object deletes that object only. Deleting an object does not delete anyreferenced object.

Exporting objectsUse the following procedure to export an object:1. Display the catalog for the object. The catalog lists the available instances of

this object.2. Click the name of the object to export to display the configuration screen.3. Click Export.4. Follow the prompts.

Viewing object-specific logsInstead of filtering the log for the default log or a configured log target, you canview log messages that are specific to an object.

Viewing log files from the catalogTo view object-specific logs from the catalog, use the following procedure:1. Display the catalog for the object. The catalog lists the available instances of

this object.2. Click the magnifying glass icon.

Viewing log files from the configuration screenTo view object-specific logs from the configuration screen, click View Logs.


Viewing object statusYou can view the status of an object and all its referenced objects to help determinewhy a configuration object is in a down state. When you view the object status, theWebGUI opens a new window. This window provides the ability to show or hideunused properties.v To show the unused properties, click Show.v If the display lists unused properties, click Hide to hide these properties. Hiding

unused properties is the default behavior.

When viewing the object status, the window provides the following information:v The name of the instance and its type with a control to collapse (hide) or expand

(show) referenced objectsv Its configuration state: New, Modified, or Saved

v It operational state: up or down

v Its administrative state: enabled or disabled

v Details about the detected error, if applicablev A link (magnifying glass icon) to view the logs for this object

Use the following procedure to view the status for an object:1. Display the catalog for the object. The catalog lists the available instances of

this object.2. Click the name of the object to view to display the configuration screen.3. Click View Status.

Cloning servicesYou might want to create a service that is similar to an existing service. Forexample, you need two equivalent services, but each service communicates with adifferent remote server. In these cases, you can create a clone of an existing serviceand edit the clone. The cloning process can expedite the creation of a similarservice.

Use the following procedure to clone a server:1. Display the catalog for the service. The catalog lists the available instances of

this service.2. Click the name of the service to clone to display the configuration screen.3. Click Clone.4. When the screen refreshes, specify the name of the clone.5. Specify the Ethernet interface that the service monitors for incoming client

requests in the Device Address field. Use the default address (0.0.0.0) to specifyall interfaces.

6. Specify the Ethernet port that the service monitors for incoming client requestsin the Device Port field.

7. As necessary, edit the other properties.8. Click Apply to save the object to the running configuration.9. Optionally, click Save Config to save the object to the startup configuration.


Accessing probe capturesAfter enabling the probe, defining the triggers, and sending transactions thatmatch the conditions defined by the triggers, you can view the capturedtransactions.

Use the following procedure to access probe captures:1. Display the catalog for the service object. The catalog lists the available

instances of this object.2. Click the name of the service for which to view the probe captures to display

the configuration screen.3. Click Show Probe.4. Click the magnifying glass icon to view details about that captured

transactions.

For complete details about using the probe, refer to the IBM WebSphere DataPowerSOA Appliances: Problem Determination Guide.


Part 2. Controlling user access to the appliance

Chapter 2. Managing user access . . . . . . 13Understanding RBM on the DataPower appliance 13Optimizing access on the DataPower appliance . . 14Capabilities of RBM . . . . . . . . . . . 14

Authenticating users . . . . . . . . . . 14Evaluating the access profile. . . . . . . . 15Authorizing access to resources. . . . . . . 15

Configuring RBM settings . . . . . . . . . 15RBM using custom authentication . . . . . . 16RBM using LDAP authentication . . . . . . 19RBM using local user authentication . . . . . 22RBM using RADIUS authentication . . . . . 24RBM using SAF authentication . . . . . . . 26RBM using SPNEGO authentication . . . . . 28RBM using SSL user certificate . . . . . . . 31RBM using XML file authentication . . . . . 33

Defining the password policy . . . . . . . . 35Defining an LDAP Search Parameters object . . . 36Managing RBM access . . . . . . . . . . . 37

Defining the account policy . . . . . . . . 37Restoring RBM access from the command line. . 38Extending RBM access to the WebGUI only. . . 39Enabling the RBM admin-state from thecommand line . . . . . . . . . . . . 39Publishing an RBM XML file to anotherappliance . . . . . . . . . . . . . . 39Flushing the RBM cache . . . . . . . . . 40

Chapter 3. Using the builder to create an RBMpolicy file. . . . . . . . . . . . . . . 41Using the RBM XML file . . . . . . . . . . 41RBM XML file for authentication and authorization 41RBM XML file for authentication . . . . . . . 43RBM XML file for authorization . . . . . . . 44

Chapter 4. Managing user group accounts . . . 47Creating a group account . . . . . . . . . . 47Format of access policy . . . . . . . . . . 48Example of access policies . . . . . . . . . 48Controlling access to the command line . . . . . 48

Adding access to a command group . . . . . 49Removing access to a command group . . . . 49

Chapter 5. Using the Access Policy builder . . . 51Elements of an access policy . . . . . . . . . 51Adding an access policy . . . . . . . . . . 52Example access profile that grants full access . . . 53Example access policy that uses wildcards . . . . 53Example access policy that grants user managementpermissions . . . . . . . . . . . . . . 53Editing an access profile . . . . . . . . . . 54Removing an access profile . . . . . . . . . 54

Chapter 6. Managing user accounts . . . . . 55Creating a user account . . . . . . . . . . 55

Resetting the admin password . . . . . . . . 56Migrating a user to a new group . . . . . . . 56Forcing a password change . . . . . . . . . 56Changing the password for the current user . . . 57Configuring SNMP V3 users. . . . . . . . . 57


Chapter 2. Managing user access

The DataPower appliance manages access through role-based management (RBM).RBM provides a flexible and integrated means to control whether an authenticateduser has the necessary privileges to access resources through access policies.

Settings on the DataPower RBM policy provide the facility to define a globalpassword policy for locally-defined users.

Understanding RBM on the DataPower applianceRBM controls the relationships between authenticated users and resources. Theuser logs in to the DataPower appliance. The user is authenticated either by aremote authentication system or by the DataPower appliance. The RBM policydetermines whether to allow an authenticated user to access specific resources.v When authentication uses a remote authentication system, such as an LDAP

server, RBM extracts the identity of the authenticated user, maps the identity toa credential, and determines whether to authorize access to the resource basedon the credential. If a problem occurs during remote authentication, RBM canuse one or more locally-defined fallback users.Figure 3 illustrates the basic components of RBM and their relationships.

v When authentication is local, authentication is by user name and password. Thegroup in which the user is a member determines whether to authorize access tothe resource. Users who are not members of a group are not under RBM control.

The RBM policy uses access profiles to determine authorization to resources. Anaccess profile is made up of one or more access policies. Each access policy defineswhich privileges to provide to a single resource. An access policy can use wildcardcharacters in regular expressions to define the same set of privileges to multipleresources.

Because RBM distances access policies from individual users, you can modify anaccess profile that affects a collection of users instead of modifying each userindividually. For example, you can modify the access profile in a user group tochange resource authorization for all members of that group. Alternatively, you canchange the access profile associated with a credential to modify all users who mapto that credential.

Figure 3. RBM processing with remote authentication


Optimizing access on the DataPower applianceTo maximize access control and to adhere to best practices, complete the followinghigh-level procedures:1. Define the global RBM policy. For information, refer to “Configuring RBM

settings” on page 15.2. Define the global password policy for locally-defined user accounts. For

information, refer to “Defining the password policy” on page 35.3. Create groups. For information, refer to “Creating a group account” on page 47.4. Create an access profile for each group. For information, refer to Chapter 5,

“Using the Access Policy builder,” on page 51.5. Create users who are members of groups. For information, refer to Chapter 6,

“Managing user accounts,” on page 55.

Capabilities of RBMRole-based management consists of the following capabilities:v Authenticating usersv Evaluating the access profilev Enforcing access to resources

Authenticating usersExtract the user identity from the access request and authenticate the user identitythat is presented. One of the following methods can be used for userauthentication:

CustomAn external programmatic method.

LDAP serverAn external authentication system.

Local userLocally configured user account.

RADIUS serverAn external authentication system.

SAF An external authentication system. This method is available on allappliances except for XML Accelerator XA35 and Low Latency ApplianceXM70 appliances.

SPNEGOAn external Windows Integrated Authentication system. This method isavailable on all appliances except for XML Accelerator XA35 appliances.

SSL user certificateAn SSL certificate from a connection peer.

XML fileA file that contains authentication information.

Note: When using an external authentication system, the mapping method todetermine the access profile must be a local resource.


Evaluating the access profileThe access profile defines the set of privileges for one or more resources on theDataPower appliance. Resources can be as broad as an XML Firewall or as specificas the ability to only configure user profiles that start with the letters foo (as infoo_one). Privileges for a resource can be one or more of the following:v Readv Writev Addv Deletev Execute

A bundle of access rights (also termed access policies) constitutes an access profile.An access profile can originate from any of the following credential mappingsources:

CustomAn external programmatic method.

Local user groupLocally configured user group.

XML fileA file that defines access profiles.

Table 1 lists the supported credential mapping methods for each userauthentication method.

Table 1. Authentication methods and supported credential mapping methods

Authentication method

Mapping Credentials method

Local user group XML file Custom

Custom No Yes Yes

LDAP No Yes Yes

Local user Yes Yes Yes

RADIUS No Yes Yes

SAF No Yes Yes

SPNEGO No Yes Yes

SSL user credential No Yes Yes

XML file Yes Yes Yes

Authorizing access to resourcesAfter the user is authenticated and the access profile is evaluated, the DataPowerappliance enforces the established access profile. For example, the WebGUI will notdisplay any resource to which the user has no access, and the command line willnot recognize commands for any resource to which the user has no access.

Configuring RBM settingsThe overview of the steps to configure role-based management is as follows:1. Select Administration → Access → RBM Settings to display the RBM Settings

(Main) screen.

Chapter 2. Managing user access 15

2. Specify whether to enforce the RBM policy for both the WebGUI and thecommand line or to enforce the RBM policy for the WebGUI only.

3. Specify whether to allow or restrict access by the admin account to the serialport.

4. Select the authentication method.

Table 2. Authentication method and configuration steps

Authentication method Configuration steps

Custom Create a style sheet. Store the file in a local directory, or stageit on an accessible file server.

LDAP Configure an LDAP server for authentication.

Local user Use the New User Account wizard to create new users, oruse the Manage User Accounts panel to modify an existinguser.

RADIUS Configure a RADIUS server.

SAF Configure a z/OS® NSS Client object for authentication withan NSS server.

SPNEGO Configure a Kerberos keytab to decrypt the client Kerberosticket.

SSL user certificate Assign a Validation Credentials for authentication.

XML file Create XML authentication file with the RBM Policy Editor.Store the file in a local directory, or stage it on an accessiblefile server.

5. Define a local user account on the appliance, if necessary, as a fallback userwhen using a remote authentication method.

6. Select the credential mapping method for evaluating access profiles.7. Save the changes to the running configuration.

Note: The change takes affect immediately. At this point, the new settings coulddisable access to the DataPower appliance for any user who does not havean active session (WebGUI, command line, Telnet, or serial port connection).In other words, the changes could disable future access through any of thefollowing methods:v Any user who attempts to access the appliance through the WebGUIv Any user who attempts to access the appliance through the command linev Any user who attempts to access the appliance through a Telnet sessionv Any user who attempts to access the appliance through the serial port

connection (WebGUI or command line)

Refer to “Restoring RBM access from the command line” on page 38 formore information.

8. Optionally save the changes to the startup configuration.

RBM using custom authentication1. Select Administration → Access → RBM Settings to display the RBM Settings

(Main) screen.2. Retain the default value for the Admin State toggle.3. Specify a descriptive object-specific summary in the Comment field.4. Use the Enforce RBM on CLI toggle to specify which access approaches the

RBM policy enforces.


on Applies the RBM policy to both WebGUI and command line access.

off (Default) Applies the RBM policy to WebGUI access only. The definedRBM policy but does not apply to command line access.

5. Use the Restrict Admin Login toggle to specify whether to allow or restrictaccess by the admin account.

on Restricts command line access by the admin account to serial portaccess only.

off (Default) Allows access by the admin account to all access methods.6. Define the user authentication method:

a. Click the Authentication tab.b. Select custom from the User Authentication Method list. The screen

refreshes.c. Specify the URL of the custom style sheet for user authentication in the

Custom URL field.d. Select whether to use local user accounts as fallback users from the Local

Login As Fallback list. With fallback users, locally-defined users can log into the appliance if the authentication method fails or in the event of anetwork outage that affects the primary login authentication (for example,the remote authentication server is down).

disabledIndicates that no local user can log in.

all usersIndicates that all local users can log in.

specific users(Default) Indicates that only specified local users can log in.

Note: Local users must be members of local user groups. Each local usermust also be defined in the remote authentication server. Thepassword for each local user must match the credentials for a userof the exact same name on the remote server.

e. When the Local Login As Fallback property is specific users, add specificlocally-defined, fallback users:1) Select a local user from the Fallback User list.2) Click Add.Repeat the previous process for each fallback user.

f. Select the desired caching mode from the Authentication Cache Mode list.

AbsoluteCaches authentication results for a period of time in theAuthentication Cache Lifetime field.

DisabledCaching is disabled. The DataPower appliance authenticates eachaccess request but does not cache results.

Maximum(Default) Compares the explicit TTL to the TTL in the response, ifany, and caches authentication results for the maximum of the twovalues.


MinimumCompares the explicit TTL to the TTL in the response, if any, andcaches authentication results for the minimum of the two values.

g. Specify an explicit TTL, in seconds, for cached authentication results in theAuthentication Cache Lifetime field. The default is 600.

7. Define the mapping credentials method:a. Click the Credentials tab.b. From the Mapping Credentials Method list, select the method to evaluate

access profiles.v When custom, specify the URL of the custom style sheet in the

Mapping Custom URL field.v When xmlfile, specify the URL of the RBM policy file in the Mapping

RBM Policy URL field. Refer to Chapter 3, “Using the builder to createan RBM policy file,” on page 41 for details.

Note: Although available, local usergroup is not a valid selection.c. When the Mapping Credentials Method is local usergroup or xmlfile, use

the Search LDAP for Group Name toggle to control whether to performan LDAP search to retrieve the user’s group.

Note: When the credential mapping method is custom, the WebGUI doesnot display this toggle.

on Enables an LDAP search for the user’s group. The authenticatedDN of the user along with the LDAP Search Parameters will beused as part of an LDAP search to retrieve the user’s group.

off (Default) Disables an LDAP search for the user’s group. Theauthenticated identity of the user (DN or user group of local user)will be used directly as the input credential.

When enabled, the screen refreshes with LDAP-specific fields:1) Specify the IP address or host name of the LDAP server in the

Credentials Server Host field.2) Specify the port number of the LDAP server in the Credentials Server

Port field.3) Select an SSL Proxy Profile to establish a secure connection to the

LDAP server from the LDAP SSL Proxy Profile list. Retain the defaultvalue to use a non-SSL connection. Refer to “Defining SSL Proxy Profileobjects” on page 177 for more information.

4) Optionally select a Load Balancer Group from the LDAP LoadBalancer Group list. If selected, LDAP queries will be load-balanced inaccordance with the group settings. This setting overrides the settingsfor the Credentials Server Host and Credentials Server Port fields.Refer to “Load Balancer Group” on page 168 for more information.

5) Specify the distinguished name (DN) for the LDAP bind operation inthe LDAP Bind DN field.

6) Specify the password for the specified DN in the LDAP BindPassword field.

7) Again, specify the password for the specified DN in the LDAP BindPassword field for confirmation.

8) Select the LDAP Search Parameters from the LDAP Search Parameterslist. The LDAP Search Parameters object serves as a container for theparameters that are used to perform an LDAP search operation to


retrieve the group name (DN or attribute value) based on thedistinguished name of the authenticated user.

8. If you defined local fallback users, optionally define the password policy.Refer to “Defining the password policy” on page 35 for more information.

9. Click Apply to save the changes to the running configuration.10. Optionally, click Save Config to save the object to the startup configuration.

RBM using LDAP authenticationLDAP-based implementations require an X.500 DN (for example,cn=Alice,dc=datapower,dc=com) and a password. When configuring LDAP forauthentication, it is typical to create a base DN (such as dc=datapower,dc=com) andthen create one entry under this base for each user.

To make LDAP authentication more usable, RBM provides the LDAP suffix. Set theLDAP suffix to the base name under which user entries are found. Unless theLDAP suffix is an empty string, an X.500-compliant DN is built as follows:v Prepending cn= to the user namev Appending a comma followed by the value of the LDAP suffix

For example, if the LDAP suffix is dc=datapower,dc=com and the user name isAlice, the DN is mapped as cn=Alice,dc=datapower,dc=com.1. Select Administration → Access → RBM Settings to display the RBM Settings








a. Click the Authentication tab.b. Select LDAP from the User Authentication Method list. The screen

refreshes.1) Specify the host name or IP address of the LDAP server in the

Authentication Server Host field.2) Specify the port number on the server in the Authentication Server

Port field.3) Select the LDAP version from the LDAP Version list.4) Select an SSL Proxy Profile to establish a secure connection to the

LDAP server from the LDAP SSL Proxy Profile list. Retain the defaultvalue to use a non-SSL connection. Refer to“Defining SSL Proxy Profileobjects” on page 177 for more information.


5) Select a Load Balancer Group from the LDAP Load Balancer Grouplist. If selected, LDAP queries will be load-balanced in accordance withthe group settings.

6) Use the Search LDAP for DN toggle to control whether to perform anLDAP search to retrieve the user’s DN.

on Enables an LDAP search for the user’s DN. The login name ofthe user along with the LDAP Search Parameters will be usedas part of an LDAP search to retrieve the user’s DN.

off (Default) Disables an LDAP search for the user’s DN. The loginname of the user along with the LDAP prefix and the LDAPsuffix will be used to construct the user’s DN.

v If Search LDAP for DN set to on:a) Specify the distinguished name (DN) for the LDAP bind

operation in the LDAP Bind DN field.b) Specify the password for the specified DN in the LDAP Bind

Password field.c) Again, specify the password for the specified DN in the LDAP

Bind Password field for confirmation.d) Select the LDAP Search Parameters from the LDAP Search

Parameters list.The LDAP Search Parameters object serves as a container for theparameters that are used to perform an LDAP search operationto retrieve the user’s DN.

v If Search LDAP for DN set to off:a) Specify an LDAP prefix in the LDAP Prefix field.b) Specify an LDAP suffix in the LDAP Suffix field.

c. Select whether to use local user accounts as fallback users from the LocalLogin As Fallback list. With fallback users, locally-defined users can log into the appliance if the authentication method fails or in the event of anetwork outage that affects the primary login authentication (for example,the remote authentication server is down).





d. When the Local Login As Fallback property is specific users, add specificlocally-defined, fallback users:1) Select a local user from the Fallback User list.2) Click Add.Repeat the previous process for each fallback user.

e. Select the desired caching mode from the Authentication Cache Mode list.






f. Specify an explicit TTL, in seconds, for cached authentication results in theAuthentication Cache Lifetime field. The default is 600.














4) Optionally select a Load Balancer Group from the LDAP LoadBalancer Group list. If selected, LDAP queries will be load-balanced inaccordance with the group settings. This setting overrides the settings


for the Credentials Server Host and Credentials Server Port fields.Refer to “Load Balancer Group” on page 168 for more information.




8) Select the LDAP Search Parameters from the LDAP Search Parameterslist. The LDAP Search Parameters object serves as a container for theparameters that are used to perform an LDAP search operation toretrieve the group name (DN or attribute value) based on thedistinguished name of the authenticated user.



RBM using local user authentication1. Select Administration → Access → RBM Settings to display the RBM Settings








a. Click the Authentication tab.b. Select local user from the User Authentication Method list if it is not

already selected. The screen refreshes if you changed the authenticationmethod.

c. Select the desired caching mode from the Authentication Cache Mode list.






d. Specify an explicit TTL, in seconds, for cached authentication results in theAuthentication Cache Lifetime field. The default is 600.



Mapping Custom URL field.v When local usergroup, RBM uses the access profiles that are associated

with the user's group. Refer to “Creating a group account” on page 47for information.

v When xmlfile, specify the URL of the RBM policy file in the MappingRBM Policy URL field. Refer to Chapter 3, “Using the builder to createan RBM policy file,” on page 41 for details.

c. When the Mapping Credentials Method is local usergroup or xmlfile, usethe Search LDAP for Group Name toggle to control whether to performan LDAP search to retrieve the user’s group.














8. Optionally define the password policy. Refer to “Defining the passwordpolicy” on page 35 for more information.


RBM using RADIUS authentication1. Select Administration → Access → RBM Settings to display the RBM Settings








a. Click the Authentication tab.b. Select radius from the User Authentication Method list.c. Select whether to use local user accounts as fallback users from the Local






d. When the Local Login As Fallback property is specific users, add specificlocally-defined, fallback users:


1) Select a local user from the Fallback User list.2) Click Add.Repeat the previous process for each fallback user.

e. Select the desired caching mode from the Authentication Cache Mode list.





f. Specify an explicit TTL, in seconds, for cached authentication results in theAuthentication Cache Lifetime field. The default is 600.













LDAP server from the LDAP SSL Proxy Profile list. Retain the default


value to use a non-SSL connection. Refer to “Defining SSL Proxy Profileobjects” on page 177 for more information.








RBM using SAF authentication1. Select Administration → Access → RBM Settings to display the RBM Settings








a. Click the Authentication tab.b. Select saf from the User Authentication Method list. The screen refreshes.c. Select a z/OS NSS client from the z/OS NSS Client Configuration list.

Refer to “z/OS NSS Client” on page 181 for more details.d. Select whether to use local user accounts as fallback users from the Local
















RBM using SPNEGO authenticationThis method is available on all appliances except for XML Accelerator XA35.1. Select Administration → Access → RBM Settings to display the RBM Settings









a. Click the Authentication tab.b. Select spnego from the User Authentication Method list. The screen

refreshes.c. Select a Kerberos keytab file from the Kerberos Keytab list.d. Select whether to use local user accounts as fallback users from the Local













7. Define the mapping credentials method:a. Click the Credentials tab.


b. From the Mapping Credentials Method list, select the method to evaluateaccess profiles.v When custom, specify the URL of the custom style sheet in the




















RBM using SSL user certificate1. Select Administration → Access → RBM Settings to display the RBM Settings

(Main) screen.2. Retain the default value for the Admin State toggle.3. Specify a descriptive object-specific summary in the Comment field.4. Retain the default value (off) for the Enforce RBM on CLI toggle.

Note: If you enable this option, only local fallback users will be able to accessthe appliance from the command line.




a. Click the Authentication tab.b. Select user cert from the User Authentication Method list. The screen

refreshes.c. Select a Crypto Validation Credentials from the User Validation

Credentials list. Refer to Chapter 3, “Using the builder to create an RBMpolicy file,” on page 41 for more details.

d. Select whether to use local user accounts as fallback users from the LocalLogin As Fallback list. With fallback users, locally-defined users can log into the appliance if the authentication method fails or in the event of anetwork outage that affects the primary login authentication (for example,the remote authentication server is down).














RBM using XML file authentication1. Select Administration → Access → RBM Settings to display the RBM Settings








a. Click the Authentication tab.b. Select xmlfile from the User Authentication Method list. The screen

refreshes.c. Specify the URL of the RBM policy file in the Authentication RBM Policy

URL field. Refer to Chapter 3, “Using the builder to create an RBM policyfile,” on page 41 for more information.

d. Select whether to use local user accounts as fallback users from the LocalLogin As Fallback list. With fallback users, locally-defined users can log into the appliance if the authentication method fails or in the event of anetwork outage that affects the primary login authentication (for example,the remote authentication server is down).















Mapping Custom URL field.v When local usergroup, RBM uses the access profiles that are associated

with the user's group. Refer to “Creating a group account” on page 47for information.

v When xmlfile, specify the URL of the RBM policy file in the MappingRBM Policy URL field. Refer to Chapter 3, “Using the builder to createan RBM policy file,” on page 41 for details.

c. When the Mapping Credentials Method is local usergroup or xmlfile, usethe Search LDAP for Group Name toggle to control whether to performan LDAP search to retrieve the user’s group.














8. If you defined local fallback users, optionally define the password policy.Refer to “Defining the password policy” for more information.


Defining the password policyThe password policy applies to locally-defined user accounts only and is universalto the DataPower appliance. This policy does not apply to any other methods ofuser authentication.

Note: Invoking the reset command from the command line while in RBM Settingsconfiguration mode restores not only all RBM default settings but alsorestores all of the default setting for the password policy.

1. Select Administration → Access → RBM Settings to display the RBM Settings(Main) screen.

2. Click the Password Policy tab.3. Select the desired options.

Minimum LengthSpecify an integer that limits the minimum number of characters in apassword.

Require Mixed CaseClick on to require mixed case passwords. Mixed case refers to the use ofuppercase and lowercase alphabetic characters.

Require Non AlphanumericClick on to require passwords to contain non alphanumeric characters.


Require DigitClick on to require passwords to contain at least one numeric character.

Disallow Username as SubstringClick on to disallow the inclusion of the user name string in thepassword. For example, if the user is george, the password george1! orpassgeorgeword would not be allowed.

Enable AgingClick on to enable password aging. When enabled, the WebGUI displaysthe Maximum Password Age field.

Maximum Password AgeSpecify the maximum age of the password in days. Use an integer in therange of 1 through 65535. The default is 30.

Disallow Password ReuseClick on to disallow the reuse of previous passwords. When enabled, theWebGUI displays the Reuse History Size field.

Reuse History SizeSpecify the number of past passwords to compare against for reuse. Usean integer in the range of 1 through 65535. The default is 5.


Defining an LDAP Search Parameters objectThe LDAP Search Parameters object serves as a container for the parameters thatare used to perform an LDAP search operation.

AuthenticationThe parameters for an LDAP search to retrieve the DN of the user.

Credentials mappingThe parameters for an LDAP search to retrieve the group name (DN orattribute) based on the DN of the authenticated user.

You need to add a prefix and optionally add a suffix to create the LDAP filter. Theprefix and suffix are constructs of the LDAP filter expression, as defined in LDAP:String Representations of Search Filters. This filter is used to perform the LDAPsearch and return matching entries.

To create an LDAP Search Parameters object, use the following procedure:1. Select Objects → Access Settings → LDAP Search Parameters to display the

catalog.2. Click Add to display the configuration screen.3. Specify the name of the object in the Name field.4. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.5. Specify a descriptive object-specific summary in the Comment field.6. Specify the base DN to begin the search in the LDAP Base DN field. This

value identifies the entry level of the tree used by the LDAP Scope property.7. Specify the name of the attribute to return for each entry that matches the

search criteria in the LDAP Returned Attribute field. The default is the dnattribute.


8. Specify the prefix of the LDAP filter expression in the LDAP Filter Prefixfield.If the prefix is mail= and the user name is [email protected], the LDAP searchfilter would be [email protected].

9. Optionally specify the suffix of the LDAP filter expression in the LDAP FilterSuffix field.If the prefix is mail=, the suffix is )(c=US)), and the user name [email protected], the LDAP search filter would be(&([email protected])(c=US)).

10. Select the depth of the search from the LDAP Scope list:

Base Searches the entry level of the tree only.

One levelSearches the entry level of the tree and any object that is one-levelbelow the input.

Subtree(Default) Search the entry level of the tree and all of its descendents.

11. Click Apply to save the object to the running configuration.12. Optionally, click Save Config to save the object to the startup configuration.

Managing RBM access

Defining the account policyThe account policy applies to locally-defined user accounts only and is universal tothe DataPower appliance. This policy does not apply to any other methods of userauthentication.

The account policy tab defines the following limitations:v The maximum number of consecutive failed login attempts allowed before the

account is locked out.v The duration for which an account is locked out after reaching the maximum

number of failed login attempts. The admin account cannot be permanentlylocked out.

v The time after which an idle command line session requires re-authentication.

To define limitations of the account policy, use the following procedure:1. To display the RBM Settings (Main) screen, select Administration → Access →

RBM Settings .2. Click the Account Policy tab.3. In the Maximum Failed Login field, enter the maximum number of consecutive

failed login attempts allowed before the account is locked out. Use an integerin the range 0 to 64. To disable the lockout duration altogether, retain thedefault value of 0.

4. In the Lockout Duration field, enter the duration in minutes during which anaccount is locked out after the failed login threshold has been reached. Use aninteger in the range 0 to 1000 minutes. The default is 1 minute.

Note: The Lockout Duration property applies to any user account that hasexceeded its login failure threshold, except the admin account. You canpermanently disable any user account that has exceeded their login


failure threshold by omitting a lockout duration value. Reset a useraccount that has been previously locked out by entering a value in theLockout Duration field.

5. In the CLI Timeout field, enter the number of seconds after which an idlecommand line session will time out and require re-authentication. Use aninteger in the range 0 to 65535 seconds. To disable the idle timer altogether,retain the default value of 0 seconds. Do not confuse this value with the Idletimeout command that refers to the Web Management Service session timeout.


Restoring RBM access from the command lineNotes:

1. If the Restrict Admin Login toggle is set to on, a user who is equivalent to theadmin account must access the appliance from the serial port.

2. Do not use the reset command while in RBM Settings configuration mode.Using the reset command will restore default settings for both the RBM policyand default password policy.

In the event that a change to the RBM Settings disables access to the DataPowerappliance, use the following procedure to restore access:1. Log in to the DataPower appliance with Telnet, SSH, or serial access.2. Log in as the admin account or other account with similar permissions.3. Enter the following command at the prompt to enter Global configuration

mode:configure terminal

The word config appears in the prompt.4. Enter the following command to enter RBM Settings configuration mode:

rbm

The letters rbm are added to the prompt.5. Enter the following command to display the current RBM settings.

show

6. Enter the following command to set the User Authentication method to itsdefault setting:au-method local

7. Enter the following command to set the Policy Access Mapping method to itsdefault setting:mc-method local

8. Enter the following command to verify your changes:show

9. Enter the following command to return to Global configuration mode:exit

10. Enter the following command to clear the RBM cache:clear rbm cache


Extending RBM access to the WebGUI onlyYou can use the Enforce on CLI toggle to apply RBM settings to the WebGUI onlyor to both the WebGUI and the command line. When applied to the WebGUI only,the RBM settings are not enforced for users who access the appliance from thecommand line.

When the Enforce on CLI toggle is set to off, RBM settings are not extended tocommand line access. Users who meet the following criteria can access thecommand line:v Users who have membership to a group and the configuration for that group

has, at a minimum, access to the configuration command group.To assign a command group to a user group, use the CLI Command Groups tabof the User Group configuration screen. For information, refer to “Creatingapplication domains” on page 128.

v Users who have membership to the legacy, privileged account type.By default, these users are not members of any group and have access to thedefault domain only. After the assignment of a privileged user to an applicationdomain, that user can no longer access the default domain but can access onlyassigned domains. For information, refer to Chapter 6, “Managing useraccounts,” on page 55.

Enabling the RBM admin-state from the command lineTo change the RBM administration state from the command, use the followingprocedure:1. Log in to the DataPower appliance with Telnet, SSH, or serial access.2. Log in as the admin account or other account with similar permissions.3. Enter the following command at the prompt to enter Global configuration

mode:configure terminal

The word config appears in the prompt.4. Enter the following command to enter RBM Settings configuration mode:

rbm

The letters rbm are added to the prompt.5. Enter the following command to enable RBM Settings:

admin-state enabled

6. Enter the following command to verify your changes:show

7. Enter the following command to returns to Global configuration mode:exit

8. Enter the following command to clear the RBM cache:clear rbm cache

The RBM Settings are enabled.

Publishing an RBM XML file to another applianceAfter creating or modifying an RBM XML file, you can publish this file to anotherDataPower appliance. You must have an identical user account with sufficientprivileges on the remote appliance.

To publish an RBM XML file, use the following procedure:


1. Click Publish File.2. Click Add to display the Configure remote appliance screen.3. In the Remote IP Address field, specify the IP address of the remote appliance.4. In the XML-Mgmt Port field, specify the port number of the XML Management

Interface on the remote appliance.5. Click Submit.6. Click Commit.7. Click Done to publish the file.

A confirmation window is displayed.

Flushing the RBM cacheFlushing the RBM cache removes all cached user names and passwords frommemory. To flush the RBM cache, perform the following procedure:1. Select Administration → Access → RBM Settings to display the RBM Settings

(Main) screen.2. Click Flush RBM cache.


Chapter 3. Using the builder to create an RBM policy file

The RBM Policy file defines credentials that associate authenticated users withAccess policies. Access policies establish access permissions for particularresources. For examples of these policies, refer to “Format of access policy” onpage 48.

Continuing from the RBM using XML file authentication section, when selectingXML as the User Authentication Method of authenticate users, or when selectingXML as the Mapping Credential Method of authorizing resources, the RBM PolicyFile builder utility guides you while configuring the XML-base RBM file.

The sample RBMInfo.xml file is in the store: directory. This RBM policy file mustconform to the AAAInfo.xsd schema in the store: directory.

Using the RBM XML fileYou can use the RBM XML file for the following actions:

Authentication and authorizationUsers are authenticated on the appliance through the global RBM policy byloading an XML file, either the RBMInfo.xml file or another XML file, intothe Authentication RBM Policy URL field. Users who are authenticated byremote servers are authenticated in the same way.

Users are authorized on the appliance through the global RBM policy byloading an XML file, either the RBMInfo.xml file or another XML file, intothe Mapping RBM Policy URL field.

Authentication defines access for users. Authorization defines availableresources that a user can access. RBM manages the credential mappingbetween users who have access and resources.

Authentication onlyUsers are authenticated on the appliance through the global RBM policy byloading an XML file, either the RBMInfo.xml file or another XML file, intothe Authentication RBM Policy URL field.

Users who are authenticated by remote servers are authenticated in thesame way. Authentication defines access for users.

Authorization onlyUsers are authorized on the appliance through the global RBM policy byloading an XML file, either the RBMInfo.xml file or another XML file, intothe Mapping RBM Policy URL field.

Authorization defines available resources that a user can access.

RBM XML file for authentication and authorizationThe RBMInfo.xml file includes an Authenticate section and a MapCredentialssection. The Authenticate section includes username, password andOutputCredential elements for each user listed in the file. The MapCredentialssection includes an InputCredential element. When the value of theOutputCredential from the Authenticate section of the file matches the value of theInputCredential from the MapCredential section of the file, users are both


authenticated and authorized under RBM. Through the name of an existing usergroup on the appliance, an associated user group defines the access policy used forauthenticating users.

Follow this procedure to provide credentials and access for authenticated usersfrom the Administration → Access → RBM Settings screen:1. Accept the (default) Enabled Admin State radio button.2. Specify a descriptive object-specific summary in the Comment field.3. Select xmlfile from the User Authentication Method list. The screen refreshes

with XML-specific fields.4. Click the + button in the Authentication RBM Policy URL area to launch the

RBM Policy File builder.

Note: To edit an existing file, select a file from the Authentication RBM PolicyURL list, and click the ... button.

5. From the Name of existing file (optional) lists, select the store: directory, andthen select RBMInfo.xml.

Note: If there is no file displayed in the list:v Click Upload to upload a file on the appliance in the store: directory.v Click Fetch to copy a file on the appliance in the store: directory.

6. Click Next to set the Default Credential.Any user that fails authentication will be granted this credential. Leave thisfield blank to deny access to all users who fail authentication.

7. Click Next to display the User Identities catalog. If this is a new file, no usersare listed.

Note: If the file exists, click ... to edit the existing policy.8. Click Add to display the Add a new User Identity Property window.

a. Specify a user name in the Username field.b. Specify a password in the Password field and the next field to confirm the

password.c. Specify the name of the credential to assign to this user in the Credential

Name field. The value in the Credential Name field is stored in theAuthenticate section of the RBMInfo.xml file as the value of theOutputCredential for this user.

9. Click Submit to add the user to the catalog. The initial catalog appears, listingthe new user. To add more users, click Add and repeat the previous step.

10. Click Next to display the Access Profile Mappings catalog. If this is a new file,no access policy maps are listed.

11. Click Add to display the Add a New Access Profile Property window.a. Specify the name for the credential in the Credential Name field. The

name can contain wildcards and regular expressions. It is matched to thecredential that is presented by the User Authentication method.

b. Create one or more Access Policies for this credential. For details, refer to“Format of access policy” on page 48.

c. Create the access policy.d. Click Submit.

12. The Access Profile Mappings screen refreshes. Click Next.


13. The Edit RBM Policy File screen refreshes. This screen allows you to renamethe RBM Policy file and add a description.

14. Specify the name of the new file and a brief summary in the fields provided.15. Click Next to display the confirmation window.16. Click Commit to create the file. A confirmation success window appears.17. Click Done to complete the process.

The RBM Settings configuration (Main) screen refreshes with the URL of the newpolicy file in place.

Continue to configure the RBM policy by:v Defining a Local Login Fallback user on the appliance.v Specifying whether to enforce this RBM policy to both the WebGUI and the

command line or exclude command line access.v Specifying whether to allow or restrict access by the

admin account.

For information, refer to the “RBM using XML file authentication” on page 33.

To publish this file to another DataPower appliance, refer to “Publishing an RBMXML file to another appliance” on page 39 for details.

RBM XML file for authenticationThe RBMInfo.xml file includes an Authenticate section that includes username,password and an OutputCredential element for each user listed in the file.

When the OutputCredential element matches the name of an existing user groupon the appliance, the user group defines the access policy uses for authenticatingusers.

Follow this procedure to provide credentials and access for authenticated usersfrom the Administration → Access → RBM Settings screen:1. Accept the (default) Enabled Admin State radio button.2. Specify a descriptive object-specific summary in the Comment field.3. Select xmlfile from the User Authentication Method list. The screen refreshes

with XML-specific fields.4. Click the + button in the Authentication RBM Policy URL area to launch the

RBM Policy File builder.

Note: To edit an existing file, select a file from the Authentication RBM PolicyURL list, and click the ... button.

5. From the Name of existing file (optional) lists select the store: directory, andthen select RBMInfo.xml.


6. Click Next to set the Default Credential.Any user that fails authentication will be granted this credential. Leave thisfield blank to deny access to all users who fail authentication.

Chapter 3. Using the builder to create an RBM policy file 43

7. Click Next to display the User Identities catalog. If this is a new file, no usersare listed.

Note: If the file exists, click ... to edit the existing policy.8. Click Add to display the Add a new User Identity Property window.

a. Specify a user name in the Username field.b. Specify a password in the Password field and the next field to confirm the

password.c. Specify the name of the credential to assign to this user in the Credential

Name field. The value in the Credential Name field is stored in theAuthenticate section of the RBMInfo.xml file as the value of theOutputCredential for this user.

9. Click Submit to add the user to the catalog. The initial catalog appears, listingthe new user. To add more users, click Add and repeat the previous step.

10. Click Next.11. Skip the Access Profile Mappings screen. Click Next.12. The Edit RBM Policy File screen refreshes. This screen allows you to rename

the RBM Policy file and add a description.13. Specify the name of the new file and a brief summary in the fields provided.14. Click Next to display the confirmation window.15. Click Commit to create the file. A confirmation success window appears.16. Click Done to complete the process.


Continue to configure the RBM policy by:v Defining a Local Login Fallback user on the appliance.v Specifying whether to enforce this RBM policy to both the WebGUI and the

command line or exclude command line access.v Specifying whether to allow or restrict access by the

admin account.

For information, refer to the “RBM using XML file authentication” on page 33.


RBM XML file for authorizationThe RBMInfo.xml file includes a MapCredentials section that includes anInputCredential and OutputCredential element.

When the name of a credential generated by a remote server for an authenticateduser (representing the OutputCredential listed in the RBMInfo.xml file) matchesthe InputCredential listed in the RBMInfo.xml file, access to resources isauthorized for this user.

Follow this procedure to provide credentials and access for authenticated usersfrom the Administration → Access → RBM Settings screen:1. Accept the (Default) Enabled Admin State radio button.2. Specify a descriptive object-specific summary in the Comment field.


3. Select xmlfile from the Mapping Credentials Method list. The screen refresheswith XML-specific fields.

4. Click the + button in the Mapping RBM Policy URL area to launch the RBMPolicy File builder.

Note: To edit an existing file, select a file from the Mapping RBM Policy URLlist, and click the ... button.

5. Optionally from the Name of existing file lists select the store: directory, andthen select RBMInfo.xml.


6. Click Next on the Default Credentials screen.7. Click Next on the User Identities screen.8. Click Next to display the Access Profile Mappings catalog. If this is a new file,

no access policy maps are listed.9. Click Add to display the Add a New Access Profile Property window.

a. Specify the name for the credential in the Credential Name field. Thename can contain wildcards and regular expressions. It is matched to thecredential that is presented by the User Authentication method.

b. Create one or more Access Policies for this credential. For details, refer to“Format of access policy” on page 48.

c. Click Add to display each added access profile to the access policyd. Click Submit.

10. The Access Profile Mappings screen refreshes. Click Next.11. The Edit RBM Policy File screen refreshes. This screen allows you to rename

the RBM Policy file and add a description.12. Specify the name of the new file and a brief summary in the fields provided.13. Click Next to display the confirmation window.14. Click Commit to create the file. A confirmation success window appears.15. Click Done to complete the process.


Continue to configure the RBM policy by:v Defining a Local Login Fallback user on the appliancev Specifying whether to enforce this RBM policy to both the WebGUI and the

command line or exclude command line accessv Specifying whether to allow or restrict access by the admin account

refer to the “RBM using XML file authentication” on page 33.


Chapter 3. Using the builder to create an RBM policy file 45

Chapter 4. Managing user group accounts

Note: Previous releases of the DataPower appliance allowed for the creation ofuser groups. In previous releases, users were assigned the rights to use onlycommand groups. These rights did not extend to DataPower resources.These groups and rights are preserved in this release.

A user group represents a collection of users who perform similar duties andrequire the same level of access to the DataPower appliance. User groups areassigned rights to one or more DataPower resources. When adding these rights tothe access profile of the specific user group, each right is known individually as anaccess policy. A collection of access policies is known as an access profile.

The types of user group accounts on the appliance include:v User-defined groups. These types of accounts are not resident on a new

appliance. You create user-defined groups on the appliance, and define accesspolicies on each group for access to resources from the WebGUI and commandline. When created, user-defined groups are controlled by Role-basedManagement (RBM).

v System-defined group. These types of accounts are resident on a new appliance.Role-based Management (RBM) automatically assigns appropriate rights to eachappliance-defined group.

The appliance provides a variety of user group accounts, but these are not visibleuntil you have defined at least one user on the appliance. The following types ofuser group accounts are available:v User group accounts that are not domain-limited. These groups always belong to

the default domain, and the appliance automatically assigns access rights toeach group. These user groups include:– A system administrator group that is named sysadmin.– A network administrator group that is named netadmin.– An access management group that is named access.– An account management group that is named account.

v User group accounts that are domain-limited. Although these groups arenormally limited to an application domain, these groups can be part of thedefault domain if they are re-configured. The appliance automatically assignsaccess rights to each group, except the user-defined group. These user groupsinclude:– A developer group that is named developer.– A backup user group that is named backup.– A guest group that is named guest and provided with read-only access.– A user-defined group that is named and whose access policy must be defined

at the time of creation.

Creating a group accountUse the following procedure to create a group:1. Select Administration → Access → Manager User Groups to display the User

Group catalog.2. Click Add.


3. Specify a name for the user group.4. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.5. Specify a descriptive object-specific summary in the Comment field.6. Click Build to establish an access profile for this group.7. Optionally define command groups for members of this group. Command

groups are sets of commands which users, through their associated groups, canaccess from the command line. Defining command groups is applicable onlywhen the Enforce RBM on CLI toggle is set to off on the RBM Settings (Main)configuration screen. Refer to “Controlling access to the command line” fordetails.


Format of access policyType the access policy directly into the available horizontal field and click Add toadd the statement to the configuration. The policy statement takes the followingform:address/domain/resource?Access=privileges&[field=value]

v The address (appliance address), domain (application domain), and resource fieldsmust be fully specified or specified with an asterisk (*). An asterisk matches allvalues.

v The privileges string is comprised of the individual permission symbols that areseparated by the plus sign (+) character. For example, the string a+d+x+r+wrepresents add, delete, execute, read, and write permissions.

v The field token must be one of the additional fields that can be added to thestring. The corresponding value can be a PCRE.

Example of access policiesThe following example access policies include the access profile and a descriptionof assigned rights:v */*/*?Access=r+w+a+d+x

All users who are members of this group have read, write, add, delete, andexecute rights to every area of the appliance.

v */*/access/change-password?Access=x

All users who are members of this group have execute rights to changepasswords on every domain of the appliance.

v */*/access/radius?Access=r

All users who are members of this group have read rights to Radius Settings onevery domain of the appliance.

Controlling access to the command lineThis section discusses adding and removing access to command groups by usergroup accounts. Command groups are defined on the CLI Command Groups tabof the User Groups configuration screen.v If the Enforce RBM on CLI toggle from the RBM Settings configuration screen is

set to off, the defined access profile applies to WebGUI access only. Commandline access is defined by Command Groups on the CLI Command Groups tabof the User Groups configuration screen.


v If the Enforce RBM on CLI toggle from the RBM Settings configuration screen isset to on, the defined access profile applies to both WebGUI access andcommand line access. Any command line access that is defined by CommandGroups on the CLI Command Groups tab of the User Groups configurationscreen is ignored.

Adding access to a command groupUse the following procedure to allow access to a command group for a user groupaccount:1. Click the CLI Command Groups tab to display the User Group (CLI Command

Groups) configuration screen.2. Select a resource group from the Command Group list, and click Add.

Note: Each resource group represents a command suite, not necessarily anindividual resource. For information on the members of each resourcegroup, click Info. Each command group added represents anotherresource group to make available to this group from the command line.

3. Repeat step 2 for each additional resource group to add.4. When you achieve the correct configuration, click the Main tab.5. Click Apply to save the object to the running configuration.6. Optionally, click Save Config to save the object to the startup configuration.

The WebGUI reports success and displays the User Group catalog. Members of thisuser group can now access this set of command groups from the command line.You can now use the New User Account utility to add users to this group.

Removing access to a command groupIf members of a group have access to at least one command group, you canremove this access. Use the following procedure to remove access to a commandgroup for a user group account:1. Click the CLI Command Groups tab to display the User Group (CLI Command

Groups) screen.2. Click the X icon that is aligned with the unwanted command group.3. Click Apply to save the object to the running configuration.4. Optionally, click Save Config to save the object to the startup configuration.

Members of this user group can no longer access this set of command groups fromthe command line.

Chapter 4. Managing user group accounts 49

Chapter 5. Using the Access Policy builder

Each access policy is a statement of access rights for all members of a specifiedgroup. RBM enforces these rights on groups throughout the appliance. A collectionof individual access policies is known as an access profile. Access profiles arereusable and easier to maintain on groups instead of on individual users.

While configuring a user group account from the Administration → Access →Manager User Groups screen , you can create an access policy by clicking Build todisplay the Access Policy Builder.

Elements of an access policyWhen building an access policy statement on the Editing Access Profile Propertyscreen, screen elements appear based on each value selected or added. The full listof elements used for building access policies includes the following terms anddefinitions:

Device AddressIdentifies the local management IP address of the appliance to which thepolicy is applied. Leave blank for all.

Application DomainIdentifies the application domain to which the policy is applied. Select(none) for all or if not applicable to resource type. Accepts regularexpressions.

Resource TypeIdentifies the type of the resource to which the policy is applied. Select(any) for all resource types.

Name MatchLimits the access policy to resources with the specified names. Use a PCREto select groups of resource instances.

Local Address MatchLimits the access policy to the specified local addresses. A PCRE expressioncan be used to select a range of addresses.

Local Port MatchLimits the access policy to the specified local ports. Use a PCRE expressionto select a range of ports.

Directory MatchLimits the access policy to the specified directories. Applies only to the fileresource type and the file management type. Use a PCRE to select sets ofdirectories.

Filename MatchLimits the access policy to the specified local files. Use a PCRE to select aset of files.

PermissionsDefines the access rights for the resources that match this policy. Optionsare Read, Write, Add, Delete, and Execute.


Adding an access policyContinuing from the “Creating a group account” on page 47, follow these steps tocreate an access policy:1. Click Build to display the Access Policy builder.2. Optionally specify an IP address in the Device Address field. If left blank, the

policy under construction will apply to all local addresses. To use a configuredlocal host alias instead of an IP address, click Select Alias, which presents a listof configured local host aliases. For information on Host Aliases, refer to“Working with local host aliases” on page 77.

3. Optionally select a DataPower Application domain from the ApplicationDomain list. Using the default value (none) causes the policy to apply to alldomains.

4. Select one Resource Type from the Resource Type list. The Resource Type listincludes group headings, which are not selectable. Instead, select an individualresource.

Note: Group headings, such as Login or XML Processing, do not refer to valid,individual resources. These are group headings only.

The screen refreshes after selecting a resource type. Depending on the resourcetype, additional fields might be displayed.These additional fields provide a way to restrict, or limit, access permissions.For example, the permissions might apply to only a resource with the specifiedname in the Name field. These fields are optional. When not defined, thesepermissions extend to all resources of the selected type.

Note: These fields are interpreted as PCRE wildcard expressions. A value offoo in the Name field, for example, matches resources with the names123foobar, afoo, foo123 as well as foo. To restrict the name to only onematch, start the entry with the carat (^) character and end it with thedollar sign ($) character, as in ^foo$. This example matches the name fooonly.

You can use wildcards in the additional fields. The expression (.*)substitutes for one or more characters. For example, the Name fieldcould be expressed as (.*)intra(.*), which would match hr-intranet,dev-intranet-releng, or ny-intrasystem. A range can be expressed as[x-y]; for example [0-3]. You can use any PCRE-compliant expression.Refer to http://www.pcre.org for more details.

5. Use the Permissions check boxes to establish access permissions.6. Click Save. The window closes. The configuration screen lists the newly built

statement in the input field.

Note: The appliance had previously added */*/*?Access=r which evaluates toRead access for the appliance, across all domains, on all resources.

7. Click Add to add the statement to the access policy under construction.8. Click Apply to save the object to the running configuration.9. Optionally, click Save Config to save the object to the startup configuration.


http://www.pcre.org

Example access profile that grants full accessOn the Editing Access Profile Property screen, the following elements define anaccess policy that grants full access to the appliance:v Leave the Device Address field blank.v Select none in the Application Domain field list.v Select (any) from the Resource Type list.v Leave the Local Address Match field blank.v Leave the Local Port Match field blank.v Leave the Directory Match field blank.v Leave the Filename Match field blank.v Check all the check boxes listed in the Permissions area.

The statement defined, */*/*?Access=a+w+r+d+x, evaluates to Add, Write, Read,Delete and Execute access to the appliance, across all domains, for managing allresources.

Note: On the User Group Configuration (Main) screen, remember to promote thisstatement onto the Access Profile for the user group by clicking Add

Example access policy that uses wildcardsOn the Editing Access Profile Property screen, the following elements define anaccess policy that uses wildcards:v Leave the Device Address field blank.v Select Basics in the Application Domain field list.v Select XML Proxy Service under the Services group heading from the Resource

Type list.v Type ^dev(.*)$ as the value in the Name Match field.v Leave the Local Address Match field blank.v Enter 200[04] in the Local Port Match field.v Check the Read and Write check boxes listed in the Permissions area.

The statement defined, */Basics/Services/xslproxy?Name=^dev(.*)$&LocalPort=200[0-4]&Access=r+w, evaluates to Read and Write access for theappliance, for the Basics domain, for managing the XSL Proxy resource in theServices category of resources.

Note: On the User Group Configuration (Main) screen, remember to promote thisstatement onto the Access Profile for the user group by clicking Add

Example access policy that grants user management permissionsOn the Editing Access Profile Property screen, the following elements define anaccess policy that grants permissions to a specific group for managing useraccounts:v Leave the Device Address field blank.v Select User Account under the Access group heading from the Resource Type

list.v Leave the Name Match field blank.v Check all the check boxes listed in the Permissions area.

Chapter 5. Using the Access Policy builder 53

The statement defined, */*/access/username?Access=r+w+a+d+x, evaluates to Read,Write, Add, Delete and Execute access to the appliance, across the default domain,for managing all user names in the Access category of resources.

Note: On the User Group Configuration (Main) screen, remember to promote thisstatement onto the Access Profile for the user group by clicking Add.

Editing an access profileFollow this procedure to edit an access profile statement on an access policy of auser group:1. Select the Administration → Access → Manager User Groups to display the

User Group Configuration (Main) screen.2. From the Access Profile list, select the access policy statement to be edited. The

statement is highlighted and appears in the Access Profile field (aligned withthe Add and Build buttons).

3. Click Build.4. From the Access Profile Property screen, modify values as necessary.5. Click Save.6. Click Add to add the revised statement to the Access Profile for this user

group.7. Click Apply to save the object to the running configuration.8. Optionally, click Save Config to save the object to the startup configuration.

Note: If there are duplicate access profiles in an access policy, the applianceremoves any duplicate access profiles after clicking the Add button.

Removing an access profileFollow this procedure to remove an access profile statement from an access policyof a user group:1. Select the Administration → Access → Manager User Groups to display the

User Group Configuration (Main) screen.2. From the Access Profile list, select the X aligned with an unwanted access

profile statement.3. Click Apply to save the object to the running configuration.4. Optionally, click Save Config to save the object to the startup configuration.


Chapter 6. Managing user accounts

User accounts identify local users. Each local user account is defined by a username and password. These credentials are used to login to the DataPowerappliance and apply the appropriate access profile to the user account. Each useraccount is defined by an access level property, and can be one of the followingtypes:

Group-definedThe group-defined account type establishes this user as a member of a usergroup.

PrivilegedThe privileged account type provides this user with access to the entireresource suite from the WebGUI and CLI on a domain-by-domain basis.Users with privileged access can configure and can monitor all applianceoperations until explicitly assigned to an application domain. Theprivileged user cannot delete the admin user. Legacy privileged users arepart of the default domain until assigned to an Application domain, atwhich time they are no longer associated with the default domain.

User The user account type provides this user with access to view configurationdetails to most, but not all, objects. Customers of previous releases whohave users that are not members of a group should migrate those users toa guest group. For information, refer to “Migrating a user to a new group”on page 56.

Creating a user accountThe online help provides details about using this wizard.

Only the admin user, while in the default domain or a member of the sysadmingroup with the correct access policy can manage user accounts.

Note: Although you can create local users with the Manage User Accountswizard, this method is not the best practice. The best practice is to createnew local users with the New User Account utility. This utility defines auser who is a member of a group.

To create a user account, select Administration → Access → New User Account. Thewizard prompts for the following information:1. Restrict this user to a domain (Yes or No).2. If Yes, select the domain to which to restrict this user.3. Domain Account Type. If user-defined Group selected in step 2 , name of

Group or create a new group. For information, refer to “Creating a groupaccount” on page 47.

4. Name of user account.5. Summary describing the user account (optional).6. Password and confirmed password for the user account.7. Click Commit.8. Optionally, click Save Config to save the object to the startup configuration.


To create more user accounts, click Start instead of Done at the end of the wizard.

Resetting the admin passwordTo edit a user account always use the Manage User Accounts utility. After loggingon to the default domain as the admin, use the following procedure to reset theadmin password:1. Select Administration → Access → Manage User Accounts to display the User

Account catalog.2. Click the target account to display an account-specific User Account

Configuration (Main) screen.3. Change the account password with the Password and Confirm Password

fields.4. Click Apply to save the changes.

Migrating a user to a new groupThe Domain Restriction controls provide a method of controlling user access tothe list of configured domains in the absence of an Access Policy. After domainrestrictions are set for a user, that user can login only into the specified domains. Ifno domain is specified, the user can login into any domain on the device. Thissetting is superseded by an existing Access Policy for the user.

To edit a user account always use the Manage User Accounts utility. Use thefollowing procedure to migrate a user to a new group:1. Select Administration → Access → Manage User Accounts to display the User


Configuration (Main) screen.3. Select the access level for this user from the Access Level value list.4. Select the name of an existing group that this user will be associated with from

the User Group value list.5. Select the name of an existing domain that this uses is restricted to from the

Domain Restriction value list, or click the + button to create a new domain.Refer to “Creating application domains” on page 128 for more information.

6. Click Apply to save the changes.

Forcing a password changeUse the following procedure to make users change their password on their nextlogin:1. Select Administration → Access → Manage User Accounts to display the User


Configuration (Main) screen.3. Click Force Password Change to mark the password as temporary and to force

the user to change the account password on the next login attempt.4. Respond to prompts.

For information on the Password Policy, refer to “Defining the password policy”on page 35.


Changing the password for the current user

Note: If you are currently logged in as admin, this procedure changes the adminpassword for both the CLI and WebGUI interfaces.

Use the following procedure when a user wishes to change his or her password:1. Select Administration → Main → System Control to display the System Control

panel.2. Locate the Change User Password section.

a. In the Old Password field, specify the password for the current user.b. In the New Password field, specify the new password.c. In the Confirm Password field, specify the new password again.d. Click Change User Password.

For information on the Password Policy, refer to “Defining the password policy”on page 35.

Configuring SNMP V3 usersThis type of user account creates an account and adds SNMP V3 credentials. Eachaccount can have multiple SNMP V3 credentials, one for each SNMP V3 enginethat is identified by an engine ID value. The secret for authentication and forprivacy can be defined either as a password (passphrase), which will be hashedand localized with the engine ID or can be defined as a localized hexadecimal key.

Note: The current implementation supports an SNMP V3 credential for the localengine ID only. Therefore, there can be only one SNMP V3 credential foreach account.

To view the local SNMP engine ID, select Status → Other Network → SNMP Status.

Subject to authentication by the local SNMP engine, this account is granted accessto any Management Information Base (MIB) on the local appliance. Generally, MIBaccess is granted for monitoring or for configuration purposes. Refer to“Configuring SNMP Settings” on page 92 for details.

Use the following procedure to create an SNMP V3 account:1. Select Administration → Access → Manage User Accounts to display the

catalog.2. Click Add to display the User Account configuration (Main) screen.3. Provide the following information:

a. In the Name field, specify the name of the SNMP V3 account.b. Retain the default setting for the Admin State toggle. To place the object in

an inactive administrative state, click disabled.c. Specify a descriptive object-specific summary in the Comment field.d. Ignore all other fields.

4. Click the SNMP V3 User Credentials tab to display the SNMP V3 UserCredentials catalog.

5. Click Add to display the SNMP V3 Users Credentials Property window.

Chapter 6. Managing user accounts 57

6. In the Engine ID field, specify the engine ID that provides a unique identifierfor the SNMP engine to authorize this user. In most cases, retain the defaultvalue (0), which specifies the local engine ID.

7. Define SNMP authentication.a. From the Authentication Protocol list, select the authentication protocol

that provides data integrity and data origin authentication for SNMPexchanges between this user and the local SNMP engine.

SHA (Default) The account uses HMAC-SHA-96 as the authenticationprotocol.

MD5 The account uses HMAC-MD5-96 as the authentication protocol.

None The account has no authentication key.b. Use the Authentication Secret Type list, select whether the secret is a

password or a fully localized key. This property is required when theauthentication protocol is MD5 or SHA.

Note: Although the User Security Model (USM) supports the directspecification of a key, retain the default value.

Password(Default) The secret is a password that will be converted to anintermediate key with a standardized algorithm, and then localizedagainst the engine ID value.

Key The secret is a fully localized key. Specifying a fully localized keyis useful when the key was initially created on another appliance.

c. Use the Authentication Secret field to specify the secret. This property isrequired when the authentication protocol is MD5 or SHA.v If password, specify a plaintext password that is at least eight characters

long.v If key and MD5 is the authentication protocol, specify the hexadecimal

representation of a 16-byte key.v If key and SHA is the authentication protocol, specify the hexadecimal

representation of a 20-byte key.You can use colons (:) between each two hexadecimal characters.

d. Use the Confirm Authentication Secret field to confirm the value of theauthentication secret.

8. Define the SNMP privacy (encryption).a. From the Privacy Protocol list, select the symmetric privacy protocol that

provides data encryption and decryption for SNMP exchanges betweenthis user and the local SNMP engine.

DES (Default) The account uses CBC-DES as the privacy protocol.

AES The account uses AES as the privacy protocol.

None The account has not privacy key.b. Use the Privacy Secret Type list, select whether the secret is a password or

a fully localized key. This property is required when the privacy protocolis AES or DES.

Note: Although the User Security Model (USM) supports the directspecification of a key, retain the default value.


Password(Default) The secret is a password that will be converted to anintermediate key with a standardized algorithm, and then localizedagainst the engine ID value.

Key The secret is a fully localized key. Specifying a fully localized keyis useful when the key was initially created on another appliance.

c. Use the Privacy Secret field to specify the secret. This property is requiredwhen the privacy protocol is AES or DES.v If password, specify a plaintext password that is at least eight characters

long.v If key and MD5 is the authentication protocol, specify the hexadecimal

representation of a 16-byte key.v If key and SHA is the authentication protocol, specify the hexadecimal

representation of a 20-byte key.You can use colons (:) between each two hexadecimal characters.

d. Use the Confirm Privacy Secret field to confirm the value of theauthentication secret.

9. Click Save to return to the SNMP V3 User Credentials catalog.10. Click Apply to save the object to the running configuration.11. Optionally, click Save Config to save the object to the startup configuration.

Repeat this procedure to create additional SNMP V3 accounts.

Chapter 6. Managing user accounts 59

Part 3. Managing the appliance

Chapter 7. Securing communication . . . . . 63Supported cryptographic formats . . . . . . . 63Working with keys and certificates . . . . . . 63

Creating key-certificate pairs . . . . . . . 63Generating keys and certificates . . . . . . 64Exporting keys and certificates . . . . . . . 65Importing keys and certificates . . . . . . . 66

Working with certificate revocation lists . . . . . 67Enabling CRL retrieval . . . . . . . . . 67Configuring CRL update policies . . . . . . 67

Defining Certificate Monitor objects . . . . . . 68

Chapter 8. Managing the appliance itself. . . . 71Ethernet and VLAN interfaces . . . . . . . . 71

Failover configurations . . . . . . . . . 71Configuring Ethernet interfaces . . . . . . . 72Configuring VLAN interfaces . . . . . . . 72Defining static routes . . . . . . . . . . 73Defining standby controls . . . . . . . . 73Removing an Ethernet interface from the network 74Initiating a packet-capture session . . . . . . 74

Configuring appliance-wide network settings . . . 74DNS Settings . . . . . . . . . . . . . . 76

Configuring the DNS service . . . . . . . 76Flushing the DNS hosts cache . . . . . . . 76

Host Alias . . . . . . . . . . . . . . . 77Working with local host aliases . . . . . . . 77Migrating configuration data . . . . . . . 77

NTP Service . . . . . . . . . . . . . . 78Managing the time on the appliance . . . . . . 79

Setting the local time and date . . . . . . . 79Setting the local time zone . . . . . . . . 79Creating a custom time zone . . . . . . . 79

Selecting the reboot configuration . . . . . . . 80Configuring throttle settings . . . . . . . . . 81Shutting down the appliance . . . . . . . . 82Controlling the locate LED (Type 9235) . . . . . 82

Activating the locate LED . . . . . . . . 82Deactivating the locate LED . . . . . . . . 83

Generating an appliance certificate . . . . . . 83Configuring appliance settings . . . . . . . . 83Configuring NFS Settings. . . . . . . . . . 84

NFS Client Settings . . . . . . . . . . . 84NFS Dynamic Mounts . . . . . . . . . . 85

Passing parameters to files . . . . . . . 86NFS Static Mounts . . . . . . . . . . . 87

Using the iSCSI protocol (Type 9235) . . . . . . 89IQN and EUI formats . . . . . . . . . . 89Configuring and initializing an iSCSI volume . . 89

Configuring an iSCSI volume . . . . . . 90Initializing an iSCSI volume . . . . . . . 90

Repairing an iSCSI volume . . . . . . . . 90Reference objects for iSCSI . . . . . . . . 91

Configuring an iSCSI Target object. . . . . 91Configuring an iSCSI CHAP object . . . . 91Configuring an iSCSI Host Bus Adapter object 92

Configuring SNMP Settings . . . . . . . . . 92Configuring global properties . . . . . . . 93Viewing MIBs . . . . . . . . . . . . 94Configuring subscriptions . . . . . . . . 94Configuring communities. . . . . . . . . 94Configuring recipients . . . . . . . . . . 95Configuring contexts . . . . . . . . . . 96

Chapter 9. Managing network access to theappliance . . . . . . . . . . . . . . . 97SSH access . . . . . . . . . . . . . . 97Telnet access . . . . . . . . . . . . . . 97WebGUI access . . . . . . . . . . . . . 98XML Management Interface . . . . . . . . 100

Services overview . . . . . . . . . . . 100Enabling interface services . . . . . . . . 101Changing default security and HTTP settings 102

SOAP interface . . . . . . . . . . . . . 102General structure of requests . . . . . . . 103General structure of responses. . . . . . . 103Available operations for requests . . . . . . 103Example request to view status . . . . . . 106Example request to compare configurations . . 107

WSDM interface . . . . . . . . . . . . 108Example request to view the number of clientrequests . . . . . . . . . . . . . . 110Example request to view active users . . . . 110Example request to view CPU usage. . . . . 111Example request to view appliance usage . . . 111Example request to view accepted connections 111

Chapter 10. Managing the firmware image . . . 113Applying a firmware image . . . . . . . . 113Rolling back an upgrade. . . . . . . . . . 113

Chapter 11. Managing files . . . . . . . . 115Directories on the appliance . . . . . . . . 115Launching the File Management utility . . . . . 117Displaying directory contents . . . . . . . . 117Creating a subdirectory . . . . . . . . . . 117Deleting a directory . . . . . . . . . . . 118Refreshing directory contents . . . . . . . . 118Uploading files from the workstation . . . . . 118Working with Java Key Stores . . . . . . . . 119

Required software . . . . . . . . . . . 119Granting permissions . . . . . . . . . . 119Types of key stores . . . . . . . . . . 119Uploading a file from a Java Key Store . . . . 119

Fetching files . . . . . . . . . . . . . 120Copying files . . . . . . . . . . . . . 120Renaming files . . . . . . . . . . . . . 121Moving files . . . . . . . . . . . . . . 121Viewing files . . . . . . . . . . . . . 122Editing files . . . . . . . . . . . . . . 122Deleting files . . . . . . . . . . . . . 122


Chapter 12. Managing auxiliary data storage 123Configuring the compact flash. . . . . . . . 123Managing the file system on the compact flash . . 123


Configuring the hard disk array . . . . . . . 124Managing the file system on the hard disk array 124


Managing the RAID volume . . . . . . . . 125Activating the volume . . . . . . . . . 125Initializing the volume . . . . . . . . . 125Rebuilding the volume . . . . . . . . . 125Deleting the volume . . . . . . . . . . 126

Chapter 13. Managing the configuration of theappliance . . . . . . . . . . . . . . 127Managing domains . . . . . . . . . . . 127

The default domain . . . . . . . . . . 127Application domains . . . . . . . . . . 127Visible domains . . . . . . . . . . . 128Creating application domains . . . . . . . 128Restarting application domains . . . . . . 129Resetting application domains . . . . . . . 130

Creating Include Configuration File objects . . . 130Creating Import Configuration File objects . . . 131Backing up and exporting configuration data. . . 133

Backing up the entire appliance . . . . . . 133Backing up domains . . . . . . . . . . 134Exporting select objects . . . . . . . . . 135Copying or moving select objects . . . . . . 136

Managing configuration checkpoints . . . . . 138Defining number configuration checkpoints toallow . . . . . . . . . . . . . . . 138Saving configuration checkpoints . . . . . . 138Listing configuration checkpoints. . . . . . 139Rolling back to a configuration checkpoint . . 139Deleting configuration checkpoints . . . . . 139

Importing configuration data . . . . . . . . 140Managing changes in configuration data . . . . 141

Comparing configurations . . . . . . . . 142Reading the change report . . . . . . . . 143Reverting changes . . . . . . . . . . . 143

Chapter 14. Configuring deployment policies 145Creating a Deployment Policy object . . . . . 145Using the deployment policy builder . . . . . 146Specifying the matching statement . . . . . . 147

Chapter 15. Managing logs . . . . . . . . 149Types of log targets . . . . . . . . . . . 149Configuring log categories . . . . . . . . . 150Configuring log targets . . . . . . . . . . 150Setting event filters . . . . . . . . . . . 150Setting object filters . . . . . . . . . . . 151Setting IP address filters . . . . . . . . . . 152Setting event subscriptions . . . . . . . . . 152Viewing log files . . . . . . . . . . . . 153Configuring an email pager . . . . . . . . 153Using a Load Balancer Group as the remote host 154


Chapter 7. Securing communication

This chapter provide information about securing communication to and from theDataPower appliance. The appliance provide these capabilities with a combinationof utilities and objects.

Supported cryptographic formatsPrivate key objects support the following formats:v DERv PEMv PKCS #8v PKCS #12

Certificate objects support the following formats:v DERv PEMv PKCS #7v PKCS #12

Neither key objects nor certificate objects directly support JKS or KDB formats.

Working with keys and certificatesThe DataPower appliance provides actions that allow you to work with keys andcertificates. With the provided cryptographic tools, you can perform the followingactions:v Create key-certificate pairsv Generate keys and certificatesv Export keys and certificatesv Import keys and certificates

Unless you are using an appliance with HSM hardware, you cannot export orimport keys. For details about using an HSM-enabled appliance, refer to the IBMWebSphere DataPower SOA Appliances: Hardware Security Module Guide.

Creating key-certificate pairsWhen you generate a key, you get a key file and a Certificate Signing Request(CSR) file. The CSR file from the initial key generation is not a signed certificate.Send the CSR to a Certificate Authority (CA), such as VeriSign. The CA signs theCSR and returns it to you, which effectively creates the certificate. Load thiscertificate on the box.

In other words, use the following procedure to create the key-certificate pair:1. Use the Crypto Tool to create the key and CSR2. Store the private key on the box and create a Key object that references it.3. Send the CSR to VeriSign. Do not store it on the box (except in the temporary:

directory).


4. VeriSign returns the signed certificate.5. Store the signed certificate on the box and create a Certificate object that

references it.6. Optionally, create an Identification Credentials object that references the key

and certificate objects.When you create the Identification Credentials object, the key-certificate pair isvalidated to ensure that pair is ready for use.

Generating keys and certificatesYou can generate a private cryptographic key and optionally a self-signedcertificate from the Crypto Tools page. The Certificate Signing Request (CSR)needed by a certificate authority (CA) is created by default.

If the file is stored in the cert: directory, it cannot be deleted or edited. If a file isstored in the local: directory or in the temporary: directory, it can be deleted andedited.

To generate a key, use the following procedure:1. Select Administration → Miscellaneous → Crypto Tools to display the

Generate Key page.2. Define the LDAP entry.

a. Use the LDAP (reverse) Order of RDNs toggle to indicate whether tocreate the LDAP entry in reverse RDN order.

on Creates the entry in reverse RDN order.

off (Default) Create the entry in forward RDN order.b. Optionally specify a country name in the Country Name (C) field.c. Optionally specify a state or province name in the State or Province (ST)

field.d. Optionally specify a locality name in the Locality (L) field.e. Optionally specify the name of an organization in the Organization (O)

field.f. Optionally specify the name of an organizational unit in the Organizational

Unit (OU) field.g. Optionally specify the names of additional organizational units in the

Organizational Unit 2 (OU), Organizational Unit 3 (OU), andOrganizational Unit 4 (OU) fields.

h. Specify a common name in the Common Name (CN) field.3. Select a key length from the RSA Key Length list. This defaults to 1024.4. Specify the name of the key file to generate in the File Name field. The value

takes the directory:///name form. Leave blank to allow the action to createthe name.

5. Specify the number of days that the key is valid in the Validity Period field.6. Specify a password to access the key file in the Password field. The password

must be at least 6 characters in length.7. Specify a password alias to access the key file in the Password Alias field.8. Use the Export Private Key toggle to indicate whether the action writes the

key file to the temporary: directory.

on Writes the key file to the temporary: directory.

off (Default) Does not write the key file to the temporary: directory.


9. Use the Generate Self-Signed Certificate toggle to indicate whether the actioncreates a self-signed certificate that matches the key.

on (Default) Creates a self-signed certificate.

off Does not create a self-signed certificate.10. Use the Export Self-Signed Certificate toggle to indicate whether the action

writes the self-signed certificate to the temporary: directory.

on (Default) Writes the self-signed certificate to the temporary: directory.

off Does not write the self-signed certificate to the temporary: directory.11. Use the Generate Key and Certificate Objects toggle to indicate whether the

action automatically creates the objects from the generated files.

on (Default) Creates the objects from the generated files.

off Does not create the objects from the generated files.12. Specify the name for the Key and Certificate objects in the Object Name field.

Leave blank to allow the action to generate the names from from the inputinformation (based on the Common Name (CN) or File Name property).

13. Specify the name of an existing Key object in the Using Existing Key Objectfield. If supplied and valid, the action generates a new certificate and a newCertificate Signing Request (CSR) that is based on the key in the identifiedKey object. In this case, the appliance does not generate a new key.

14. Click Generate Key to generate a private key and, if requested, a self-signedcertificate. A CSR is created automatically.

15. Follow the prompts.

The CSR can be submitted to a certificate authority (CA) to receive a certificate thatis based on this private key. This action creates the following files and objects:v Creates the private key file in the cert: directory; for example,

cert:///sample-privkey.pem

v Creates the CSR in the temporary: directory; for example, temporary:///sample.csr

v If Generate Self-Signed Certificate is enabled, creates a self-signed certificate inthe cert: directory; for example, cert:///sample-sscert.pem

v If Export Self-Signed Certificate is enabled, creates a copy of the self-signedcertificate in the temporary: directory; for example, temporary:///sample-sscert.pem

v If Generate Key and Certificate Objects is enabled, creates a Key object and aCertificate object

If the action creates a self-signed certificate, you can use this certificate-key pair forthe following purposes:v Establish Identification Credentialsv Encrypt or decrypt XML documents

Exporting keys and certificatesUse the Export Crypto Objects tab of the Crypto Tools screen to export key andcertificate objects.

Note: If the appliance has HSM hardware, you can export Key objects. For details,refer to IBM WebSphere DataPower SOA Appliances: Hardware Security ModuleGuide.

Chapter 7. Securing communication 65

1. Select Administration → Miscellaneous → Crypto Tools to display the CryptoTools screen.

2. Click the Export Crypto Object tab.3. Provide the following information:

Object TypeSelect the type of object to export. Any appliance can export certificates.Devices with HSM hardware can export private keys.

Object NameType the exact name of the object. To view a list of all such objects,select Objects → Crypto Objects → Cryptographic Certificate (or Key).

Output File NameSpecify the name of a export package to contain the exported objects.Do not specify a local directory or file extension. The appliance writesthe file to the temporary: directory.

Encryption MechanismSelect Key-Wrapping-Key.

Note: Available when the appliance has HSM hardware to specify theencryption mechanism to export private keys.

4. Click Export Crypto Object to create the export package with the selectedobject.

Use the File Management utility to access the file.

Importing keys and certificatesUse the Import Crypto Objects tab of the Crypto Tools screen to import key andcertificate objects.

Objects that are exported from one DataPower appliance can be imported toanother appliance. Importing objects, rather than uploading files, eliminates theneed to create objects from files.

Note: If the appliance has HSM hardware, you can import Key objects. For details,refer to IBM WebSphere DataPower SOA Appliances: Hardware Security ModuleGuide.

1. Select Administration → Miscellaneous → Crypto Tools to display the CryptoTools screen.

2. Click the Import Crypto Object tab.3. Provide the following information:

Object TypeSelect the type of object to import. Any appliance can importcertificates. Devices with HSM hardware can import private keys.

Object NameSpecify the name of the object to create on import. This name must be aunique in the object namespace.

Input File NameUse the controls to select the export package. If the file does not resideon the DataPower appliance, click Upload or Fetch to transfer the file.


PasswordOptionally specify a password for accessing the file. Any entity oragent needing to access the file must supply this password.

Password AliasThe password can optionally be given an alias, providing a level ofindirection and thus additional security. If an alias is established, usethe alias instead of the actual password.

4. Click Import Crypto Object.

An object with the specified name is created. Otherwise, an error is returned.

Working with certificate revocation listsA certificate revocation list (CRL) update policy enables the periodic refresh ofCRLs. To use CRLs, enable the CRL Retrieval object and configure at least oneinstance of the CRL Policy object.

Note: The appliance supports CRLs that are in the DER format only.

Enabling CRL retrievalTo enable the CRL update policy, use the following procedure:1. Select Objects → Crypto → CRL Retrieval.2. Provide the following input:

Admin StateRetain the default setting. To place the object in an inactive administrativestate, click disabled.

Configuring CRL update policiesAfter enabling the CRL update policy, you need to configure the CRL updatepolicy. To configure the CRL update policy, use the following procedure:1. Click the CRL Policy tab.2. Click Add.3. Provide the following inputs:

Policy NameSpecify the name of the CRL Update Policy.

ProtocolSelect the protocol that supports access to a CRL server.

HTTP (Default) Uses HTTP to enable the CRL update policy.

LDAP Uses LDAP to enable the CRL update policy. When selected, thisprotocol requires additional inputs.

CRL Issuer Validation CredentialsSelect the validation credentials to apply to the CRL Issuer credentials.

Refresh IntervalSpecify the refresh interval (the interval, in minutes, between CRLupdates).

Cryptographic ProfileOptionally specify the name of the Profile object. This profile assigns aforward (client) proxy to the CRL Update Policy. The policy uses the clientcredentials that are referenced by the Profile object when establishing an


SSL connection with a CRL server. If not specified, the CRL Update Policyattempts to establish a nonsecure connection with the CRL server.

Fetch URLWhen enabled through HTTP, specify the location of the target CRL.

LDAP ServerWhen enabled through LDAP, specify the IP address or fully qualifieddomain name of the CRL server.

LDAP PortWhen enabled through LDAP, specify the remote LDAP port.

LDAP Read DNWhen enabled through LDAP, specify the distinguished name of theCertificate Authority (CA) that issued the target CRL.

LDAP Bind DNWhen enabled through LDAP, specify the account name used to log in tothe LDAP server.

LDAP Bind PasswordWhen enabled through LDAP, specify the password to use to log in to theLDAP server.

Confirm LDAP Bind PasswordWhen enabled through LDAP, again specify the password to use to log into the LDAP server.

4. Click Save.5. Click Apply to save the object to the running configuration.6. Optionally, click Save Config to save the object to the startup configuration.

Defining Certificate Monitor objectsThe Certificate Monitor is a configurable periodic task that checks the expirationdate of all certificate objects. User-specified values establish both a pollingfrequency and a notification window, during which the monitor generates logmessages recording that a specified certificate is nearing its expiration date. TheCertificate Monitor scans all certificates when first enabled.

To create a certificate monitor, use the following procedure:1. Select Objects → Crypto → Crypto Certificate Monitor.2. Provide the following inputs:


CommentsSpecify a descriptive object-specific summary.

Polling IntervalSpecify the frequency with which the Certificate Monitor examinescertificate object expiration dates. Specify an integer value in the range 1through 65535 that specifies the number of days between certificateexpiration scans. For example, the value 3 schedules an expiration scanevery 72 hours.

Reminder TimeSpecify the notification window, the number of days before certificate


expiration that triggers a log event. Specify an integer value in the range1 through 65535 that specifies the notification window. For example, thevalue 21 specifies that all scanned certificate objects due to expire in 3weeks or less generate a log entry.

Log LevelSelect the priority of log messages generated in response to an expiredcertificate, or to a certificate that is about to expire (as defined by theReminder Time property).

Disable Expired CertificatesSpecify the response to certificate expiration.

on Specifies that on certificate expiration, all objects that use theexpired certificate (either directly or through inheritance) aredisabled and are no longer in service. For example, certificateexpiration triggers the disablement of the associated Certificateobject. Disablement of the Certificate object triggers thedisablement of all Firewall Credential, Identification Credential,and Validation Credential that use the expired certificate. In turn,Profile objects that use disabled Identification Credential andValidation Credential are disabled, leading to the disablement ofSSL Proxy Profile objects that depend on the now-disabled Profileobjects. Ultimately, the DataPower service can be disabled as theresult of certificate expiration.

off (Default) Specifies that the certificate object and objects that usethe expired certificate are not disabled on certificate expiration.

3. Click Apply to save the object to the running configuration and return to theobject catalog.

4. Optionally, click Save Config to save the object to the startup configuration.


Chapter 8. Managing the appliance itself

This chapter contains information about managing the appliance itself and thenetwork in to which it is configured.

Ethernet and VLAN interfacesThe DataPower appliance provides four Ethernet interfaces. There is one dedicatedmanagement port, labelled MGMT, and three network ports.

A virtual LAN (VLAN) object generally provides a trunk between adjacentDataPower appliances. The VLAN object creates a virtual IP interface (VIP) on oneof the physical Ethernet interfaces on the appliance. VLAN packets are identifiedby the IEEE 802.1Q tagging protocol.

You can create multiple VLAN objects on a single Ethernet interface.

Note: All DataPower appliances except for B2B Appliance XB60 appliancessupport IPv6 addresses.

Failover configurationsYou can implement a failover configuration to ensure that an interface on oneDataPower appliance is available if an active interface on another DataPowerappliance becomes unavailable. An interface might become unavailable as a resultof an internal hardware failure, an intermittent network failure, or another failure.

By default, all interfaces in a group VIP seek to be active at the same priority. Theactive interface changes only if that interface goes down or is disconnected. Thepriority property allows favoring some appliances over others, with higher valuesbeing higher priority. The active interface changes only when the previous activeinterface goes down, unless preemption is enabled.

Only one interface, either Ethernet or VLAN, on a given physical Ethernet interfacecan have a failover configuration. Only one interface on a given appliance canhave a failover configuration with a particular group VIP.

The following failover configurations are available:

active-standbyA topology in which an active interface on one appliance backs up aninactive interface on another appliance. The inactive interface is operationalon the network, but it is inactive. The inactive interface only monitors theactive interface. If the standby interface detects that the active interface hasbecome unresponsive, it assume the IP address of the formerly activeinterface and enabled all its own network services. In this scenario, assuredfailure protection is provided at a cost of one idle standby interface foreach active one.

active-activeA topology in which an active interface on one appliance backs up anactive interface on another appliance.


Configuring Ethernet interfacesOn Type 9235 appliances, you cannot modify the Physical Mode property.

Use the following procedures to provision local interfaces:1. Select Network → Interface → Ethernet Interface to display the catalog.2. Click the name of the target interface to display the configuration screen.3. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.4. Define the network configuration of the interface.

a. Set the primary IP address.v For an IPv4 address, use the Use DHCP toggle to control whether to

obtain the address using Dynamic Host Configuration Protocol (DHCP).v For an IPv6 address, in the IP Address field, specify the IP address and

subnet mask in CIDR format.b. Set the default gateway.c. Define secondary IP addresses.d. For an IPv4 address, determine whether to enable Address Resolution

Protocol (ARP).e. For an IPv6 address, determine how whether to use address

autoconfiguration. If manual, define Stateless Address Autoconfiguration(SLAAC) and Duplicate Address Detection (DAD) behavior.

5. Optionally modify the way the Ethernet interface works within the network.v Change the maximum transmission unit (MTU) for its default value of 1500.v Change the MAC (physical) address from the “burned-in” value on the

network interface card (NIC). The NIC provides the physical interface. Theaddress must be in hexadecimal format, for example 00:11:22:33:44:55:EE.

v Change the physical setting for operational mode interface speed and duplex.6. Optionally add static routes to the routing table. For details, refer to “Defining

static routes” on page 73.7. Optionally define standby controls for interface failover. For details, refer to

“Defining standby controls” on page 73.8. Click Apply to save the object to the running configuration.9. Optionally, click Save Config to save the object to the startup configuration.

For information about these properties, refer to the online help.

Configuring VLAN interfacesUse the following procedures to configure VLAN interfaces:1. Select Network → Interface → VLAN Sub-Interface to display the catalog.2. Click the name of the target interface to display the configuration screen.3. Specify the name of the object in the Name field.4. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.5. Specify a descriptive object-specific summary in the Comment field.6. Define the network configuration of the interface.

a. Set the primary IP address.v For an IPv4 address, use the Use DHCP toggle to control whether to

obtain the address using Dynamic Host Configuration Protocol (DHCP).


v For an IPv6 address, in the IP Address field, specify the IP address andsubnet mask in CIDR format.

b. Set the default gateway.c. Define secondary IP addresses.d. For an IPv4 address, determine whether to enable Address Resolution

Protocol (ARP).e. For an IPv6 address, determine how whether to use address

autoconfiguration. If manual, define Stateless Address Autoconfiguration(SLAAC) and Duplicate Address Detection (DAD) behavior.

7. Associate the VLAN interface to an Ethernet interface.a. Select the Ethernet interface to provide connectivity.b. Specify the identifier.c. Specify the outbound priority.

8. Optionally add static routes to the routing table. For details, refer to “Definingstatic routes.”

9. Optionally define standby controls for interface failover. For details, refer to“Defining standby controls.”



Defining static routesTo add static routes to an interface during configuration:1. Click the Static Routes tab.2. Add a static route to the routing table.

a. Click Add to display the property window.b. Define the properties for the static route. For information about these

properties, refer to the online help.v Its destination network addressv The network address of its next-hop router (gateway)v Its routing preference (metric)

c. Click Save to commit the static route and return to the configuration screen.3. Repeat the previous step to add another static route to the routing table.


Defining standby controlsTo define standby controls for interface failover during configuration, define theproperties on the Standby Control tab. For information about these properties,refer to the online help.

The failover configuration requires the configuration of both interfaces with thefollowing requirements:v Both interfaces must be assigned to the same group.

The value must be distinct from all group numbers that are being used by IProuters or switches in the same broadcast domain. The active interface in the

Chapter 8. Managing the appliance itself 73

group will change its Ethernet MAC address to 00:00:0C:07:AC:XX, where XX isthe group number. This number must be unique among all standby groups on agiven appliance.

v Both interfaces must use the same virtual IP address (VIP). The VIP serves as thedefault gateway.

v The active interface can be put in preempt mode to determine whether itreturns to the active role when it becomes available. When a preemptionhappens, all TCP connections to the VIP are lost. The VIP moves to the interfacethat is preempting, but the TCP connections cannot move.

v The standby interface must be assigned a priority less than 100. Assignment of apriority to the active interface is optional.

v Both interfaces must use the same security token (first four and last fourauthentication bytes).

Removing an Ethernet interface from the networkThe administrative state of an Ethernet interface can be changed from enabled todisabled while Ethernet cables are still physically connected to the appliance. Usethis method to remove the appliance from the network without physicallyremoving network cables.

Initiating a packet-capture sessionYou can initiate a packet-capture session on an Ethernet or VLAN interface. Thedata in a packet capture is saved in the pcap format. Use a utility, such astcpdump or ethereal, to interpret the file.

To start a package capture session from the configuration screen, use the followingprocedure:1. Click Start Packet Capture.2. Follow the prompts.

The appliance initiates a default packet-capture session on the target interface. Theappliance closes the session after 30 seconds or after the capture of 10 Megabytesof data, whichever occurs first. Alternatively, click Stop Packet Capture to end apacket-capture session. By default, captured data is stored in the capture.pcap filein the temporary: directory (temporary:///capture.pcap).

Configuring appliance-wide network settingsThe configuration of network settings allows you to control the followingproperties:v The behavior of the underlying network stack. By default, the appliance issues

ICMP replies (address mask, echo, information, and timestamp) in response tothe receipt of corresponding ICMP requests.

v Source-based routing or destination-based routingv Interface isolation levelsv Retry behavior of the TCP engine

To change the network settings, perform the following steps:1. Select Network → Interface → Network Settings.2. Provide the following inputs:


Admin StateRetain the default setting. To place the object in an inactiveadministrative state, click disabled.


ICMP DisablePopulate the list with one or more control message types. Theappliance will not generate messages that are not in the list.

ECN DisableDisable the generation of ECN TCP sessions. By default, ECN sessionsare enabled.

Destination Based RoutingUse the toggle to control the way that the DataPower appliancedetermines the route to return responses (the outbound packet) to theoriginating client (destination of the outbound packet).

off (Default) Interface selection is based on the interface that isbound to the address of the service that generated the response.If the service is bound to a single address, responses are routedusing the interface that is assigned to that address. If theservice is bound to more than one address (a configuration of0.0.0.0), responses are routed using the interface that receivedthe original client request (not the interface that is bound to theservice that generated the response).

on Interface selection is based on the best path to the client,regardless of the receiving interface or the service. Best path isdetermined by static routes that are bound to the availableinterfaces. Destination-based routing is for backwardcompatibility only. Enable destination-based routing only if anupgrade disables existing connectivity.

Relaxed Interface IsolationUse the toggle to relax isolation of network interfaces. As a securitypolicy, the interface that receives the network packet must also beconfigured with the IP address that is the destination address of thepacket. Enabling this option relaxes that restriction so that the packet isallowed if the interface it arrives on contains an IP address in the samesubnet as the destination address of the packet. Whether the interfacethat receives a packet is used for the response depends on the behaviorthat is established with the Destination Based Routing toggle. Bydefault, if the request is addressed to 10.10.1.2 but received on 10.10.1.3(which relaxed interface isolation allows), the reply uses interface10.10.1.2. The requesting client, therefore, receives an answer with asource IP address that matches the address of the destination of therequest.

Never Enforce Interface IsolationUse the toggle to turn on or turn off enforced interface isolation. If setto on, any interface that is bound to the destination service can receivethe packet.

TCP RetriesSpecify an integer to establish the maximum number of times to retry aTCP SYN when none is received in response.


ARP RetriesSpecify an integer to establish the maximum number of times to retry afailed ARP.

ARP Retry IntervalSpecify the number of milliseconds to wait before retrying failed ARP.


DNS SettingsThe appliance maintains a domain name table that enables the use of non-fullyqualified domain names (host names) in lieu of IP addresses. The applianceattempts to resolve a host name with any domain in the domain name table. Thehost name is resolved by the initial match.

With a domain name table that contains entries for macrocorp.com, megacorp.com,and gigacorp.com, a host name of ragnarok will attempt to be resolved in thefollowing order:1. ragnarok.macrocorp.com

2. ragnarok.megacorp.com

3. ragnarok.gigacorp.com

Note: All DataPower appliances except for B2B Appliance XB60 appliancessupport IPv6 addresses.

Configuring the DNS serviceTo configure the DNS service, use the following procedure:1. Select Network → Interface → DNS Settings to display the configuration screen.2. On the Main tab, enable the DNS service and provide the basic settings.3. On the Search Domains tab, define the domains to search for a match when a

partial host name is submitted to the DNS service.4. On the DNS Servers tab, define the list of DNS servers to contact to locate the

DNS server to use for DNS name resolution.5. On the Static Hosts tab, define the list of host-address maps for static hosts.6. Click Apply to save the object to the running configuration.7. Optionally, click Save Config to save the object to the startup configuration.

For information about the properties, refer to the online help.

Flushing the DNS hosts cacheThe appliances maintains a cache of DNS hosts. To flush the cache, click FlushDNS Cache

This action is available on the following WebGUI screens:v On the object page for DNS Settings (Network → Interface → DNS Settings)v On the status page for DNS Cached Hosts (Status → IP-Network → DNS Cached

Hosts).


Host AliasThis feature allows any service that binds to a particular IP address to bind to alocal host alias, rather than a specific address. For example, an XSL Proxy could beconfigured (bound) to the local IP address 10.10.1.1 (which in turn was assigned toone of the Ethernet interfaces that is configured on the DataPower appliance).Using the local host alias feature, you could bind the XSL Proxy to an alias name,such as proxy1. The host alias, in turn, is bound to a valid local IP address, such as10.10.1.1.

Local host aliases can be useful when exporting configurations to other machines;for example, a staging appliance on subnet 10 to a production appliance on subnet135. The exported configuration uses a local host alias that can be defined on theappliance where the configuration is being imported. However, the local host aliason the appliance where the configuration is being imported can bind to a differentlocal IP address. No IP address change is required during migration.

Working with local host aliases

Note: Changing the IP address that is assigned to an alias will cause all servicesthat use the alias to rebind to the new address.

Deleting an alias brings down the operational state of all services that use the alias.

When created, local host aliases can be used in place of IP addresses for manyservices. The following services can use host aliases:v XML Firewall servicev XSL Proxy servicev HTTP servicev TCP Proxy servicev SSL Proxy servicev XSL Coprocessor service

Note: Although the Select Alias button is on the Log Targets page, any host aliasresolves to local IP address 0. Specify IP addresses instead.

For example, to use an alias perform the following steps:1. Select Objects → Services → New XSL Proxy.2. Click Select Alias to assign a host alias for the local IP address instead of the

actual IP address of an Ethernet interface.3. Click Apply to set the appliance address to the selected alias.

After a service is set to use an alias, the exported configuration identifies the aliasin the exported configuration file. You can change the real IP address of the serviceby editing the alias to use a different IP address.

Migrating configuration dataImplementing the local host alias feature for migration of configuration datarequires the following steps:1. Use the Host Alias screen to establish aliases2. Set the configuration of each service (such as an XML Firewall or XSL Proxy) to

use the host aliases.


Select Network → Interface → Host Alias to display the Host Alias catalog.

Click Add to display the Host Alias Configuration screen that you use to create anew host alias.

Name Specify the alias name. This name cannot begin with the reservedletters “eth” or “mgt”.

Admin State Retain the default setting. To place the object in an inactiveadministrative state, click disabled.

Comments Specify a descriptive object-specific summary.

IP Address Specify a local IP address.

Note: Select Status → Ethernet Interfaces to view a list of allconfigured interfaces and IP addresses.

Click Apply to save the object to the running configuration and return to the objectcatalog.

Optionally, click Save Config to save the object to the startup configuration.

You can verify that new aliases were applied by selecting Status → DNS StaticHosts.

NTP ServiceYou can use the WebGUI to identify NTP (Network Time Protocol) servers. After atleast one NTP server is identified, the appliance acts as a Simple Network TimeProtocol (SNTP) client as described in RFC 2030. The time that is retrieved fromthis server can be different from the time that is displayed on the WebGUI due tothe Time Settings on the local appliance. Refer to “Managing the time on theappliance” on page 79.

By default, the appliance issues requests to the first NTP server in the list. If thisserver is not available, the appliance attempts to contact the next server in the list.

To manage NTP servers, use the following procedure:1. Select Network → Interface → NTP Service to display the NTP Service

Configuration screen.2. Provide the following inputs:



NTP ServerSpecify the host name or IP address of an NTP server.

Click Add to add this server to the list of available servers. Servers arecontacted in the listed order.

Refresh IntervalSpecify the interval (in seconds) between the time-of-day requests that aregenerated by the appliance when acting as an SNTP client. The default is900.



Managing the time on the applianceThe time on the appliance consists of the following specifications:v Setting the local time and datev Setting the time zone

The date and time settings with the setting for the time zone determine thedisplayed time. The time zone setting allows the administrator to set a time zoneand any daylight savings time adjustments.

Setting the local time and dateTo set the local time and date, use the following procedure:1. Select Administration → Main → System Control to display the System Control

panel.2. Locate Set Time and Date section.

a. In the Date field, specify the date in yyyy-mm-dd format.b. In the Time field, specify the time in hh:mm:ss format.c. Click Set Time and Date to display a confirmation window.

3. Click Confirm.4. Click Close.

Setting the local time zoneThe time zone for the local time affects the time displayed by the local appliance.The appliance clock runs on Zulu time. If daylight savings time applies to theselected time zone, the appliance adjusts the displayed time when a daylightsavings time boundary is crossed.

To set the local time, use the following procedure:1. Select Administration → Device → Time Settings to display the Time Settings

Configuration screen.2. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.3. From the Local Time Zone list, select the time zone.4. Click Apply to save the object to the running configuration.5. Optionally, click Save Config to save the object to the startup configuration.

Creating a custom time zoneTo create a custom time zone, use the following procedure:1. Select Administration → Device → Time Settings to display the Time Settings

Configuration screen.2. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.3. From the Local Time Zone list, select Custom (user defined).4. Provide the following information:

Name A name for this custom time zone, which is appended to the time.


Specify up to 6 characters. For example, if Name is set to PKD, the timeappears as Fri Jan 14 04:32:10 2005 PKD

Direction from UTCSelect East (Asia is East of UTC) or West (North America is West ofUTC).

Hours from UTCSpecify an integer indicating the hour offset from UTC.

Minutes from UTCSpecify an integer indicating the minute offset from UTC.

Daylight Savings Time (DST) OffsetSpecify an integer that indicates the offset to be implemented whenDaylight Savings Time is in effect. This value is 0 by default.

DST NameA symbolic name for daylight savings time. Specify up to 6 characters.This name will be appended to the time display when daylight savingstime applies.

DST Start MonthSelect a month to indicate when DST starts.

DST Start WeekSpecify an integer (such as 1 to indicate the first week of the month) toindicate when DST starts.

DST Start DaySelect a day to indicate when DST starts.

DST Start HoursSpecify an integer between 0 and 23 to indicate when DST starts.

DST Start MinutesSpecify an integer between 0 and 59 to indicate when DST starts.

DST Stop MonthSelect a month to indicate when DST stops.

DST Stop WeekSpecify an integer (such as 1 to indicate the first week of the month) toindicate when DST stops.

DST Stop DaySelect a day to indicate when DST stops.

DST Stop HoursSpecify an integer between 0 and 23 to indicate when DST stops.

DST Stop MinutesSpecify an integer between 0 and 59 to indicate when DST stops.

Selecting the reboot configurationTo select a firmware image to load the next time the appliance reboots, use thefollowing procedure:1. Select Administration → Main → System Control to display the System Control

panel.2. Locate the Select Configuration section.3. Select a configuration file. If the file is not in the list, click Upload to upload

the file to the appliance.


4. Click Select Configuration.

The selected configuration file will be used the next time the appliance is rebooted.

Configuring throttle settingsThe appliance monitors its memory usage, temporary file space usage, and QCodesusage. The appliance reacts to low conditions by refusing to accept newconnections. If the refusal to accept new connections does not free sufficientresources after a certain duration, the appliance responds by restarting itself.

This process, referred to as throttling, works as follows:v When the number of available QCodes fall below the namespace-threshold (a

measure of free QCodes expressed as a percentage of the total QCodes), theappliance writes an alert to the log. This message indicates that the appliancedetected a shortage of free QCodes. When you receive this alert, the percentageof available QCodes is below the defined threshold. After you receive this alert,schedule a reboot as soon as possible to prevent an unscheduled reboot. If theavailable QCodes is less than 5% available, the appliance reboots.

v When free memory or file space falls below the throttle-threshold (a measure offree memory or file space expressed as a percentage of total memory), theappliance refuses to accept new connections. By default, the throttle-threshold isset to 20 (20% of total memory or file space).

v If the amount of free memory or file space does not rise above thethrottle-threshold in the specified timeout (expressed in seconds), the appliancerestarts. By default, the timeout is set to 30 (seconds).

v If free memory or file space falls below the kill-threshold (also a measure of freememory or file space expressed as a percentage of total memory or file space),the appliance restarts immediately. By default, the kill-threshold is set to 5 (5%of total memory or file space).

To enable or disable throttling and to customize configuration properties, use thefollowing procedure:1. Select Administration → Device → Throttle Settings to display the Throttle

Settings Configuration screen.2. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.3. Specify a descriptive object-specific summary in the Comment field.4. Specify the throttle-threshold for available memory in the Memory Throttle

At field. This threshold is the point at which the appliance stops acceptingnew connections. Use an integer in the range 0 through 100. A value of 0disables throttling. The default is 20.

5. Specify the kill-threshold of minimal available memory in the MemoryTerminate At field. This threshold is the point at which the appliance restarts.Use an integer in the range 0 through 100. This integer must be less than thethrottle-threshold. The default is 5.

6. Specify the throttle-threshold for available temporary space in the Temp FileSpace Throttle At field. This threshold is the point at which the appliancestops accepting new connections. Use an integer in the range 0 through 100. Avalue of 0 disables throttling. The default is 0.

7. Specify the kill-threshold of minimal available temporary space in the TempFile Space Terminate At field. This threshold is the point at which the


appliance restarts. Use an integer in the range 0 through 100. This integermust be less than the throttle-threshold. The default is 5.

8. Specify the namespace-threshold for available QCodes in the NamespaceQCodes Warn At field. This threshold is the point at which the appliancewrites an alert to the log about a shortage of QCodes. Use an integer in therange 5 through 100. The default is 10.

9. Specify the amount of time that the appliance waits to restart after reaching adefined threshold in the Timeout field. The default is 30 seconds.

10. Use the Status Log toggle to control the collection of throttle log messages.The default is off.

11. If on, select the priority of the message from the Log Level list. The priority isthe criticality of the periodic status log. The default is debug.

12. Use the Environmental Monitor toggle to control the collection ofenvironment log messages about fan speed and about power supply status.The default is on.


Shutting down the applianceTo shut down the DataPower appliance, use the following procedure:1. Select Administration → Main → System Control to display the System Control

panel.2. Locate the Shutdown section.3. Use the Mode list to select the shut down type.

Reboot SystemShuts down the appliance and restarts the appliance. Temporary files arelost.

Reload FirmwareRestarts the appliance without a reboot. Temporary files are not lost.

Halt SystemShuts down the appliance.

4. In the Delay field, specify the amount of time (in seconds) to wait beforestarting the shut down procedure. Valid value is an integer in the range of 0through 65535. The default is 1 second. A value of 0 denotes immediate shutdown.

5. Click Shutdown to initiate the shut down procedure.

Controlling the locate LED (Type 9235)Type 9235 appliances have a locate LED light that the DataPower firmware canactivate and deactivate. The locate LED is on the front of the appliance.v When activated, the locate LED light is illuminated in blue.v When deactivated, the locate LED light is not illuminated.

Only administrators in the default domain with the appropriate permissions cancontrol the locate LED.

Activating the locate LEDTo activate the locate LED, use the following procedure:


1. Select Administration → Main → System Control to display the System Controlpanel.

2. Locate the Control Locate LED section.3. Click on.4. Click Control Locate LED.5. Follow the prompts.

Deactivating the locate LEDTo deactivate the locate LED, use the following procedure:1. Select Administration → Main → System Control to display the System Control

panel.2. Locate the Control Locate LED section.3. Click off.4. Click Control Locate LED.5. Follow the prompts.

Generating an appliance certificateTo generate a certificate for the appliance, which can be a self-signed certificate,use the following procedure:1. Select Administration → Main → System Control to display the System Control

panel.2. Locate the Generate Device Certificate section.

a. In the Common Name (CN) field, specify the common name for theappliance.

b. For Generate Self-Signed Certificate, select on (default) to generate aself-signed certificate; otherwise, select off.

c. Click Generate Device Certificate.

Configuring appliance settingsTo modify the settings for the appliance, use the following procedure:1. To display the System Settings Configuration screen, select Administration →

Device → System Settings.2. Provide the following inputs:

a. Specify a descriptive object-specific summary in the Comment field.b. In the Entitlement Number field, specify the serial number of the original

appliance after receiving a replacement appliance. The entitlement numberidentifies the level of support defined with each appliance purchase.Without the serial number of the original appliance, IBM cannot entitle thereplacement appliance for future maintenance or warranty service.

c. In the Contact field, specify the person responsible for managing thisappliance by name, telephone number, email address, or a combination ofthese details.

d. In the System Identifier field, specify the name of the appliance.e. In the Location field, specify the location of the appliance.f. Use the Custom User Interface File controls to select the URL of the custom

user interface file. The location must be local file (in the local: or store:


directory), not a file on a mounted file system (like iSCSI). For informationabout creating this file, refer to Appendix A, “User interface customization,”on page 183.

g. In the Audit Reserve Space field, specify the amount of disk space inkilobytes to reserve for the audit log. The reserve space must be at leastfour kilobytes less than the total amount of free space that is currentlyavailable on the file system. The value 0 indicates that the reserve functionis disabled. Use an integer in the range of 0 through 10000. The default is40.


The following properties are read-only and cannot be modified:v The Admin State toggle is always enabled and cannot be disabled.v The Product OID field identifies the installed DataPower software.v The Description field identifies the appliance model.v The Serial Number field identifies the serial number for the appliance.v The Product ID field identifies the type of the appliance.v The Services field identifies support for application services, presentation

services, session services, and datalink layer services.v The Product Mode value list identifies the operational mode of the appliance.

Configuring NFS SettingsNFS Client Settings

Specify global NFS client properties for either dynamic mounts or staticmounts.

NFS Dynamic MountsEnable and disable dynamic NFS mounted directories. Dynamic mountsare used for unscheduled retrieval of URLs.

NFS Static MountsEnable and disable static NFS mounted directories. Static mounts are usedfor logging to NFS servers and for responses from an FTP Server FrontSide Handler.

NFS Client SettingsBefore establishing NFS static or dynamic mount points, you must set global NFSclient properties as follows.

Select Objects → Network → NFS Client Settings to display the NFS Client Settingsscreen.1. Provide the following inputs:



Mount Refresh TimeSpecify the frequency of mount re-validation; the property defaults to avalue of 10 seconds.


Kerberos KeytabSpecify the keytab to use for Kerberos 5 authentication or create a newKerberos Keytab. For information, refer to Understanding SPNEGO.


NFS Dynamic MountsTo create or edit an NFS Dynamic Mount object, which supports unscheduledURL retrieval and remains active only until the expiration of an inactivity timer,follow this procedure:1. Select Objects → Network → NFS Dynamic Mounts to display the NFS

Dynamic Mounts Configuration screen.2. Provide the following values:



NFS VersionSpecify the preferred NFS protocol version for mount. If the Version is3, but the server only implements Version 2, the client will fall back toVersion 2. If the Version is 4, there is no fallback, since the remoteexport paths are not the same. The default is 3.

After specifying this value, the screen refreshes.

Transport ProtocolFor NFS version 2 or version 3, select the transport protocol to usewhen initiating the mount. If TCP is selected and it is not available onthe NFS server, UDP will be used instead.

For NFS version 4, this property is ignored. NFS version 4 onlysupports TCP.

Authentication ProtocolWhen NFS Version is 4, select the authentication protocol.

AUTH_SYS(Default) Indicate the original NFS scheme.

krb5 Indicate the authentication version to use based on theKerberos Credentials stored on the appliance.

krb5i Indicate the authentication version to use based on theKerberos Credentials stored on the appliance, and includes asecure hash to protect the NFS data from being changed by thenetwork.

krb5p Indicate the authentication version to use based on theKerberos Credentials stored on the appliance, includes a securehash to protect the NFS data from being changed by thenetwork, and also includes data encryption so that the datacannot be read or changed by the network.

Local IP AddressWhen NFS Version is 4, identify the local appliance addresses


monitored by this NFS server for incoming requests. Retain the defaultvalue (0.0.0.0) if you want this server to monitor all active (provisioned)interfaces.

You can use a host alias instead of a local IP address. Click Select Aliasto choose a local host alias. Refer to “Host Alias” on page 77 for moreinformation.

Read-OnlySpecify the mount-specific file access privileges.

on Specify read-only file access.

off (Default) Specify read/write file access.

Read SizeSpecify an integer determining the size, in bytes, of file reads. Thedefault is 4096. Use a smaller value if this size proves difficult for theserver to maintain.

Write SizeSpecify an integer determining the size, in bytes, of file writes. Thedefault is 4096. Use a smaller value if this size proves difficult for theserver to maintain.

Retransmission TimeoutSpecify an integer to determine the retransmission timeout, in tenths ofseconds. Use a value in the range of 1 through 600. The default is 7. Ifthe appliance cannot successfully complete an operation after 0.7seconds (assuming default value), the retransmission fails.

Maximum RetransmissionsSpecify an integer to determine the number of times a retransmissionwill be attempted before the operation fails completely. Use an integerin the range of 1 through 60. The default is 3. After threeretransmissions (assuming default value), the operation is deemedunsuccessful.

Inactivity TimeoutSpecify the idle time, in seconds, that triggers tear down of thedynamic mount. The default is 900.

Mount TimeoutSpecify the maximum time, in seconds, that the appliance attempts toestablish a dynamic mount. The default is 30.


Passing parameters to filesIt is possible to employ parameters in the dpnfs: syntax. The following exampleincludes parameters:dpnfs://fred/test.xml?a=b&c=d

Note: When parameters are used in the URL syntax, the appliance will firstattempt to open a file with a name that includes the parameterspecifications. If that fails, the appliance will then attempt to open the fileusing the name specified prior to the ? in the URL.

These parameters are passed to the file that is being opened. Style sheets, forexample, can then use these parameters.


NFS Static MountsTo create or edit an NFS Static Mount object, which is mounted and maintained aslong as its resident domain is up, follow this procedure:1. Select Objects → Network → NFS Static Mounts to display the NFS Static

Mounts catalog.2. To edit an existing NFS Static Mount object, click the name of the object. To

create a new NFS Static Mount object, click Add to display the NFS StaticMounts configuration (Main) screen.

Name Specify a unique name for this NFS Static Mount object. This name isused in the dpnfs: syntax to designate the mounted directory. Forexample, if this name is server1dir, then files contained in this mountpoint can be accessed using a syntax such as dpnfs://server1dir/subdirectory/filename.ext.



Remote NFS ExportSpecify the URL of the remote exported mount point in the formhost:/path, where host is the DNS name of the host, and path is thepath exported by the host to mount. This path must be exported on thehost given or the static mount will fail.

Local Filesystem AccessEnable or disable command line access to the mount point that isidentified by the Remote NFS Export property.

on Indicates that the mount point is accessible from the commandline. The NFS mount will be available through the commandline under the nfs-mount folder, where mount is the name of themount point.

off (Default) Indicates that the mount point is not accessible fromthe command line.

NFS VersionSpecify the preferred NFS protocol version for this mount. If theVersion is 3, but the server only implements Version 2, the client willfall back to Version 2. If the Version is 4, there is no fallback, since theremote export paths are not the same. The default is 3.

After specifying this value, the screen refreshes.

Transport ProtocolFor NFS version 2 or version 3, select the transport protocol to usewhen initiating the mount. If TCP is selected and it is not available onthe NFS server, UDP will be used instead.

For NFS version 4, this property is ignored. NFS version 4 onlysupports TCP.

Authentication ProtocolWhen NFS Version is 4, select the authentication protocol.

AUTH_SYS(Default) Indicate the original NFS scheme.


krb5 Indicate the authentication version to use is based on theKerberos Credentials that are stored on the appliance.

krb5i Indicate the authentication version to use is based on theKerberos Credentials that are stored on the appliance andincludes a secure hash to protect the NFS data from beingchanged by the network.

krb5p Indicate the authentication version to use is based on theKerberos Credentials that are stored on the appliance, includesa secure hash to protect the NFS data from being changed bythe network, and includes data encryption so that the datacannot be read or changed by the network.

Local IP AddressWhen NFS version 4, identify the local appliance addresses monitoredby this NFS server for incoming requests. Retain the default value(0.0.0.0) if you want this server to monitor all active (provisioned)interfaces.


Read-OnlySpecify the mount-specific file access privileges.

on Indicates read-only file access.

off (Default) Indicates read-write file access.

When mounting the same NFS version 4 mount point in differentdomains, the first mount sets file access privileges. For example, ifdomain-A mounts host:/foo as read-only access and then domain-Bmounts host:/foo as read-write access, both mounts are read-only.

Read SizeSpecify the size of a read operation in bytes. The default is 4096.Specify a smaller number if this size proves difficult for the server tomaintain.

Write SizeSpecify the size of a write operation in bytes. The default is 4096.Specify a smaller number if this size proves difficult for the server tomaintain.

Retransmission TimeoutSpecify an integer to determine the retransmission timeout, in tenths ofseconds. Use a value in the range of 1 through 600. The default is 7. Ifthe appliance cannot successfully complete an operation after 0.7seconds (assuming default value), the retransmission fails.

Maximum RetransmissionsSpecify an integer to determine the number of times a retransmissionwill be attempted before the operation fails completely. Use an integerin the range of 1 through 60. The default is 3. After threeretransmissions (assuming default value), the operation is deemedunsuccessful.



Using the iSCSI protocol (Type 9235)Type 9235 appliances provide two Ethernet interfaces (eth1 and eth2) that supportiSCSI. To use iSCSI on one of these interfaces, you need to configure an iSCSIVolume object. This object access a volume (LUN) on the remote iSCSI server.

For information about Ethernet interfaces, refer to “Configuring Ethernetinterfaces” on page 72.

The configuration of the iSCSI Volume object, requires the configuration of thefollowing objects:

iSCSI Host Bus Adapter (HBA)The HBA establishes communications between the appliance and theremote iSCSI server.

iSCSI Challenge Handshake Authentication Protocol (CHAP)The CHAP is the handshake that authenticates the credentials on theappliance with the remote iSCSI server.

iSCSI TargetThe target defines the connection information to the remote iSCSI server.

The appliance, through the iSCSI HBA, can use the iSCSI protocol to communicatewith the remote iSCSI server. The iSCSI HBA, acting as the software initiator,negotiates through the iSCSI CHAP to establish connectivity. When connected, aniSCSI session is started.

After configuring and initializing an iSCSI volume, you can manage files on theiSCSI volume as if they were local. During startup, the volume is mounted underthe local: and logstore: directories in each application domain.

IQN and EUI formatsEach iSCSI HBA is defined on the DataPower appliance by an iSCSI qualifiedname (IQN).

Each iSCSI target is defined on the DataPower appliance by an IQN or by an IEEEExtended Unique Identifier (EUI).

IQN Specifies a worldwide unique and valid name for iSCSI HBA instances oriSCSI target instances. The name, based on IETF RFC 3270, can be between1 and 244 characters in length. Sample formats are iqn.2001-04.com.example or iqn.2001-04.com.example:storage.disk2.sys1.xyz.

EUI Specifies a worldwide unique and valid name for iSCSI target instances.The name, based on IETF RFC 3270, is a hexadecimal value that can bebetween 1 and 244 characters in length. A sample format iseui.02004567A425678D.

Configuring and initializing an iSCSI volumeThe LUN setting and its read-only or read-write setting on an iSCSI volume aredisclosed to the iSCSI HBA by the iSCSI target.

After configuring and initializing an iSCSI volume, you can access the remoteiSCSI file system from the local: and logstore: directories in each applicationdomain.


To access an iSCSI volume on a remote iSCSI server, use the following high-levelprocedure:1. Configure the volume2. Initialize the volume.

Configuring an iSCSI volumeTo configure the iSCSI volume, use the following procedure:1. Select Administration → Storage Devices → iSCSI Volume to display the

catalog.2. Click Add to display the iSCSI Volume configuration screen.3. Specify the name of the object in the Name field.4. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.5. Specify a descriptive object-specific summary in the Comment field.6. Use the Read-Only toggle to indicate whether the files on the volume have

read-only access.

on Sets the file system to read-only access.

off (Default) Sets the file system to read-write access.7. Specify the directory under which to make the files on the volume available in

the Directory field.8. Specify the logical unit number (LUN) in the LUN field. Use an integer in the

range of 0 through 255.9. Select the instance of the iSCSI Target object to which to bind the iSCSI

volume from the iSCSI Target list. Refer to “Configuring an iSCSI Targetobject” on page 91 for more information.


Initializing an iSCSI volumeInitializing the iSCSI volume allows it to be made active. The iSCSI volume mustbe disabled before it can be initialized.

To initialize the iSCSI volume, use the following procedure:1. Select Objects → Network Settings → iSCSI Volume to display the catalog.2. Click the instance name to display the configuration screen.3. Select the disable radio button for the Admin State toggle.4. Click Apply to save the object to the running configuration.5. Click Initialize File System.6. Follow the prompts to complete the initialization.7. Select the enable radio button for the Admin State toggle.8. Click Apply to save the object to the running configuration.9. Optionally, click Save Config to save the object to the startup configuration.

Repairing an iSCSI volumeYou might need to repair the iSCSI volume if its contents were corrupted by anabnormal shutdown or other error. Before you can repair a volume, you mustdisable it. After repairing the volume, you must enable it.

To repair the iSCSI volume on the appliance, use the following procedure:


1. Select Objects → Network Settings → iSCSI Volume to display the catalog.2. Click the instance name to display the configuration screen.3. Select the disable radio button for the Admin State toggle.4. Click Apply to save the object to the running configuration.5. Click Repair File System.6. Follow the prompts.7. Select the enable radio button for the Admin State toggle.8. Click Apply to save the object to the running configuration.9. Optionally, click Save Config to save the object to the startup configuration.

Reference objects for iSCSIThe following reference objects that must be defined to use the iSCSI protocol:v iSCSI Targetv iSCSI Host Bus Adapterv iSCSI CHAP

Configuring an iSCSI Target objectThe iSCSI target waits for SCSI commands. An iSCSI target cannot initiate an iSCSIsession. The iSCSI target is a connection instance of a remote iSCSI target.

To configure an iSCSI target, use the following procedure:1. Select Objects → Network Settings → iSCSI Target to display the catalog.2. Click Add to display the configuration screen.3. Specify the name of the object in the Name field.4. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.5. Specify a descriptive object-specific summary in the Comment field.6. Specify the IQN or EUI of the HBA on the remote iSCSI server in the Target

Name field. Refer to “IQN and EUI formats” on page 89 for details.7. Specify the host name or IP address of the remote iSCSI server in the Host

field.8. Specify the listening port on the remote iSCSI server in the Port field. The

default is 3260.9. Select a HBA instance to use to initiate the iSCSI session from the Host Bus

Adapter list. Refer to “Configuring an iSCSI Host Bus Adapter object” onpage 92 for more information.

10. Select the CHAP instance to use for authentication from the CHAP list. Referto “Configuring an iSCSI CHAP object” for more information.


Configuring an iSCSI CHAP objectThe iSCSI Challenge Handshake Authentication Protocol (CHAP) defines thecredentials to use to authenticate the DataPower appliance with the remote iSCSIserver. The CHAP presents credentials to the iSCSI target instances during startup.

To configure the iSCSI CHAP, use the following procedure:1. Select Objects → Network Settings → iSCSI CHAP to display the catalog.2. Click Add to display the configuration screen.


3. Specify the name of the object in the Name field.4. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.5. Specify a descriptive object-specific summary in the Comment field.6. Specify the user name for the CHAP in the User Name field.7. Specify the password for this user in the Password field.8. Specify the password again in the Confirm Password field.9. Click Apply to save the object to the running configuration.


Configuring an iSCSI Host Bus Adapter objectThe iSCSI Host Bus Adapter (HBA) is the hardware that is responsible for themanagement of iSCSI communications. The iSCSI HBA initiates the iSCSI sessionbetween the DataPower appliance and the iSCSI target.

Each DataPower appliance provides an HBA for each of the following Ethernetinterfaces:v On the eth1 interface, there is the iscsi1 HBA instance.v On the eth2 interface, there is the iscsi2 HBA instance.

Each instance is pre-configured, but each instance is in the [down] operational state.The only required configuration is to change the value of the Admin State togglefrom disabled to enabled.

To configure the iSCSI Host Bus Adapter, use the following procedure:1. Select Objects → Network Settings → iSCSI Host Bus Adapter to display the

catalog.2. Click the HBA instance to modify to display the configuration screen.3. Change the value for the Admin State toggle from disabled to enabled.4. Specify a descriptive object-specific summary in the Comment field.5. Optionally change the IQN in the iSCSI Name field. The IQN is already

defined but not visible. To view this value, select Status → Other Network →iSCSI Host Bus Adapter Status.

6. Determine whether to use Dynamic Host Configuration Protocol (DHCP) or astatic address.v To use DHCP, set the Use DHCP toggle to on.v To use a static address, use the following procedure:

a. Set the Use DHCP toggle to off.b. Specify a unique IP address in the IP Address field.c. Specify the default gateway in the Default Gateway field.


Configuring SNMP SettingsThe appliance supports SNMP versions 1, 2c, and 3. You can do anything withversion 3 that you can do with version 1 or version 2c. With version 3, you cansecurely perform these operations in terms of encryption and authentication, butnot in terms of inform requests.


The configuration of SNMP consists of the following procedures:v Configuring global propertiesv Viewing enterprise MIBsv Configuring event subscriptionsv Configuring communitiesv Configuring recipientsv Configuring contexts

Configuring global propertiesUse the following procedure to configure global (or generic) SNMP properties:1. Select Administration → Access → SNMP Settings to display the SNMP

Configuration screen.2. On the Main tab, provide the following information:

a. Retain the default setting for the Admin State toggle. To place the object inan inactive administrative state, click disabled.

b. Specify a descriptive object-specific summary in the Comment field.c. Specify the IP address of the Ethernet interface in the Local IP Address

field. The local SNMP entity monitors this address for incoming SNMPrequests. If blank or the default value of 0.0.0.0, the local SNMP entitymonitors all local IP addresses for incoming SNMP requests.To use a host alias instead of a local IP address. Click Select Alias to choosea host alias. Refer to “Host Alias” on page 77 for more information.

d. Specify the port number of the Ethernet interface in the Local Port field.The local SNMP entity monitors this port for incoming SNMP requests. Usean integer in the range of 1 through 65535. The default is 161.

e. To implement version 3 user-based security or to implement version 3notifications, use the SNMPv3 Users controls to compile a list of SNMPusers. Refer to “Configuring SNMP V3 users” on page 57 for moreinformation.

f. Select the settings for authentication and privacy from the SNMPv3 SecurityLevel list.

Authentication, Privacy(Default) Protocol exchanges are authenticated and encrypted.

Authentication, No PrivacyProtocol exchanges are authenticated.

No Authentication, No PrivacyProtocol exchanges are neither authenticated nor encrypted.

g. Select the access privilege for SNMP V3 users from the SNMPv3 AccessLevel list.

read-only(Default) Users have read-only access to SNMP MIBs.

read-writeUsers have read-write access to SNMP MIBs.

none Users have no access to SNMP MIBs.3. Click Apply to save the object to the running configuration4. Optionally, click Save Config to save the object to the startup configuration.


Viewing MIBsTo view enterprise MIBs, use the following procedure:1. Select Administration → Access → SNMP Settings to display the SNMP

Configuration screen.2. Click the Enterprise MIBs tab.3. Click any listed MIB to view its details.

Configuring subscriptionsTo configure SNMP subscriptions that generate traps, use the following procedure:1. Select Administration → Access → SNMP Settings to display the SNMP

Configuration screen.2. Click the Trap Event Subscriptions tab to display the current subscriptions.3. Select the minimum event priority from the Minimum Priority list. The default

is error.4. Use the Event Subscriptions controls to compile a list of events that generate

traps.5. Click Apply to save the object to the running configuration6. Optionally, click Save Config to save the object to the startup configuration.

Configuring communitiesMany operational environments support only two SNMP communities:v A public (read-only) communityv A private (read-write) community

However, there is no limit to the number of communities that can be supported,nor is there any limit to the number of SNMP managers that can be contained in aspecific community.

To identify remote SNMP managers or engines that are granted access to theappliance, use the following procedure:1. Select Administration → Access → SNMP Settings to display the SNMP

Configuration screen.2. Click the SNMP V1/V2c Communities tab to display the communities catalog.3. Click Add to display the SNMP V1/V2c Communities property window.

a. Specify the SNMP community name in the Community field. An SNMPcommunity name (essentially a password) is included in the incomingSNMP message header.

b. Select the application domain to which this community is granted accessfrom the Associated Domain list.

c. Select the domain-specific access privileges accorded to this communityfrom the Mode list.

read-only(Default) Read-only communities are restricted to SNMP getoperations, which means that these communities can read butcannot change system values.

read-writeRead-write communities have access to both SNMP get and setoperations. These communities can read and change system values.


none Disables a previously configured community. These communitiescannot access system values.

d. Specify the IP address of an SNMP manager that belongs to this communityin the Remote Host Address field.

e. Click Save to return to the catalog.4. Repeat step 3 on page 94 to add additional communities.5. Click Apply to save the object to the running configuration6. Optionally, click Save Config to save the object to the startup configuration.

Configuring recipientsThe SNMP agent or engine issues the following generic events that are referred toas notifications in SNMP version 3 and traps in earlier versions:v authenticationFailure

v linkDown

v coldStart

v linkUp

Additionally, you can configure an SNMP log that issues logging events in theform of SNMP traps or notifications. Refer to “Configuring log categories” on page150 for information about SNMP logs.

To designate notification recipients, use the following procedure:1. Select Administration → Access → SNMP Settings to display the SNMP

Configuration screen.2. Click the Trap and Notification Targets tab to display the recipients catalog.3. Click Add to display the Traps and Notifications property window.

a. Specify the IP address of a recipient in the Remote Host Address field. TheIP address must be unique for each recipient and is the notification target.

b. Specify the port number monitored by the remote SNMP manager or enginefor incoming SNMP traps in the Remote Port field. Use an integer in therange 1 through 65535. The default is 162.

c. Specify the community name to access the remote SNMP manager in theCommunity field. If you are issuing version 3 notifications, leave blank.

d. Select the protocol version from the Version list.e. When the protocol version is 3, specify an SNMP version 3 user who is

associated with the recipient in the Security Name field.f. Select the authentication and privacy from the Security Level list. The

authentication and privacy are used to authenticate and encryptnotifications.

Authentication, Privacy(Default) Notifications are authenticated and encrypted.

Authentication, No PrivacyNotifications are authenticated.

No Authentication, No PrivacyNotifications are not authenticated or encrypted

g. Click Save to return to the catalog.4. Repeat step 3 to designate additional recipients.5. Click Apply to save the object to the running configuration



Configuring contextsAn SNMP version 3 context is defined in RFC 3411, An Architecture for DescribingSimple Network Management Protocol (SNMP) Management Frameworks, as a physicalor logical collection of management information accessible by an SNMP entity. Interms of the DataPower appliance, an SNMP context equates to an applicationdomain.

To map application domains to SNMP contexts, use the following procedure:1. Select Administration → Access → SNMP Settings to display the SNMP

Configuration screen.2. Click the SNMPv3 Contexts tab to display the contexts catalog.3. Click Add to display the SNMP V3 Contexts property window.

a. Specify the context name in the Context Name field. You can use the nameof the mapped application domain as the context name.

b. Select the application domain to map to the context name from theApplication Domain list.

c. Click Save to return to the catalog.4. Click Apply to save the object to the running configuration5. Optionally, click Save Config to save the object to the startup configuration.


Chapter 9. Managing network access to the appliance

SSH accessUse this page to enable or disable SSH service. Select Network → Management →SSH Service to display the SSH Service Configuration (Main) screen.

Provide the following inputs:


Local IP AddressOptionally bind SSH to a specific active (provisioned) appliance interface.

Without an explicit address assignment, SSH, once enabled, first attempts tobind to the appliance management port. If the management port has not beenpreviously configured, SSH binds to all configured appliance interfaces.

You can use a host alias instead of a local IP address. Click Select Alias tochoose a local host alias. Refer to “Host Alias” on page 77 for moreinformation.

Port NumberOptionally bind SSH to a specific port. Without an explicit port assignment,SSH, once enabled, binds to port 22, the well-known SSH port.

Access Control ListAssign an Access Control List to the SSH service. Refer to “Access ControlList” on page 161 for more information.



Telnet accessUse this page to enable or disable Telnet service. Select Network → Management →Telnet Service to display the Telnet Service catalog.

Click Add to display the Telnet Service configuration screen.


NameSpecify the name of this Telnet server.


Local IP AddressIdentify the local appliance addresses monitored by this Telnet server forincoming Telnet requests. Retain the default value (0.0.0.0) if you want thisTelnet server to monitor all active (provisioned) interfaces.



Local PortIdentify the local port on the IP address identified above monitored by thisTelnet server for incoming Telnet requests.

Access Control ListAssign an Access Control List to this Telnet server. Refer to “Access ControlList” on page 161 for more information.



WebGUI accessAccess to the appliance via the WebGUI is supported by a dedicated HTTP serverthat you configured during the initial appliance configuration process.

After creating the dedicated server, you can use the WebGUI to modify serverproperties. Select Network → Management → Web Management Service to displaythe Web Management Service configuration (Main) screen.



Local IP AddressIdentify the local IP address of the appliance that is monitored for incomingWebGUI requests.

If you want the Web Management Service to monitor all active interfaces,retain the default value (0.0.0.0).


Port NumberSpecify the specific UDP port (in the range 1 through 65535) monitored bythe Web Management.

Access Control ListOptional, select the ACL to use when making a connection to the WebGUI.Refer to “Access Control List” on page 161 for more information.


Custom User AgentOptional, select the User Agent to use when making a connection to theWebGUI.

Save Config OverwriteSpecify the desired behavior after a running configuration is saved as thestartup configuration. The startup configuration is saved by clicking the Save


Config button. By default, the startup configuration is saved to theautoconfig.cfg file in the config: directory. To override the default behavior,click the no radio button.

Idle TimeoutSpecify the idle timeout value. That is, specify the period of inactivity afterwhich the Web Management Service shuts down the WebGUI connection.

Allowable values are in the range 0 through 65535, with a default value of600 (seconds). The special value 0 disables the idle timeout.

To change default security settings and HTTP connections settings, click theAdvanced tab to display the Web Management Service configuration (Advanced)screen.

Custom SSL Proxy ProfileTo employ an SSL Proxy Profile other than the default for connection to theWeb Management interface, select an SSL profile.

By default, the DataPower appliance uses a self-signed certificate during theSSL handshake. This field (possibly used with the Generate Certificate tool)offers an opportunity to employ different certificates and keys in support ofthe SSL connection to the Web Management interface.

You can access the Generate Certificate tool, which creates an SSL ProxyProfile based on newly generated self-signed certificate and an associatedprivate key, by clicking Generate Certificate on the Advanced screen. Afterclicking Generate Certificate, a confirmation window is displayed.

Click Confirm to create an SSL Proxy Profile, suitable for Web ManagementService usage, named appliance-id.

If desired, you can use the File Management utility to verify that thefollowing files were created:

cert:///appliance-id-privkey.pemA protected .pem-formatted file that contains the generated privatekey

cert:///appliance-id-sscert.pemA protected .pem-formatted file that contains the generatedself-signed certificate

If desired, you can use the Objects screen to verify that the following objectswere created:

appliance-idA Crypto Key object that references the appliance-id-privkey.pem file

appliance-idA Crypto Certificate object that references the appliance-id-sscert.pemfile

appliance-idAn Identification Credentials object that references the appliance-idCrypto Key object and Certificate object.

appliance-idA Crypto Profile object that references the appliance-id IdentificationCredentials object

Chapter 9. Managing network access to the appliance 99

appliance-idAn SSL Proxy Profile object that references the appliance-id CryptoProfile object

Custom User AgentSelect an User Agent to associate with the WebGUI.



XML Management InterfaceThe DataPower appliance can be configured and managed completely through theXML Management Interface. When enabled, this interface allows administrators tosend status and configuration requests to the DataPower appliance through astandard SOAP interface. The URL for this interface takes the following form:https://appliance_ip:port/service_uri

For example:https://192.168.1.25:5550/service/mgmt/current

This interface requires the HTTPS protocol for communication. By default, theinterface acts as an SSL server, using the default keys that are installed in theappliance. These keys are the same keys that are used for the WebGUI and SSHinterfaces.

Services overviewThe appliance supports a range of administrative services through the XMLManagement Interface. An overview of these services are as follows:v Device Configuration and Management using SOAP XML requests and

responses. The appliance offers an older version of this interface (v2004) and thecurrent version.

SOAP Management URIEnables processing of messages that are received on any (*) URI forolder applications. One example would be an application that postsSOAP management requests to "/". By default, this service is enabled.

SOAP Configuration ManagementEnables support for SOAP Configuration Management. The URI for theSOAP Configuration Management is /service/mgmt/current. By default,this service is enabled.

SOAP Configuration Management (v2004)Enables support for legacy SOAP Management format. The URI for theSOAP Configuration Management is /service/mgmt/2004. By default,this service is enabled.

Refer to “SOAP interface” on page 102 for more information.v WS-Management Endpoint implementing portions of the WS-Management

specification.

WS-Management EndpointEnables a management endpoint that supports the WS-Managementfamily of protocols. The URI for the WS-Management endpoint is/service/ws-management.


v WSDM Endpoint, implementing portions of the WSDM specification.

WSDM EndpointEnables a management endpoint that supports the WSDM 1.0 family ofprotocols. The URI for the WSDM 1.0 endpoint is /service/wsdm-10.

Service can be obtained at the following URI:/service/wsdm-10

Refer to “WSDM interface” on page 108 for more details.

The following interfaces are implemented but not used for configuring theappliance:

AMP EndpointEnables the appliance to expose a proprietary management interfaceprotocol that is used for multi-box management. Multi-box managementuses an external tool. By default, this service is enabled.

SLM EndpointEnables a management endpoint that supports the SLM protocol. The URIfor the SLM protocol is /service/slm/datashare/1.0. The SLM protocol isused to exchange real time transaction monitoring and statistics used bythe Service Level Monitoring peer. This service is not a public Web service.By default, this service is enabled.

UDDI SubscriptionEnables the appliance to listen for UDDI subscription notifications that aresent by remote UDDI registries.

Enabling interface servicesYou can enable a single XML Management Interface (that is accessible by anauthorized user) to provide external access to configuration and status data. Bydefault, the XML Management Interface runs SSL and uses HTTP BasicAuthentication (user name and password).

To enable the desired interface services:1. Select (Network → Management → XML Management Interface to display the

XML Management Configuration (Main) screen.2. Provide the following inputs:


Local IP AddressThe IP interface address monitored for incoming management requests.

If you want the XML Management Interface to monitor all activeinterfaces, retain the default value (0.0.0.0).


Port NumberThe specific UDP port (in the range 1 through 65535) monitored by theXML Management Interface.

Access Control ListTo employ an ACL other than the default for connection to the XML


Management Interface, click the + button to create a new one. Refer to“Access Control List” on page 161 for more information.


Enabled ServicesUse the check boxes to enable (selected) or disable (not selected)support for various management protocols. For details about theseservices, refer to “Services overview” on page 100.

When the SLM endpoint is enabled.a. Click the SLM tab.b. Use the SLM Update Interval field to specify the interval, in

seconds, between data updates that are issued by the appliance.3. Click Apply to save the object to the running configuration.4. Optionally, click Save Config to save the object to the startup configuration.

The XML Management Interface requires basic HTTP authentication of theadministrative user who is configured on the appliance. Typically, HTTPauthentication requires the default admin account and corresponding password.

Changing default security and HTTP settingsTo change default security settings and HTTP connections settings, use thefollowing procedure:1. Select (Network → Management → XML Management Interface to display the

XML Management Configuration (Main) screen.2. Click the Advanced tab to display the XML Management Interface

configuration (Advanced) screen.3. Provide the following inputs:

Custom SSL Proxy ProfileSelect an SSL Proxy Profile from the list. The SSL Proxy Profilereferences the certificates and keys for the SSL connection to the XMLManagement Interface.

By default, the DataPower appliance uses a self-signed certificate, notan SSL Proxy Profile. This field offers an opportunity to select adifferent SSL Proxy Profile.

Refer to “Defining SSL Proxy Profile objects” on page 177 for moreinformation.

Custom User AgentSelect an instance of the User Agent object from the list. The UserAgent object defines how to retrieve resources from remote servers.


SOAP interfaceThe SOAP Interface provides many of the same capabilities that the WebGUI andcommands provide. However, the SOAP Interface is a programmatic interface,while the WebGUI or the command line are non-programmatic.

To use the SOAP Interface, you must be able to read XML schemas to create avalid XML request. This document provides basic details only.


The SOAP Interface is described by the following set of files that are in the store:directory.

xml-mgmt.xsdThe schema file that defines the non-primitive management types in SOAPmessages.

xml-mgmt-base.xsdThe schema file that defines the primitive management types in SOAPmessages.

xml-mgmt-ops.xsdThe schema file that defines that defines the operations that can be sent inSOAP requests.

xml-mgmt.wsdlThe WSDL file that defines the services that are available through theSOAP Interface.

Note: If you submit a request without credentials, the appliance returns a faultinstead of a response.

General structure of requestsThe general structure of request documents is as follows:<?xml version="1.0" encoding="UTF-8"?><env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">

<env:Body><dp:request xmlns:dp="http://www.datapower.com/schemas/management">

...</dp:request>

</env:Body></env:Envelope>

The request can contain the domain attribute to specify in which applicationdomain to perform the operation.

General structure of responsesThe general structure of response documents is as follows:<?xml version="1.0" encoding="UTF-8"?><env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">

<env:Body><dp:response xmlns:dp="http://www.datapower.com/schemas/management">

<dp:timestamp>timestamp</dp:timestamp>

...</dp:response>


Available operations for requestsThe <request> element can contain any combination of the operations that aredefined in the store:///xml-mgmt-ops.xsd schema file. The SOAP Interfacesupports the following operations:

Retrieve a login tokenDefine the <dp:get-samlart> element. To retrieve, as a binary token, theSAML artifact that is in use for the current session:<dp:get-samlart user="bmclarke" password="n0wv0y@g3r" />

Retrieve a status object (also known as a status provider)Define the <dp:get-status> element. To retrieve all status objects:<dp:get-status />

To retrieve a specific status object:<dp:get-status class="StatusEnum" />

Refer to the StatusEnum type in the store:///xml-mgmt.xsd schema file forthe list of the supported status objects.

Compare configurationsDefine the <dp:get-diff> element. Refer to the store:///xml-mgmt-ops.xsdschema file for details about the structure for this type of request.

Generate a conformance reportDefine the <dp:get-conformance-report> element. Refer to thestore:///xml-mgmt-ops.xsd schema file for details about the structure forthis type of request.

List files and directoriesDefine the <dp:get-filestore> element. To list the root contents of the filesystem:<dp:get-filestore />

To list the contents of a directory:<dp:get-filestore location="directory" />

Retrieve log dataDefine the <dp:get-log> element. To retrieve all log data:<dp:get-log />

To retrieve log data for a specific log target:<dp:get-log name="logTarget" />

Download a file.Define the <dp:get-file> element. To download a file:<dp:get-file name="directory:///file" />

Upload a fileDefine the <dp:set-file> element. To upload a file to a specific location:<dp:get-file name="directory:///file">

...</dp:get-file>

The request must contain the name and location of the file to upload. Thename attribute on the operation element defines the destination.

Export configuration dataDefine the <dp:do-export> element. Refer to the store:///xml-mgmt-ops.xsd schema file for details about the structure for this type of request.

To export a domain configuration, define the <dp:do-backup> element.

Import configuration dataDefine the <dp:do-import> element. Refer to the store:///xml-mgmt-ops.xsd schema file for details about the structure for this type of request.

To import a domain configuration, define the <dp:do-restore> element.

Create a backup of a domainDefine the <dp:do-backup> element. Refer to the store:///xml-mgmt-ops.xsd schema file for details about the structure for this type of request.

Restore a domain from a backupDefine the <dp:do-restore> element. Refer to the store:///xml-mgmt-ops.xsd schema file for details about the structure for this type of request.

Perform a specific actionDefine the <dp:do-action> element. The node for each action in a requestrequires a different definition. For example to shutdown the appliance after30 seconds and restart:<dp:do-action>

<ActionShutdown><Mode>reboot</Mode><Delay>30</Delay>

</ActionShutdown></dp:do-action>

Refer to the AnyActionElement type in the store:///xml-mgmt.xsd schemafile for the list of the supported actions.

Create an objectDefine the <dp:set-config> element. To create an object:<dp:set-config>

...</dp:set-config>

Refer to the AnyConfigElement type in the store:///xml-mgmt.xsd schemafile for the list of the supported objects.

Retrieve object configurationDefine the <dp:get-config> element. To retrieve the configuration of allobjects:<dp:get-config />

To retrieve the configuration of all objects of a specific class:<dp:get-config class="ConfigEnum" />

To retrieve the configuration of a specific objects:<dp:get-config class="ConfigEnum" name="name" />

Refer to the ConfigEnum type in the store:///xml-mgmt.xsd schema file forthe list of the supported objects.

Modify the configuration of an objectDefine the <dp:modify-config> element. To modify an object:<dp:modify-config>

...</dp:modify-config>

Refer to the AnyModifyElement type in the store:///xml-mgmt.xsd schemafile for the list of the supported objects.

Delete an objectDefine the <dp:del-config> element. To delete an object:

<dp:delete-config>

...</dp:delete-config>

Refer to the AnyDeleteElement type in the store:///xml-mgmt.xsd schemafile for the list of the supported objects.

Example request to view statusThe following example uses the curl program to post a request to the XMLManagement Interface (10.10.13.7:1080) to view object status. The request iscontained in the get-status.xml file.$ curl -k -u user:password -d @get-status.xml https://10.10.13.7:1080

–k Enables the performance of a nonsecure SSL connection and transfer. (nocertificate checking)

–u user:passwordSpecifies the user name and password for server authentication.

–d Sends the data in an HTTP POST request.

Sample requestThe get-status.xml request could contain the following message.<?xml version="1.0" encoding="UTF-8"?><env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">


<dp:get-status class="ActiveUsers"/></dp:request>


Sample responseThe get-status.xml request could generate the following response on success.<?xml version="1.0" encoding="UTF-8"?><env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">

<env:Body><dp:response xmlns:dp="http://www.datapower.com/schemas/management">

<dp:timestamp>2007-07-30T13:58:28-04:00</dp:timestamp><dp:status>

<ActiveUsers><session>1</session><name>wlynch</name><connection>serial-port</connection><address/><login>Fri May 23 12:31:02 2003</login>

</ActiveUsers></dp:status>

</dp:response></env:Body>

</env:Envelope>

The get-status.xml request could generate the following response onauthentication failure.<?xml version="1.0" encoding="UTF-8"?><env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">

<env:Body><dp:response>

<dp:result>Authentication failure</dp:result></dp:response>


Example request to compare configurationsThe following example uses the curl program to post a request to the XMLManagement Interface (10.10.13.7:1080) to compare configurations. The request iscontained in the get-diff.xml file.$ curl -k -u user:password -d @get-diff.xml https://10.10.13.7:1080

–k Enables the performance of a nonsecure SSL connection and transfer. (nocertificate checking)

–u user:passwordSpecifies the user name and password for server authentication.

–d Sends the data in an HTTP POST request.

Sample requestThe get-diff.xml request could contain the following message. This messagecompares an exported configuration (store:///export.zip to the runningconfiguration.<?xml version="1.0" encoding="UTF-8"?><env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">


<dp:get-diff><dp:from>

<dp:export>store:///export.zip</dp:export></dp:from><dp:to>

<dp:object class="all-classes" name="all-objects"/></dp:to>

</dp:get-diff></dp:request>


Sample responseThe get-diff.xml request could generate a response that contains multiple objectelements. Each element object shows its current configuration. Each changed objectin the configuration has one of the following attributes:

new="true"Indicates an object that was added to the configuration. For example:<Matching new="true" name="GetDiff2XMLFirewall"

xmlns:env="http://www.w3.org/2003/05/soap-envelope"xmlns:dp="http://www.datapower.com/schemas/management">

<mAdminState>enabled</mAdminState><MatchRules>

<Type>url</Type><HttpTag /><HttpValue /><Url>*</Url><ErrorCode /><XPATHExpression />

</MatchRules><MatchWithPCRE>off</MatchWithPCRE><CombineWithOr>off</CombineWithOr>

</Matching>

removed="true"Indicates an object that was deleted from the configuration.

modified="true"Indicates an object that was modified in the configuration.

Review the response for these attributes to determine which objects were added to,deleted from, or modified in the configuration.

WSDM interfaceThe DataPower appliance includes an implementation of the Web ServicesDistributed Management (WSDM) protocol specification (Version 1.0 OASIS,February 2006). When enabled, this implementation provides a protocol-specificinterface for managing Web Service endpoints that were instantiated on theappliance through Web Service Proxy objects.

You can use the sample wsdm.xml and wsdmfirm.xml files in the store: directory torequest information from the WSDM interface.

You can use the sample wsrp-status.xsd schema in the store: directory to requestinformation from the WSDM interface.

http://IP-address:WSDM-port/service/wsdm10/wsrp-status.xsd

You can use the sample xml-mgmt-wsdm.wsdl file, which is generated dynamicallyon the appliance, to extract supported status properties. Retrieve this WSDL filefrom the router by sending a request to the following URL:

/service/wsdm10?wsdl

You can discover the capabilities of the WSDM endpoint by issuing a request toreturn a management capability list.<?xml version="1.0" encoding="UTF-8"?><s12:Envelope

xmlns:s12="http://www.w3.org/2003/05/soap-envelope"xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/addressing"xmlns:wsrp="http://docs.oasis-open.org/wsrf/2004/06/

wsrf-WS-ResourceProperties-1.2-draft-01.xsd"xmlns:muws-p1="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"xmlns:muws-p2="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"xmlns:mows="http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd"xmlns:mows-1-1="http://docs.oasis-open.org/wsdm/mows-2.xsd"xmlns:dpt="http://www.datapower.com/schemas/transactions">

<s12:Header><wsa:Action>

http://docs.oasis-open.org/wsrf/2004/06/WS-ResourceProperties/GetResourceProperty

</wsa:Action><wsa:To s12:mustUnderstand="1">

https://127.0.0.1:5550/service/wsdm10></wsa:To><dpt:DomainDisambiguator>wsdm</dpt:DomainDisambiguator><dpt:ResourceTypeDisambiguator>wsm/endpoint</dpt:ResourceTypeDisambiguator><dpt:InstanceDisambiguator>

http://0.0.0.0:14000/wsdm/service-a</dpt:InstanceDisambiguator>

</s12:Header><s12:Body>

<wsrp:GetResourceProperty>

muws-p1:ManageabilityCapability</wsrp:GetResourceProperty>

</s12:Body></s12:Envelope>

Note that the <dpt:DomainDisambiguator> node must be set to an existingapplication domain on the appliance or set to default. If the domain does notexist, an error will result.

The type of request returns a list of capabilities, such as the following list:<s12:Envelope xmlns:dpt="http://www.datapower.com/schemas/transactions"

xmlns:mows="http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd"xmlns:mows-1-1="http://docs.oasis-open.org/wsdm/mows-2.xsd"xmlns:muws-p1="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"xmlns:muws-p2="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"xmlns:s12="http://www.w3.org/2003/05/soap-envelope"xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/addressing"xmlns:wsrp="http://docs.oasis-open.org/wsrf/2004/06/

wsrf-WS-ResourceProperties-1.2-draft-01.xsd">

<s12:Header><wsa0:Action xmlns:wsa0="http://schemas.xmlsoap.org/ws/2003/03/addressing">

http://docs.oasis-open.org/wsrf/2004/06/WS-ResourceProperties/GetResourcePropertyResponse

</wsa0:Action></s12:Header><s12:Body>

<wsrp:GetResourcePropertyResponse><muws-p1:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Identity</muws-p1:ManageabilityCapability><muws-p1:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/ManageabilityCharacteristics

</muws-p1:ManageabilityCapability><muws-p1:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/OperationalStatus</muws-p1:ManageabilityCapability><muws-p1:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/OperationalStatus</muws-p1:ManageabilityCapability><muws-p1:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics</muws-p1:ManageabilityCapability><muws-p1:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Identification</muws-p1:ManageabilityCapability><muws-p1:ManageabilityCapability>

http://docs.oasis-open.org/wsdm/2004/12/mows/capabilities/Metrics</muws-p1:ManageabilityCapability><muws-p1:ManageabilityCapability>

http://docs.oasis-open.org/mows-2/capabilities/Metrics</muws-p1:ManageabilityCapability><muws-p1:ManageabilityCapability>

http://docs.oasis-open.org/mows-2/capabilities/OperationMetrics</muws-p1:ManageabilityCapability>

</wsrp:GetResourcePropertyResponse></s12:Body>

</s12:Envelope>

This list contains the supported capabilities. Use the standards-specified requestformats to use these capabilities.

Example request to view the number of client requestsThe following example shows a request to view the number of client requests tothe particular service.<?xml version="1.0" encoding="UTF-8"?><s12:Envelope

xmlns:s12="http://www.w3.org/2003/05/soap-envelope"xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/addressing"xmlns:wsrp="http://docs.oasis-open.org/wsrf/2004/06/

wsrf-WS-ResourceProperties-1.2-draft-01.xsd"xmlns:muws-p1="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd"xmlns:muws-p2="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"xmlns:mows="http://docs.oasis-open.org/wsdm/2004/12/mows/wsdm-mows.xsd"xmlns:mows-1-1="http://docs.oasis-open.org/wsdm/mows-2.xsd"xmlns:dpt="http://www.datapower.com/schemas/transactions">

<s12:Header><wsa:Action>

http://docs.oasis-open.org/wsrf/2004/06/WS-ResourceProperties/GetResourceProperty

</wsa:Action><wsa:To s12:mustUnderstand="1">

https://127.0.0.1:5550/service/wsdm10</wsa:To><dpt:DomainDisambiguator>wsdm</dpt:DomainDisambiguator><dpt:ResourceTypeDisambiguator>wsm/endpoint</dpt:ResourceTypeDisambiguator><dpt:InstanceDisambiguator>

http://0.0.0.0:14000/wsdm/service-a</dpt:InstanceDisambiguator>

</s12:Header><s12:Body>

<wsrp:GetResourceProperty>mows:NumberOfRequests

</wsrp:GetResourceProperty></s12:Body>

</s12:Envelope>

Example request to view active usersThe following example shows a request to view active users on the appliance:<s12:Body>

<wsrp:GetResourcePropertyResponsexmlns:mows-1-1="http://docs.oasis-open.org/wsdm/mows-2.xsd">

<status.active-users xmlns="http://www.datapower.com/schemas/management"><ActiveUsers>

<session>48</session><name>admin</name><connection>web-gui</connection><address>10.10.13.35</address><login>Tues Oct 16 08:53:33 2007</login><domain>default</domain>

<session>49</session><name>CLIAdmin</name><connection>cli</connection><address>10.10.13.35</address><login>Tues Oct 16 08:54:12 2007</login><domain>default</domain>

<session>50</session><name>JulieSmith</name><connection>web-gui</connection><address>10.10.13.35</address><login>Tues Oct 16 08:54:48 2007</login><domain>default</domain>

</ActiveUsers></status.active-users>


Example request to view CPU usageThe following example shows a request to view CPU usage on the appliance:<s12:Body>


<status.cpu xmlns="http://www.datapower.com/schemas/management"><CPUUsage>

<tenSeconds>23</tenSeconds><oneMinute>24</oneMinute><tenMinutes>22</tenMinutes><oneHour>23</oneHour><oneDay>23</oneDay>

</CPUUsage></status.cpu>


Example request to view appliance usageThe following example shows a request to view appliance usage on the appliance:<s12:Body>


<status.system xmlns="http://www.datapower.com/schemas/management"><SystemUsage>

<Interval>1000</Interval><Load>30</Load><WorkList>0</WorkList>

</SystemUsage></status.system>


Example request to view accepted connectionsThe following example shows a request to view accepted connections on theappliance:<s12:Body>


<status.accepted-connectionsxmlns="http://www.datapower.com/schemas/management">

<ConnectionsAccepted><tenSeconds>0</tenSeconds><oneMinute>0</oneMinute><tenMinutes>5</tenMinutes><oneHour>613</oneHour><oneDay>8979</oneDay>

</ConnectionsAccepted></status.accepted-connections>

Chapter 10. Managing the firmware image

Before performing a firmware upgrade, contact IBM Customer Support and refer tothe IBM WebSphere DataPower SOA Appliances: Upgrade and Rollback Guide:Generation 2 Firmware. This document is available on the DataPower Support Website.

Applying a firmware imageUse the following procedure to apply a firmware image, which might be anupgrade:1. Select Administration → Main → System Control to display the System Control

panel.2. Locate the Boot Image section of the System Control panel.3. If the desired firmware file is not on the appliance, click Upload or Fetch. Refer

to Chapter 11, “Managing files,” on page 115 for details.4. From the Firmware File list, select the firmware file.5. Click Boot Image to boot the appliance with the selected file.6. Click Confirm to apply the upgrade and reboot the appliance.

An additional confirmation screen is display that confirms that the firmware filewas installed.

The appliance can take up to 3 minutes to reboot.

Rolling back an upgradeUse the following procedure to roll back to the previous firmware image:1. Select Administration → Main → System Control to display the System Control

panel.2. Locate the Firmware Roll-Back section of the System Control panel.3. Click Firmware Roll-Back.4. Click Confirm.

The appliance is rolled back to the last-installed release.


Chapter 11. Managing files

The appliance contains no hard drive for file storage. As a result, the storage spacefor files and other artifacts is limited.

Directories on the applianceThe file system contains many examples and critical configuration files. Thesedirectories and their contents are as follows:

audit: This directory contains the audit logs. Each appliance contains only oneaudit: directory. This directory cannot be the destination of a copy. Thisdirectory is available from the command line in the default domain only.

To view the audit log from the WebGUI, select Status → View Logs → AuditLog.

cert: This encrypted directory contains private key and certificate files thatservices use in the domain. You can add, delete, and view files, but youcannot modify these files while in the domain. Each application domaincontains one cert: directory. This directory is not shared across domains.

chkpoints:This directory contains the configuration checkpoint files for the appliance.Each application domain contains one chkpoints: directory. This directoryis not shared across domains.

config:This directory contains the configuration files for the appliance. Eachapplication domain contains one config: directory. This directory is notshared across domains.

dpcert:This encrypted directory contains files that the appliance itself uses. Thisdirectory is available from the command line in the default domain only.

export:This directory contains the exported configurations that are created withthe Export Configuration utility. Each application domain contains oneexport: directory. This directory is not shared across domains.

image: This directory contains the firmware images (primary and secondary) forthe appliance. This directory is where firmware images are stored typicallyduring an upload or fetch operation. Each appliance contains only oneimage: directory. This directory is available in the default domain only.

local: This directory contains miscellaneous files that are used by the serviceswithin the domain, such as XSL, XSD, and WSDL files. Each applicationdomain contains one local: directory. This directory can be made visible toother domains. When viewed from other domains, the directory namechanges from local: to the name of the application domain.

logstore:This directory contains log files that are stored for future reference.Typically, the logging targets use the logtemp: directory for active logs. Youcan move log files to the logstore: directory. Each application domaincontains one logstore: directory. This directory is not shared acrossdomains.


logtemp:This directory is the default location of log files, such as theappliance-wide default log. This directory can hold only 13 MB. Thisdirectory cannot be the destination of a copy. Each application domaincontains one logtemp: directory. This directory is not shared acrossdomains.

pubcert:This encrypted directory contains the security certificates that are usedcommonly by Web browsers. These certificates are used to establishsecurity credentials. Each appliance contains only one pubcert: directory.This directory is shared across domains.

sharedcert:This encrypted directory contains security certificates that are shared withpartners. Each appliance contains only one sharedcert: directory. Thisdirectory is shared across domains. However, you must be in defaultdomain to create or upload keys and certificates.

store: This directory contains example style sheets, default style sheets, andschemas that are used by the local appliance. Do not modify the files inthis directory.

Each appliance contains only one store: directory. By default, this directoryis visible to all domains. You can make changes to the contents of thisdirectory from the default domain only.

The store: directory has the following subdirectories:

meta This encrypted subdirectory contains files that are used by theappliance itself.

msgcatThis subdirectory contains the message catalogs.

policiesThis subdirectory contains the following subdirectories. Thecontents of these subdirectories affect Web services policy.

customThis subdirectory contains custom style sheets.

mappingsThis subdirectory contains mapping style sheets.

templatesThis subdirectory contains XML files.

profilesThis subdirectory contains style sheets that are used by DataPowerservices.

schemasThis subdirectory contains schemas that are used by DataPowerservices.

dp This encrypted subdirectory contains files that are used by theappliance itself. This subdirectory is available from the commandline only.


pubcertsThis encrypted subdirectory contains files that are used by theappliance itself. This subdirectory is available from the commandline only.

tasktemplates:This directory contains the XSL files that define the display of specializedWebGUI screens. Each appliance contains only one tasktemplates: directory.This directory is visible to the default domain only.

temporary:This directory is used as temporary disk space by processing rules. Eachapplication domain contains one temporary: directory. This directory is notshared across domains.

Launching the File Management utilityTo manage files, launch the File Management utility with one of the followingmethods:v Select the File Management icon from the Files and Administration section of

the Control Panel.v Select Administration → Main → File Management.

Either method displays the File Management screen. The initial screen shows thetop level directories.

Displaying directory contentsTo display (expand) the contents of a directory, perform the following procedure:1. Launch the File Management utility. Refer to “Launching the File Management

utility” for details.2. Select the directory to display its contents.

To hide (collapse) the content-view of a directory, select that directory again.

Creating a subdirectorySubdirectories can only be creates under the local: directory or one of itssubdirectories.

Follow these steps to create a subdirectory under the local: directory or one of itssubdirectories:1. Launch the File Management utility. Refer to “Launching the File Management

utility” for details.2. From the Action column, click Actions aligned with the directory for the

subdirectory to be created.3. Click Create Subdirectory. The File Management screen displays.4. Enter the name of the new subdirectory in the directory Name field.5. Click Confirm Create. The File Management screen refreshes.6. Click Continue. The File Management screen displays the top-level directories

only.

Chapter 11. Managing files 117

Deleting a directoryDirectories can only be deleted in the local: directory or one of its subdirectories.

Follow these steps to delete a directory under the local: directory or one of itssubdirectories:1. Launch the File Management utility. Refer to “Launching the File Management

utility” on page 117 for details.2. From the Action column, click Actions aligned with the directory to be deleted.3. Click Delete Directory. The File Management screen displays.4. Click Confirm Delete. The File Management screen refreshes.5. Click Continue. The File Management screen displays the top-level directories

only.

Refreshing directory contentsTo refresh contents, click the Refresh Page icon. The WebGUI redraws the FileManagement screen. The screen displays the top-level directories only.

Uploading files from the workstationUse the following procedure to upload a file from your workstation to theappliance:1. Launch the File Management utility. Refer to “Launching the File Management

utility” on page 117 for details.2. Navigate to the directory into which you want to upload the file.3. Click Actions in that row to open the Directory Actions menu.4. Click Upload Files to display the File Upload screen.5. Specify the path-qualified name of the workstation file in the File to upload

field, or click Browse to locate the file on the workstation.6. Specify the file name in the Save as field.

Note: If you used browsing to select the file or if you navigated to this fieldusing the tab key, the field contains the file name.

7. To add another file to be uploaded:a. Click Add.b. Repeat steps 5 and 6.

8. If one of the files already exists in the selected directory and you want tooverwrite this file, check the Overwrite Existing Files check box. If you donot select this check box and the file already exists, the file is not uploaded.

9. Click Upload.10. When the appliance reports success (or an error is the file already existed),

click Continue to return to the File Management screen.

The target directory now contains the uploaded files. To verify, use the proceduredescribed in “Displaying directory contents” on page 117.


Working with Java Key StoresA Java™ Key Store (JKS) is a Sun-proprietary format file that contains private keysand certificates. The java.security package and sub-packages access the data inthe JKS to carry out their cryptographic operations.

Required softwareJKS support requires the following software on the WebGUI workstation:v Version 1.4.2 of the Java runtime environment (j2re1.4.2)v SDK (j2sdk1.4.2)v Internet Explorer

Note: You must have the JRE or Java SDK /bin path name in the Windows® PATHenvironment variable on the WebGUI workstation. The Java Key Store filecannot reside on any of the local directories. It must be uploaded from aworkstation.

Granting permissionsIn addition, the user must have the grant permission for the upload in the.java.policy file on the workstation that contains the Java Key Store files. Thefollowing example .java.policy file should be defined on the workstationcomputer before starting the upload:grant {

permission java.io.FilePermission "<<ALL FILES>>","read";permission java.util.PropertyPermission "*", "read";permission java.lang.RuntimePermission "accessClassInPackage.sun.*";

};

You can grant read-only permission to the JKS file.

Types of key storesSun offers two common methods to support key store creation:v Sun Java 2.1.4.2 runtime environment or SDK use a program called keytool to

create and manage a JKS-type file store with no provider name.v SunJCE (Java Crypto Extension) generates a JCEKS-type (Java Crypto Extension

Key Store) file store with the provider name SunJCE.

You must know the key store type to successfully upload files from a JKS.

Uploading a file from a Java Key StoreUse the following procedure to upload a file from a Java Key Store (JKS) to theappliance:1. Launch the File Management utility. Refer to “Launching the File Management

utility” on page 117 for details.2. Navigate to the directory into which you want to upload the file.3. Click Actions in that row to open the Directory Actions menu.4. Click Upload Files to display the File Upload screen.5. Click the Java Key Store radio button to display the JKS Upload screen.

Note: When you click the Java Key Store radio button, the Java Console ofthe browser opens and shows whether the Java Key Store Access

Applet is running. If the applet cannot be accessed, you cannot uploadJKS files. Ensure that your browser is enabled to use the Java 1.4.2applet.

6. Specify the full path to the target JKS in the Java key store field or clickBrowse.

7. Specify JKS or JCEKS (the JKS type) in the Key store type field.8. If the type is JCEKS, specify SunJCE (the provider name) in the Key store

provider field. Otherwise, leave blank.9. Specify the JKS password in the Key store password field.

10. Identify the files to upload with the Key to upload list. Use the Refreshbutton, if necessary.

11. Specify the key-specific password in the Key password field.12. Specify the file name in the Save as field.13. If the file already exists in the selected directory and you want to overwrite

this file, check the Overwrite Existing Files check box. If you do not selectthis check box and the file already exists, the file is not uploaded.

14. Click Upload.15. When the appliance reports success, click Continue to return to the File

Management screen.

The target directory now contains the uploaded key or certificate. To verify that thefile exists, use the procedure described in “Displaying directory contents” on page117.

If the upload fails, look at the Java Console of the browser to determine whetheran exception was thrown.

Fetching filesUse the following procedure to retrieve a file from a remote URL (fetch) and storethat file in a specified directory on the appliance:1. Launch the File Management utility. Refer to “Launching the File Management

utility” on page 117 for details.2. Navigate to the directory into which you want to upload the file.3. Click Actions in that row to open the Directory Actions menu.4. Click Fetch Files to display the Fetch File screen.5. Specify the location of the file in the Source URL field.6. Specify the file name in the Save as field.7. If the file already exists in the selected directory and you want to overwrite this

file, check the Overwrite Existing Files check box. If you do not select thischeck box and the file already exists, the file is not uploaded.

8. Click Fetch.9. When the appliance reports success, click Continue to return to the File

Management screen.

The target directory now contains the retrieved file. To verify, use the proceduredescribed in “Displaying directory contents” on page 117.

Copying filesUse the following procedure to copy a file from one directory to another:


1. Launch the File Management utility. Refer to “Launching the File Managementutility” on page 117 for details.

2. Navigate to the directory that contains the files to be copied.3. Select files by clicking the box adjacent to the file name.4. Scroll to the top or bottom of the screen and click Copy to display the File

Copy screen.5. From the New Directory Name list, select the target directory.6. Specify the name for the file, if different, in the New File Name field.7. If one of the selected files already exists in its associated target directory and

you want to overwrite this file, check the Overwrite Existing Files check box. Ifyou do not select this check box and the file already exists, the file is notcopied.

8. Click Confirm Copy to copy the files to the target directories.9. When the appliance reports success, click Continue to return to the File

Management screen.

The target directories now contain the copied files. To verify that the files exist, usethe procedure described in “Displaying directory contents” on page 117.

Renaming filesUse the following procedure to rename a file:1. Launch the File Management utility. Refer to “Launching the File Management

utility” on page 117 for details.2. Navigate to the directory that contains the files to be copied.3. Select files by clicking the box adjacent to the file name.4. Click Rename to display the File Rename screen.5. Specify the name of the file in the New File Name field.6. If one of the selected files already exists in the target directory and you want to

overwrite this file, check the Overwrite Existing Files check box. If you do notselect this check box and the file already exists, the file is not copied.

7. Click Confirm Rename.8. When the appliance reports success, click Continue to return to the File

Management screen.

The target directories now contain the renamed files. To verify that the files exist,use the procedure described in “Displaying directory contents” on page 117.

Moving filesUse the following procedure to move a file from one directory to another:1. Launch the File Management utility. Refer to “Launching the File Management

utility” on page 117 for details.2. Navigate to the directory that contains the files to be moved.3. Select files by clicking the box adjacent to the file name.4. Click Move to display the Move File screen.5. From the New Directory list, select the target directory.6. If one of the selected files already exists in its directory and you want to

overwrite this file, select the Overwrite Existing Files check box. If you do notselect this check box and the file already exists, the file is not moved.


7. Click Confirm Move.8. When the appliance reports success, click Continue to return to the File

Management screen.

The target directories now contain the moved files. To verify that the files exist, usethe procedure described in “Displaying directory contents” on page 117.

Viewing filesUse the following procedure to view a text file:1. Launch the File Management utility. Refer to “Launching the File Management

utility” on page 117 for details.2. Navigate to the directory that contains the file.3. Click the file to open a browser that contains the file.

When finished viewing the file, close the browser.

Editing filesUse the following procedure to edit a text file:1. Launch the File Management utility. Refer to “Launching the File Management

utility” on page 117 for details.2. Navigate to the directory that contains the files to be edited.3. Select the file to be edited by clicking Edit in the row that is associated with

that file. The WebGUI displays a file preview.4. Click Edit to change to Edit Mode.5. Edit the file as required.6. Click Submit to complete the edit process.7. When the appliance reports success, click Close to return to the File

Management screen.

Deleting filesUse the following procedure to delete a file:1. Launch the File Management utility. Refer to “Launching the File Management

utility” on page 117 for details.2. Navigate to the directory that contains the files to be deleted.3. Select files by clicking the box adjacent to the file name.4. Scroll to the top or bottom of the screen and click Delete to display the Delete

File screen.5. Click Confirm Delete to delete the files.6. When the appliance reports success, click Continue to return to the File

Management screen.

The selected files were deleted. To verify that the files no longer exist, use theprocedure described in “Displaying directory contents” on page 117.


Chapter 12. Managing auxiliary data storage

Depending on the model, each Type 9235 appliance has one of the following typesof auxiliary data storage:v Compact flash storage cardv Hard disk array

After you configure and enable auxiliary data storage, you can access the availablefiles in defined subdirectory. This subdirectory is in the local: and logstore:directories in each application domain.

Note: Other model types for DataPower appliances do not provide hardware tosupport auxiliary data storage.

Configuring the compact flashTo configure the compact flash as auxiliary data storage, use the followingprocedure:1. Select Administration → Storage Devices → Compact Flash to display the

catalog.2. Click the name of the compact flash to display the configuration screen.3. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.4. Use the Read-Only toggle to indicate whether the files on the compact flash

have read-only access.

on Sets the files as read-only access.

off (Default) Sets the files to read-write access.5. In the Directory field, specify the directory under which to make the files on

the compact flash available in the local: and logstore: directories in eachapplication domain.


Managing the file system on the compact flashTo manage the file system on the compact flash, you might need to perform one ofthe following actions:v Initialize the file systemv Repair the file system

Initializing the file systemInitializing the file system on the compact flash allows it to be made active. Wheninvoked against auxiliary data storage that contains content, this action destroysthe existing content.

To initialize the file system on the compact flash, use the following procedure:1. Select Administration → Storage Devices → Compact Flash to display the

catalog.


2. Click the name of the compact flash to display the configuration screen.3. Click Initialize File System.4. Follow the prompts.

Repairing the file systemYou might need to repair the file system on the compact flash if its contents werecorrupted by an abnormal shutdown of the appliance or other error.

To repair the file system on the compact flash, use the following procedure:1. Select Administration → Storage Devices → Compact Flash to display the

catalog.2. Click the name of the compact flash to display the configuration screen.3. Click Repair File System.4. Follow the prompts.

Configuring the hard disk arrayTo configure the hard disk array as auxiliary data storage, use the followingprocedure:1. Select Administration → Storage Devices → Hard Disk Array to display the

catalog.2. Click the name of the hard disk array to display the configuration screen.3. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.4. Use the Read-Only toggle to indicate whether the files on the hard disk array

have read-only access.

on Sets the files as read-only access.

off (Default) Sets the files to read-write access.5. In the Directory field, specify the directory under which to make the files on

the hard disk array available in the local: and logstore: directories in eachapplication domain.


Managing the file system on the hard disk arrayTo manage the file system on the hard disk array, you might need to perform oneof the following actions:v Initialize the file systemv Repair the file system

Initializing the file systemInitializing the file system on the hard disk array allows it to be made active.When invoked against auxiliary data storage that contains content, this actiondestroys the existing content.

To initialize the file system on the hard disk array, use the following procedure:1. Select Administration → Storage Devices → Hard Disk Array to display the

catalog.2. Click the name of the hard disk array to display the configuration screen.


3. Click Initialize File System.4. Follow the prompts.

Repairing the file systemYou might need to repair the file system on the hard disk array if its contents werecorrupted by an abnormal shutdown of the appliance or other error.

To repair the file system on the hard disk array, use the following procedure:1. Select Administration → Storage Devices → Hard Disk Array to display the

catalog.2. Click the name of the hard disk array to display the configuration screen.3. Click Repair File System.4. Follow the prompts.

Managing the RAID volumeTo manage the RAID volume of the hard disk array, you might need to performone of the following actions:v Activate the volumev Initialize the volumev Rebuild the volumev Delete the volume

Activating the volumeYou might need to activate the RAID volume to change the state of the hard diskarray to active. Generally, you need to perform this action when the hard diskarray volume is in the inactive state, typically with the foreign volume inactivestate. After activating the RAID volume, it will be accepted as a local volume.

To activate the RAID volume of the hard disk array, use the following procedure:1. Select Administration → Storage Devices → Hard Disk Array to display the

catalog.2. Click the name of the hard disk array to display the configuration screen.3. Click Activate RAID-1 Array.4. Follow the prompts.

Initializing the volumeYou might need to initialize the RAID volume. This action makes the disks into aRAID volume. This action destroys all content.

To initialize the RAID volume of the hard disk array, use the following procedure:1. Select Administration → Storage Devices → Hard Disk Array to display the

catalog.2. Click the name of the hard disk array to display the configuration screen.3. Click Initialize RAID-1 Array.4. Follow the prompts.

Rebuilding the volumeYou might need to rebuild the RAID volume. This action copies the contents fromthe primary disk in the array to the secondary disk.

Chapter 12. Managing auxiliary data storage 125

To rebuild the RAID volume of the hard disk array, use the following procedure:1. Select Administration → Storage Devices → Hard Disk Array to display the

catalog.2. Click the name of the hard disk array to display the configuration screen.3. Click Rebuild RAID-1 Array.4. Follow the prompts.

Deleting the volumeYou might need to delete the RAID volume. This action makes the disks that arepresently a RAID volume no longer a RAID volume. This action destroys allcontent, including all metadata.

To delete the RAID volume of the hard disk array, use the following procedure:1. Select Administration → Storage Devices → Hard Disk Array to display the

catalog.2. Click the name of the hard disk array to display the configuration screen.3. Click Delete RAID-1 Array.4. Follow the prompts.


Chapter 13. Managing the configuration of the appliance

This chapter provide information about managing the configuration of theappliance, managing application domains, and importing and exportingconfigurations.

Managing domainsWhen initialized, a DataPower appliance has a default domain. The appliancesupports the addition of application domains. An application domain consists ofthose resources that are configured to provide and support one or more services.

After a log in to an application domain, all configuration activities apply to thisapplication domain only. This control provides a level of administrativepartitioning and safety. For example, users in domainA cannot alter services indomainB.

The default domainA number of appliance-wide resources and settings can be defined only in thedefault domain. The following list contains a subset of the appliance-wideresources that can be set in default domain only:v Network interfacesv Users and access controlsv Application domains

After any user enters an application domain, either though logging in or switchingdomains, that use can no longer access appliance-wide resources. When viewedfrom the main navigation area, these resources are disabled.

The default domain cannot be deleted.

Application domainsApplication domains can only be created in the default domain.

When configuring an application domain, specific directories in other domains canbe made visible.

Users can be assigned to specific application domains to allow for greateradministrative control. Users that are restricted to specific application domains, canperform activities in only those application domains (provided that the user hasthe appropriate access controls). Services defined in one application domain cannotbe shared with another application domain.

Application domains can be restarted independently without affecting any otherdomain and without requiring a restart of the entire appliance. When a domain isrestarted, the persisted configuration file for that domain is used, which mightchange the running configuration of the domain.


A domain can read its configuration from a locally stored file or from a file that isstored on a remote, central configuration server. The use of a remote configurationfile enables centralized management of multiple domains across multipleappliances.

When creating a new application domain from an imported package, refer to“Importing configuration data” on page 140.

Visible domainsWhen the default domain or an application domain is made visible duringconfiguration, the domain being configured can see specific directories from thespecified visible domains. Being able to see the files in a directory allows resourceconfigurations to be common across application domains.v When the default domain is made visible, the application domain being

configured has read access to the store: directory of the default domain. Whenviewed through the File Management utility, the directory shows up in thelisting as store. By default, the default domain is visible to all applicationdomains. The store: directory contains DataPower-supplied processing resources,such as style sheets, schemas, and files for authentication and authorization.

v When an application domain is made visible, the application domain beingconfigured has read access to the local: directory of the specified applicationdomain. When viewed through the File Management utility, the directory showsup in the listing as the domain name. For example, if domainB is made visible todomainA, the local: directory of domainB would show up as domainB when viewedfrom domainA.

Note: References to visible domains are explicit, not bidirectional. If domainA ismade visible to domainB, domainB cannot see domainA. In this case, youcannot make domainA visible to domainB. References to visible domainscannot be circular.

Creating application domainsTo create an application, use the following procedure:1. Select Administration → Configuration → Application Domain to display the

Application Domain catalog.2. Click Add to display the Configure Application Domain (Main) screen.

a. Specify the name of the object in the Name field.b. Retain the default setting for the Admin State toggle. To place the object in

an inactive administrative state, click disabled.c. Specify a descriptive object-specific summary in the Comment field.d. Use the Visible Domains controls to select the application domains that this

application domain can see.e. Use the local: File Permissions check boxes to select the desired file access

permissions. These permissions apply to the local: directory of the newapplication domain.

f. Use the ’local:' File Monitoring check boxes to select the desired monitoringand logging states for files in the local: directory. Logging and auditing eachcreates a record of file accesses and activities that can be useful at a laterdate to determine changes to files.

3. Define the type of domain configuration mode to use.a. Click the Configuration tab.


b. Specify the maximum number of configuration checkpoints to allow in theConfiguration Checkpoint Limit field. Use an integer in the range of 1through 5. The default is 3.

c. Select the desired configuration mode from the Configuration Mode list.

Local(Default) Reads the domain configuration from a local configurationfile.

ImportImports the domain configuration from a remote configuration file.When you selected Import:1) Specify a URL for the file in the Import URL field.2) Select the file format from the Import Format list.

ZIP (Default) Indicates that the configuration package is in ZIPformat. If the format is ZIP, the bundle is unzippedautomatically.

XML Indicates that the configuration package in XML format.3) (Optional) Select a Deployment policy from the Deployment

Policy list. The package to import is preprocessed before beingapplied to the configuration file. For more information, refer toChapter 14, “Configuring deployment policies,” on page 145.

4) Select whether to allow local IP addresses to be rewritten to matchequivalent interfaces on the appliance with the Local IP Rewritetoggle.

on (Default) Allows local IP addresses to be rewritten.

off Does not allow local IP addresses to be rewritten.5) Click Apply to save the object to the running configuration.6) Optionally, click Save Config to save the object to the startup

configuration.

Restarting application domainsYou can restart an application domain, including the default domain, withoutrestarting the entire appliance. The application domain is reloaded using thecurrently saved configuration for the domain. The saved configuration could bedifferent than the running configuration of the domain. If the runningconfiguration of the domain is different than the saved configuration, a noticeappears at the top of the screen.

You can restart application domains in one of the following ways:v From the System Control panelv From the Application Domain catalog

Restarting from the System Control panelTo restart the current application domain from the System Control panel, use thefollowing procedure:1. Select Administration → Main → System Control to display the System Control

panel.2. Locate the Restart Domain section.3. Click Restart Domain.4. Follow the prompts.

Chapter 13. Managing the configuration of the appliance 129

Restarting from the catalogTo restart an application domain from the object catalog, use the followingprocedure:1. Select Administration → Configuration → Application Domain to display the

Application Domain catalog.2. Click on the name of the domain to display the domain-specific configuration

screen.3. Click Restart Domain.4. Follow the prompts.

Resetting application domainsYou can reset an application domain, including the default domain, to delete theconfiguration of the domain. Resetting a domain is different from deleting andrecreating a domain.v Resetting a domain deletes all configured objects in the domain but retains the

configuration of the domain and retains all files in the local: directory.v Deleting a domain deletes all configured objects in the domain, deletes all files

in the domain, and deletes the configuration of the domain itself.

You can reset domains in one of the following ways:v From the System Control panelv From the Application Domain catalog

Resetting from the System Control panelTo reset the current application domain from the System Control panel, use thefollowing procedure:1. Select Administration → Main → System Control to display the System Control

panel.2. Locate the Reset Domain section.3. Click Reset Domain.4. Follow the prompts.

Resetting from the catalogTo reset an application domain from the object catalog, use the followingprocedure:1. Select Administration → Configuration → Application Domain to display the

catalog.2. Click on the name of the domain to display the configuration screen.3. Click Reset Domain.4. Follow the prompts.

Creating Include Configuration File objectsInclude Configuration File objects allow you to include configuration informationfrom an external configuration file in the local configuration information. Thisexternal file can be stored on a centralized configuration server or anotherDataPower appliance. The information in the Include Configuration File object isappended to the local configuration information when the configuration of theDataPower appliance is reloaded (such as during appliance reboot, firmwarereload, or domain restart).


An Include Configuration File object can include configuration information only.On the other hand, an Import Configuration File object is a configuration packagethat can include both configuration information and supporting files.

To append configuration information from an external file to the localconfiguration information, perform the following procedure:1. Select Objects → Configuration Management → Include Configuration File to

display the catalog.2. Click the name of an existing Include Configuration File object to edit it, or

click Add to create a new one. The Include Configuration File configurationscreen is displayed.


inactive administrative state, click disabled.5. Specify a descriptive object-specific summary in the Comment field.6. Specify the URL of the configuration file in the URL of Configuration File

field. For example, specify https://config.server.com/datapower/firewalls.cfg.

7. Use the Execute on Startup toggle to indicate whether to import theconfiguration package at startup.

on (Default) Imports the configuration package at startup. Theconfiguration is marked external and cannot be saved to the startupconfiguration. This behavior is equivalent to always importing theconfiguration.

off Imports the configuration package when manually triggered. Theconfiguration is not marked external and can be saved to the startupconfiguration. This behavior is equivalent to importing theconfiguration one time.

8. When retrieving the configuration file, select when to retrieve theconfiguration file with the Interface Detection toggle.

on Retrieves the configuration file after the local interface is up.

off (Default) Retrieves the configuration file at appliance reload withoutwaiting for the local interface to be up.


Note: Unless you click Save Config, the included configuration file will not takeaffect when the appliance is started.

Creating Import Configuration File objectsImport Configuration File objects allow you to import a configuration packagefrom an external configuration file into the local configuration information. Theexternal file can be stored on a centralized configuration server or anotherDataPower appliance. The configuration data and files in the configuration file isadded to the local configuration information when the configuration of theDataPower appliance is reloaded (such as during appliance reboot, firmwarereload, or domain restart). The default configuration of an Import ConfigurationFile object does not provide warnings about conflicts with existing files andobjects.


An Import Configuration File object is a configuration package that can includeboth configuration information and supporting files. On the other hand, an IncludeConfiguration File object can include configuration information only.

To import a configuration package from an external file to the local configurationinformation, perform the following procedure:1. Select Objects → Configuration Management → Import Configuration File to

display the catalog.2. Click the name of an existing configuration package to edit it, or click Add to

create a new one. The Import Configuration File configuration screen isdisplayed.


inactive administrative state, click disabled.5. Specify a descriptive object-specific summary in the Comment field.6. Specify the URL of the configuration package in the URL of Configuration

Package field. For example, specify https://config.server.com/datapower/firewalls.zip.

Note: You cannot use the SCP or SFTP protocol to retrieve a configurationpackage. All other URL protocols are available; for example, HTTP,HTTPS, or FTP.

7. Select the package format from the Format of Configuration Package list.

ZIP (Default) Indicates that the configuration package is in ZIP format. Ifthe format is ZIP, the bundle is unzipped automatically.

XML Indicates that the configuration package in XML format.8. Use the Overwrite Files toggle to control the overwrite behavior.

on (Default) Overwrites files of the same name.

off Does not import the file if a file of the same name exists.9. Use the Overwrite Objects toggle to control the overwrite behavior.

on (Default) Overwrites objects of the same name.

off Does not import the objects if an objects of the same name exists.10. (Optional) Select a deployment policy that preprocesses the configuration

package from the Deployment Policy list. For more information, refer toChapter 14, “Configuring deployment policies,” on page 145.

11. Use the Local IP Rewrite toggle to indicate whether to rewrite local IPaddresses on import.

on (Default) Rewrites IP addresses to match the local configuration whenimported. For example, a service in the configuration package thatbinds to eth1 is rewritten to bind to eth1 when imported.

off Retains the original IP address in the configuration package.12. Use the Import on Startup toggle to indicate whether to import the

configuration package at startup.

on (Default) Imports the configuration package at startup. Theconfiguration is marked external and cannot be saved to the startupconfiguration. This behavior is equivalent to always importing theconfiguration.

off Imports the configuration package when manually triggered. The


configuration is not marked external and can be saved to the startupconfiguration. This behavior is equivalent to importing theconfiguration one time.


Backing up and exporting configuration dataThe backup and export utility copies specified configuration data from theappliance to a file in the export: directory. You can optionally download the file toyour workstation.

Note: Exported configuration data should not be imported to an appliance with anearlier release level. Between releases, configuration data for properties canchange. If you attempt to import configuration data from an appliance of alater release level into an appliance of an earlier release level, the operationmight report success, but the configuration data might not be the same.Therefore, use this utility to exchange configuration data among appliancesof the same release level.

You can use this utility to perform the following operations:v Create a backup of the entire appliancev Create a backup of one or more application domainsv Export select objects from the current domainv Copy or move select objects between domains

Note: The following objects are never exported:v User account objectsv Certificate objectsv Key objects (HSM appliances only)

The following files are never exported:v Log filesv Firmware files

To ensure that all other objects and files are exported, use the admin account.For any other user, only objects and files that are accessible to that user areincluded in the export package.

To start a back up or export operation, select Administration → Configuration →Export Configuration to display the initial Export Configuration screen. Thisscreen provides the following export options:v Create a backup of the entire system

v Create a backup of one or more application domains

v Export configuration and files from the current domain

v Copy or move configuration and files between domains

Backing up the entire applianceUse the following procedure to back up (export) all configuration data for theappliance.


1. Select Administration → Configuration → Export Configuration to display theInitial Export Configuration screen.

2. Select Create a backup of the entire system and click Next to display the FileName screen.a. Specify a descriptive object-specific summary in the Comment field.b. Optionally create or select the name of a Deployment Policy to accept, filter,

or modify a configuration during import.c. The Export File Name defaults to export (.zip). If a file of this name exists

in the export: directory, it is overwritten.d. Click Next. The configuration of the entire appliance is backed up.

When the backup completes, the file is in the export: directory. You can optionallydownload the export file to your workstation.

Note: The Import Configuration utility requires that the export file resides on yourworkstation.

3. Optionally click Download to download the file to your workstation.4. Click Done to close this window and return to the Control Panel.

The export file can be accessed from the export: directory. If downloaded, theexport file is on your workstation.

Backing up domainsBest practice is to periodically back up all domains individually.

To back up configuration information for one or more application domains, followthis procedure:1. Select Administration → Configuration → Export Configuration to display the

Initial Export Configuration screen.2. Select Create a backup of one or more application domains and click Next to

display the selection screen.3. Provide the following inputs:

a. Specify a descriptive object-specific summary in the Comment field.b. Optionally create or select the name of a Deployment Policy to accept, filter,

or modify a configuration during import.c. The Export File Name defaults to export (.zip). If a file of this name exists

in the export: directory, it is overwritten.d. Select the check boxes adjacent to each domain to export.e. Click Next






Exporting select objectsThe Export Configuration utility remains available from the initial ExportConfiguration screen. To export select objects and files, use the followingprocedure:1. Select Administration → Configuration → Export Configuration to display the

Initial Export Configuration screen.2. Select Export configuration and files from the current domain and click Next

to display the Export Configuration screen.3. Provide the following inputs:

a. Specify a descriptive object-specific summary in the Comment field.b. Optionally create or select the name of a Deployment Policy to accept, filter,

or modify a configuration during import.c. The Export File Name defaults to export (.xml or .zip depending on the

selected export format). If a file of this name exists in the export: directory,it is overwritten.

d. Use the To radio buttons to specify the export format.

XML ConfigExports configuration data as XML files. Include Configuration filesare referenced in the XML document only, they are not included.

ZIP BundleExports configuration data in compressed ZIP format. IncludeConfiguration files are in the bundle.

e. Use the Configuration radio button to specify the data to export.

Currently running configurationExports the configuration data from the running configuration, notthe startup configuration.

Last persisted configurationExports the configuration data from the startup configuration, notthe current running configuration.

f. Use the Referenced Objects radio buttons to specify the scope of the data toexport.

Include only the selected base objectsExports only the configuration data for the selected objects.

Include all objects required by selected base objectsExports configuration data for the selected objects and all objectsthat are required by the selected objects. For example, if exporting anXSL Proxy, the export includes configuration data for the XSL Proxy,the assigned XML manager, and all associated matching rules,processing policies, processing rules, cryptographic certificates,credentials, and keys.

g. Use the Export Files radio buttons to specify the scope of the data toexport.

Export no filesNo files are included in the export. If, for example, the selectedobjects use files, such as a style sheet, those files are not included.This option is useful when the configuration data itself is all that isneeded.


Export files referenced by exported objectsIn addition to the selected objects (and possibly referenced objects),exports public files that are associated with the selected objects.

Note: The export does not include private files. These files are in thecert: and sharedcert: directories.

Export all local filesExports public files that are associated with the selected objects andall files that are in the following directories:v config:v local:v pubcert:v store:v tasktemplates:

h. From the Objects list, select the type or class of configuration data toexport.After selecting an entry, all instances of that type or class are listed in theleft-hand box.1) Select the objects from the left-hand list. To select multiple objects, select

objects in combination with the Shift and Control keys.2) Click > to move the selected object to the Selected Base Objects list.

i. Adjust the Selected Base Objects list, if necessary.1) Select objects in the right-hand list. To select multiple objects, select

objects in combination with the Shift and Control keys.2) Click < to remove the selected objects or click <<to remove all objects

from the Selected Base Objects list.j. Click Show Contents at any time to display all contents marked for

inclusion in the export.k. Click Next.





Copying or moving select objectsThe copy or move utility is available from the initial Export Configuration screen.To copy or move selected objects and files, use the following procedure:1. Select Administration → Configuration → Export Configuration to display the

Initial Export Configuration screen.2. Select Copy or move configuration and files between domains and click Next

to display the Export Configuration screen.a. Optionally create or select the name of a Deployment Policy to accept, filter,

or modify a configuration during import.

b. Use the Delete After Export toggle to indicate whether the operation is acopy operation or a move operation.

on Indicates a move operation.

off Indicates a copy operation.c. Use the Configuration radio button to specify the data to export.

Currently running configurationExports the configuration data from the running configuration, notthe startup configuration.

Last persisted configurationExports the configuration data from the startup configuration, notthe current running configuration.

d. Use the Referenced Objects radio buttons to specify the scope of the datato export.

Include only the selected base objectsExports only the configuration data for the selected objects.

Include all objects required by selected base objectsExports configuration data for the selected objects and all objectsthat are required by the selected objects. For example, if exportingan XSL Proxy, the export includes configuration data for the XSLProxy, the assigned XML manager, and all associated matchingrules, processing policies, processing rules, cryptographiccertificates, credentials, and keys.

e. Use the Export Files radio buttons to specify the scope of the data toexport.

Export no filesNo files are included in the export. If, for example, the selectedobjects use files, such as a style sheet, those files are not included.This option is useful when the configuration data itself is all that isneeded.

Export files referenced by exported objectsIn addition to the selected objects (and possibly referenced objects),exports public files that are associated with the selected objects.

Note: The export does not include private files. These files are in thecert: and sharedcert: directories.

Export all local filesExports public files associated with the selected objects and all filescontained in the following directories:v config:v image:v pubcert:v store:v tasktemplates:

f. From the Objects list, select the type or class of configuration data to export.After selecting an entry, all instances of that type or class are listed in theleft-hand box.1) Select the objects from the left-hand list. To select multiple objects, select

objects in combination with the Shift and Control keys.


2) Click the > button to move the selected objects to the Selected BaseObjects list.

g. Adjust the Selected Base Objects list, if necessary.1) Select objects in the right-hand list. To select multiple objects, select

objects in combination with the Shift and Control keys.2) Click < to remove the selected objects or click <<to remove all objects

from the Selected Base Objects list.3. Click Show Contents at any time to display all contents marked for inclusion

in the export.4. Click Next to display the Import File window.

a. From the Domain list, select the domain where the configuration data is toimported.

b. Click Import to initiate file transfer.5. Respond to WebGUI prompts.6. Click Done to close the Import File screen.

Managing configuration checkpointsA configuration checkpoint contains configuration data from a specific point intime. The configuration checkpoint might be equivalent to the persistentconfiguration, might be equivalent to the running configuration, or might bedifferent from the persisted configuration or running configuration.

Within each application domain, the administrator who is associated with theadmin account defines the number of configuration checkpoints to allow. You cansave up to the allowed number of configuration checkpoints.

When saved, a ZIP formatted file for the configuration checkpoint is written thechkpoints: directory for that application domain.

Defining number configuration checkpoints to allowThe administrator who is associated with the admin account can define the numberof checkpoint configurations to allow for each application domain. To define thenumber of checkpoint to allow for an existing domain, use the followingprocedure:1. Select Administration → Configuration → Application Domain to display the

Application Domain catalog.2. Select the specific application domain to open the domain-specific configuration

screen.3. Select the Configuration tab.4. Specify the number of checkpoint configuration to allow in the Configuration

Checkpoint Limit field. Use an integer in the range of 1 through 5. The defaultis 3.


Saving configuration checkpointsDo not click Save Config to save a configuration checkpoint. This button does notallow you the option of saving a configuration checkpoint.

To save a configuration checkpoint, use the following procedure:

1. Select Administration → Configuration → Configuration Checkpoints.2. Specify the name of the configuration checkpoint in the Checkpoint Name

field.3. Click Save Checkpoint.4. Respond to WebGUI prompts.

A ZIP-formatted configuration file of the specified name is written to thechkpoints: directory.

You cannot overwrite a configuration checkpoint. You must first delete the originalconfiguration checkpoint before saving a new configuration checkpoint of the samename. For details, refer to “Deleting configuration checkpoints.”

Listing configuration checkpointsYou can view the list of saved configuration checkpoint in one of the followingways:v From the Configuration Checkpoints screenv From the File Management screen

Listing from the Configuration Checkpoints screenTo view from the Configuration Checkpoints screen, select Administration →Configuration → Configuration Checkpoints. This screen displays the list of savedconfiguration checkpoints at the time by name and timestamp.

This section of the screen provides the following actions:

RollbackLoads the configuration that is defined in the configuration checkpoint.

RemoveDeletes the checkpoint configuration from the chkpoints: directory.

CompareLaunches the Compare Configuration utility. For details, refer to“Comparing configurations” on page 142.

Listing from the File Management utilityTo view from the File Management utility, use the following procedure:1. Select the File Management icon from the Control Panel.2. Expand the chkpoints: directory.

Rolling back to a configuration checkpointTo load the configuration that is defined in the configuration checkpoint, use thefollowing procedure:1. Select Administration → Configuration → Configuration Checkpoints. This

screen displays the list of saved configuration checkpoints at the time by nameand timestamp.

2. Click Rollback.3. Respond to WebGUI prompts.

Deleting configuration checkpointsYou can delete configuration checkpoint in one of the following ways:v From the Configuration Checkpoints screen


v From the File Management screen

Deleting from the Configuration Checkpoints screenTo delete from the Configuration Checkpoints screen, use the following procedure:1. Select Administration → Configuration → Configuration Checkpoints. This

screen displays the list of saved configuration checkpoints at the time by nameand timestamp.

2. Click Remove.3. Respond to WebGUI prompts.

Deleting from the File Management screenTo delete from the File Management screen, use the following procedure:1. Select the File Management icon from the Control Panel.2. Expand the chkpoints: directory.3. Select the check box beside the configuration checkpoint file.4. Click Delete.5. Respond to WebGUI prompts.

Importing configuration dataThe import utility copies specified configuration data from your workstation to theDataPower appliance.

Note: Exported configuration data should not be imported to an appliance with anearlier release level. Between releases, configuration data for properties canchange. If you attempt to import configuration data from an appliance of alater release level into an appliance of an earlier release level, the operationmight report success, but the configuration data might not be the same.Therefore, use this utility to exchange configuration data among appliancesof the same release level.

While importing a configuration, you can:v Set the local address bindings of services contained in the export package to

match the equivalent interfaces of the local device with the Rewrite LocalService Addresses toggle (optional).

v Add, modify or delete values in the configuration package being importedwhose values match the defined match statement in a Deployment policy withthe Use Deployment Policy list (optional).

Best practice when the goal is to add, modify or delete values in a configurationpackage is to use a Deployment policy while importing the configuration package.

Use the following procedure to import configuration data.1. Select Administration → Configuration→ Import Configuration to display the

Import Configuration window.a. Use the From radio buttons to specify the import format.

XML ConfigImports configuration data as XML files.

ZIP BundleImports configuration data in compressed ZIP format.

b. Retain the selection of the File radio button.c. Click Browse to select the file to import.


d. Retain the selection of (none) for the Use Deployment Policy list. For moreinformation, refer to the Chapter 14, “Configuring deployment policies,” onpage 145.

e. Use the Rewrite Local Service Addresses toggle to control whether tosubstitute IP addresses:

on (Default) Allows local IP addresses to be rewritten.

off Does not allow local IP addresses to be rewritten.2. Click Next to display the Select Application Domains for Import window. If

there are no objects in the configuration you are importing, skip to step 6c.When importing from any domain other than default, the importedconfiguration applies only to the current domain. The WebGUI might displayan error message when importing data that was exported from the defaultdomain.

3. Select the desired domains. To select all domains, click All. To deselect selecteddomains, click None. If a selected domain does not exist on the appliance, asindicated, it will be created.

4. Click Next to display the Import Object Selection List window.5. Select the objects to import.

Note: Click Save Config to save the configuration for each domain thatcontains imported objects or files.

To effectively complete an appliance import (restore), use the adminaccount. The appliance to be restored must also first be re-initializedthrough the command line.

6. Click Next to display the Import Summary window, which details the contentsof the target file. In some cases, the summary might indicate differences in fileversions.

Note: Warnings can appear on this screen that alert you to a range of possibleconflicts that the imported configuration might cause. Depending on thewarning, you might want to create a new application domain, or youmight want to choose not to overwrite objects or files.

a. Select each item to overwrite. To select all item, click All. To deselectselected items, click None. Only selected items are imported.

b. Click Import to initiate file transfer.At the completion of the import process, the WebGUI displays the ObjectImport Results window, which details the results.

c. Click Done to close this window.

If more than one domain is being imported, the Import Summary window isdisplayed for the next domain to import.

Managing changes in configuration dataYou to create a report that lists the differences between two configurations.Generally, the two configurations that are being compared are the persistedconfiguration and the running configuration. However, you can compare eitherconfiguration to a saved version of the configuration. These saved versions of theconfiguration can be an exported configuration (XML format or ZIP format), abackup configuration (ZIP format only), or a configuration checkpoint.


When you compare configurations, the report provides a list of objects thatchanged between the two configurations and the changes that were made to theseobjects. The report list how the configuration changed:v An object was addedv An object was deletedv An object was modified

Comparing configurationsTo compare configurations, use the following procedure:1. Select Administration → Configuration → Compare Configuration to display

the Configuration Comparison screen.2. From the From list, select which configuration to be the first configuration

source; and from the To list, select which configuration to be the secondconfiguration source. The source for each of the configurations can be one ofthe following:

Persisted ConfigurationThe last saved configuration on the appliance. This is the default in theFrom list.

Running ConfigurationThe configuration that is currently running on the appliance. This is thedefault in the To list.

Domain ConfigurationThe last saved or currently running domain configuration on theappliance.

XML ConfigurationThe XML file that was created during an export operation. This file hasan .xcfg extension.

Export ZIP BundleA ZIP file that was created during an export operation. This file has a .zipextension.

Backup ZIP BundleA ZIP file that was created during backup operation. This file has a .zipextension.

CheckpointA ZIP file that was created through a save checkpoint operation. This filehas a .zip extension and is in the chkpoint: directory.

3. When the source (From or To) is XML Configuration, Export ZIP Bundle, orBackup ZIP Bundle, specify or browse for and select the configuration file.Also, create or select a deployment Policy that can be used to accept, filter, ormodify a configuration.

4. When the source (From or To) is Checkpoint, select the checkpoint from theCheckpoint list.

5. From the View list, select whether the report lists only changed objects betweenthe configurations or all objects in the configurations. The default is changedobjects only.

6. Click Run Comparison to generate the report.

The results are displayed below the horizontal rule.


Reading the change reportAfter running a comparison, the results are displayed below the horizontal rule.Review the report to determine whether these changes should be saved to thestartup configuration, reverted to their original settings, saved to a configurationcheckpoint, or a combination of these operations.

Each item in the report contains the following data:

Type The object type

Name The name of the object

PropertyThe name of the property

From The value of the property as defined in the From source

To The value of the property as defined in the To source

ChangeThe type of change between the From source and the To source. Thechange is one of the following values:v modified

v added

v deleted

Beside each item is a check box.

Reverting changesAfter running a comparison and reviewing the results, you can revert selectchanges or all changes between the two configurations. You can revert changes atthe property level only. To revert changes to select properties for an object, use theobject-specific configuration screens.

To revert changes, use the following procedures:1. Determine which objects to revert:

v To revert select objects, select the check box beside those objects.v To revert all objects, click Select All.

2. Click Undo Selected.

The results are displayed on a new screen.

If a selected object is a referenced object, it cannot be deleted until after thedeletion of its parent object. You might need to run the comparison multiple timesto delete referenced objects. For example, you cannot delete certificates that arereferenced by a validation credentials list until after the deletion of the validationcredentials list itself.


Chapter 14. Configuring deployment policies

Deployment policies use fine-grained matching statements and clause types tocontrol the inclusion of configuration data from imported configuration packages.

Depending on the clause type, the deployment policy can perform the follow typesconfiguration management against the imported configuration package:v Use an accepted configuration to include resources in the package that match

specified criteria.v Use a filtered configuration to delete resources in the package that match specified

criteria.v Use a modified configuration to modify resources in the package that match the

specified criteria. Modified configurations support the following actions:

Add Adds the property with the identified value during the import.

ChangedSubstitutes the value for the identified property during the import.

DeletedDeletes the property during the import.

The processing sequence is as follows:1. Process the accepted configuration, the whitelist, to always include resources

that match.2. Process the filtered configuration, the blacklist, to always delete resources that

match.3. Process the modified configuration to change the resources based on the

defined action type.

Creating a Deployment Policy objectA deployment policy is a sequence of accepted, filtered, and modifiedconfigurations that respectively include, delete, or change configuration data in theconfiguration package during the import. When specifying the matching statement,you can use the builder or manually specify the statement.v For details about using the builder to define the statement, refer to “Using the

deployment policy builder” on page 146.v For details about manually specifying the statement, refer to “Specifying the

matching statement” on page 147.

Note: You cannot modify the administrative state of Deployment Policy objects.

To create a Deployment Policy object, use the following procedure:1. Select Objects → Configuration Management → Deployment Policy to display

the catalog.2. Click Add to display the configuration screen.3. Specify the name of the object in the Name field.4. Specify a descriptive object-specific summary in the Comment field.5. Define accept clauses.


a. Specify the matching statement in the Accepted Configuration field, or clickBuild.

b. Click Add.Repeat this step to define another accept clause.

6. Define filter clauses.a. Specify the matching statement in the Filtered Configuration field, or click

Build.b. Click Add.Repeat this step to define another filter clause.

7. Define modify clauses on the Modified Configuration tab.a. Click Add to display the Modified Configuration property window.b. Specify the matching statement for the modify clause in the Configuration

Match field, or click Build.c. Select the type of configuration modification from the Modification Type

list.

Add ConfigurationAdds a configuration setting.

Delete ConfigurationDeletes a configuration setting.

Change ConfigurationChanges a configuration setting.

d. If adding a configuration, specify the name of the property to add in theConfiguration Property field.

e. If adding or changing a configuration, specify the value of the property toadd or modify in the Configuration Value field.

f. Click Save to return to the configuration screen.Repeat this step to define another modify clause.


Using the deployment policy builderDeployment policies include a builder to help create matching statements in thefollowing format:address/domain/resource[?Name=resource-name

&Property=property-name&Value=property-value]

To access the builder, click Build. This button is associated with the followingproperties:v Accepted Configuration on the Main tabv Filtered Configuration on the Main tabv Configuration Match in the properties Window that the WebGUI displays after

clicking Add on the Modified Configuration tab

To create a matching statement with the builder, use the following procedure:1. Click Build to open the builder.2. Specify the IP address or host alias in the Device Address field. The value *

matches all IP addresses.


3. Select the name of the application domain from the Application Domain list.The selection (none) matches all domains.

4. Select the resource type from the Resource Type list. The select (all resources)matches all resource types.

5. Optionally specify a name match for a resource in the Name Match (PCRE)field. This property limits the matching statement to resources of the specifiedname. Use a PCRE to select groups of resource instances. For example, foo*would match all resources with names that start with foo.

6. Optionally specify the name of the configuration property in the ConfigurationProperty field. This property limits the matching statement to resources of thespecified property.

7. Optionally specify the value for the configuration property in theConfiguration Value Match (PCRE) field. This property limits the matchingstatement to resources of the specified value. Use a PCRE Match Expression toselect groups of configuration property values.

8. Click Save.

The statement is added to the list of matching statements.

Specifying the matching statementInstead of using the builder, you can manually specify the matching statement.Matching statements have the following format:address/domain/resource[?Name=resource-name

&Property=property-name&Value=property-value]

addressSpecifies the IP address or host alias. The value * matches all IP addresses.

domain Specifies the name of the application domain. The value * matches alldomains.

resourceSpecifies the resource type. The value * matches all resource types.

Name=resource-nameOptionally specifies a name match for a resource. This property limits thematching statement to resources of the specified name. Use a PCRE toselect groups of resource instances. For example, foo* would match allresources with names that start with foo.

Property=property-nameOptionally specifies the name of the configuration property. This propertylimits the matching statement to resources of the specified property.

Value=property-valueOptionally specifies the value for the configuration property. This propertylimits the matching statement to resources of the specified property.

PCRE documentation is available at the following Web site:

http://www.pcre.org

Chapter 14. Configuring deployment policies 147

http://www.pcre.org

Chapter 15. Managing logs

Log targets capture logging messages that are posted by the various objects andservices that are running on the appliance. Target types enable additionalcapabilities that include rotating files, encrypting and signing files or messages,and sending messages to remote hosts.

Types of log targetsThe following types of log targets are available:

Cache Writes log entries to memory.

ConsoleWrites log entries to the screen when using Telnet, SSH, or command lineaccess through the serial port.

File Writes log entries to a file on the appliance. This file can be archived usingthe rotate or upload method. The file can be sent as email. The entire filecan be encrypted and signed.

Depending on the machine type, the supported location can differ.

Type 7993 (9003)Supports the local file system only.

Type 9235Supports the local file system and the model-specific, auxiliarydata storage (compact flash or hard disk array).

NFS Writes log entries to a file on a remote NFS server. The file can be archivedusing the rotate or upload method. The file can be send as email. Theentire file can be encrypted and signed. The processing rate can be limited.

SMTP Forwards log entries as email to configured addresses. Log contents can beencrypted or signed before they are sent to the configured remote serverand email address. The processing rate can be limited.

SNMPForwards log entries as SNMP traps issued to all configured recipients ofSNMP traps. The processing rate can be limited.

SOAP Forwards log entries as SOAP messages. The URL can be set. Theprocessing rate can be limited.

syslog Forwards log entries using UDP to a remote syslog daemon. The localaddress, remote address, remote port, and syslog facility can be set. Theprocessing rate can be limited.

syslog-ngForwards log entries using TCP to a remote syslog daemon. The localaddress, remote address, remote port, and syslog facility can be set. An SSLconnection to the syslog host can be created. The processing rate can belimited.


Configuring log categoriesThe appliance provides many default log categories, but you might want to createyour own categories. All of the categories that the appliance recognizes are listedin the Log Category catalog.

To create a log category:1. Select Administration → Miscellaneous → Configure Log Categories to display

the catalog.2. Click Add to display the configuration screen.3. Define the properties of the log category. For information about the properties,

refer to the online help.4. Click Apply to save the object to the running configuration.5. Optionally, click Save Config to save the object to the startup configuration.

The name of the log category is the name to display in the event catalog on logtargets screens and is the name of an event category that generates custom eventnotices. For more information about event subscriptions, refer to “Setting eventsubscriptions” on page 152.

Configuring log targetsTo configure a log target:1. Select Administration→ Miscellaneous→ Manage Log Targets to display the

catalog.2. Click Add to create a new log target to display the configuration screen.3. Define the properties of the log target. Each type of log target provides

different configuration properties. For information about the properties, refer tothe online help.

4. Optionally define event filters. For details, refer to “Setting event filters.”5. Optionally define object filters. For details, refer to “Setting event filters.”6. Optionally define IP address filters. For details, refer to “Setting IP address

filters” on page 152.7. Define event subscriptions. For details, refer to “Setting event subscriptions” on

page 152.8. Click Apply to save the object to the running configuration.9. Optionally, click Save Config to save the object to the startup configuration.

Messages in log targets can be restricted by object filters, event category, and eventpriority. By default, a log target cannot accept messages until it is subscribed toone or more events. Refer to “Setting event subscriptions” on page 152 for details.

Setting event filtersYou can create filters for the log target based on event codes.v An event subscription filter allows only those log messages that contain the

configured event codes to be written to this log target. With this filter, it ispossible to create a log target that collects only log messages for a specific set ofevent codes.


v An event suppression filter suppresses those log messages that contain theconfigured event codes to be written to this log target. With this filter, it ispossible to create a log target that collects a wide range of log messages exceptfor a specific set of event codes.

To define an event filter:1. Click the Event Filters tab.2. Specify the event code by performing either of the following procedures:

v Specify by event code:a. Specify a valid Event Code in the field beside the Add button.b. Click Add to add the event code to the list.

v Select the event code for the available list:a. Click Select Code to display the list of event codes.b. Click Select that corresponds with the desired event code and return to

the list.c. Click Add.

Click Help to read information about the event code.

The log target still requires at least one event subscription. The subscription can beset to all. For information, refer to “Setting event subscriptions” on page 152.

Setting object filtersYou can use the Object Filters page to create object filters for log targets. Objectfilters allow only those log messages for specific objects to be written to this logtarget. Object filters are based on object classes. With this filter, it is possible tocreate a log target that collects only log messages for specific classes of objects. Youcan further restrict the filter to particular instances of these classes by instancename.

To define an object filter for a log target:1. Click the Object Filters tab to display the catalog of Object Filters objects.2. Click the name of a existing object filter to edit it, or click Add to create a new

object filter.3. Define the object filter:

a. Select an object type from the Object Type list. This filter will restrictmessages to only messages generated by the selected object type.

b. Specify the name of an existing object instance of the selected object type inthe Object Name field. You must specify a value for this property.

c. Use the Add Referenced Objects toggle to indicate whether to log messagesfor objects that the selected object instance references.

on Logs messages for all objects that the selected object instancereferences.

off (Default) Logs messages for the selected object instance only.d. Click Save to return to the catalog.

Chapter 15. Managing logs 151

Setting IP address filtersYou can use the IP Address Filters page to create IP address filters for log targets.IP address filters allow only those log messages from specific IP addresses to bewritten to this log target.

To define an IP address filter for a log target:1. Click the IP Address Filters tab.2. Click Add.3. Add an IP address:

a. In the IP Address field, specify an IP address. This filter will restrictmessages to only messages generated by the selected IP address.

b. Click Apply.4. Repeat the previous step to add another IP address.

Setting event subscriptionsYou can subscribe the current log target to particular event categories. Someexample categories include:

auth Authorization events

mgmt Configuration management events

xslt XSLT processing events

For each event category chosen (including the all category), you can establish apriority level which must be met before the log message will be captured by thecurrent log target.

Note: To allow the target to capture messages, at least one event subscription mustbe configured, which can be for ″all″ events. If no event subscriptions areset, no events are included by default.

1. Click the Event Subscriptions tab.2. Click the name of a pre-configured subscription, or click Add.3. Provide the following information.

Event CategorySelect one event category. Refer to “Configuring log categories” on page150 for more information.

Minimum Event PrioritySelect a minimum event priority. The priorities are hierarchical; the lowestis listed last.

It is possible to generate custom events by creating a style sheet that usesthe DataPower-specific version of the <xsl:message> extension element.For example:<xsl:message dp:type="custom"></xsl:message><xsl:message dp:type="custom" dp:priority="error"></xsl:message>

The first entry is treated as an information-level message. The secondentry is treated as an error-level message. For additional information onthis extension element, refer to the IBM WebSphere DataPower SOAAppliances: Extension Elements and Functions Catalog.

4. Click Submit.5. Create as many event subscriptions as desired by clicking Add.


Viewing log filesTo view the contents of log files, click the View Logs icon on the control panel toopen the System Log page.

From this page, you can select whether to view messages for a specific log targetor for all log targets. You can also select how to filter these messages. You can filterbased on the following criteria:v Application domain (available in the default domain only)v Log categoryv Message level

While viewing the messages, you can sort them by clicking one of the followingcolumn headers:

time Sorts by timestamp, most recent to oldest. This is the default presentation.

categorySorts by log category, alphabetic order.

level Sorts by message level, highest to lowest.

domain (available in the default domain only)Sorts by application domain, reverse alphabetic order with the defaultdomain at the end of the list. Messages associated with the defaultdomain do not contain this value.

tid Sorts by transaction ID, highest to lowest.

msgid Sorts by message ID, highest to lowest.

Alternatively, selectStatus → View Logs → System Logs.

Configuring an email pagerThis wizard helps you create a log target that sends email to a configured addresswith all critical log events.

Select Administration → Miscellaneous → New Email Pager to start the email pagerwizard.1. Adjust the log target name as desired.2. Specify any summary comments desired.3. Click Next to display the next page of the wizard.4. Specify an email address to which the log messages will be sent. Only critical

level messages are sent to this address.5. Specify the IP address or domain name of the email server to use. By default,

the canonical TCP Port 25 will be used.6. Click Next to display the confirmation window.7. Click Commit to create the new log target and display a confirmation screen.8. Click Done to quit the wizard.9. Click Again to return to the beginning and create another Email Pager log.

Chapter 15. Managing logs 153

To verify the creation of the log, select Administration → Miscellaneous → ManageLog Targets. The new pager log should appear in the catalog.

Optionally, test the new email pager log by generating a log event. From theControl Panel, click the Troubleshooting icon. On the Troubleshooting page,generate a log event.

Using a Load Balancer Group as the remote hostThe following example explains how to use a load balancer group as the statictarget for a TCP-based, network log target. This example creates new objects andprovides information about only the configuration that is required for loadbalancing. However, you can modify existing objects.1. Create the syslog-group Load Balancer Group and define syslog-1 and

syslog-2 as members that reference the actual servers.The configuration of a DataPower service defines the default port on thebackend servers. You can override the default server port for one or moremembers with the Mapped Server Port property.

2. Modify the default XML Manager by adding the syslog-group group to theLoad Balancer Groups list.

3. Create a Log Target, for example the allSyslogMessages Log Target, and specifysyslog-group (the Load Balancer Group) as the host in the Remote Host field.Refer to “Configuring log targets” on page 150 for more information.


Part 4. Referenced objects

Chapter 16. Service objects . . . . . . . . 157HTTP Service . . . . . . . . . . . . . 157SSL Proxy Service . . . . . . . . . . . . 158TCP Proxy Service. . . . . . . . . . . . 159

Chapter 17. Referenced objects . . . . . . 161Access Control List . . . . . . . . . . . 161

Overview. . . . . . . . . . . . . . 161Creating an Access Control List object . . . . 162

Defining Certificate objects . . . . . . . . . 162Defining Identification Credentials objects . . . . 164Working with Kerberos objects . . . . . . . 164

Points to remember when using Kerberos . . . 165Kerberos KDC Server objects . . . . . . . 166Kerberos Keytab File objects . . . . . . . 166

Defining Key objects . . . . . . . . . . . 167Load Balancer Group . . . . . . . . . . . 168

Health of member servers . . . . . . . . 168Healthy . . . . . . . . . . . . . 168Quarantined. . . . . . . . . . . . 168Convalescent . . . . . . . . . . . 169

Setting the health state with a variable . . . . 169Configuring Load Balancer Group objects . . . 169

Providing basic configuration . . . . . . 169Defining server members . . . . . . . 171Defining health checks . . . . . . . . 172

Defining Profile objects . . . . . . . . . . 173RADIUS Settings . . . . . . . . . . . . 175

NAS-identifier . . . . . . . . . . . . 175Configuring RADIUS Settings . . . . . . . 175

Adding SSH known hosts . . . . . . . . . 176Defining SSL Proxy Profile objects . . . . . . 177

Creating a forward (or client) proxy . . . . . 177Creating a reverse (or server) proxy . . . . . 177Creating a two-way proxy . . . . . . . . 178

Working with Validation Credentials objects . . . 179Creating for non-expiring, non-password-protected certificates . . . . . . . . . . 179Creating for select certificates . . . . . . . 179

z/OS NSS Client . . . . . . . . . . . . 181Creating the z/OS NSS Client . . . . . . . 182


Chapter 16. Service objects

This chapter describes how to create and manage service objects from the objectview.

You can access the following service objects from the Objects → Services menu:

HTTP ServiceCreates an HTTP server

SSL Proxy ServiceCreates a secure SSL-based relay or forwarding service

TCP Proxy ServiceCreates a nonsecure TCP-based relay or forwarding service

HTTP ServiceYou can create an HTTP service that serves documents from a specified directoryon the appliance.

To create an HTTP service, use the following procedure:1. Select Objects → Services → HTTP Service to display the catalog.2. Click Add to display the HTTP Service configuration screen.3. Specify the name of the object in the Name field.4. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.5. Specify the local IP address to monitor in the Local IP Address field. Retain

the default value (0.0.0.0) to bind to all local interfaces.To use a local Host Alias instead of a static IP address, click Host Alias. AHost Alias allows you to specify a locally configured alias that resolves to astatic IP address. Aliasing can help when moving configurations acrosssystems.

6. Specify a descriptive object-specific summary in the Comment field.7. Select a priority for scheduling or for resource allocation from the Service

Priority list.

High Receives above normal priority.

Low Receives below normal priority.

Normal(Default) Receives normal priority.

8. Specify the port to monitor in the Port Number field. The default is 80.9. Select the operational mode from the Mode list.

Echo Input is looped back to the sender. This mode is intended for test anddebug environments.

Normal(Default) Enables standard HTTP server operation

10. Optionally specify the value for the Server response header in the Identifierfield. The Server response header generally contains information (name and


version) that describes the application software. By default, the inclusion ofthe Server response header is suppressed.

Note: Consider the security implications before revealing version information.11. Specify the local directory from which to serve documents in the Base

Directory field.

config:///Identifies the config directory.

local:///Identifies the local directory.

store:///(Default) Identifies the store directory.

temporary:///Identifies the temporary directory.

12. Optionally use the Start Page controls to identify the page to load when anclient accesses this service. Without a start page, this service displays adirectory listing for the defined base directory.

13. Optionally select an Access Control List from the Access Control List list.Refer to “Access Control List” on page 161 for more information.


SSL Proxy ServiceYou can create an SSL Proxy Service, most commonly used to enable thetransmission of syslog-ng from an SSL application (for example, Stunnel). The SSLProxy Service uses a secure connection to relay all traffic received on a specifiedlocal address to a specified remote peer.

Select Objects → Services → SSL Proxy Service to display the SSL Proxy Servicecatalog.

Click Add to display the SSL Proxy Service configuration screen. Use this screen tospecify SSL forwarding service property values.


Name Specify the name of the SSL forwarding service.


Local IP AddressSpecify the local IP address to monitor. All traffic that is received on thisaddress is forwarded to a remote peer. Retain the default value (0.0.0.0)to bind to all local interfaces.

To use a local Host Alias instead of a static IP address, click Host Alias. AHost Alias allows you to specify a locally configured alias that resolves toa static IP address. Aliasing can help when moving configurations acrosssystems.


Service PriorityAssigns a priority for scheduling or for resource allocation. Use one of thefollowing values:




Port NumberSpecify the port to monitor.

Remote HostSpecify the host name or IP address of the remote host to send SSL traffic.Click Ping to verify connectivity.

Remote PortSpecify the port on the remote host.

SSL Proxy ProfileSelect a client SSL Proxy Profile. The SSL Proxy Profile identifies the keysand certificates to use in the handshake. Refer to “Defining SSL ProxyProfile objects” on page 177 for more information.



TCP Proxy ServiceYou can create a TCP Proxy service that uses a TCP connection to relay or forwardall traffic that is received on a specified local address (or host alias) to a specifiedremote peer.

Select Objects → Services → TCP Proxy Service to display the TCP Proxy Servicecatalog.

Click Add to display the TCP Proxy Service configuration screen.


Name Specify the name of the TCP forwarding service.


Local IP AddressSpecify the local IP address to monitor. All traffic that is received on thisaddress is forwarded to a remote peer. Retain the default value (0.0.0.0)to bind to all local interfaces.

To use a local Host Alias instead of a static IP address, click Host Alias. AHost Alias allows you to specify a locally configured alias that resolves toa static IP address. Aliasing can help when moving configurations acrosssystems.

Chapter 16. Service objects 159

Service PriorityAssigns a priority for scheduling or for resource allocation. Use one of thefollowing values:




Port NumberSpecify the port to monitor.

Remote HostSpecify the host name or IP address of the remote host to send TCP traffic.Click Ping to verify connectivity.

Remote PortSpecify the port on the remote host.




Chapter 17. Referenced objects

Access Control ListAn Access Control List (ACL) object consists of a sequence of allow and denyclauses. Each clause identifies an IP address or range of addresses that allow orthat deny access to a service.

The DataPower appliance provides the following Access Control List object:v ssh for use by the SSH servicev web-mgmt for use by the Web Management Servicev xml-mgmt for use by the XML Management Interface

Each of these objects, when enabled, provides full access from all IPv4 addresses. Ifthe Ethernet for the local address for these services supports IPv6 addresses,modify its Access Control List object to include an allow clauses for specific or allIPv6 addresses.

OverviewAn ACL is associated with a specific DataPower service. An ACL grants access tothe service to only addresses that are defined by the allow clause. All otheraddresses are denied access.

Candidate addresses are evaluated sequentially against each clause in the ACL. Acandidate address is denied or granted access in accordance with the first clausethat matches. Consequently, the order of clauses in the ACL is vital.

For example, the following ACL fails its intended purpose. The address range thatis specified by the deny clause (192.168.14.224 through 192.168.14.255) is grantedaccess before the allow clause.allow 192.168.14.0/24deny 192.168.14.0/27

However, as shown in the following example, reversing the order of the clausesachieves the desired effect.deny 192.168.14.0/27allow 192.168.14.0/24

An ACL that contains only deny clauses effectively disables a service by denyingaccess to all addresses. To complete an ACL, include an IP family-specific allowclause to ensure that addresses that are not explicitly denied access are grantedaccess:v allow 0.0.0.0 if only IPv4v allow ::/0 if a combination of IPv4 and IPv6

The following example denies access to two ranges of addresses and allows accessto all other IPv4 addresses.deny 10.10.10.0/24deny 172.16.0.0/16allow 0.0.0.0


Creating an Access Control List objectTo create an ACL, use the following procedure:1. Select Objects → Access Settings → Access Control List to display the catalog.2. Click Add to display the configuration screen.3. Specify the name of the object in the Name field.4. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.5. Define the allow and deny clauses on the Entry tab.

a. Click Add to display the Property window.b. From the Access list, select the type of clause to create.

Allow Indicates an allow clause.

Deny Indicates an deny clause.c. In the Address Range field, specify an IP address with its prefix length (net

mask). Use a forward slash (/) between the address and the prefix length.Examples of address ranges are as follows:v 10.10.100.0/28 specifies the IPv4 address range from 10.10.100.0

through 10.10.100.15

v 10.10.100.9/32 specifies the single IPv4 addressv 0.0.0.0 (without a prefix length) specifies all IPv4 addressesv ::/0 specifies all IPv4 and IPv6 addresses

d. Click Save.Repeat this step for each additional clause.


If you delete a clause, the WebGUI does not prompt for confirmation. If youinadvertently delete a clause, click Cancel and OK to restore the ACL to its priorconfiguration.

Defining Certificate objectsA Certificate object that provides an added layer of security by supplying aindirect reference (or alias) to a certificate file. The alias provided by the Certificateobject is later used in the creation of a Firewall Credentials, an IdentificationCredentials, or a Validation Credentials.

To create and configure a Certificate, use the following procedure:1. Select Objects → Crypto → Crypto Certificate.2. Click Add.3. Provide the following inputs:

NameSpecify the name of the object.



File NameAccess a list of files, contained in the cert: or pubcert: file repository, andselect the file that contains the certificate referenced by this Certificateobject.

You can click Upload or Fetch to transfer the file.

You can also click Details to display information about the selectedcertificate file.

PasswordDepending of business security policies, provide one of the following:v If local security policies provide for password-protected keys, specify

the password (or a password alias).v If local polices do not support password protection, leave blank.v If key files are protected by a plaintext password, specify the password.

Note: Plaintext passwords appear as such in the configuration script.v If key files are protected by an aliased password, specify the alias.

The CLI provides a password-map command that uses alocally-generated key to 3DES encrypt a password used to access aprivate key file. The command maps the encrypted password to apassword alias in a password map file. The password map and thelocally-generated key are saved to separate files on the appliance.Plaintext passwords are not stored in memory or saved on the appliance.

Password AliasUse the toggle to specify if the text entered in the Password field is aplaintext password or a password alias.

on Identifies the text as a password alias for an encrypted password.

off (Default) Identifies the text as a plaintext password.

Ignore Expiration DatesUse these toggle to allow the creation of a certificate prior to its activationdate (the NotBefore value in the certificate) or after its expiration date (theNotAfter value in the certificate).

off (Default) Prevents the creation of certificates outside of theirinternal expiration values.

on Creates the certificate and places it in the up state. Although thecertificate is in the up state, objects that reference the certificateuse the internal expiration values. In other words, the certificateitself is in the up state, but Validation Credentials, FirewallCredentials, or Identification Credentials that references thecertificate adhere to the internal expiration values.

In other words, the certificate itself is in the up state, butValidation Credentials, Firewall Credentials, or IdentificationCredentials that references the certificate adhere to the internalexpiration values. If the certificate is used for a certificate chainvalidation from a Validation Credentials and the certificate is notvalid, validation fails. Similarly, if the certificate is used from anIdentification Credentials, the DataPower appliance sends thecertificate to the SSL peer for an SSL connection, but the peer canreject the certificate as not valid.

Chapter 17. Referenced objects 163



Defining Identification Credentials objectsAn Identification Credentials consists of a Key object and a Certificate object. AnIdentification Credentials identifies the matched public key cryptography publicand private keys used by an object for SSL authentication. An IdentificationCredentials can be used in document encryption, document decryption, and digitalsignature operations.

To create an Identification Credentials, use the following procedure:1. Select Objects → Crypto → Crypto Identification Credentials to display the

Crypto Identification Credentials catalog.2. Click Add to display the Crypto Identification Credentials Configuration

screen.3. Provide the following inputs:



Crypto KeyAccess a list of all Key objects, and select the Key object for thisIdentification Credentials. Refer to “Defining Key objects” on page 167 formore information.

CertificateAccess a list of all Certificate objects, and select the Certificate object forthis Identification Credentials. Refer to “Defining Certificate objects” onpage 162 for more information.

Intermediate CA CertificateIntermediate CA certificates might be required when the CA that issigning this certificate is not widely-recognized. If the intermediate CAcertificate is also signed by a less recognized CA, an additionalintermediate CA certificate might be required for that CA. You can specifyas many intermediate certificates as are required.

If necessary, use the list of available Certificate objects to establish averifiable trust-chain. A trust-chain consists of one or more CertificationAuthority (CA) certificates and provides a linked path from the certificatethat is in the Identification Credentials to a CA that is trusted by a remoteappliance. The trust chain enables the appliance to authenticate thecertificate.


Working with Kerberos objectsA basic description of the Kerberos authentication protocol is helpful forunderstanding the support provided by the DataPower appliance.


The Kerberos authentication protocol uses a star topology. The Key DistributionCenter (KDC) is at the center of the star. Each Kerberos principal (a human, acomputer client, or an instance of a service running a specific computer) isregistered with the KDC and has a shared secret known only to the principal andto the KDC. This shared secret takes the form of a password for human principalsand a randomly generated keytab file for nonhuman principals.

When a Kerberos client (for example, Alice) wants to communicate securely with aKerberos server (for example, the FTP service), Alice must access KDC of herKerberos realm and request a ticket for the FTP service. At this point, the KDC hasthe option of requiring pre-authentication before responding, or the KDC canimmediately issue the ticket to Alice.

The KDC response contains two items:v A randomly generated session key encrypted with Alice’s shared secretv A ticket for the FTP service

The ticket contains:v The idobj for Alicev The idobj for the FTP servicev A ticket lifetimev Another copy of the session key

The ticket is encrypted with the shared secret of the FTP service principal.Consequently, there are two encrypted copies of the session key (one for Alice, andone for the FTP service).

At this point, Alice uses her shared secret to decrypt her copy of the session keyand generates an authenticator (which proves that the person talking to the FTPservice is the client for which this ticket was issued, and not a malicious userreplaying a previously issued ticket) that she sends along with her ticket to theFTP service. The ticket plus authenticator is called an AP-REQ message.

When the FTP service receives the AP-REQ from Alice, it decrypts the ticket andverifies the authenticator. At this point the FTP server has authenticated Alice, andthey share a session key which can be used to secure the rest of theircommunications.

Points to remember when using KerberosWhen using Kerberos, keep the following points in mind:v Both clients and servers are principals in the KDC database. More accurately,

services running on server computers are principals in the KDC database.v A client principal must request a separate ticket for each server with which it

communicates.v Services must have a name and shared secret registered with the KDC.v A service must have access to its shared secret to decrypt Kerberos tickets.v A Kerberos ticket that is issued by a KDC contains the cryptographic material

that allows both the client and the server to generate the same session key.v All Kerberos cryptographic operations are symmetric in nature.v In an AAA Policy, Kerberos is an idobj extraction, authentication protocol, or

both.v Kerberos is not an authorization protocol.


There is no restriction in Kerberos that specifies which clients can request ticketsfor a particular service.

Note: Microsoft® Windows, when configured to use an Active Directory domain, isbased on a security infrastructure that is, at its core, Kerberos. As ofWindows 2000, authentication in a Windows domain is handled byKerberos. Such authentication is entirely transparent to the user. Refer toUnderstanding SPNEGO for implementation details.

Kerberos KDC Server objectsUse the following procedure to configure a Kerberos KDC Server:1. Select Objects → Crypto → Kerberos KDC server to display the Kerberos KDC

Server catalog.2. Click Add to display the Kerberos KDC Server configuration screen.3. Provide the following inputs:




Kerberos realm nameSpecify the name of the Kerberos realm that is serviced by this KDC.There is exactly one KDC per Kerberos realm.

Kerberos KDC ServerSpecify the host name or IP address of the KDC server. Click Ping toverify connectivity.

Use TCPSelect whether to use UDP or TCP as the Transport Layer protocol toaccess the KDC server.

on Use Transmission Control Protocol (TCP)

off (Default) Use User Datagram Protocol (UDP)

Server Port NumberSpecify the UDP or TCP port that is monitored by the KDC for incomingKerberos requests. The default is 88.

UDP TimeoutWhen the Transport Layer protocol is UDP, specify the UDP timeout.


Kerberos Keytab File objectsA Kerberos Keytab file contains the keys needed to decrypt the ticket presented bya client attempting to obtain services. Previously, only a password was required.This has been changed to an encrypted key for added security. The KerberosKeytab File object identifies the file that contains the keys needed to decrypt theticket.

Use the following procedure to configure a Kerberos Keytab File:


1. Select Objects → Crypto → Kerberos Keytab to display the Kerberos Keytabcatalog.

2. Click Add to display the Kerberos Keytab Configuration screen.3. Provide the following inputs:




File NameSelect the keytab file. This list includes files that are stored in theencrypted and protected cert: directory of the appliance. If the file doesnot reside on the appliance, click Upload or Fetch to transfer the file.

Note: This file is not generated on the DataPower appliance. It isgenerated through the Kerberos system itself.


Defining Key objectsA key is an object that provides an added layer of security by supplying a indirectreference (or alias) to a file that contains a private key. The alias provided by theKey object is later used in the creation of a Firewall Credentials object or anIdentification Credentials object.

To create and configure a Key object, use the following procedure:1. Select Objects → Crypto → Crypto Key to display the Crypto Key catalog.2. Click Add to display the Crypto Key Configuration screen.3. Provide the following inputs:



File NameAccess a list of files (contained in the cert: file repository) and select thefile that contains the private key aliased by this Key object.

You can click Upload or Fetch to transfer the file.

Note: Keys can be retrieved from a Java Key Store residing on the localworkstation. Click Java Key Store on the Upload field. Refer toIBM WebSphere DataPower SOA Appliances: Appliance Overview formore information.

PasswordDepending on business security policies, provide one of the following:


v If local security policies provide for password-protected keys, specifythe password (or a password alias).

v If local polices do not support password protection, leave blank.v If key files are protected by a plaintext password, specify the password.

Note: Plaintext passwords appear as such in the configuration script.v If key files are protected by an aliased password, specify the alias.

The CLI provides a password-map command that uses a locally-generatedkey to 3DES encrypt a password used to access a private key file. Thecommand maps the encrypted password to a password alias in apassword map file. The password map and the locally-generated key aresaved to separate files on the appliance. Plaintext passwords are notstored in memory or saved on the appliance.

Password AliasUse the toggle to specify if the text entered in the Password field is aplaintext password or a password alias.

on Identifies the text as a password alias for an encrypted password.

off (Default) Identifies the text as a plaintext password.4. Click Apply to save the object to the running configuration.5. Optionally, click Save Config to save the object to the startup configuration.

Load Balancer GroupA Load Balancer Group is a server pool that can provide redundancy among acollection of servers. A Load Balancer Group can be used as the backend server fora DataPower service or can be used to provide LDAP or IMS™ Connect serverfailover protection. A request to connect to a Load Balancer Group results in theselection of a healthy server to receive an incoming client request.

Each instance of a Load Balancer Group can support 512 members.

Health of member serversThe health of each member of the group is considered one of the following :v Healthy or upv Quarantined or softdownv Convalescent or down

HealthyBy default, all servers are considered healthy and are eligible to receive forwardedclient requests. When healthy, the health state is up.

QuarantinedDuring a normal HTTP transaction or the TCP ping, a failure to connect to a servercauses the server to be quarantined until a dampening period elapses. When thedampening period elapses, the server returns to the healthy state and becomeseligible to receive forwarded client requests. When quarantined, the health state issoftdown.

While quarantined, the server is:v Removed from the server poolv Ineligible to receive forwarded client requestsv Excluded from the optional health check


ConvalescentOptionally, you can associate a periodic health check with a Load Balancer Group.If the health check fails, the server is deemed convalescent. The server is notconsidered to be healthy until it passes a health check. When deemed convalescent,the health state is down.

While deemed convalescent, the server is:v Removed from the server poolv Ineligible to receive forwarded client requests

Setting the health state with a variableThe health state for each server can be set with the service/lbhealth/ servicevariable. This variable takes one of the following syntax statements:var://service/lbhealth/group/server/state

var://service/lbhealth/group/server:port/state

Where:

group The name of the Load Balancer Group

server The IP address or host name of the member

port The port of the member

state The state of the server, which is one of the following values:v upv downv softdown

Refer to “Health of member servers” on page 168 for details.

Configuring Load Balancer Group objectsThe configuration of a Load Balancer Group consists of the following activities:1. Providing basic configuration properties on the Main tab2. Defining server members on the Members tab3. Optionally defining health check criteria on the Health tab

Providing basic configurationTo start the configuration, perform the following procedure:1. Select Objects → Network → Load Balancer Group to display the catalog.2. Click Add to display the configuration screen.3. Provide the following inputs:

Name Specify the name for the Load Balancer Group.



AlgorithmSelect the algorithm to select the actual server. The following values areavailable:

First AliveUses the concept of a primary server and backup servers. When


the primary server is healthy, all connections are forwarded tothis server. When the primary server is quarantined orconvalescent, connections are forwarded to backup servers. Theprimary server is the first server in the members list.

Hash Uses the IP address of the client or the value of an HTTPheader as the basis for server selection.

When using an HTTP header, use the Load Balancer HashHeader property to identify the header to read. This property isavailable for Multi-Protocol Gateway and Web Service Proxyservices only. Additionally, this property is available only in theobject view, and this property is on the Main tab.

The same client is served by the same server. This algorithm isused in applications that require the storage of server-side stateinformation, such as cookies.

Least ConnectionsMaintains a record of active server connections and forward anew connection to the server with the least number of activeconnections.

Round Robin(Default) Maintains a list of servers and forwards a newconnection to the next server on the list.

Weighted Round RobinMaintains a weighted list of servers and forwards newconnections in proportion to the weight (or preference) of eachserver.

Damp TimeSpecify the number of seconds that a server remains in an softdownstate. Use a value in the range of 1 through 86400. The default is 120.

This property does not impact servers that are in the down state.

Do not Bypass Down StateSelect the connection-behavior when no member is up.

on Does not forward the connection to any member. Makes thenext attempt when at least one members is in the up state.

off (Default) Selects the first member in the down state andforwards the connection to this server.

Try Every Server Before FailingSelect the retry-behavior for a failed attempt.

on Sends the requests to each server until one responds or all fail.Each server that fails is set to the softdown state.

off (Default) Does not attempt to contact other members.

Masquerade as Group NameSelect which name to present in the message header.

on Uses the name of the Load Balancer Group. Ifappserver1.domain.com is a member of the Appsters LoadBalancer Group, the message header contains Appsters.

off (Default) Use the host name of the member. If


appserver1.domain.com is a member of the Appsters LoadBalancer Group, the message header containsappserver1.domain.com.

4. Continue with procedure that is provided in “Defining server members.”

Defining server membersUse the following procedure to add members or assign weight to members. For allalgorithms except First Alive, the order of members is not important.1. Select the Members tab to display the catalog.2. Click Add to display the property window.3. Provide the following inputs:

Actual HostSpecify the IP address or the domain-qualified host name of themember.

WeightIf the algorithm is Weighted Round Robin only, specify the relativeweight (preference). Use a value in the range of 1 through 65000. Thedefault is 1.

The greater the value, the more likely this server is to receive aconnection request. For example there are three members (A, B, and C)that have the assigned weights of 100, 60, and 40, respectively. Becauseof the weighting, A receives 50% of requests, B receives 30% of requests,and C receives 20% of requests.

Mapped Server PortSpecify the member-specific target port or retain the default value (0) touse the DataPower service-defined port. Use a value in the range of 0through 65535. The default is 0.

By default, member servers are contacted on the DataPowerservice-defined port. However, if you have services running ondifferent ports for different member servers, explicitly identify themember-specific target port. If you specify a nonzero value, thatmember server will always be contacted on this port.

Health PortSpecify the member-specific health port or retain the default value (0)to use the Load Balancer Group-defined port. Use a value in the rangeof 0 through 65535. The default is 0.

A nonzero value overrides the value for the Remote Port property ofthe health check. This property is available during the configuration ofthe health check on the Health screen.

4. Click Save to return to the catalog.

Assignment of all members to a Load Balancing Group completes the requiredconfiguration.v To associate a periodic health check with the new Load Balancer Group, refer to

“Defining health checks” on page 172.v If you are completed with the configuration, click Apply to save the object to the

running configuration and return to the object catalog.v Optionally, click Save Config to save the object to the startup configuration.


Defining health checksA health check is essentially a scheduled rule that sends the same request to eachserver member. The successful completion of the health check requires that theserver passes normal TCP and HTTP connection criteria. Optionally, the healthcheck contains a filter to test the response from the server. If the filter accepts theresponse, the server is considered to be healthy; otherwise, it is considered to beconvalescent.

Use the following procedure to define the health check:1. Click the Health tab to display the configuration screen.2. Provide the following inputs:

EnabledControls whether to perform the periodic health check.

on Enables the health check.

off (Default) Disables the health check.

URI When the check type is Standard, specify the non-server (file path)portion of the target URI. That is, specify the URI to receive the clientrequest that is generated by the rule. The default is /.

This URI is used with the specified remote port.

Remote PortSpecify the port on the target server to receive the query. The default is80.

You can override this value for one or more members of the LoadBalancer Group with the Health Port property. This property isavailable during the configuration of member servers in the group.

The response from the server is evaluated to determine the healthstatus of each member server in the group. The request is sent to thetarget URI and remote port.

Health Check TypeSelect the type of check to perform.

Standard(Default) Select if the group does not consist of LDAP servers.

LDAP Select if the group consists of LDAP servers.

IMS ConnectSelect if the group consists of IMS Connect servers.

Send SOAP Request?When the check type is Standard, specify the HTTP method to accessthe target URI.

on (Default) Click to access the target URI with an HTTP POSToperation (by posting a SOAP message).

off Click to access the target URI with an HTTP GET operation.

SOAP Request DocumentWhen Send SOAP Request? is on, specify the SOAP message to sendas a client request. The default is the healthcheck.xml file in the store:directory (store:///healthcheck.xml).


TimeoutSpecify the number of seconds for the completion of the health check.Use a value in the range of 2 through 86400. The default is 10.

If successful, the server is deemed healthy and is marked as up;otherwise, the server is deemed convalescent and is marked as down.

FrequencySpecify the number of seconds between health checks. Use a value inthe range of 5 through 86400. The default is 180.

XPath ExpressionWhen the check type is Standard, use with the XSL Health CheckFilter property to specify the XPath expression that must be found in avalid server response. If necessary, click XPath Tool to define an XPathexpression.

XSL Health Check FilterWhen the check type is Standard, specify the style sheet to filter theserver response. The default is the healthcheck.xsl file in the store:directory (store:///healthcheck.xsl).

This style sheet uses the specified XPath Expression value as input andscans the server response for its presence. If found, the server isdeemed healthy and is marked as up; otherwise, the server is deemedconvalescent and is marked as down.

SSL proxy profileOptionally, when the check type is Standard, select an SSL ProxyProfile to provide the resources for a secure connection.


Defining Profile objectsA Profile object identifies a collection of SSL resources that support SSLconnections with remote peer appliances.

To create and configure a Profile object, use the following procedure:1. Select Objects → Crypto → Crypto Profile to display the catalog.2. Click Add to display the configuration screen.3. Provide the following inputs:



Identification CredentialsSelect the Identification Credentials to assign to this Profile object, orretain the default value, none, when no Identification Credentials isneeded.

The Identification Credentials provides the PKI certificate-key pair thatwill be used to authenticate the appliance during the SSL handshake.

Refer to “Defining Identification Credentials objects” on page 164 formore information.


Validation CredentialsSelect the Validation Credentials for this Profile object, or retain thedefault value, none, when no Validation Credentials is needed. Refer to“Working with Validation Credentials objects” on page 179 for moreinformation.

CiphersUse the field to identify the symmetric key-encryption algorithms for thisProfile object. Common cipher values are as follows:

ALL Includes all cipher suites, except the eNULL ciphers.

DEFAULTIncludes all cipher suites, except for the following ciphers andcipher suites:v eNULL ciphersv Cipher suites that use DH authenticationv Cipher suites that contain the RC4, RSA, and SSL version 2

ciphers

HIGH Includes all “high” encryption cipher suites. These cipherssupport a key length in excess of 128 bits.

MEDIUMIncludes all “medium” encryption cipher suites. These cipherssupport a key length of 128 bits.

LOW Includes all “low” encryption cipher suites. These ciphers supporta key length of 56 or 64 bits, but exclude EXPORT cipher suites.

EXPORTIncludes all cipher suites that support a key length of 40 or 56 bitsand are eligible for export outside of the United States.

For a detailed list of ciphers, refer to the profile command in theproduct-specific version of the Command Reference.

OptionsUse the check boxes to disable support for SSL versions and variants. Bydefault, SSL Version 2, SSL Version 3, and Transaction Level Security(TLS) Version 1 are enabled.v To disable SSL Versions 2, click Disable-SSLv2.v To disable SSL Version 3, click Disable-SSLv3.v To disable TLS Version 1, click Disable-TLSv1.

Send Client CA ListUse the toggle to enable the transmission of a Client CA List during theSSL handshake.

Note: Transmission of a Client CA List is meaningful only when thisProfile object supports a reverse (or server) proxy and when thisProfile object has an assigned Validation Credentials.

on Enables transmission of a Client CA List.

off (Default) Disables transmission of a Client CA List.

A Client CA List consists of a listing of the CA certificates in theValidation Credentials for this Profile object. A Client CA List can be sentby an SSL server as part of the request for a client certificate. The Client


CA list provides the client with a list of approved CAs whose signaturesare acceptable for authentication purposes.

Note: SSL servers are not required by the protocol to send a Client CAList. Generally, SSL servers do not send a Client CA list.

Some implementations or local policies, however, might mandatethe use of Client CA lists.


RADIUS SettingsRADIUS settings define RADIUS servers. RADIUS settings can be defined in thedefault domain only.

Within the DataPower appliance, RADIUS servers can be used for the followingpurposes:v On any appliance, to authenticate access using RBM.v On all appliances except XML Accelerator XA35, to authenticate access in AAA

Policy objects.

Each RADIUS server has a positional value that the DataPower appliance uses todetermine the order in which to contact the servers. The appliances contacts theservers from most preferred (lowest number) to least preferred (highest number).The appliance sends the request to the next server based on the global timeoutvalue and the global retry value.

If the configuration defines three RADIUS servers with positional values of 10, 20,and 30, the appliance contacts the servers in the following sequence:1. Requests are always first sent to server 10.2. If the request times out, it is sent to server 20.3. If the request times out, it is sent to server 30.

NAS-identifierThe DataPower appliance is a client to RADIUS servers. The NAS-identifier is aRADIUS attribute that the client uses to identify itself to a RADIUS server. TheNAS-Identifier, as defined in Section 5.32 of RFC 2865, can be used instead of an IPaddress to identify the client. The NAS-identifier consists of one or more octets andmust be unique in the scope of the RADIUS server. The NAS-identifier is often thefully qualified domain name (FQDN) of the RADIUS client.

Configuring RADIUS SettingsTo configure RADIUS settings, use the following procedure:1. Select Administration → Access → RADIUS Settings.2. Configure global settings for all RADIUS servers.

a. Retain the default setting for the Admin State toggle. To place the object inan inactive administrative state, click disabled.

b. Specify a descriptive object-specific summary in the Comment field.c. Specify the NAS-identifier in the Identifier field.


d. Specify the interval in milliseconds that the appliance waits for a reply froma RADIUS server before retransmitting the outstanding request in theTimeout field. Use an integer in the range of 1 through 5000. The default is1000.

e. Specify the number of times that the appliance retransmits an unansweredrequest to a RADIUS server before contacting another server in the list inthe Retries field.

3. Do not define RADIUS servers to authentication CLI access without the use ofRBM. In other words, do not define any RADIUS servers on the CLI Serverstab. This functionality is deprecated. If using RADIUS for authentication, defineRADIUS as the RBM method and define the appropriate RADIUS servers onthe AAA/RBM Servers tab.

4. Define RADIUS servers for use by AAA Policy objects or by the RBM policy.a. Click the AAA/RBM Servers tab.b. Define a server.

1) Click Add.2) Specify the relative position of this server in the list in the Number

field.3) Specify the IP address or domain name of the server in the Server

Address field,4) Specify the listening port on the remote server in the Server Port field.

The default is 1812.5) Specify the password to log in to the server in the Secret field.6) Reenter the password in the Confirm Secret field.7) Click Save.

c. Repeat the previous step to add additional servers to the list.5. Click Apply to save the object to the running configuration.6. Optionally, click Save Config to save the object to the startup configuration.

Adding SSH known hostsUse the SSH Known Host page to create a list of SSH known hosts.

You do not need to define hosts as a known hosts to use SCP or SFTP. On rareoccasions, you might need to change an entry when the server key for an SSHserver changes. The server key generally changes only after you reinstall thefirmware. If this happens, delete or edit that entry to make SCP or SFTP workagain.

To add an SSH peer as an SSH known host, use the following procedure:1. Select Administration → Miscellaneous → Crypto Tools to display the Crypto

Tools screen.2. Click the Add SSH Known Host tab.3. Provide the following information:

Host Specify the fully-qualified host name or IP address for the peer. Forexample:

ragnarok.datapower.com10.97.111.108

Type Retain ssh-rsa. This is the only selection.

Key Specify the host public key for the peer. For example:


AAAAB3NzaC1yc2EAAAABIwAAAIEA1J/99rRvdZmVvkaKvcG2a+PeCm25p8OJl87SA6mtFxudA2ME6n3lcXEakpQ8KFTpPbBXt+yDKNFR9gNHIfRlUDho1HAN/a0gEsvrnDY5wKrTcRHrqDc/x0buPzbsEmXi0lud5Pl7+BXQVpPbyVujoHINCrx0k/z7Qpkozb4qZd8==

4. Click Add SSH Known Host.

Defining SSL Proxy Profile objectsAn SSL Proxy Profile defines a level of SSL service when operating as an SSLproxy. The SSL proxy has the following modes:

forwardThe SSL proxy acts as an SSL client (or acts in the forward direction). Inclient proxy mode, SSL is used over the appliance-to-server connection.

reverseThe SSL proxy acts as an SSL server (or acts in the reverse direction). Inserver proxy mode, SSL is used over the appliance-to-client connection.

two-wayThe SSL proxy acts as both an SSL client and SSL server (or acts in bothdirections). In two-way mode, SSL is used over the appliance-to-serverconnection and the appliance-to-client-connection.

Creating a forward (or client) proxyTo create a forward SSL Proxy Profile, use the following procedure:1. Select Objects → Crypto → SSL Proxy Profile to display the SSL Proxy Profile

catalog.2. Click Add to display the SSL Proxy Profile Configuration screen.3. Specify the name of the object in the Name field.4. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.5. Select Forward from the SSL Direction list.6. Select the profile that defines SSL service to the backend server from the

Forward (Client) Crypto Profile list.7. Use the Client-side Session Caching toggle to enable or disable client side

caching.8. Click Apply to save the object to the running configuration.9. Optionally, click Save Config to save the object to the startup configuration.

Creating a reverse (or server) proxyTo create a reverse SSL Proxy Profile, use the following procedure:1. Select Objects → Crypto → SSL Proxy Profile to display the SSL Proxy Profile


inactive administrative state, click disabled.5. Select Reverse from the SSL Direction list.6. Select the profile that defines SSL service to frontend clients from the Reverse

(Server) Crypto Profile list.7. Use the Server-side Session Caching toggle to enable or disable server side

caching.


8. Specify the time that session-specific state data is maintained in the servercache in the Server-side Session Cache Timeout field.

9. Specify the maximum size of the server-side cache in the Server-side SessionCache Size field.

10. Use the Client Authentication is optional toggle to control when SSL clientauthentication is optional.

on Client authentication is not required. When there is no clientcertificate, the request does not fail.

off (Default) Requires client authentication only when the servercryptographic profile has an assigned Validation Credentials.

11. Use the Always Request Client Authentication toggle to control when torequest SSL client authentication.

on Always requests client authentication.

off (Default) Requests client authentication only when the servercryptographic profile has an assigned Validation Credentials.


Creating a two-way proxyTo create an SSL Proxy Profile, use the following procedure:1. Select Objects → Crypto → SSL Proxy Profile to display the SSL Proxy Profile


inactive administrative state, click disabled.5. Select Two Way from the SSL Direction list.6. Select the profile that defines SSL service to the backend server from the

Forward (Client) Crypto Profile list.7. Select the profile that defines SSL service to frontend clients from the Reverse

(Server) Crypto Profile list.8. Use the Server-side Session Caching toggle to enable or disable server side

caching.9. Specify the time that session-specific state data is maintained in the server

cache in the Server-side Session Cache Timeout field.10. Specify the maximum size of the server-side cache in the Server-side Session

Cache Size field.11. Use the Client-side Session Caching toggle to enable or disable client side

caching.12. Use the Client Authentication is optional toggle to control when SSL client

authentication is optional.

on Client authentication is not required. When there is no clientcertificate, the request does not fail.

off (Default) Requires client authentication only when the servercryptographic profile has an assigned Validation Credentials.

13. Use the Always Request Client Authentication toggle to control when torequest SSL client authentication.


on Always requests client authentication.

off (Default) Requests client authentication only when the servercryptographic profile has an assigned Validation Credentials.


Working with Validation Credentials objectsA Validation Credentials consists of a list of certificate objects. ValidationCredentials are used to validate the authenticity of received certificates and digitalsignatures. You can create Validation Credentials with the following types ofcredentials:v All non-expiring, non-password-protected credentialsv Select credentials

Independent of which type of Validation Credentials, the creation starts at thesame location. To create any Validation Credential, select Objects → Crypto →Crypto Validation Credentials.

Creating for non-expiring, non-password-protected certificatesYou can create a Validation Credential includes all valid, non-expired,non-password-protected certificates in the pubcert: file repository. The followingprocedure silently creates a Certificate object for each valid certificate file in thepubcert: file repository

To create this type of Validation Credentials, use the following procedure:1. Select Objects → Crypto → Crypto Validation Credentials.2. Click Create Validation Credential from pubcert: to display a confirmation

screen.3. Click Confirm to create the Validation Credentials, with the appliance-supplied

name of pubcert.4. After the WebGUI reports successful completion, click Close.

To refresh the Crypto Validation Credentials catalog, select Objects → Crypto →Crypto Validation Credentials. Click Refresh List.

To save the Validation Credentials to the startup configuration, click Save Config.

Creating for select certificatesTo prepare a Validation Credentials that contains selected certificate objects fromthe pubcert: file repository, use the following procedure:1. Select Objects → Crypto → Crypto Validation Credentials.2. Click Add.3. Provide the following inputs:




CertificatesUse the list to add select Certificate objects to the Validation Credentials.

Certificate Validation ModeSelect one of the following modes:

Match exact certificate or immediate issuer(Default) The behavior is that the Validation Credentials containseither the exact peer certificate to match or the certificate of theimmediate issuer, which could be an intermediate CA or a rootCA. This mode is useful when you want to match the peercertificate exactly, but that certificate is not a self-signed (root)certificate.

Full certificate chain checking (PKIX)The complete certificate chain is checked from subject to rootwhen using this Validation Credentials for certificate validation.Validation succeeds only if the chain ends with a root certificatein the Validation Credentials. Non-root certificates in theValidation Credentials will be used as untrusted intermediatecertificates. Additional untrusted intermediate certificates will beobtained dynamically from the context at hand (SSL handshakemessages, PKCS#7 tokens, PKIPath tokens, and so forth).

Use CRLsDetermines whether each Certificate Revocation List (CRL) is checkedduring the processing of the certificate chain.

on (Default) Checks the CRLs.

off Does not check CRLs.

Require CRLsWhen CRLs are checked during processing of the certificate chain,determines whether the processing should fail when no CRL is available.

on Processing fails.

off (Default) Processing succeeds.

CRL Distribution Points HandlingDetermines how to handle Certificate Revocation List (CRL) checking ofX.509 CRL Distribution Points extensions during processing of thecertificate chain and controls how to handle certificates in the ValidationCredentials.

Ignore Ignores extensions.

RequireChecks, but does not retrieve, extensions.

Initial Certificate Policy SetWhen the mode is PKIX, defines the certificate chain validation input thatRFC 3280 calls the “user-initial-policy-set”. This set of OIDs specifies theonly allowable values of Certificate Policies at the end of chainprocessing.

If you define an initial certificate policy set, you will want to enable theRequire Explicit Certificate Policy field. Otherwise, these certificatepolicy sets will be used only when there are Policy Constraints extensionsin the certificate chain.

The default contains the OID for anyPolicy.


Require Explicit Certificate PolicyWhen the mode is PKIX, controls whether the validation chain(algorithm) can end with an empty policy tree (that RFC 3280 calls the“initial-explicit-policy”).

on The algorithm must end with a non-empty policy tree.

off The algorithm can end with an empty policy tree unless PolicyConstraints extensions in the chain require an explicit policy.



z/OS NSS ClientThe z/OS NSS client enables integration with RACF® on the z/OSCommunications Server. The z/OS NSS Client object specifies the authenticationinformation required to allow the DataPower appliance to function as an NSSclient. The z/OS NSS Client object specifies the following properties:v Remote Address

v Remote Port

v SSL Proxy Profile

v Client ID

v System Name

v User Name

v Password

Based on these properties and the request type, the following actions occur:v DataPower requests a secure connection to the z/OS Communications Serverv RACF performs authentication of usersv RACF performs authorization to resourcesv RACF logs authorized and unauthorized attempts to access RACF-protected

resourcesv z/OS Communications Server NSS protocol provides return codes and reason

codes for connectivity requests

To support this functionality, the NSS server must be configured to support theNSS client. See the following z/OS Communications Server documentation forthese configuration steps:v Enable the XMLAppliance discipline support. For further information, refer to the

section on network security services server in the z/OS Communications Server: IPConfiguration Reference.

v Authorize the client userid to SAF profiles representing security services andresources. For further information, refer to the section on preparing to providenetwork security services in the z/OS Communications Server: IP ConfigurationGuide.

v Configure SSL for the TCP connection between the client and server. For furtherinformation, refer to the section on configuring the NSS server in the z/OSCommunications Server: IP Configuration Guide.

Only one physical connection per Remote Address, Remote Port, and Client ID isallowed. Additional z/OS NSS Client objects might be configured, but if more thanone client with the same tuple try to connect, the connection will fail. If the


connection is not established or the provided parameters are not valid, the objectoperational state is down and shows one of the following event codes:v Invalid registration parametersv TCP connection retry (interval is 1 minute)v TCP connection in progressv Communication failedv Cannot connect to host

For additional information on logged NSS protocol return codes and reason codes,refer to http://www.ibm.com/support/docview.wss?rs=852&uid=swg21329236 forz/OS Communications Server: IP Diagnosis Guide updates.

Contact NSS for SAF Authentication is selected as the Authenticate method in theAAA policy configuration and Contact NSS for SAF Authorization is selected forthe Authorization method.

Creating the z/OS NSS ClientTo configure a z/OS NSS client, use the following procedure:1. Select OBJECTS → z/OS Configurations → z/OS NSS Client to display the

catalog.2. To display the configuration screen, click Add.3. Specify the name of the object in the Name field.4. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.5. Specify a descriptive object-specific summary in the Comment field.6. Specify the IP address or hostname of the NSS server in the Remote Address

field.7. Specify the port on which the NSS server listens in the Remote Port field.8. Select an SSL Proxy Profile in the SSL Proxy field to provide a secure

connection to the remote authentication server.9. Specify the client ID to be used for registration with the NSS server in the

Client ID field.10. Specify the system name to identify the NSS client to the NSS server in the

System Name field.11. Specify the user name to use to authenticate with the SAF in the User Name

field.12. Specify the password to use to authenticate with the SAF in the Password

field.13. Reenter the password in the Confirm Password field.14. Click Apply to save the object to the running configuration.15. Optionally, click Save Config to save the object to the startup configuration.


http://www.ibm.com/support/docview.wss?rs=852&uid=swg21329236

Appendix A. User interface customization

This appendix contains information about creating an XML file that defines aspectsof the command line interface and the WebGUI user interface that you cancustomize. By using these custom interface extensions, the DataPower interfacescan display business and IT-centric information to users on each DataPowerappliance.

Each DataPower appliance can have a different custom user interface file, and allcustomized aspects of the interfaces apply to all users in all application domains.

To customize the user interfaces and to adhere to best practices, complete thefollowing high-level procedures:1. Build an XML that defines the aspects of the user interfaces to customize.2. Validate the conformance of the file against its schema.

The remaining sections of this appendix detail the markup that is necessary tocustom-tailor this XML file.

Using any text editor to create the XML file, you must cut and paste the markup,and then specify the content of each customized message within the markup.

After the XML file is complete, validate the conformance of the file against itsschema with the test schema command. For information about the test schemacommand, refer to the product-specific version of the Command Reference.

Aspects that can be customizedYou can custom-tailor the following aspects of the user interfaces:v The command line prompt extension to include the appliance identifier.v Pre-login, post-login, and appliance messages in command line sessions.v Pre-login, post-login, and appliance messages in WebGUI sessions, and the text

color and background color for these messages.

Markup supported for the XML fileWhen creating an XML file that defines the custom aspects of the user interface,the schema supports the following case-sensitive elements:

<User-Interface>The <User-Interface> element is the root element of the XML file anddefines the required namespace statements. The XML file must contain thiselement from the template without modification.

<CustomPrompt>The <CustomPrompt> element indicates whether to extend the command lineprompt with the appliance identifier. To enable this aspect, add thiselement from the template without modification.

<MarkupBanner>The <MarkupBanner> element identifies the messages to display to users inWebGUI sessions. The file can contain up to four <MarkupBanner> elements,based on a combination of the type attribute and location attribute.

The element supports the following attributes:

type="message-type"The type attribute identifies the type of message. This attributesupports the following keywords:

pre-loginDisplays the message before users log in to the WebGUI.You can define one pre-login message.

post-loginDisplays the message in a popup window immediatelyafter users log in to the WebGUI. You can define onepost-login message.

system-bannerDisplays the message on each WebGUI screen. You candefine two appliance messages depending on the keywordassociated with the location attribute. Use the locationattribute to define where on the WebGUI screen to displaythe message.

location="location"The location attribute indicates the location on the WebGUI screento display the message. This attribute is relevant only when usedwith type="system-banner". The location attribute supports thefollowing keywords:

header Displays the message at the top of each WebGUI screen.You can define one message with this keyword. You cannotdefine a message with this keyword and another with theboth keyword.

footer Displays the message at the bottom of each WebGUIscreen. You can define one message with this keyword. Youcannot define a message with this keyword and anotherwith the both keyword.

both (Default) Displays the message at the top and the bottomof each WebGUI screen. You can define one message withthis keyword. You cannot define a message with thiskeyword and another with the header keyword or with thefooter keyword.

foreground-color="color"The foreground-color attribute identifies the color of the text inthe WebGUI message. This attribute supports the followingkeywords:v none (Default)v blue

v green

v orange

v red

v yellow

The none keyword displays the text of a message in black.


background-color="color"The background-color attribute identifies the color of thebackground in the WebGUI message. This attribute supports thefollowing keywords:v none (Default)v blue

v green

v orange

v red

v yellow

The none keyword removes any color from the messagebackground.

For WebGUI messages, the contents of the <MarkupBanner> element caninclude the following standard HTML tags:

 Defines individual paragraphs.

 Defines text to display in italics.

Defines text to display in bold.

<tt> Defines text to display in monospace.

<TextBanner>The <TextBanner> element identifies the messages to display to users incommand line sessions. The file can contain up to three <TextBanner>elements, one for each keyword associated with the type attribute.

This element supports the following attribute:

type="message-type"The type attribute identifies the type of message. This attributesupports the following keywords:

pre-loginDisplays the message before users log in from thecommand line.

post-loginDisplays the message immediately after users log in fromthe command line.

system-bannerDisplays the message immediately after completing eachcommand invocation from the command line.

For command line messages, the content of the <TextBanner> elementcannot include other HTML or XML elements.

Structure of the XML fileThe following excepts display the structure of the XML file that defines aspects ofthe command line interface and the WebGUI interface that you can customize. Fora complete sample, refer to “Template of the custom user interface file” on page188.

Appendix A. User interface customization 185

<User-Interfacexmlns="http://www.datapower.com/schemas/user-interface/1.0">

<CustomPrompt>%s</CustomPrompt><MarkupBanner ... > ... </MarkupBanner><TextBanner ... > ... </TextBanner>

</User-Interface>

Command line prompt extension definitionTo custom-tailor the command line prompt, you must add the following markupwithout modification to the XML file:

<CustomPrompt>%s</CustomPrompt>

The %s indicates a variable that represents the appliance identifier, as defined withthe System Identifier field in System Settings (Administration → Device → SystemSettings).

For example, if the System Identifier field is IDD, the generic xi50# prompt wouldchange to the custom IDD:xi50# prompt.

Example messages for WebGUI sessionsMessages for WebGUI sessions include the pre-login message, the post-loginmessage, and the appliance message. WebGUI messages can be an unlimitednumber of characters in length.

Example pre-login messageThe following example shows the markup for a pre-login message that displaysbefore users log in. In this example, the color behind the message is blue.<MarkupBanner type="pre-login" background-color="blue">

XYZ LLC - London</MarkupBanner>

Example post-login messageThe following example shows the markup for a post-login message that displays ina popup window immediately after users log in. In this example, the text color isred, and the word “refreshed” is in italics.<MarkupBanner type="post-login" foreground color="red">

XYZ cycles after-hour servers each day. Use a refreshedserver number at all times.

</MarkupBanner>

Example appliance messagesSystem messages for WebGUI sessions can be displayed on the top of the screen(location= "header"), the bottom of the screen (location= "footer"), or in bothlocations (location= "both").

The following example shows the markup for an appliance message that displayson the top of the screen. In this example, the text color is green on a redbackground.<MarkupBanner type="system-banner" location="header"

foreground-color="green" background-color="red">Use a supervisor console to access a public Internet Web site.

</MarkupBanner>

The following example shows the markup for an appliance message that displayson the bottom of the screen. In this example, the text color is blue on a yellowbackground.<MarkupBanner type="system-banner" location="footer"

foreground-color="blue" background-color="yellow">Use a supervisor console to access a public Internet Web site.

</MarkupBanner>

Example messages for command line sessionsMessages for command line sessions include the pre-login message, the post-loginmessage, and the appliance message. Pre-login and post-login messages can be anunlimited number of characters in length, but appliance messages are limited to255 characters in length.

Example pre-login messageThe following example shows the markup for a pre-login message that displaysbefore users log in.<TextBanner type="pre-login">

Use XYZ access codes for all external requests.</TextBanner>

Example post-login messageThe following example shows the markup for a post-login message that displaysimmediately after users log in.<TextBanner type="post-login">

Only XYZ employees are authorized to use this station.</TextBanner>

Example appliance messageThe following example shows the markup for an appliance message that displaysafter each command invocation.<TextBanner type="system-banner">

XYZ NA</TextBanner>

Appendix A. User interface customization 187

Template of the custom user interface fileThe following template is an XML file to help you create the custom user interfacefile for your DataPower appliance. This template conforms to the schema(store:///schemas/dp-user-interface.xsd).

<User-Interfacexmlns="http://www.datapower.com/schemas/user-interface/1.0">

<CustomPrompt>%s</CustomPrompt>

<MarkupBanner type="pre-login" foreground-color="red" background-color="blue">

WebGUI pre-login message</MarkupBanner><MarkupBanner type="post-login" foreground-color="blue" background-color="yellow">

WebGUI post-login pop up message</MarkupBanner><MarkupBanner type="system-banner" location="header" foreground-color="green"

background-color="red">WebGUI system message - header

</MarkupBanner><MarkupBanner type="system-banner" location="footer" foreground-color="blue"

background-color="yellow">WebGUI system message - footer

</MarkupBanner>



<MarkupBanner type="system-banner">WebGUI system message - header and footer

</MarkupBanner>

<TextBanner type="pre-login">

Command line pre-login message</TextBanner><TextBanner type="post-login">

Command line post-login message</TextBanner><TextBanner type="system-banner">

Command line system message</TextBanner>

</User-Interface>

Appendix B. Getting help and technical assistance

This section describes the following options for obtaining support for IBMproducts:v “Searching knowledge bases”v “Getting a fix”v “Contacting IBM Support” on page 190

Searching knowledge basesIf you encounter a problem, you want it resolved quickly. You can search theavailable knowledge bases to determine whether the resolution to your problemwas already encountered and is already documented.

DocumentationThe IBM WebSphere DataPower documentation library provides extensivedocumentation in Portable Document Format (PDF). You can use thesearch function of Adobe® Acrobat to query information. If you downloadand store the documents in a single location, you can use the search facilityto find all references across the documentation set.

IBM SupportIf you cannot find an answer in the documentation, use the Search Supportfeature from the product-specific support page.

From the Search Support (this product) area of the product-specificsupport page, you can search the following IBM resources:v IBM technote databasev IBM downloadsv IBM Redbooks®

v IBM developerWorks®

Getting a fixA product fix might be available to resolve your problem. To determine what fixesare available for your IBM product, check the product support site by performingthe following steps:1. Go to the IBM Support site at the following Web address:

http://www.ibm.com/support2. Select Support & Downloads → Download to open the Support & downloads

page.3. From the Category list, select WebSphere.4. From the Sub-Category list, select WebSphere DataPower SOA Appliances.5. Click the GO icon to display the list of most recent updates.6. Click the link for the firmware and documentation download that is specific to

your WebSphere DataPower product.7. Follow the instructions in the technote to download the fix.


http://www.ibm.com/support

Contacting IBM SupportIBM Support provides assistance with product defects. Before contacting IBMSupport, the following criteria must be met:v Your company has an active maintenance contract.v You are authorized to submit problems.

To contact IBM Support with a problem, use the following procedure:1. Define the problem, gather background information, and determine the severity

of the problem. For help, refer to the Software Support Handbook. To access theonline version of this handbook, use the following procedure:a. Access the IBM Software Support Web page at the following Web address:

http://www.ibm.com/software/supportb. Scroll down to the Additional support links section of the page.c. Under Support tools, click the Software Support Handbook link.d. Bookmark this page for future reference.From this page, you can obtain a PDF copy of the handbook.

2. Gather diagnostic information.a. Access the product support at the following Web address:

http://www.ibm.com/software/integration/datapower/supportb. Locate the Assistance area of the product support page.c. Click Information to include to access that technote that lists the

information that is required to report a problem.3. Submit the problem in one of the following ways:

OnlineFrom the IBM Support Web site (http://www.ibm.com/support), selectSupport & Downloads → Open a service request. Following theinstructions.

By phoneFor the phone number to call in your country, refer to “Contacts” in theSoftware Support Handbook. From the Software Support Handbook Website, click Contacts. In the U.S. and Canada, call 1–800–IBM-SERV(1–800–426–7378) and select option 2 for software.

If the problem you should submit is for a software defect or for missing orinaccurate documentation, IBM Support creates an authorized program analysisreport (APAR). The APAR describes the problem in detail. Whenever possible, IBMSupport provides a workaround that you can implement until the APAR isresolved and a fix is delivered.


http://www.ibm.com/software/support

http://www.ibm.com/software/integration/datapower/support

http://www.ibm.com/support

Notices and trademarks

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information about theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law: INTERNATIONALBUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS”WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFNON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULARPURPOSE. Some states do not allow disclaimer of express or implied warranties incertain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvements orchanges in the product(s) or the program(s) described in this publication at anytime without notice.

TrademarksIBM, the IBM logo, CICS, developerWorks, DB2, DataPower, IMS, RACF,Redbooks, Tivoli, WebSphere, and z/OS are registered trademarks of theInternational Business Machines Corporation in the United States or othercountries.

Adobe, the Adobe logo, PostScript, and the PostScript logo are either registeredtrademarks or trademarks of Adobe Systems Incorporated in the United States,and/or other countries.

Microsoft and Windows are trademarks of Microsoft Corporation in the UnitedStates, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries.


Other company, product, and service names may be trademarks or service marksof others.


Index

Special characters... button

list of referenced object 5referenced object 4

.java.policy file 119+ button

list of referenced object 5referenced object 4

Numerics9235 features

auxiliary data storage 123

AAAA

authenticationsearch parameters 36

search parameters 36AAA Policy

z/OS NSS Client 181accepted configuration

deployment policy 145Access Control List

clause sequence 161configuring 162creating 162IPv6 161object pages 162overview 161ssh instance 161SSH service 161Web Management Service 161web-mgmt instance 161XML Management Interface 161xml-mgmt instance 161

access management 13access policy

adding 52editing access profile 54elements 51examples

granting full access 53granting user management

permissions 53using wildcards 53

removing access profile 54Access Policy builder 51access profile

editing access policy 54removing from access policy 54

access rights for CLIdefined on user groups 48

access rights for WebGUIdefined on group account 47

accountsSee also group-defined accountsSee also privileged accountsSee also user accounts

accounts (continued)accessing MIB 57changing passwords 57configuring SNMP users 57forcing password change 56group-defined access level 55managing 55privileged access level 55RBM policy 37user access level 55

ACLSee Access Control List

active-activefailover configurations

Ethernet interfaces 71VLAN interfaces 71

active-standbyfailover configurations


Add buttonlist of referenced object 5

Address Resolution Protocol (ARP)See ARP

admin accountexporting configuration data 133

Administration menu 3administrative states, objects 8allow clauses, ACL 161AMP endpoint 100AP-REQ message, Kerberos 164appliance

appliance settings 83generating appliance certificate 83rebooting 82reloading firmware 82rolling back firmware 113selecting reboot configuration 80setting time 79shutting down 82upgrading firmware 113

appliance certificate 83appliance configuration

backing up 133comparing 142configuration checkpoints 138copying

files 136objects 136

exporting 133select objects and files 135

importing configuration 140managing configuration changes 141moving


reading change report 143reverting changes 143undoing changes 143

appliance management 71

appliance settingsconfiguring 83

appliance-wide loglocation 115

Application Domainobject pages 128

application domainsSee also domainsbacking up configuration 134catalog 128creating 128restarting

from catalog 130from System Control panel 129,

130Apply button 6ARP

defining retries 75defining retry intervals 76

aspects ofcustomizing the interface 183

au-method of authenticationRBM policy file 41

audit loglocation 115viewing 115

audit: directory 115authenticate users

RBM 14authentication

configuring RADIUS settings 175custom RBM method 16LDAP 36LDAP RBM method 19local user RBM method 22RADIUS RBM method 24RBM 14SAF RBM method 26search parameters 36SPNEGO RBM method 28SSL user certificate RBM method 31XML file RBM method 33

authfile.xml file 41authorization

RBM 15authorize access to users

RBM 15auto-config.cfg file 6auxiliary data storage 123

Bbold typeface xibuilder

access policy 51deployment policy 146RBM policy file 41

buttons... 4+ 4Apply 6


buttons (continued)Cancel 6Delete 7Edit 5Logout 3Save Config 3, 6Undo 7View 5

Ccaches

DNS hostsflushing 76

Cancel button 6capabilities

RBM 14capture.pcap file 74cert: directory 115certificate files

location 115Certificate objects

export packages 133Certificate Revocation List

See CRLcertificates

DER 63exporting 65generating 64importing 66PEM 63PKCS #12 63PKCS #8 63security

location, shared 116location, Web browsers 116

supported formats 63uploading 119

checkpoint configuration fileslocation 115

chkpoints: directory 115CLI

removing access to a commandgroup 49

CLI access rightsdefined on user groups 48

Clone link 8command groups

controlling access 48command line

customizing the interface 183RBM

changing admin-state 39restoring access 38

commandsSee also utilitiesweb-mgmt 3

communities, SNMP 94compact flash

configuring 123file system

initializing 123managing 123repairing 124

config: directory 115

configurationmanaging appliance

configuration 127configuration checkpoints

defining number to allow 138deleting 139listing 139loading 139overwriting 138rolling back 139saving 138

configuration dataapplying 6backing up

SOAP Interface 104WebGUI 133

backing up application domains 134comparing

SOAP Interface 104WebGUI 142

configuration checkpoints 138copying


different release level 133exchanging 133exporting

location of files 115select objects and files 135SOAP Interface 104WebGUI 133

files not included 133importing

SOAP Interface 104WebGUI 133, 140

managing changes 141moving


objects not included 133reading change report 143reading changes 143restoring

SOAP Interface 105saving 6undoing changes 143

configuration filesexported, location 115location 115

configuration states, objects 8Conformance Report

generatingSOAP Interface 104

contexts, SNMP 96Control Panel

File Management 117credentials

identificationconfiguring 164creating 164

credentials mappingLDAP 36search parameters 36

CRLenabling update policy 67update policy 67

CRL Retrievalobject pages 67

Crypto Certificateconfiguring 162creating 162object pages 162

Crypto Certificate Monitorconfiguring 68creating 68object pages 68

Crypto Identification Credentialsobject pages 164

Crypto Keyconfiguring 167creating 167object pages 167

Crypto Profileconfiguring 173creating 173object pages 173

Crypto Toolsadding SSH known hosts 176exporting certificates 65exporting keys 65generating certificates 64generating keys 64importing certificates 66importing keys 66

Crypto Validation Credentialsobject pages 179

customer supportcontacting 190obtaining fixes 189searching knowledge bases 189

customizing the interfaceaspects of 183defining messages for CLI 187defining messages for WebGUI 186defining the CLI prompt 186structure of XML file 185supported markup 183

Ddashboard 3data storage

9235 only 123auxiliary 123compact flash

configuring 123file system, initializing 123file system, managing 123file system, repairing 124

hard disk arrayconfiguring 124file system, initializing 124file system, managing 124file system, repairing 125RAID volume, activating 125RAID volume, deleting 126RAID volume, initializing 125RAID volume, managing 125RAID volume, rebuilding 125

datesetting 79

default loglocation 115


defining messages for CLIcustomizing the interface 187

defining messages for WebGUIcustomizing the interface 186

defining the CLI promptcustomizing the interface 186

del-config element 105Delete button 7

list of referenced object 5deny clauses, ACL 161deployment policy

accepted configuration 145creating 145filtered configuration 145modified configuration 145using the builder 146

Deployment Policyobject pages 145

deployment policy buildercreating matching statements 146

DERcertificate format 63key format 63

destination based routing, managing 75directories

audit: 115available 115cert: 115chkpoints: 115config: 115displaying contents 117dpcert: 115export: 115hiding contents 117image: 115local: 115logstore: 115logtemp: 115managing 115pubcert: 116refreshing contents 118sharedcert: 116store: 116tasktemplates: 117temporary: 117

disabled administrative state 8DNS Cached Hosts

flushing the cache 76DNS Settings

configuring name resolution 76flushing the cache 76IPv6 76object pages 76purpose 76search domains 76static hosts 76

do-action element 105do-backup element 104do-export element 104do-import element 104do-restore element 105documentation conventions, typefaces xiDomain list 3domains

application domains 127default domain 127managing 127

domains (continued)visible domains 128

down operation state 8dpcert: directory 115

EECN

disabling TCP sessions 75Edit button 5email pager

configuring 153enabled administrative state 8endpoints

AMP 100SLM 100UDDI Subscription 100

enterprise MIBsSee MIBs

ethereal utility 74Ethernet Interface

configuring 72managing 72object pages

Main 72Standby Control 73Static Routes 73

Ethernet interfacesfailover configuration 71IPv6 71overview 71packet capture 74removing from network 74static routes 73

EUIformat 89iSCSI HBA 89iSCSI Target 89

evaluate access profileRBM 15

event subscription filterssetting 150

event subscriptionssetting 152

event suppression filterssetting 150

examplesaccess policy

granting full access 53granting user management

permissions 53using wildcards 53

SOAP Interfacecomparing configurations 107sample request, compare

configurations 107sample request, status 106sample response, compare

configurations 107sample response, status 106viewing status 106

Explicit Congestion Notification (ECN) inTCP

See ECNExport link 7export packages

admin account 133

export packages (continued)files not included 133objects not included 133permission 133

export: directory 115Extended Unique Identifier

See EUI

Ffailover configuration


file formatspcap 74

file managementiSCSI

repairing volume 90File Management utility, launching 117file space

thresholds 81throttle 81

file systemSee directories

files.java.policy 119authfile.xml 41auto-config.cfg 6capture.pcap 74certificates

location 115checkpoint configurations

location 115configurations

location 115copying 120

remote URL 120creating custom user interface 188deleting 122downloading

SOAP Interface 104editing

during configuration 6File Management utility 122

exported, location 115fetching 120healthcheck.xml 172healthcheck.xsl 173listing

SOAP Interface 104logs, viewing 153managing 115moving 121not in export packages

firmware files 133log files 133

packet captures (pcap) 74private keys

location 115RBMInfo.xml 41renaming 121uploading

JKS 119remote 120SOAP Interface 104workstation 118

Index 195

files (continued)viewing

during configuration 6File Management utility 122

XML Management Interfaceschema 102WSDL 102

xml-mgmt-base.xsd 102xml-mgmt-ops.xsd 102xml-mgmt.wsdl 102xml-mgmt.xsd 102

filtered configurationdeployment policy 145

firmwareapplying 113rolling back 113upgrading 113

firmware filesbetween release levels 133export packages 133

firmware imageslocation 115

fixes, obtaining 189flash drive

See directoriesflush RBM cache

RBM 40

Gget-config element 105get-conformance-report element 104get-diff element 104get-file element 104get-filestore element 104get-log element 104get-samlart element 103get-status element 104group account

defining access rights for WebGUI 47

Hhard disk array

configuring 124file system

initializing 124managing 124repairing 125

RAID volumeactivating 125deleting 126initializing 125managing 125rebuilding 125

health checkfilter 173SOAP request 172

healthcheck.xml file 172healthcheck.xsl file 173Host Alias

object pages 77host aliases

using local aliases 77Host Bus Adapter

See iSCSI HBA

hostsadding known (SSH) 176

HTTP Serviceconfiguring HTTP Service

objects 157configuring SSL Proxy Service

objects 158creating HTTP Service objects 157creating SSL Proxy Service

objects 158object pages 157, 158service description 157

IICMP

disabling 75managing requests 75

Identification Credentialsconfiguring 164creating 164

image: directory 115Import Package

creating 131Include Configuration File

creating 130object pages 130

installation imagesSee firmware images

intellectual property 191interface isolation

enforcing 75relaxing 75

IP address filterssetting 152

IPv6DNS 76Ethernet interfaces 71VLAN interfaces 71

IQNformat 89iSCSI HBA 89

iSCSI CHAPconfiguring 91object pages 91

iSCSI HBAconfiguring 92IQN 89object pages 92

iSCSI Host Bus AdapterSee iSCSI HBA

iSCSI qualified nameSee IQN

iSCSI Targetconfiguring 91EUI 89IQN 89object pages 91

iSCSI volumeconfiguring 90initializing 90managing 89repairing 90

iSCSI, support 89italics typeface xi

JJ2RE (j2re1.4.2) 119j2re1.4.2 (J2RE) 119j2sdk1.4.2 (SDK) 119Java Crypto Extension

See SunJCEJava Crypto Extension Key Store

See JCEKSJava Key Store

See JKSjava.security package 119JCE

See SunJCEJCEKS 119JKS

crypto extension 119granting permissions 119java.security package 119keytool utility 119managing 119required software 119uploading certificates 119working with 119

KKDC, Kerberos 164Kerberos

AP-REQ message 164configuring KDC server 166KDC 164keytab 164principal 164

Kerberos KDC serverconfiguring 166creating 166object pages 166

Kerberos keytabconfiguring 166definition 164

Kerberos Keytab Fileobject pages 166

Key Distribution CenterSee KDC

Key objectsexport packages 133

key-certificate pairscreating 63

keysDER 63exporting 65generating 64importing 66PEM 63PKCS #12 63PKCS #7 63supported formats 63

knowledge basessearching 189

LLDAP

authenticationsearch parameters 36


LDAP (continued)credentials mapping

search parameters 36RBM authentication 19search parameters 36

LED lightslocate LED

activating 82controlling 82deactivating 83

licensingsending inquiries 191

limitationsRBM account policy 37

linksClone 8Export 7Show Probe 9View Logs 7View Status 8

load balancer groupcreating 168server state 168

Load Balancer Groupadding members 171assigning weight 171configuring, basic 169example

Log Target 154health

convalescent (down) 169healthy (up) 168quarantined (softdown) 168

health checksenabling 172overriding port 171

health of members 168object pages

Health 172Main 169Members 171

service/lbhealth/ variable 169local: directory 115locate LED

activating 82controlling 82deactivating 83

log categoriesconfiguring 150

log filesexport packages 133

log files, viewing 153Log Target

Load Balancer Group 154XML Manager 154

log targetsconfiguring 150event subscription filters 150event suppression filters 150IP address filters 152managing 150object filters 151types 149

login token, retrieving 103Logout button 3

logsappliance-wide

location 115audit

location 115viewing 115

defaultlocation 115

retrievingSOAP interface 104

viewing from catalog 7viewing from configuration screen 7viewing object-specific logs 7

logstore: directory 115logtemp: directory 115

MManagement Information Base

See MIBmatching statements

deployment policy builder 146deployment policy, manual 147

mc-method of authorizationRBM policy file 41

memorythresholds 81throttle 81

message catalogs 116MIB

configuring access 57MIBs

viewing 94modified configuration

deployment policy 145Modified configuration state 8modify-config element 105monospaced typeface xi

NNAS-identifier 175navigation

Administration menu 3Network menu 3Objects menu 3Services menu 3Status menu 3

networkremoving Ethernet interfaces 74

Network menu 3network setting

ARP retries 75ECN in TCP 75ICMP 75interface isolation 75routing 75TCP retries 75

network settingsobject pages 74

New configuration state 8NFS Dynamic Mounts

object pages 85NFS Static Mounts

object pages 87notices 191

notification recipients, SNMP 95NTP Service

object pages 78

Oobject filters

setting 151object pages

Access Control List 162Application Domain 128CRL Retrieval 67Crypto Certificate 162Crypto Certificate Monitor 68Crypto Identification Credentials 164Crypto Key 167Crypto Profile 173Crypto Validation Credentials 179Deployment Policy 145DNS Settings 76Ethernet Interface


Host Alias 77HTTP Service 157Include Configuration File 130iSCSI CHAP 91iSCSI HBA 92iSCSI Target 91Kerberos KDC server 166Kerberos Keytab File 166Load Balancer Group

Health 172Main 169Members 171

NFS Dynamic Mounts 85NFS Static Mounts 87NTP Service 78SSH Service 97SSL Proxy Profile 177SSL Proxy Service 158TCP Proxy Service 159Telnet Service 97VLAN Sub-Interface


Web Management Service 98XML Management Interface

Advanced 102Main 101

objectsadministrative state 8configuration state 8creating

SOAP Interface 105deleting

SOAP Interface 105modifying

SOAP Interface 105not in export packages

Certificate 133Key 133User 133

operational state 8

Index 197

objects (continued)referenced

... button 4+ button 4creating 4modifying 4selecting 4

retrievingSOAP Interface 105

status 8Objects menu 3objects pages

Network setting 74operational states, objects 8

Ppacket captures

initiating 74pager, email

configuring 153passwords

changing 57forcing change 56RBM policy 35

patents 191pcap files 74PEM

certificate format 63key format 63

PKCS #12certificate format 63key format 63

PKCS #7certificate format 63

PKCS #8key format 63

principal, Kerberos 164private key files

location 115private keys

uploading 119pubcert: directory 116

QQCodes

thresholds 81throttle 81

RRADIUS

NAS-identifier 175purpose 175RBM authentication 24

RBMaccount policy 37authenticate users 14authorizing access to resources 15builder 41capabilities 14changing admin-state 39configuration steps 15custom authentication 16defining access credentials 47

RBM (continued)defining credential mapping 41defining user authentication 41defining user groups accounts for 47evaluate access profile 15extending RBM access to WebGUI

only 39flushing RBM cache 40LDAP authentication 19local user authentication 22password policy 35RADIUS authentication 24restoring access from command

line 38retrieving credentials 15SAF authentication 26settings 13SPNEGO authentication 28SSL user certificate authentication 31XML file authentication 33

RBM policy fileau-method of authentication 41mc-method of authorization 41

RBMInfo.xml file 41reboot configuration, selecting 80referenced objects

... button 4+ button 4creating 4modifying 4selecting 4

referenced objects, lists... button 5+ button 5Add button 5adding 5creating 5Delete button 5deleting 5modifying 5selecting 5

remote file managementiSCSI volume

configuring 90initializing 90managing 89

removing access to a command groupCLI 49

retrieving credentialsRBM 15

role-based managementSee RBM

routingdestination based 75

SSAML artifact, retrieving 103Save Config button 3, 6Saved configuration state 8schema files

XML Management Interface 102schemas

location 116SDK (j2sdk1.4.2) 119search domains

configuring 76

search domains (continued)DNS 76

search parameters, LDAP 36security certificates

sharedlocation 116

Web browserslocation 116

server poolSee load balancer group

server stateload balancer group 168

service ACLSee Access Control List

service/lbhealth/ variable 169Services

HTTP Service 157SSL Proxy Service 158TCP Proxy Service 159

Services menu 3set-config element 105set-file element 104sharedcert: directory 116Show Probe link 9SLM endpoint 100SNMP

configuring accounts 57configuring communities 94configuring contexts 96configuring notification recipients 95configuring settings 92configuring subscriptions 94configuring traps 95global properties 93traps, SNMP 95versions 92viewing MIBs 94

SOAP interfaceaccessing configuration data 102XML Management Interface 102

SOAP Interfaceexample

comparing configurations 107viewing status 106

requestsavailable operations 103general structure 103

responsesgeneral structure 103

sample requestcompare configurations 107status 106

sample responsecompare configurations 107status 106

SOAP requesthealthcheck.xml 172

SOMASee SOAP Interface

SPNEGORBM authentication 28

SSH known hostsadding 176

SSH serviceAccess Control List 161IPv6 161


SSH Serviceobject pages 97

SSLclient proxy, creating 177forward proxy, creating 177reverse, proxy, creating 177server proxy, creating 177two-way proxy, creating 178

SSL authentication 173SSL Proxy Profile

creatingclient proxy 177forward proxy 177reverse proxy 177server proxy 177two-way proxy 178

object pages 177SSL Proxy Service

service description 158static hosts

configuring 76DNS 76

static routesEthernet interfaces 73VLAN interfaces 73

Status menu 3status object, retrieving 104status provider

See status objectstatus providers

DNS Cached Hosts 76store: directory 116structure of XML file

customizing the interface 185style sheets

healthcheck.xsl 173location 116

subdirectoriescreating 117deleting 118

subscriptionsSNMP 94

SunJCEJCEKS 119

supportSee customer support

supported markupcustomizing the interface 183

Ttasktemplates: directory 117TCP

defining retries 75disabling due to ECN 75SYN 75

TCP Proxy Serviceconfiguring TCP Proxy Service

objects 159creating TCP Proxy Service

objects 159object pages 159service description 159

tcpdump utility 74Telnet Service

object pages 97

templatescreating custom user interface 188

temporary: directory 117thresholds

file space 81memory 81QCodes 81

throttleconfiguring 81

timesetting 79

time zonecreating custom 79setting 79

trademarks 191typeface conventions xi

UUDDI Subscription

endpoint 100XML Management Interface 100

Undo button 7up operational state 8update policy, CRL 67upgrades

applying 113rolling back 113

user accountmigrating user to new group 56resetting admin password 56restrict user to domain 56

user authenticationRADIUS 175

user group accountsdefining RBM access credentials 47managing 47

user groupsaccess policy

builder 51Access Policy builder 51creating 47defining access policy 51defining access rights for CLI 47managing command line access 48

user interfacescustomizing 183

User objectsexport packages 133

usersaccount policy 37password policy 35

utilitiesethereal 74keytool 119tcpdump 74

VValidation Credentials

creatingnon expiring, non-password-

protected certificates 179select certificates 179

types of lists 179

variablesload balancer service

service/lbhealth/ 169View button 5View Logs link 7View Status link 8virtual LAN interface

See VLAN interfacevisible domains 128VLAN interfaces

configuring 72failover configuration 71IPv6 71managing 72overview 71packet capture 74static routes 73

VLAN Sub-Interfaceobject pages


WWeb Management Interface 3Web Management Service

Access Control List 161IPv6 161object pages 98

Web Services Distributed ManagementSee WSDM

web-mgmt command 3WebGUI

accessing 3Administration menu 3applying configuration changes 6canceling changes 6cloning services 8common tasks 6customizing the interface 183dashboard 3deleting objects 7Domain list 3exporting objects 7extending RBM access to WebGUI

only 39logging in 3Logout button 3Network menu 3Objects menu 3resetting configuration 7reverting changes 7Save Config button 3saving configuration changes 6Services menu 3Status menu 3viewing object status 8viewing object-specific logs 7viewing probe data 9Welcome screen 3

WebGUI access rightsdefined on user groups 48

Welcome screen 3workstation

uploading files 118

Index 199

WSDL filesXML Management Interface 102

WSDMendpoint 100

WSDM interfaceaccessing configuration data 108XML Management Interface 108

XXML Management Interface

Access Control List 161changing default security 102changing HTTP settings 102endpoints

AMP 100SLM 100UDDI Subscription 100WS-Management 100WSDM 100

IPv6 161object pages

Advanced 102Main 101

overview 100Services

available 100enabling 101

SOAP interface 102WSDM interface 108

XML ManagerLoad Balancer Group

Log Target 154xml-mgmt-base.xsd schema file 102xml-mgmt-ops.xsd schema file 102xml-mgmt.wsdl WSDL file 102xml-mgmt.xsd schema file 102

Zz/OS NSS Client

creating 182overview 181


��

Printed in USA

3.7.3-AdministratorsGuide

Documents

Transcript of 3.7.3-AdministratorsGuide