am611 sms admin

Tivoli® Access Manager for e-businessVersion 6.1.1

Shared Session ManagementAdministration Guide

SC23-6509-01

��

NoteBefore using this information and the product it supports, read the information in Appendix D, “Notices,” on page 101.

Edition notice

This edition applies to version 6, release 1, modification 1 of IBM Tivoli Access Manager (product number5724-C87) and to all subsequent releases and modifications until otherwise indicated in new editions.

All rights reserved.

© Copyright IBM Corporation 2005, 2010.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

About this publication . . . . . . . . vIntended audience . . . . . . . . . . . . vPublications . . . . . . . . . . . . . . v

IBM Tivoli Access Manager for e-business library viRelated products and publications. . . . . . viiAccessing terminology online . . . . . . . viiiAccessing publications online . . . . . . . viiiOrdering publications . . . . . . . . . . ix

Accessibility . . . . . . . . . . . . . . ixTivoli technical training . . . . . . . . . . ixTivoli user groups . . . . . . . . . . . . xSupport information . . . . . . . . . . . . xConventions used in this publication . . . . . . x

Typeface conventions . . . . . . . . . . xOperating system-dependent variables and paths xi

Chapter 1. Introduction . . . . . . . . 1Session management server administration options . 1Session management server features . . . . . . 2

Session information consistency . . . . . . . 3Cluster-wide login policy enforcement . . . . . 3Failover . . . . . . . . . . . . . . . 3Session information management . . . . . . 3Support for multiple instances . . . . . . . 3Limited session realms . . . . . . . . . . 4

Session management server architecture . . . . . 4Deployment considerations . . . . . . . . . 6Security considerations . . . . . . . . . . . 9

Configuring secure communications . . . . . 9Configuring secure communications between theWebSphere Web server plug-in and theWebSphere server . . . . . . . . . . . 10Configuring session management serverauthorization . . . . . . . . . . . . . 11Configuring security role membership for SMSadministrator . . . . . . . . . . . . . 13

WebSEAL and Plug-in for Web Serversconfiguration . . . . . . . . . . . . . . 14Single sign-on with the session management server 14Back-end storage mechanisms . . . . . . . . 15

Single server . . . . . . . . . . . . . 15Clustered server . . . . . . . . . . . . 16

Chapter 2. Configuration . . . . . . . 17Installing the session management server . . . . 17

Installing Fixpack upgrades . . . . . . . . 18Deploying the session management server . . . . 18Configuring the session management server . . . 19

Gathering configuration details . . . . . . . 20Running the configuration utility . . . . . . 23

Configuring the command line extensions . . . . 23Which command line to use? . . . . . . . 23Other considerations . . . . . . . . . . 23

Unconfiguring the session management server . . 24Deploying and configuring additional instances . . 24

Adding a new member to an SMS cluster . . . . 26

Chapter 3. Using the sessionmanagement server . . . . . . . . . 27Searching user sessions . . . . . . . . . . 27Ending user sessions . . . . . . . . . . . 28Setting the maximum concurrent sessions . . . . 28Displaying session realms and replica sets . . . . 29Managing replica sets and realms . . . . . . . 29Managing keys . . . . . . . . . . . . . 30Session management server statistics . . . . . . 30Tracking login activity . . . . . . . . . . . 31

Storing the login activity data . . . . . . . 31Creating the login activity database . . . . . 32

Setting rules for credential refresh . . . . . . . 32

Chapter 4. Session management serverbest practices. . . . . . . . . . . . 35Zone rules and zone configuration. . . . . . . 35

Zone configuration . . . . . . . . . . . 35Zone rule . . . . . . . . . . . . . . 35WebSphere eXtreme Scale zones . . . . . . 35

Load balancer settings . . . . . . . . . . . 36SMS sessions and session limit policy . . . . . 37

Session limit policy . . . . . . . . . . . 37Number of concurrent sessions . . . . . . . 37Session cache size . . . . . . . . . . . 37

Tuning the Java Virtual Machine . . . . . . . 38WebSphere Application Server Heap Size . . . 38WebSphere Application Server DeploymentManager Heap Size. . . . . . . . . . . 38WebSphere Application Server Node Agent HeapSize . . . . . . . . . . . . . . . . 3932-bit and 64-bit considerations . . . . . . . 39Configuring the Object Request Broker . . . . 39

Session Management Server High AvailabilityConsiderations . . . . . . . . . . . . . 39

Hard failure detection . . . . . . . . . . 40eXtreme Scale container JVMs . . . . . . . 40Container failure . . . . . . . . . . . 41eXtreme Scale Catalog service . . . . . . . 41Running catalog servers inside WebSphereApplication Server JVM processes . . . . . . 41Running catalog servers inside stand-alone JVMs 42Catalog service failure . . . . . . . . . . 43Catalog service quorum behavior . . . . . . 43Failure scenarios. . . . . . . . . . . . 45Recovery procedures . . . . . . . . . . 47

Appendix A. SMS pdsmsadmin andpdadmin commands . . . . . . . . . 49Reading syntax statements . . . . . . . . . 49login . . . . . . . . . . . . . . . . 50set instance . . . . . . . . . . . . . . 51

© Copyright IBM Corp. 2005, 2010 iii

instances list . . . . . . . . . . . . . . 52server list . . . . . . . . . . . . . . . 53key change . . . . . . . . . . . . . . 54key show . . . . . . . . . . . . . . . 56realm list . . . . . . . . . . . . . . . 58realm show . . . . . . . . . . . . . . 60session refresh all_sessions . . . . . . . . . 62session refresh session . . . . . . . . . . . 64replica set list. . . . . . . . . . . . . . 66replica set show . . . . . . . . . . . . . 68session list. . . . . . . . . . . . . . . 70session terminate all_sessions . . . . . . . . 72session terminate session . . . . . . . . . . 74trace get . . . . . . . . . . . . . . . 76trace set . . . . . . . . . . . . . . . 78

Appendix B. SMS utilities. . . . . . . 81pdsmsclicfg . . . . . . . . . . . . . . 82smsbackup . . . . . . . . . . . . . . 85smscfg . . . . . . . . . . . . . . . . 87smsservicelevel . . . . . . . . . . . . . 94

Appendix C. Support information . . . 95Searching knowledge bases . . . . . . . . . 95

Searching information centers . . . . . . . 95Searching the Internet . . . . . . . . . . 95

Obtaining fixes . . . . . . . . . . . . . 95Registering with IBM Software Support . . . . . 96Receiving weekly software updates . . . . . . 96Contacting IBM Software Support . . . . . . . 97

Determining the business impact . . . . . . 97Describing problems and gathering information 98Submitting problems . . . . . . . . . . 98

Appendix D. Notices . . . . . . . . 101Trademarks . . . . . . . . . . . . . . 103

Glossary . . . . . . . . . . . . . 105

Index . . . . . . . . . . . . . . . 115

iv Shared Session Management Administration Guide

About this publication

IBM® Tivoli® Access Manager for e-business session management server (SMS)manages sessions across clustered Tivoli Access Manager security servers.Implemented as a WebSphere® Application Server service, the session managementserver permits the sharing of session information and provides a user interfacefrom which authorized persons can administer and monitor user sessions.

IBM Tivoli Access Manager for e-business provides an access control managementsolution to centralize network and application security policy for e-businessapplications.

For details about supported platforms, disk and memory requirements, see theIBM Tivoli Access Manager for e-business: Release Notes.

For details about software prerequisites and installation and initial configuration ofthe session management server components, see the IBM Tivoli Access Manager fore-business: Installation Guide.

For technical reference information, deployment considerations, and usageinformation for the session management server with Tivoli Access Manager Plug-infor Web Servers, see the IBM Tivoli Access Manager for e-business: Plug-in for WebServers Administration Guide.

For technical reference information, deployment considerations, and usageinformation for the session management server with Tivoli Access ManagerWebSEAL, see the IBM Tivoli Access Manager for e-business: WebSEAL AdministrationGuide.

Intended audienceThis guide is for system administrators responsible for the deployment andadministration of the Tivoli Access Manager session management server.

Readers should be familiar with the following:v Microsoft® Windows® and UNIX® operating systems.v Database architecture and concepts.v Security management.v Internet protocols, including HTTP, HTTPS and TCP/IP.v WebSphere Application Server administration.v Authentication and authorization.

If you are enabling Secure Sockets Layer (SSL) communication, you also should befamiliar with SSL protocol, key exchange (public and private), digital signatures,cryptographic algorithms, and certificate authorities.

PublicationsThis section lists publications in the IBM Tivoli Access Manager for e-businesslibrary and related documents. The section also describes how to access Tivolipublications online and how to order Tivoli publications.

© Copyright IBM Corp. 2005, 2010 v

IBM Tivoli Access Manager for e-business libraryThe following documents are in the Tivoli Access Manager for e-business library:v IBM Tivoli Access Manager for e-business: Quick Start Guide, GI11-9333

Provides steps that summarize major installation and configuration tasks.v IBM Tivoli Access Manager for e-business: Release Notes, GC23-6501

Provides information about installing and getting started, system requirements,and known installation and configuration problems.

v IBM Tivoli Access Manager for e-business: Installation Guide, GC23-6502Explains how to install and configure Tivoli Access Manager for e-business.

v IBM Tivoli Access Manager for e-business: Upgrade Guide, SC23-6503Upgrade from version 5.0, 6.0, or 6.1 to version 6.1.1.

v IBM Tivoli Access Manager for e-business: Administration Guide, SC23-6504Describes the concepts and procedures for using Tivoli Access Manager. Providesinstructions for performing tasks from the Web Portal Manager interface and byusing the pdadmin utility.

v IBM Tivoli Access Manager for e-business: WebSEAL Administration Guide,SC23-6505Provides background material, administrative procedures, and referenceinformation for using WebSEAL to manage the resources of your secure Webdomain.

v IBM Tivoli Access Manager for e-business: Plug-in for Edge Server AdministrationGuide, SC23-6506Provides instructions for integrating Tivoli Access Manager with the IBMWebSphere Edge Server application.

v IBM Tivoli Access Manager for e-business: Plug-in for Web Servers AdministrationGuide, SC23-6507Provides procedures and reference information for securing your Web domainusing a Web server plug-in.

v IBM Tivoli Access Manager for e-business: Shared Session Management AdministrationGuide, SC23-6509Provides deployment considerations and operational instructions for the sessionmanagement server.

v IBM Global Security Kit: Secure Sockets Layer Introduction and iKeyman User's Guide,SC23-6510Provides information for enabling SSL communication in the Tivoli AccessManager environment.

v IBM Tivoli Access Manager for e-business: Auditing Guide, SC23-6511Provides information about configuring and managing audit events using thenative Tivoli Access Manager approach and the Common Auditing andReporting Service. You can also find information about installing andconfiguring the Common Auditing and Reporting Service. Use this service forgenerating and viewing operational reports.

v IBM Tivoli Access Manager for e-business: Command Reference, SC23-6512Provides reference information about the commands, utilities, and scripts thatare provided with Tivoli Access Manager.

v IBM Tivoli Access Manager for e-business: Administration C API Developer Reference,SC23-6513

vi Shared Session Management Administration Guide

Provides reference information about using the C language implementation ofthe administration API to enable an application to perform Tivoli AccessManager administration tasks.

v IBM Tivoli Access Manager for e-business: Administration Java Classes DeveloperReference, SC23-6514Provides reference information about using the Java™ language implementationof the administration API to enable an application to perform Tivoli AccessManager administration tasks.

v IBM Tivoli Access Manager for e-business: Authorization C API Developer Reference,SC23-6515Provides reference information about using the C language implementation ofthe authorization API to enable an application to use Tivoli Access Managersecurity.

v IBM Tivoli Access Manager for e-business: Authorization Java Classes DeveloperReference, SC23-6516Provides reference information about using the Java language implementation ofthe authorization API to enable an application to use Tivoli Access Managersecurity.

v IBM Tivoli Access Manager for e-business: Web Security Developer Reference,SC23-6517Provides programming and reference information for developing authenticationmodules.

v IBM Tivoli Access Manager for e-business: Error Message Reference, GI11-8157Provides explanations and recommended actions for the messages and returncode.

v IBM Tivoli Access Manager for e-business: Troubleshooting Guide, GC27-2717Provides problem determination information.

v IBM Tivoli Access Manager for e-business: Performance Tuning Guide, SC23-6518Provides performance tuning information for an environment consisting of TivoliAccess Manager with the IBM Tivoli Directory Server as the user registry.

Related products and publicationsThis section lists the IBM products that are related to and included with a TivoliAccess Manager solution.

IBM Global Security KitTivoli Access Manager provides data encryption through the use of the GlobalSecurity Kit (GSKit), version 7.0. GSKit is included on the IBM Tivoli AccessManager Base CD for your particular platform, as well as on the IBM Tivoli AccessManager Web Security CDs, the IBM Tivoli Access Manager Shared Session ManagementCDs, and the IBM Tivoli Access Manager Directory Server CDs.

The GSKit package provides the iKeyman key management utility, gsk7ikm, whichcreates key databases, public-private key pairs, and certificate requests. The IBMGlobal Security Kit: Secure Sockets Layer Introduction and iKeyman User's Guide isavailable on the Tivoli Information Center Web site in the same section as theTivoli Access Manager product documentation.

IBM Tivoli Directory ServerIBM Tivoli Directory Server, version 6.1, is included on the IBM Tivoli AccessManager Directory Server set of CDs for the required operating system.

About this publication vii

You can find additional information about Tivoli Directory Server at:

http://www.ibm.com/software/tivoli/products/directory-server/

IBM Tivoli Directory IntegratorIBM Tivoli Directory Integrator, version 6.1.1, is included on the IBM TivoliDirectory Integrator CD for the required operating system.

You can find additional information about IBM Tivoli Directory Integrator at:

http://www-306.ibm.com/software/tivoli/products/directory-integrator/

IBM DB2 Universal DatabaseIBM DB2 Universal Database™ Enterprise Server Edition, version 9.1, is providedon the IBM Tivoli Access Manager Directory Server set of CDs and is installed withthe Tivoli Directory Server software. DB2® is required when using Tivoli DirectoryServer or z/OS® LDAP servers as the user registry for Tivoli Access Manager. Forz/OS LDAP servers, you must separately purchase DB2.

You can find additional information about DB2 at:

http://www.ibm.com/software/data/db2

IBM WebSphere Application ServerWebSphere Application Server, version 6.1, is included on the IBM Tivoli AccessManager WebSphere Application Server set of CDs for the required operating system.WebSphere Application Server enables the support of the following applications:v Web Portal Manager interface, which administers Tivoli Access Manager.v Web Administration Tool, which administers Tivoli Directory Server.v Common Auditing and Reporting Service, which processes and reports on audit

events.v Session management server, which manages shared session in a Web security

server environment.v Attribute Retrieval Service.

You can find additional information about WebSphere Application Server at:

http://www.ibm.com/software/webservers/appserv/infocenter.html

Accessing terminology onlineThe Tivoli Software Glossary includes definitions for many of the technical termsrelated to Tivoli software. The Tivoli Software Glossary is available at the followingTivoli software library Web site:

http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm

The IBM Terminology Web site consolidates the terminology from IBM productlibraries in one convenient location. You can access the Terminology Web site athttp://www.ibm.com/software/globalization/terminology .

Accessing publications onlineThe documentation CD contains the publications that are in the product library.The format of the publications is PDF, HTML, or both. Refer to the readme file onthe CD for instructions on how to access the documentation.

viii Shared Session Management Administration Guide

http://www.ibm.com/software/tivoli/products/directory-server

http://www-306.ibm.com/software/tivoli/products/directory-integrator/

http://www.ibm.com/software/data/db2

http://www.ibm.com/software/webservers/appserv/was

http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm

http://www.ibm.com/software/globalization/terminology

The product CD contains the publications that are in the product library. Theformat of the publications is PDF, HTML, or both. To access the publications usinga Web browser, open the infocenter.html file. The file is in the appropriatepublications directory on the product CD.

IBM posts publications for this and all other Tivoli products, as they becomeavailable and whenever they are updated, to the Tivoli Documentation CentralWeb site at http://www.ibm.com/tivoli/documentation.

Note: If you print PDF documents on other than letter-sized paper, set the optionin the File → Print window that allows Adobe® Reader to print letter-sizedpages on your local paper.

Ordering publicationsYou can order many Tivoli publications online at http://www.elink.ibmlink.ibm.com/publications/servlet/pbi.wss.

You can also order by telephone by calling one of these numbers:v In the United States: 800-879-2755v In Canada: 800-426-4968

In other countries, contact your software account representative to order Tivolipublications. To locate the telephone number of your local representative, performthe following steps:1. Go to http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss.2. Select your country from the list and click Go.3. Click About this site in the main panel to see an information page that

includes the telephone number of your local representative.

AccessibilityAccessibility features help users with a physical disability, such as restrictedmobility or limited vision, to use software products successfully. With this product,you can use assistive technologies to hear and navigate the interface. You can alsouse the keyboard instead of the mouse to operate all features of the graphical userinterface.

Visit the IBM Accessibility Center at http://www.ibm.com/alphaworks/topics/accessibility/ for more information about IBM's commitment to accessibility.

For additional information, see the Accessibility Appendix in IBM Tivoli AccessManager for e-business: Installation Guide.

Tivoli technical trainingFor Tivoli technical training information, refer to the following IBM TivoliEducation Web site at http://www.ibm.com/software/tivoli/education.

About this publication ix

http://www.ibm.com/tivoli/documentation

http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

http://www.ibm.com/alphaworks/topics/accessibility/

http://www.ibm.com/alphaworks/topics/accessibility/

http://www.ibm.com/software/tivoli/education

Tivoli user groupsTivoli user groups are independent, user-run membership organizations thatprovide Tivoli users with information to assist them in the implementation ofTivoli Software solutions. Through these groups, members can share informationand learn from the knowledge and experience of other Tivoli users. Tivoli usergroups include the following members and groups:v 23,000+ membersv 144+ groups

Access the link for the Tivoli Users Group at http://www.tivoli-ug.org/.

Support informationIf you have a problem with your IBM software, you want to resolve it quickly. IBMprovides the following ways for you to obtain the support you need:

OnlineAccess the Tivoli Software Support site at http://www.ibm.com/software/sysmgmt/products/support/index.html?ibmprd=tivman. Access the IBMSoftware Support site at http://www.ibm.com/software/support/probsub.html .

IBM Support AssistantThe IBM Support Assistant is a free local software serviceability workbenchthat helps you resolve questions and problems with IBM softwareproducts. The Support Assistant provides quick access to support-relatedinformation and serviceability tools for problem determination. To installthe Support Assistant software, go to http://www.ibm.com/software/support/isa.

Troubleshooting GuideFor more information about resolving problems, see the IBM Tivoli AccessManager for e-business: Installation Guide.

Conventions used in this publicationThis publication uses several conventions for special terms and actions, operatingsystem-dependent commands, and paths.

Typeface conventionsThis publication uses the following typeface conventions:

Bold

v Lowercase commands and mixed case commands that are otherwisedifficult to distinguish from surrounding text

v Interface controls (check boxes, push buttons, radio buttons, spinbuttons, fields, folders, icons, list boxes, items inside list boxes,multicolumn lists, containers, menu choices, menu names, tabs, propertysheets), labels (such as Tip:, and Operating system considerations:)

v Keywords and parameters in text

Italic

v Citations (examples: titles of publications, diskettes, and CDsv Words defined in text (example: a nonswitched line is called a

point-to-point line)

x Shared Session Management Administration Guide

http://www.tivoli-ug.org/

http://www.ibm.com/software/sysmgmt/products/support/index.html?ibmprd=tivman

http://www.ibm.com/software/sysmgmt/products/support/index.html?ibmprd=tivman

http://www.ibm.com/software/support/probsub.html


http://www.ibm.com/software/support/isa

http://www.ibm.com/software/support/isa

v Emphasis of words and letters (words as words example: "Use the wordthat to introduce a restrictive clause."; letters as letters example: "TheLUN address must start with the letter L.")

v New terms in text (except in a definition list): a view is a frame in aworkspace that contains data.

v Variables and values you must provide: ... where myname represents....

Monospace

v Examples and code examplesv File names, programming keywords, and other elements that are difficult

to distinguish from surrounding textv Message text and prompts addressed to the userv Text that the user must typev Values for arguments or command options

Operating system-dependent variables and pathsThis publication uses the UNIX convention for specifying environment variablesand for directory notation.

When using the Windows command line, replace $variable with % variable% forenvironment variables and replace each forward slash (/) with a backslash (\) indirectory paths. The names of environment variables are not always the same inthe Windows and UNIX environments. For example, %TEMP% in Windowsenvironments is equivalent to $TMPDIR in UNIX environments.

Note: If you are using the bash shell on a Windows system, you can use the UNIXconventions.

About this publication xi

xii Shared Session Management Administration Guide

Chapter 1. Introduction

The session management server is an optional Tivoli Access Manager componentthat runs as a WebSphere service. It manages user sessions across Tivoli AccessManager servers, ensures that the session state remains consistent across theparticipating servers, and allows for the implementation of session policy acrossthe participating servers.

The session management server allows Tivoli Access Manager WebSEAL and theTivoli Access Manager Plug-in for Web Servers to share a unified view of allcurrent sessions, and permits authorized users to monitor and administer usersessions. The session management server also makes available session statistics,provides secure and high-performance failover, and provides single sign-oncapabilities for clustered environments.

Designed to manage sessions across clustered Web server environments, thesession management server can adapt to complicated deployment architectures.

The session management server is a J2EE application that runs on the WebSphereserver, or within a WebSphere cluster.

Session management server administration optionsSessions can be administered using any (or all) of the following tools:

pdadminDetails of pdadmin commands that can be used for session managementare described in Appendix A, “SMS pdsmsadmin and pdadmincommands,” on page 49.

pdsmsadminThe pdsmsadmin command line uses the SOAP protocol to communicatedirectly with a session management server installed on WebSphereApplication Server.

The session management server Integrated Solutions ConsoleThe session management server Integrated Solutions Console (hereafterreferred to as the ISC) is a graphical user interface that resides on theWebSphere Application Server, and is installed as an extension to theWebSphere ISC. Figure 1 on page 2 shows the extended main menu items.

© Copyright IBM Corp. 2005, 2010 1

For further details of specific administration tasks, see Chapter 3, “Using thesession management server,” on page 27.

Additional administrative tasks are performed using the session managementserver utilities described in Appendix B, “SMS utilities,” on page 81.

When deciding which administration options are best suited to your sessionmanagement server environment, see “Deployment considerations” on page 6.

Session management server featuresSession management server functions generally require initial configuration, andminimal user intervention thereafter.

Figure 1. Integrated Solutions Console session management server extension menu

2 Shared Session Management Administration Guide

Session information consistencyThe session management server is a centralized Web service that maintains sessioninformation across Web security servers. Session data includes user credentials,session timeout information, and other data used by Tivoli Access Manager totrack the state of all user sessions.

For example, this consistency applies to users' authentication level so that when auser steps up to a higher authentication level, all replicated WebSEAL and Webserver plug-in servers automatically have the updated credential available.

Similarly, when a user's session times out, either due to inactivity or sessionlifetime expiry, the user session ends across all servers.

Cluster-wide login policy enforcementThe centralized view of all user sessions maintained by the session managementserver provides a single point from which to enforce user identity-based sessionpolicies.

The maximum number of concurrent sessions a user has across the cluster can belimited by policy. The session management server enforces the policy that caneither be set to disallow a new session that exceeds the maximum or set to replacea current session with the new session.

FailoverEarlier versions of Tivoli Access Manager required the use of a failover cookie toapproximate the session replication capabilities of the session management server.When configured to use the session management server, there is no longer anyneed to use the failover cookie. The session management server provides a moreconsistent and complete view of user sessions across sets of replicated Websecurity servers.

Session information managementThe session management server records a variety of session information. Havingsession information available in a central location offers the ability to manage andmonitor sessions across servers. The session management server records thefollowing session information:v Concurrent log in informationv Session statistics information, such as the number of users logged in

Authorized users have access to this information and can use this information topromote system security.

Support for multiple instancesTivoli Access Manager for eBusiness version 6.1 supports multiple sessionmanagement server installations on a single WebSphere Application Server. Eachinstallation is called an instance. Each session management server instance cancontain one or more session realms, and each session realm can contain one ormore replica sets. These terms and concepts are explored more fully in “Sessionmanagement server architecture” on page 4.

Using the session management server administrative tools, you can view allavailable instances, deploy and configure new instances, or swap from one instanceto another to perform administrative tasks.

Chapter 1. Introduction 3

Limited session realmsTivoli Access Manager for eBusiness version 6.1 allows you to limit the maximumnumber of sessions for a particular session realm. Once the maximum number ofsessions has been reached, further session requests will be denied until the numberof sessions has dropped below the set threshold.

Session management server architectureThe session management server is built to run on WebSphere Application Serverand WebSphere Network Deployment.

The session management server supports communications using the IBMWebSphere Web server plug-in (IBM HTTP Server) or Microsoft IIS (on Windows).During configuration you are prompted to provide the WebSphere port number.This port number should be the port for WebSphere communication using theWebSphere Web server plug-in.

Figure 2 shows the Tivoli Access Manager blade and WebSphere interface.

The session management server is useful in environments that have replicated Websecurity servers. Web servers secured by Tivoli Access Manager are replicated toprovide high availability and load balancing. Alternatively, single servers in acluster of servers can form part of a larger application.

When servers are clustered for reasons of high availability and load balancing, thecontent of the participating servers is identical. Often a load balancer is used todistribute the Internet traffic across each replicated server.

The term replica set is used to refer to a collection of replicated WebSeal (or Webserver plug-in) Web security servers. Replicated servers within a replica set servethe same content, are configured the same way, and enforce the same securitypolicies.

Figure 3 on page 5 and Figure 4 on page 5 show typical architectures for failoverand load balancing with either Tivoli Access Manager Plug-in for Web Servers orWebSEAL. In both cases, WebSEAL and the plug-in are replicated, and both usethe session management server to maintain session information across the clustered

WebSEALreplica 1

WebSEALreplica 2

Replica set

Firewall

SessionManagement

Server

IBM HTTP Server

WebSphere

Web server plug-in

WebSphere ApplicationServer

Figure 2. Simple session management server architecture.


servers. From a user point of view, a session exists as a single entity across eachenvironment.

The protected servers shown in Figure 3 and Figure 4 might also be used to hostcontent for different (yet related) Web sites, or each server might form part of alarger, single application. When a user who is accessing these servers perceivethem as a single application that requires a single login and consistent concurrentsession policy, the session management server can be used to provide secure accessacross all of the servers.

WebSEALreplica 1

SD

Loadbalancer

Firewall Firewall

Junctionedservers

DMZ


Tivoli AccessManager

communications

Registry

Policydatabase

Sessionmanagement

server

Browser

WebSEALreplica 3

WebSEALreplica 2

Replica set

Figure 3. A typical session management server architecture with WebSEAL

A.tivoli.com

plu

g-in

A.tivoli.com

plu

g-in

A.tivoli.com

plu

g-in

SD

Loadbalancer

Firewall Firewall

DMZ


Tivoli AccessManager

communications

Registry

Policydatabase

Sessionmanagement

server

Browser

A.tivoli.com replica set

Figure 4. Basic session management server architecture with Tivoli Access Manager Plug-infor Web Servers.


The extent of a session within a server cluster is referred to as the session realm.The session management server can provide a seamless single sign-on experienceacross a session realm. Servers are added to or removed from session realms byconfiguration within WebSEAL or the Tivoli Access Manager Plug-in for WebServers.

Figure 5 shows a representation of a session realm. A session realm consists of oneor more replica sets and the user's session is replicated across the entire sessionrealm. When users log in, they are considered logged in to the entire session realm.Concurrent session policy is applied across the entire session realm. If a user whois limited to a single concurrent session logs in to one replica set within the realmand then tries to log in to another replica set within realm, the second login isdenied.

Deployment considerationsSet up the Tivoli Access Manager environment before installing and configuringthe session management server. The configuration requires that you have athorough understanding of the structure of your session realms and associatedreplica sets and the replica sets that are not assigned to a specific session realm.

Before installation and configuration, decide whether you want to have replicatedsession management server instances (WebSphere Network Deployment only).Having more than one session management server that serves your Tivoli AccessManager sessions can provide a failover capability and improve performance.

A.tivoli.com

plu

g-in

plu

g-in

A.tivoli.com replica set

B.tivoli.com replica set

A.tivoli.com

Session ManagementServer

WebSEALreplica 1

Browser

SD

WebSEALreplica 2

Junctionedservers

Tivoli.com session realm

Figure 5. An example architecture with two replica sets within a session realm.


To use the pdadmin command for administration purposes, you must install andconfigure the Session Management Server Command Line Extension component toa Tivoli Access Manager authorization server. By contrast, pdsmsadmin does notrequire an authorization server as it communicates directly to WebSphereApplication Server.

The pdadmin command line provides server tasks that communicate with thesession management server to perform administrative operations. As server tasks,they are suitable for use in custom administrative applications of your own thatcan be developed using Tivoli Access Manager administration APIs. Such APIdevelopment can only be performed with pdadmin, not pdsmsadmin.

An authorization server is required to make use of the credential refreshcapabilities of the session management server or is required to use the certificatesthat are issued by the Tivoli Access Manager policy server. The certificates that areissued by the policy server provide authentication between the sessionmanagement server and its client applications. For additional details, see “Securityconsiderations” on page 9.

When an authorization server is required, it is typical to deploy an authorizationserver to each machine that hosts an instance of the session management server.

Figure 6 shows a basic structure of the various administration interfaces for thesession management server.

WebSEALreplica 1

Policy server

Junctionedserver

WebSEALreplica 2

Authorizationserver with

SMS command lineextension

Replica set

SMSadministrationusing pdadmin

SD

Browser

Firewall

SessionManagementServer ISC

SessionManagement

Server

SMS adminusing

pdsmsadmin

WebSphereApplication Server

Authorizationserver for

credential refresh

Figure 6. Session management server administration architecture


When deployed, the session management server is a critical Tivoli Access Managercomponent. It must remain highly available so that the client does not becomeunavailable. The session management server should therefore be run in a clusteredenvironment consisting of at least two cluster members. If all clusters membersbecome unavailable, the session data maintained by the session managementserver will be lost.

For continued service when restarting the SMS cluster, only use the WebSphereApplication Server ripple start functionality if there are three or more clustermembers. If there are only two cluster members in the cluster, use a manual startand stop of each cluster member one at a time. This process ensures that thesecond cluster member is brought down only when the first one is back up andrunning again. To help ensure high availability, only restart the SMS cluster underconditions of low activity, when there are minimal Tivoli Access Manager sessionsopen. It is also important to ensure that the catalog service is always running andany container servers can connect to it during a restart.

A WebSphere core group should be set up, and dedicated to the sessionmanagement server. This core group should only include those cluster memberswhich contain an instance of the session management server. To avoid unnecessarydata replication across the network, the WebSphere Application Server NetworkDeployment Manager should not be a member of the session management servercore group. More information about WebSphere Application Server Core Groupscan be obtained from the WebSphere Application Server Information Center.

In some situations, the heap size of the hosting WebSphere Application Servers willneed to be increased. This will usually be required if a large number of concurrentsessions will be managed by the Session Management Server. To increase the heapsize of the WebSphere Application Server, perform the following steps:1. Open the Integrated Solutions Console2. On the left hand side, expand the Servers' heading and click Application

servers.3. Click on the name of the server you wish to modify.4. Under the Server Infrastructure heading, expand the Java and Process

Management heading and click Process Definition.5. Under the Additional properties heading, select Java Virtual Machine.6. In the Maximum Heap Size text box, specify the new maximum heap size and

click OK.7. Click Save to save the changes.8. Restart the application server for the changes to take effect.

The maximum heap size of the Deployment Manager can be modified byperforming the following steps:1. Open the Integrated Solutions Console2. On the left hand side, expand the System administration heading and click

Deployment manager.3. Under the Server Infrastructure heading, expand the Java and Process

Management heading and click Process Definition.4. Under the Additional properties heading, select Java Virtual Machine.5. In the Maximum Heap Size text box, specify the new maximum heap size and

click OK.6. Click Save to save the changes.


7. Restart the deployment manager server for the changes to take effect.

Security considerationsThere are two steps to applying security when using the session managementserver:1. Configuring secure communications between the WebSphere server that hosts

the session management server and the session management server clientapplications.

2. Enabling J2EE security on the WebSphere server that hosts the sessionmanagement server including defining the membership of the sessionmanagement server application roles.

Configuring secure communicationsReferring to Figure 6 on page 7, secure communications can be configured amongthe following components:v The Tivoli Access Manager Web security and authorization servers and the

WebSphere Web server plug-in that access the session management server.v The WebSphere Web server plug-in and the WebSphere server itself.

Configuring SSL for these connections can result in a small performancedegradation. However, session information should be considered sensitive and allattempts should be made to keep it secure. It is recommended that SSL beconfigured for these connections.

Notes:

1. When security is enabled in a WebSphere environment, you must use the sameuser registry as that used by Tivoli Access Manager. You will also need to addthe sms-administrator role to the list of users or groups who will access thesession management server ISC. To perform this task, select Users and Groupsin the WebSphere ISC.

2. For WebSphere clustered environments, changes to key and trust stores willneed to be consistent across every server in the cluster. Refer to the WebSpheredocumentation for assistance.

The following options can be used to achieve the communications previouslydescribed:v Leave the connections unsecuredv Configure SSL between the connections using the certificates issued by the Tivoli

Access Manager policy server during the configuration of each Tivoli AccessManager server

v Configure SSL between the connections using certificates that you provideyourself.

Configuring secure communications using certificates issued bythe policy serverWhen a Tivoli Access Manager server is configured, the policy server issues acertificate that the server uses to authenticate itself to the Tivoli Access Managerinfrastructure. These same certificates can be used to authenticate SSLcommunications between these servers and the session management server.

To use these certificates, the Web server that hosts the WebSphere Web serverplug-in must be configured with a certificate issued by the Tivoli Access Managerpolicy server, and with the Tivoli Access Manager policy server CA certificate. The


WebSphere Web server plug-in is used to communicate with the sessionmanagement server. The certificate issued by the policy server ensures that theclient applications trust the Web server. The policy server CA certificate ensuresthat the Web server trusts the client applications.

To obtain a certificate from the policy server for use by the Web server you can runthe svrsslcfg utility on a machine that is configured with the Tivoli AccessManager runtime (for example, a machine running WebSEAL or an authorizationserver or the policy server). You can run the utility as follows:touch /tmp/was-pi-sms.confsvrsslcfg -config -n was-pi-sms -h hostname_of_web_server -l no -a no \

-f /tmp/was-pi-sms.conf -d /tmp -r 0 -s remote

This will create a was-pi-sms.kdb and was-pi-sms.sth files in the /tmp directorythat contains the certificate to be used by the Web server and the password neededto access the certificate file respectively.

If you are using IBM HTTP Server as the Web server, these files can be configureddirectly to IBM HTTP Server when enabling it for SSL. For Web servers that do notunderstand the CMS key file format, use the IBM GSKit iKeyman tool to convertthe key file into a format that the Web server can understand.

The subject distinguished name (DN) specified in certificates issued by the policyserver do not correspond directly to user entries in the Tivoli Access Manager userregistry. When using certificates to authenticate to WebSphere, WebSphere requiresthe subject DN to map exactly to the DN of user defined in the WebSphere userregistry. To overcome this, the session management server provides a TrustAssociation Interceptor (TAI) that maps the subject DN of a policy server issuedcertificate to the DN of the user to whom the certificate corresponds. Part of thesession management server configuration process, therefore, enables TAIs.

For more information about WebSphere TAIs, see the WebSphere documentation.

Configuring secure communications using user-providedcertificatesYou can use certificates other than those issued by the Tivoli Access Managerpolicy server for either end of the communications between the sessionmanagement server and its client applications.

You can obtain such certificates either from an external source, your own PKIinfrastructure or by creating self-signed certificates using a tool like the IBM GSKitiKeyman tool.

The only requirement is that each end of the communication has a certificationauthority (CA) certificate that can verify the validity of the certificate that ispresented by the other end of the communication.

Configuring secure communications between the WebSphereWeb server plug-in and the WebSphere server

When you install the WebSphere Web server plug-in you are provided with a keyfile that contains sample certificates for use in communication between the plug-inand the application server.

Note: Do not use the sample certificates in an environment that requires securecommunications between the plug-in and the application server.


The WebSphere documentation describes how to create your own certificates forthe plug-in to use when communicating with WebSphere that you can follow. Inaddition, you can configure the plug-in to use the same certificates used by theWeb server itself to communicate with the session management server clientapplications. To simplify this when you are using certificates issued by the TivoliAccess Manager policy server, the session management server configurationprocess creates a WebSphere SSL repertoire (also consisting of policy server- issuedcertificates). For details on changing the SSL repertoire that is used incommunication with an application, see the WebSphere documentation.

Configuring session management server authorizationThe session management server uses the J2EE role-based authorization model thatis provided by WebSphere to authorize operations that are requested by its clientapplications. WebSphere J2EE security must be enabled before authorization ofsession management server operations can be performed. The WebSpheredocumentation describes in detail how to enable J2EE security. The requirements ofthe session management server are as follows:v Lightweight Third Party Authentication (LTPA) is enabled as the authentication

mechanism.v The subject DNs of certificates used to authenticate to WebSphere by session

management server client applications correspond to the DN of users in theWebSphere registry. This requires use of an LDAP-based user registry (forexample, IBM Tivoli Directory Server or Microsoft Active Directory).

v To avoid replication of user data between Tivoli Access Manager and WebSphereyou should configure WebSphere to use the same user registry as Tivoli AccessManager.

After security is enabled, access to the roles used to authorize access to the varioussession management server operations must be granted.

The session management server defines the following interfaces:

Session management interfaceThe interface that is used by Web security servers to create, retrieve,modify, and end user sessions.

Session administration interfaceThe interface that is used by administrative applications to performadministration on the session management server and the sessions itmaintains.

Access to these interfaces is authorized separately.

Session management interface authorizationAccess to the session management interface is controlled by the sms-client role.

Session management server client applications authenticate to WebSphere usingtheir certificate. This certificate corresponds to a WebSphere user. Access for sessionmanagement server client application users can be granted either directly or bygroup membership.

It is recommended that you define groups of users and assign these groups toroles, rather than assigning users to roles directly. This makes changes in roleassignments simpler to manage because you just need to change the groupmembership.


To assign a user or group to the sms-client role of the session management server:1. Login to the WebSphere administration console.2. Select Applications then Enterprise Applications then the instance name.3. Click Security role to user/group mapping.4. Select the sms-client role check box, and click either Lookup groups or Lookup

users.5. Lookup the groups and users you want to assign the sms-client role and add

the required groups or users.6. Click OK.7. Save the WebSphere configuration changes (this will automatically restart the

session management server application).

Session administration interface authorizationThe authorization of accesses to the session administration interface is slightlydifferent. Because administration operations are requested by either pdsmsadminor the Tivoli Access Manager authorization server, it is the user identity for theseprocesses that authenticates to WebSphere.

Users logging in to pdsmsadmin or the Tivoli Access Manager authorization serverpass user identity information on to the session management server, indicating theidentity of the real user who is requesting the administration operation(sec_master, for example). As such, the identity from the client certificate for eitherpdsmsadmin or the Tivoli Access Manager authorization server acts as a delegateof the real user requesting the operation.

The preceding diagram shows two levels of security between pdsmsadmin and theIHS or IIS server:v Communication channel security is provided by the client certificate. To ensure

that only trusted entities can specify the identity of the real user who isrequesting the administration operation, the first authorization that occurschecks that the user authenticated to WebSphere has the sms-delegate role,indicating that the user can be trusted to reliably specify the real identity of theuser requesting the administration operation.

v The User ID provides application security. If the first security test is passed, thenthe real user identity performs a second authorization. The real user must

pdsdmadmin

WebSphereApplication Server

sessionmanagement

server

IHS or IIS

SSL

sms-administrator

sms-delegate

Figure 7. Security levels for pdsmsadmin communications


possess the Administrator and sms-administrator roles to perform sessionmanagement server administrative tasks.

For example, consider a deployment where:v An authorization server is running on host server1.ibm.com, with a user name

of ivacld/server1.ibm.com (configured with the session management servercommand line extension)

v A user called sms-admin logs in to pdadmin to perform administrationoperations against the session management server

For the administration operations to succeed, the ivacld/server1.ibm.com usermust have the sms-delegate role and the sms-admin user must have theAdministrator and sms-administrator roles. Access to these roles is granted in thesame manner as access to the sms-client role previously described.

WebSphere usage of LDAP-based user registriesWebSphere allows configuration of a base distinguished name (DN). This is usedas a starting point for all searches of the registry.

Configuration of a base DN allows you to login, for example to the WebSphereadministration console, without specifying the full DN of the user you are loggingin as.

However, when a base DN is specified, all DNs used for authentication must be achild of this base DN. If not, authentication will fail.

For example, if you have configured a base DN of C=US, O=IBM, then DN of allusers must begin with C=US, O=IBM. Users with a DN of C=AU, O=IBM will not beable to authenticate.

Some Tivoli Access Manager administrative users have Tivoli Access Managerspecific DNs. In particular, the administrative user sec_master will generally nothave a DN of the form used by other users in the registry. To perform sessionmanagement server administrative operations as the user sec_master you musttherefore ensure no base DN is configured for the WebSphere LDAP user registry.

Similarly, if you are using Tivoli Access Manager policy server issued certificatesfor authenticating SSL communications between the session management serverand its client application, you must ensure no base DN is configured for theWebSphere LDAP user registry. Tivoli Access Manager certificates correspond toregistry users with a DN in a Tivoli Access Manager specific part of the userregistry.

Configuring security role membership for SMS administratorWhen WebSphere Administrative Security is enabled, you must configure the SMSadministrator to be a member of the following roles:v Administratorv sms-administrator

You can configure security role membership for an SMS administrator for theWebSphere Application Server version 6.1 and version 7.0 using the WebSphereIntegrated Solutions Console.

For WebSphere Application Server 6.1, complete the following steps:


1. Open the Integrated Solutions Console.2. Navigate to Security > Secure administration, applications, and infrastructure

> Administrative User Roles > User.3. Enter the SMS administrator ID.4. Select Administrator and sms-administrator roles.5. Click Ok.6. Save the master configuration.

For WebSphere Application Server 7.0, complete the following steps:1. Open the Integrated Solutions Console.2. Navigate to Users and Groups > Administrative User Roles.3. Click Add to create a new user for the SMS administrator.4. Select Administrator and sms-administrator roles, search for the appropriate

user and click → to add them to the Mapped to role box.5. Click Ok.6. Save the master configuration.

Note: In WebSphere Application Server, version 7.0, you cannot change the roles ofthe primary administrative user. Create a separate administrative user toadminister the SMS.

WebSEAL and Plug-in for Web Servers configurationThe participating Tivoli Access Manager blades (WebSEAL, the Plug-in for WebServers, or both) need to be configured to use the session management server formanaging sessions. Configuration of these products is not covered in thisdocument and is instead detailed in the respective guides for these products:v IBM Tivoli Access Manager for e-business: WebSEAL Administration Guide

v IBM Tivoli Access Manager for e-business: Plug-in for Web Servers AdministrationGuide

Configuration of these components is the last step in session management serverconfiguration. However, it is important to realize that configuration of theseentities is required. Therefore, they need to be installed and running before thesession management server can operate. For complete installation instructions forTivoli Access Manager components, see the IBM Tivoli Access Manager for e-business:Installation Guide.

Single sign-on with the session management serverThe session management server provides a single sign-on (SSO) capability acrossreplica sets in a session realm. This SSO is based on a domain cookie set by theTivoli Access Manager blade. Use of a domain cookie requires that all of the replicasets be peer DNS domains, so that when set by a member of one replica set in therealm the browser will submit the cookie to the other replica sets in the realm.

If SSO across DNS domains is required, an e-Community single sign-on (eCSSO),cross-domain single sign-on (CDSSO), or External Authentication Interface (EAI)solution should be considered. Details on these cross-domain SSO approaches aredocumented in the IBM Tivoli Access Manager for e-business: WebSEAL AdministrationGuide and the IBM Tivoli Access Manager for e-business: Plug-in for Web ServersAdministration Guide.


Note: Single sign-on performed using anything other than the session managementserver domain cookie results in multiple sessions for the user being createdat the session management server. To apply concurrent session policy, youneed to take this into account when designing your replica sets and sessionrealms. If each replica set is configured as part of the same session realm, asingle user, signed on to multiple replica sets using eCSSO, will havemultiple sessions. If single sign-on can occur between replica sets using amethod other than the session management server domain cookie and youwant to make use of concurrent session policy in the replica sets, thosereplica sets should not be part of the same session realm. That is, thefollowing conditions must apply before it is necessary to split the replicasets into different realms:v Requires concurrent session policyv Requires the ability to single sign-on between replica sets using a method

other than session management server domain cookies

The session management server single sign-on facility across replica sets within aDNS domain removes the need for the failover cookie.

A single session ID is used across each replica set to represent the user's singlesession across the entire session realm. A session realm can consist of replica sets ofany kind (for example, WebSEAL and Plug-in for Web Servers).

If access privileges permit, the client (as illustrated in Figure 5 on page 6) canmove between any of the servers in the session realm (tivoli.com, in the figure)without the need to re-authenticate.

The session management server allows for single sign-off across replica sets.Signing out of one replica set ends the session across the entire realm.

Back-end storage mechanismsYou can configure the Session Management Server to use one of three differentback-end storage mechanisms. The deployment configuration options on the targetcomputer or cluster of the SMS deployment determine which storage mechanism isused.

Single serverTwo back-end storage mechanisms are available for a stand-alone SMS server:v In-memoryv Database

In-memoryThe in-memory storage mechanism is the default mechanism for a singlestand-alone SMS server. In-memory storage is not suitable for a productionenvironment because this mechanism does not scale and is not fault tolerant.In-memory storage is a good option to use when performing a demo or reviewingthe capabilities of the SMS in a proof-of-concept environment.

DatabaseYou can store the SMS session data in a database. To enable this storagemechanism you need to specify yes to the Enable database storage option whendeploying the SMS using the smscfg tool. Only a single-server SMS deploymentsupports storing session data in a database, which makes this storage mechanismless viable for a highly available production environment.


NOTE: Database storage can be used for last login information, even in a clusteredenvironment.

Clustered serverFor a clustered SMS environment, WebSphere eXtreme Scale storage is the onlyavailable back-end storage mechanism.

WebSphere eXtreme ScaleIn a clustered environment, the SMS session data is stored using WebSphereeXtreme Scale, which is a separate IBM product that the SMS uses. WebSphereeXtreme Scale is a scalable data grid that can replicate data across JVM instances toensure high availability. This configuration is the most appropriate for aproduction environment because of its high availability and scalability.


Chapter 2. Configuration

This chapter explains how to deploy, configure, and unconfigure sessionmanagement server instances. It contains the following sections:v “Installing the session management server”v “Deploying the session management server” on page 18v “Configuring the session management server” on page 19v “Configuring the command line extensions” on page 23v “Unconfiguring the session management server” on page 24v “Deploying and configuring additional instances” on page 24v “Adding a new member to an SMS cluster” on page 26

Installing the session management serverFor complete session management server installation details, includingpre-installation considerations and requirements, see the "Session ManagementServer" section of the IBM Tivoli Access Manager for e-business: Installation Guide.

Installation of the session management server involves:v setting up a session management server,v setting up the session management command line(s).

Both tasks can be performed using either native utilities or installation wizards.Following installation, the session management server application must bedeployed and configured. For deployment details, see “Deploying the sessionmanagement server” on page 18. For configuration details, see “Configuring thesession management server” on page 19.

Once you have installed, deployed and configured the session management server,administrative tasks for session management can be performed using any and allof the following administrative tools:v the pdadmin command line extension,v the pdsmsadmin command line extension, orv the Session Management Server ISC, which is installed as an extension to the

WebSphere ISC.

The availability of these tools will depend on your installed session managementcomponents. To administer the session management server with the pdadmin orpdsmsadmin commands, you must install the PDSMSCLI package. For pdadmin,the PDSMSCLI package must be installed on the same system as your TivoliAccess Manager authorization server.

To administer the session management server from the ISC, you must install thePDSMS package on your WebSphere system. Once you have deployed the sessionmanagement server ISC extension, you can use it to deploy and configureadditional session management server instances (see “Deploying and configuringadditional instances” on page 24).

For full installation details, see the "Session Management Server" section of theIBM Tivoli Access Manager for e-business: Installation Guide.


Installing Fixpack upgradesTo install a new session management server fixpack:1. Install the updated package (installshield, RPM, pkgadd, etc.) on your

deployment manager (for network deployment) or application server machine(for single servers).

2. For each deployed SMS instance, run the command:smscfg -action upgrade -instance instance_name

This will apply the installed fixpack level to the specified SMS application. Duringthis process, the session management server application will be restarted. Forclusters spread across multiple nodes, no data will be lost.

To remove a fixpack, run the following command:smscfg -action revert -instance instance_name

This will revert the most recent fixpack applied to the specified instance (that is,the version that was installed before the fixpack was applied).

A complete version history is kept, so you can revert all the way back to theversion that was originally installed. Again, the application will be restarted.

You can only apply a fixpack if it is more recent than your current applicationversion. To apply an older fixpack, you must first revert to a version older than thefixpack. For example, if you upgraded your SMS instance from fixpack 2 to fixpack4 to fix one problem, but were not happy with fixpack 4, you would have to revertto fixpack 2 first before upgrading to fixpack 3. When fixpack 5 came out,however, you could upgrade directly to that.

Deploying the session management serverThe installation process includes deployment of the session management serverapplication. This can be done using the smscfg utility or the session managementserver ISC.

Notes:

1. Before it can be used, the ISC extension must itself be deployed. This can bedone with the command:smscfg -action deploy -instance ISC

2. The use of DB2 as the session storage mechanism in a WebSphere ApplicationServer clustered environment is unsupported. You can however use it forstoring the last login information.

3. If you intend to use a DB2 database to store login history information, youmust create the database before deploying the session management serverapplication. For details, see the IBM Tivoli Access Manager for e-business:Installation Guide.

4. A supported version of WebSphere eXtreme Scale must be installed on eachnode of the WebSphere cluster prior to the deployment of the SMS. For details,see the "Session Management Server" section of the IBM Tivoli Access Managerfor e-business: Installation Guide.

To deploy the session management server application using the smscfg utility:1. Prior to running smscfg, run the WebSphere setupCmdLine.bat or

setupCmdLine.sh script (depending on your operating system).


2. Deploy the session management server application using the command:smscfg -action deploy -instance instance_name

For further details, see “smscfg” on page 87.

To deploy an instance of the Session Management Server application using the ISC:1. Log in to the ISC as the Session Management Server administrator.2. Select Tivoli Session Management Server then Deployment.3. In the Application name field, enter the name of the Session Management

Server application. This field is required.4. In the Target field, enter the WebSphere Application Server cell element to

which the Session Management Server instance will be deployed.5. In the Virtual host field, enter the Web server virtual hosts that will service the

Session Management Server application instance.6. In the Data source field, enter the data source to use with the Session

Management Server application instance.7. When you are ready to deploy, click Deploy.

Deployment of the application may take several minutes without generating anymessages. Click the Refresh button to update the current progress. Uponsuccessful deployment, the new instance should be visible.

Configuring the session management serverThe session management server itself requires configuration to initialize it in theenvironment.

After installing and configuring the session management server and extensioncomponents, the participating servers in the session realm (either WebSEAL or thePlug-in for Web Servers, or both) will require configuration. Configuration atWebSEAL and the plug-in points these blades at the session management serverinstance.

The session management server configuration utility, smscfg, can be run in any ofthree ways, including a combination of the three:v Interactively using the –interactive yes parameter. With this approach, you are

prompted to input the required parameters as the utility proceeds.v Non-interactively using the –interactive no parameter. With this approach all

parameters are required to be supplied with the command entry.v Using a response file (–rspfile path_to_file) to store the necessary parameters and

having the utility read from the file. You can also record a response file andre-use the stored information for later configuration purposes. Parametersentered on the command line take precedence over parameters in the responsefile.

The discussion of the session management server configuration commands in thischapter assumes you have used the –interactive yes parameter so that thecommand prompts you for input. A complete listing and explanation of all sessionmanagement server utilities is included in Appendix B, “SMS utilities,” on page 81.

Chapter 2. Configuration 19

Gathering configuration detailsBefore performing the configuration, run the setupCmdLine command to set upthe correct execution environment for the tool. In network deploymentenvironments, this utility is located in the WebSphere deployment manager /bindirectory.

Table 1 lists the information that should be gathered before beginning theconfiguration of the session management server.

Table 1. Session management server configuration considerations.

Item Description

WebSphere cluster name You must decide whether you are deploying the sessionmanagement server to a WebSphere cluster or a standaloneserver. If deploying to a cluster, you will require the clustername.

The WebSphere server hostname

Specifies the name of the host where the sessionmanagement server is deployed.

In WebSphere network deployment architectures, the hostvalue is the same as that for the deployment manager.

In WebSphere single server environments, the host value isfor the WebSphere server where the session managementserver was installed.

During configuration, default values are offered. Thesedefault values are obtained from the wsadmin.propertiesfile.Note: The installation wizard uses wsadmin to connect tothe WebSphere server and obtain a list of servers. Someadditional setup is required for wsadmin to connect to theWebSphere server when security is enabled using privatecertificates. The soap.client.props file in theWAS_path/profiles/default/properties/ directory must beedited to reference the new client key files.

WebSphere user name andpassword.

To enable a secure connection between the participatingWeb servers and the WebSphere server that is hosting thesession management server, supply the user name andpassword required for access to the WebSphere server.

The full path to the truststore and the trust storepassword.

Values for the full path to the WebSphere trust store andthe trust store password are only necessary whenWebSphere security is enabled. A default value for the truststore location is offered during configuration.

The full path to the key storeand the key store password.

The full path to the key store and the associated passwordare only required when WebSphere security is enabled.Default values are offered.

Session realm and replica setstructure.

The configuration requires you to enter a session realmstructure with associated replica sets. It is not necessary tospecify any session realms but at least one replica setshould be specified.

Session limit policy. Controls whether the session limit and displacement policyis enabled. The default value is to enable this policy.


Table 1. Session management server configuration considerations. (continued)

Item Description

Auditing configuration file. Two auditing log files are available, depending on whetheryou are logging to a file or a CARS service:

v install_root/etc/textfile_emitter.properties.template for logging to afile, and

v install_root/etc/webservice_emitter.properties.template for logging toa CARS service.

These templates must be edited to add configuration detailsbefore you configure your SMS server. See the templates forfurther details.

Key lifetime The lifetime of the key used to sign session managementserver session IDs will require configuration. After theconfigured time has elapsed the session management serverwill automatically regenerate the key. This process occurswithout the need for user intervention.

A reasonable setting for this option should take intoconsideration security issues associated with key lifetime.

Tivoli Common Directory(TCD) Logging

You will have the option of configuring the Tivoli CommonDirectory on each machine where the session managementserver is installed. This will require the entry of the fullpath location of the Tivoli Common Directory or theexisting value can be used, if present.

Information on the Tivoli Common Directory can be foundin the IBM Tivoli Access Manager for e-business: InstallationGuide.

Tivoli Access Managerconfiguration information.

You have the option to enable integration with TivoliAccess Manager. Tivoli Access Manager integration shouldbe enabled if you want to use credential refreshfunctionality. It is not required for other SMS functionality.

If you choose to enable Tivoli Access Manager integration,then you will be prompted to enter data covering the useof Tivoli Access Manager certificates for authentication ofclients. Requested details include:

v The policy server host name.

v The policy server port. The default port is 7135.

v The Tivoli Access Manager administrator ID. The defaultvalue is sec_master.

v The Tivoli Access Manager administrator password.

v Authorization server(s) details. PDJRTE 6.1 is required ifmultiple authorization servers are to be used.


Table 1. Session management server configuration considerations. (continued)

Item Description

Last login parameters. The session management server can be configured to recordlast login information. This information includes the dateand time of the last login (from the current browser) andthe number of failed login attempts since the last successfullogin before the current login. This information is thenavailable for display in a browser if required.

A number of parameters are required for configuring lastlogin. You will be asked to enter:

v The name of the database table used to store the lastlogin information. This information is only required ifyou have selected a data storage type of DB (database).The default database table name is AMSMSUSERINFOTABLE.

v The maximum number of entries to be stored in thememory cache for the last login information. The defaultnumber of maximum entries is 5000.

v The name of the last login JSP file. The default value islastLogin.jsp. This file is located on the install directoryfor the session management server.

Data storage type. This parameter defines the registered JDBC database that isused for storing last login and session data, whichfacilitates recovery should your system fail.

If you have chosen to deploy the session managementserver in a clustered WebSphere architecture, then sessioninformation is stored and distributed using WebSphereeXtreme Scale. In a clustered deployment it is not possibleto store the session information to a DB2 database.

In single server architectures, session information can bestored in a database. The session management serversupports the use of DB2 for storage of session informationin single server WebSphere architectures.

The use of DB2 as the session storage mechanism in aWebSphere Application Server clustered environment isunsupported. You can however use it for storing the lastlogin information.

If you choose not to store session information or are usinga database other than DB2 (in single server architectures),the session management server cannot recover sessioninformation after a failure.

Last login data can either be stored to memory or to adatabase. If you are storing to a database, the selectedsource must be the same as used to store the session table.The session table can also be stored to a database, memory,or direct to a cluster. The session table can only be stored tomemory if deploying to a standalone server rather than acluster.

Client idle timeout. The client idle timeout will require configuration. This is atime value, in seconds, after which the session managementserver will stop communication with a server. For adiscussion of this, see “Session information consistency” onpage 3.


Running the configuration utilityThe session management server can be configured using the smscfg –action configutility. If details are incomplete, the utility launches an interface that prompts youfor additional information.

The session management server configuration utility is installed in the /binsubdirectory of the session management server installation by default:Linux® and UNIX operating systems

/opt/pdsms/binWindows operating systems

C:\Program Files\Tivoli\pdsms\bin

A log of the configuration progress is stored in the /var/pdsms/log/msg_pdsms_config.log file.

For complete details about this utility, see “smscfg” on page 87.

Configuring the command line extensionsThe session management server requires configuration before either thepdsmsadmin or pdadmin command lines can be used for administrative purposes.

Which command line to use?Integration with Tivoli Access Manager is required for pdadmin, but not forpdsmsadmin. From a programmer's perspective, pdadmin provides access toTivoli Access Manager administrative API's, which can be used to execute sessionmanagement server commands, whereas pdsmsadmin does not. pdadmin alsoprovides backwards compatibility with version 6.0 of the session managementserver, for which integration with Tivoli Access Manager was compulsory.

Other considerationsThe following points should be also considered prior to configuration:v Further configuration will require the name of the server that hosts the session

management server and the port number used for communications. If youchoose to integrate with Tivoli Access Manager, you will also require the nameof the authorization server which hosts the command line extension utility. Morethan one session management server can be installed for failover andperformance reasons. In such cases, the host name, instance and communicationport number for each should be recorded.

v If integration with Tivoli Access Manager is enabled, the configuration commandwrites properties to the host authorization server's configuration file,ivacld.conf. If this file is not in the default location then the exact location willneed to be entered at the time of configuration.

v You will need to decide whether to enable SSL communications between theauthorization server and the WebSphere server that is hosting the sessionmanagement server. While SSL can provide additional security for your network,this will entail a performance cost that should also be considered.SSL for this connection can use the authorization server certificates, but thisrelies on the session management server having also been configured to use theTivoli Access Manager certificates. Alternatively, you can configure the SSLconnection using custom or private certificates, as described in “Securityconsiderations” on page 9.The configuration command will require the following information:


– The full path to the SSL key file that is to be used to encryptcommunications.

– The full path to the SSL key file stash file.– The label of the client certificate in the SSL key file.

To configure the session management server command line extension, use thepdsmsclicfg -action config utility. If integration with Tivoli Access Manager isenabled, you can also use the pdconfig utility. Run the command from the serverthat is hosting the session management server. The command is located in the /bindirectory on the session management server installation. For complete informationabout this utility, see “pdsmsclicfg” on page 82.

There are three ways to configure the session management server command lineextension on Windows:v Tivoli Access Manager Configuration GUI,v SMS CLI GUI (this is C:\Program Files\Tivoli\PDSMS\bin\pdsmsclicfg.exe), orv SMS CLI command line (C:\Program Files\Tivoli\PDSMS\bin\pdsmsclicfg-

cl.exe).

Unconfiguring the session management serverUnconfiguration will remove the session management server from the TivoliAccess Manager Policy Server. This may be useful if you enabled Tivoli AccessManager integration when configuring your session management server instance.

To unconfigure session management server components, use the following utilities:v smscfg –action unconfig

v pdsmsclicfg –action unconfig

For complete details about using these utilities, see “smscfg” on page 87 and“pdsmsclicfg” on page 82 respectively.

Deploying and configuring additional instancesYou can use smscfg or the session management server ISC to deploy and configureadditional instances on WebSphere Application Server.

To deploy a new instance of the session management server using the smscfgcommand:smscfg -action deploy [-instance instance_name]

You can deploy a new instance of the session management server using either thesmscfg utility or the ISC. The smscfg command is:smscfg -action config -instance instance_name

To deploy a new instance with the ISC:1. Select deployment from the main menu of the session management server ISC.2. Enter an Application name for the new instance in the text field.3. Use the dropdown menus to select appropriate values for the following:

v Target

v Virtual host

v Data source


4. Click Deploy.

Deployment of the application may take several minutes without generating anymessages. Click the Refresh button to update the current progress. Uponsuccessful deployment, the new instance should be visible.

To configure a new instance of the session management server extension:1. Select configuration from the main menu of the session management server

ISC.2. Select the checkbox next to the instance that you wish to configure. If a new

instance is not visible, click the Update SMS instance list button.3. Click the configure button to proceed. The configuration process involves

providing the following information:

Session Realms and Replica Sets

Specify a new session realm name to create a new session realm, ormodify an existing session realm by specifying a session realm namethat already exists. To limit the maximum sessions for the sessionrealm, select the checkbox and enter a limit value. Then click theUpdate Session Realms button.

To create a replica set, specify a replica set name that does not alreadyexist and the appropriate session realm and then click the Updatereplica sets button. To modify an existing replica set, specify the nameof the existing replica set and the modified session realm name andthen click the Update replica sets button.

Clients which have the same configuration can connect to the samereplica set, but clients with different configurations must connect todifferent replica sets. Click Next to proceed.

Tivoli Access Manager integrationSelect the checkbox to enable Tivoli Access Manager integration. ClickNext to proceed to dialogs requesting further data.

Last Login recordingSelect the checkbox to enable Last Login recording. Click Next toproceed to dialogs requesting further data.

Tivoli Common Directory loggingSelect the checkbox to enable Tivoli Common Directory (TCD) logging.Accept the default path for the log directory, or specify a new path.Click Next to proceed to dialogs requesting further data.

AuditingSelect the checkbox to enable auditing. Click Next to proceed to dialogsrequesting further data.

TimeoutsSelect the checkbox to configure timeouts. Accept the default values fortimeouts (600 seconds) and key lifetime (186 days), or specify newvalues. Click Next to proceed.

4. The Summary screen displays the information you have entered. Click Finishto complete the configuration process.

5. Deployment may take a few minutes and progress is not displayed on screen.To verify whether the deployment has completed, click the Refresh button. Onsuccessful completion, the new instance should be visible.


Adding a new member to an SMS clusterAdding additional Websphere Application Servers to an existing SMS clusterprovides additional resources to process requests from SMS clients. The additionalservers also expand the number of sessions that the SMS can store. The SMS canscale to double the original deployment size. After deployment, only some parts ofthe back-end storage system continue to scale. If a cluster doubles its original size,perform the following actions to reset the scalability limit:1. Unconfigure and undeploy the cluster.2. Re-deploy and re-configure the cluster.

See “smscfg” on page 87 for more details.

Perform the following steps to add a new cluster member to an SMS cluster:1. Install WebSphere Application Server Network Deployment including

appropriate fix packs on the new server and create an appropriate profile.2. Install WebSphere eXtreme Scale and associated fixes, augmenting the new

profile during installation.3. Federate the new node into the existing cell.4. Create a new WebSphere Application Server instance in the cluster.


Chapter 3. Using the session management server

You can administer the session management server and the sessions that itmaintains using the various tools described in “Session management serveradministration options” on page 1.

Tasks that can be performed using the ISC, pdsmsadmin or pdadmin includelocating, refreshing and terminating sessions, managing key information forvalidating external sessions IDs, and generating new keys.

Additionally, you can use the smscfg –action config utility to modify theconfiguration by performing tasks such as:v Moving replica sets from one session realm to another.v Add and remove session realms.v Add and remove replica sets that are not assigned to a session realm.

This chapter details how to perform a variety of common tasks, principally usingthe ISC. For further details on pdsmsadmin and pdadmin commands, seeAppendix A, “SMS pdsmsadmin and pdadmin commands,” on page 49. For detailsof smscfg –action config commands, see “smscfg” on page 87.

Searching user sessionsAll currently active sessions can be listed, or more refined searches of sessions canbe made.

You can search user sessions as follows:1. Select Search Sessions from the session management server ISC main menu.2. Determine the session management server instance you wish to search.3. The following fields are available to restrict your search:

v The User ID field accepts wildcard values.v The Maximum Results field restricts the number of returned session IDs.v The Session Realm field must include a session realm value.

4. Click the Search button to start your search.

Search results are returned showing the session user ID and the login time for thesession. Users with multiple sessions are grouped together. You can select, filterand sort the results using the appropriate icons.


The pdsmsadmin and pdadmin command line utilities provide equivalentcommands, such as session list for listing user sessions. The usage of thesecommands is described in detail in Appendix A, “SMS pdsmsadmin and pdadmincommands,” on page 49.

Ending user sessionsThe ability to end user sessions is often useful when, for example, a browser erroroccurs and the user cannot log back in. When the administrator has located andended the active session, the user will be required to authenticate again, thuscreating a new session.

To end one or more user sessions, search the current sessions using the ISCmethod described in the section above. Select the check box corresponding to theuser ID you want to end and click Terminate.

The pdsmsadmin and pdadmin command line utilities provides equivalentcommands for ending user sessions using either terminate session or terminateall_sessions. The usage of these commands is described in detail in Appendix A,“SMS pdsmsadmin and pdadmin commands,” on page 49.

Setting the maximum concurrent sessionsThe policy get and policy set commands in pdadmin allow you to display and setmaximum concurrent Web session policy. These are standard Tivoli AccessManager pdadmin commands, which can be useful for session managementpurposes but are not available in pdsmsadmin or the ISC.

Figure 8. Filtered searching of session realms using the ISC


The following command returns an integer value corresponding to the maximumpermitted Web sessions for a user:policy get max-concurrent-web-sessions [-user user_name]

The search can be performed for a specific user by employing the –user user_nameoption.policy set max-concurrent-web-sessions {unset|number|displace|unlimited}

[-user user_name]

This command sets the maximum number of Web sessions the sessionmanagement server will permit for any one user.

For details of the syntax used with these commands, see the IBM Tivoli AccessManager for e-business: Command Reference.

Notes:

1. When an administrator switches to another user, the new session for the targetuser will not be subject to concurrent session policy.

2. This functionality is only available if the session limit policy option has beenenabled during the configuration of the SMS instance.

Displaying session realms and replica setsAn authorized user can monitor session activity, display session realms, list theparticipating replica sets, list current sessions and search for specific sessions.

The session management server components can be displayed using the ISC or thecommand line utilities.

The following commands are available in pdadmin and pdsmsadmin:v realm show

v realm list

v replica set show

v replica set list

The usage of these commands is described in detail in Appendix A, “SMSpdsmsadmin and pdadmin commands,” on page 49.

Managing replica sets and realmsReplica sets and session realms can be managed using the Configuration menu ofthe ISC.

New realms and replica sets can be added by working through the configurationdialogs. To add a new session realm or replica set, specify a name that does notalready exist. To modify an existing realm or replica set, enter the name of anexisting realm or replica set.

Note: Clients which have the same configuration can connect to the same replicaset, but clients with different configurations must connect to different replicasets.

Realms and replica sets can be removed by selecting the relevant checkbox andclicking the Remove Selected button.

Chapter 3. Using the session management server 29

For further information, see Chapter 2, “Configuration,” on page 17, in particularthe section “Deploying and configuring additional instances” on page 24.

Managing keysThe session management server uses a key to sign session IDs. This signing keylessens the possibility of a denial of service attack against the session managementserver. A single key is used across the entire cluster.

The details of the session signing key can be accessed from the sessionmanagement server ISC:1. From the session management server ISC menu, select Key Management.2. The Key Management screen is displayed. Use the current instance, or select

another session management server instance.3. The screen displays information about the current key. The date and time

information is local to the application server that is hosting the WebSphereApplication Server.

4. You can force the creation of a new key by clicking Generate new key now.You might want to forcibly create a new key when you suspect that the existingkey has been compromised.

The pdsmsadmin and pdadmin utilities provide equivalent commands formanaging keys using key show and key change. These commands are detailed inAppendix A, “SMS pdsmsadmin and pdadmin commands,” on page 49.

Session management server statisticsServer statistics for Tivoli Access Manager session management server 6.1 arevisible in the WebSphere ISC. Click on monitoring and tuning then performanceviewer.

The following statistics can provide a useful overview of session activity:

session lifetimeHow long, on average, user sessions are lasting.

session limit enforcementsThe number of times users have been denied a login due to concurrentsession limits - only useful if there is a concurrent session limit.

session displacementsThe number of times users have displaced an existing session to log in -only useful if session displacement is enabled.

active sessionsThe number of currently active sessions.

active clientsThe number of web security servers currently accessing the SMS.

To examine how sessions are created and deleted over a period of time, you canreset the sessions created, logouts, terminations, idle timeouts, and discardedsessions statistics, record them for a set duration, then plot the results.

Other session management statistics are not particularly useful from a customerperspective.


For complete details about using WebSphere statistics, see the WebSpheredocumentation.

Tracking login activityThe session management server can record information about the last time a userlogged in and the number of failed attempts to login since the last successful login.This information is useful when displayed to users at the time of login. Thisinformation alert users of any potential illegal activity on their account.

A sample JSP file for displaying last login information is available in the followingoperating system-specific directory:Linux and UNIX operating systems

/opt/pdsms/etcWindows operating systems

C:\Program Files\Tivoli\PDSMS\etc

This file can be used as a template for customizing your own display of last logininformation.

Note: The login information displayed is dependent upon the browser that a useremploys to access the system. Therefore, an unsuccessful attempt to loginfrom another browser will not be displayed on the original browser. Forexample, consider the following activity.1. Login at 12:002. Logout at 12:203. Login failure at 12:254. Login failure at 12:265, Login at 12:276. Login failure (from another browser) at 12:307. Display data via 1st browser

The following information would be displayed to the user:Last Login=12:00, 2 login failures since that time, last failure at 12:26.

The login history is displayed as it was at the time of login only. Laterevents are not displayed.

Storing the login activity dataLogin activity information is stored in session management server using a JDBCdata source. This database is installed at the time of session management serverinstallation. Login activity information is stored using the schema listed in Table 2.

Table 2. Login activity database schema.

Value Data type Description

UserName (Primary Key) String The unique user name of the user.

UUID String UUID for the user name.

nFailures Integer A count of the failed logins since the lastsuccessful login.

LastLoginFailure String A date/time stamp of the last failed login.

LastLoginSuccess String A date/time stamp of the last successfullogin.

A mechanism for reconciling this data with the user registry is not provided. Thisdata schema can be used to develop your own reconciliation capability.


Creating the login activity databaseFor details about creating the login activity database, see the IBM Tivoli AccessManager for e-business: Installation Guide.

The sessions management server uses the generic JDBC interface provided byWebSphere to communicate with the database that is used for storing last logindata. Despite JDBC being a common interface, different JDBC implementationsprovided by different database vendors often behave differently. This particularlypertains to database schema operations.

If you use a database other than DB2 and you enable the last login data trackingcapability of the session management server and then the session managementserver configuration fails when creating the last login database, you must createthe last login database manually and restart the session management serverconfiguration procedure.

The details of the schema required by the session management server for the lastlogin database are provided in Table 2 on page 31 to enable you to manually createthis database.

Setting rules for credential refreshWhere a WebSEAL or Web Plug-in server has been configured for step-upauthentication and SMS session storage, a user will be prompted to re-authenticatewhenever an administrator refreshes user credentials via the SMS. This is becausethe default SMS credential refresh configuration does not preserve the"AUTHENTICATION_LEVEL" attribute in a user's credential. After their credentialis refreshed, the authentication level is reset to zero, so any POPs that requirehigher authentication levels will result in the user being prompted to login again.To prevent this from occurring, you must update the SMS credential refreshconfiguration to include a rule that preserves the "AUTHENTICATION_LEVEL"attribute.

This can be done using the graphic user interface or command line.

GUI configuration:

1. Source the WebSphere setupCmdLine.sh or setupCmdLine.bat file toconfigure your Java environment.

2. Invoke the PDSMS configuration utility: /opt/pdsms/bin/smscfg-action config (for UNIX), or PDSMS_Install_Dir/bin/smscfg-action config (Windows). This launches the graphical configurationutility for the SMS.

3. Enter any required security information to contact the WebSphereserver.

4. Once you reach the SMS configuration screens, click Next on eachscreen until you reach the Specify the credential attribute refreshrules dialog.

5. Click Add Rule to create a new rule.6. Click on the Refresh entry of the new rule and change it to Preserve.7. Click on the * entry of the rule and change it to authentication_level.8. Click on Next until you reach the summary page.9. Click Finish to start the configuration update.


10. Once the configuration update is complete, click OK to exit theconfiguration utility.

Using the command line:

1. Create an SMS configuration response file smsconfig.rsp that containsany information necessary to contact the WebSphere server, such as thehostname of the WebSphere Application Server or deploymentmanager, the SOAP port number, and any WebSphere ApplicationServer security information. For example:was_host=wasdm.example.comwas_port=8880was_enable_security=yeswas_admin_id=wasadminwas_admin_pwd=secret123trust_store=/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/etc

/AS01ClientTrustFile.jkstrust_store_pwd=passw0rd

2. Update the smsconfig.rsp file to include the credential refresh rulesyou want to specify. Remember to include any existing credentialrefresh rules. The default credential refresh rule set ispreserve=tagvalue_*. To add a rule to preserve theauthentication_level attribute, include these two lines in thesmsconfig.rsp file:cred_refresh_rule=preserve=authentication_levelcred_refresh_rule=preserve=tagvalue_*

3. Source the WebSphere setupCmdLine.sh (UNIX) or setupCmdLine.bat(Windows) file to configure your Java environment.

4. Change directories to the location of the smscfg program:/opt/pdsms/bin (UNIX) or PDSMS_Install_Dir/bin (Windows).

5. Invoke the SMS configuration tool with your response file:./smscfg -action config -interactive no -rsp_file path-to-smsconfig.rsp

The configuration tool will update your configuration and restart theDSess application.


Chapter 4. Session management server best practices

This chapter covers the following topics:v “Zone rules and zone configuration”v “Load balancer settings” on page 36v “SMS sessions and session limit policy” on page 37v “Tuning the Java Virtual Machine” on page 38v “Session Management Server High Availability Considerations” on page 39

Zone rules and zone configurationYou can use a combination of zone rules, zone configuration, and the SessionManagement Server (SMS) client configuration to minimize traffic in an SMSenvironment.

Zone configurationA well-planned combination of WebSphere eXtreme Scale zones can minimize theSMS traffic between zone boundaries. When using zones in the SMS, the clientconfiguration must reflect the SMS zone configuration to minimize cross-zonetraffic. Zones can represent computer, building, or data boundaries. Rulesdetermine how partitions are laid out in and between the zones. Use theWebSphere Application Server Network Deployment node group feature toconfigure the zone for a server.

Zone ruleThe SMS includes a default zone rule and populates it with appropriate zonenames. The WebSphere Application Server management interface provides thesezone names during deployment. The default rule places primary and synchronousreplicas in the same zone, and asynchronous replicas in a different zone. TheWebSphere Application Server Network Deployment node groups define zones byprefixing the zone name with ReplicationZone. For example, the node groupnamed ReplicationZoneOne represents the zone named One. Each server can belongto:v Multiple node groups.v Only one eXtreme Scale zone. If the deployment process discovers a server that

belongs to multiple zones, it displays an invalid configuration error.

WebSphere eXtreme Scale zonesWebSphere eXtreme Scale zones and zone rules control the placement of partitionsacross the grid. Zones group servers in a particular location. Zone rules define howpartitions are placed in and across these zones. Zone-preferred routing permitsWebSphere eXtreme Scale clients to write to WebSphere eXtreme Scale servers inspecific zones. Writing to specific zones limits the amount of cross-zone traffic in agrid.

The following diagram shows an example deployment using eXtreme Scale zones.


You can find more information about eXtreme Scale zones in the WebSphereeXtreme Scale Version 7.0 information center:

http://publib.boulder.ibm.com/infocenter/wxsinfo/v7r0/index.jsp

See "Using zones for replica placement" and "Zone-preferred routing" in theWebSphere eXtreme Scale Product Overview.

The WebSphere Application Server information center also describes how toconfigure eXtreme Scale zones before deploying the SMS. The information centerincludes instructions for configuring cluster members to be part of a node groupthat represents a zone. See the "Viewing, adding, and deleting node groupmembers" section in the Network Deployment (All operating systems), Version 7.0Guide located in the Websphere Application Server Version 7.0 information center:

http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp

Load balancer settingsUse a load balancer to:v Spread the load equally across a cluster of SMS clients.v Provide fault tolerance and scalability.

You can use many different load balancers and numerous algorithms. SessionStickiness in the load balancer is the most important setting for an SMS

Zone 1

Zone 2

Figure 9. Example deployment using eXtreme Scale Zones



http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp

environment. Stickiness is the ability of a load balancer to forward all requests froma particular client to the same server for the duration of the client session. Use theclient IP address to maintain session stickiness.

You must set session stickiness for an SMS cluster to function efficiently andeffectively. Set the timeout for session stickiness to be equal to the timeout of theclient session as defined by timeout in the session stanza of the configuration file.

SMS sessions and session limit policy

Session limit policyThe SMS can enforce a session limit policy. This policy can either be on a per userbasis, a per realm basis, or enforce session displacement for users. Theconfiguration of the session limit policy occurs in the SMS client (for example,WebSEAL) and is sent to each SMS. During the SMS configuration, you can disablethe session limit policy so that the SMS ignores the limits sent by the client.Disabling the session limit policy at the SMS causes enhanced performance ingeneral operations. However, disabling the session limit policy reduces internalindexing, which reduces performance in administration operations such as sessionsearch and terminate.

Number of concurrent sessionsThe number of concurrent sessions in the SMS environment dictates how muchmemory each SMS uses. This value also partially determines the required numberof SMS servers. The number of authentications per second required, the sessionidle timeout, the maximum session lifetime, and the number of logouts determinethe number of concurrent sessions.

ExampleConsider an environment with four SMS clients and four SMS cluster members.Assume 50 authentications per second with an idle timeout of 30 minutes and amaximum session time of 1 hour. The calculations that follow assume that 80% ofthe sessions expire and the remaining 20% reach the maximum session lifetime.

50 auth/sec * 60 = 300 auth/minute

300 auth/min * 30 minutes = 9000 sessions created in 30 minutes

After that time, 80% of the sessions become idle = 7200; 1800 remain.

In the next 30 mins another 9000 are created, making a total of 10800 sessions.

So at any one time, up to 11,000 sessions can be in the SMS.

Session cache sizeThe sum of the maximum number of sessions that can be held by each SMS client(for example, WebSEAL) determines the maximum concurrent sessions in the SMS.When the client session caches are full, the local cache drops sessions based on aLeast Recently Used (LRU) algorithm. Sessions might be removed from the SMS ifno other client instances hold a reference to the session.

For example, consider an environment with a maximum of 10,000 sessions in theSMS. To accommodate this number of sessions, set the minimum cache size foreach of the four clients to 2500. This setting is not adequate if two clients fail. In

Chapter 4. Session management server best practices 37

this situation, the maximum number of sessions per client is 5000. In this case, setthe cache size of each client to 5000 users.

Tuning the Java Virtual MachineIn most cases, you must increase the heap size of WebSphere Application Servers,including those servers acting as part of the catalog service. These servers caninclude application servers running the SMS application, node agents, or thedeployment manager. An increase in the Java Virtual Machine (JVM) heap size isrequired if many concurrent sessions must be managed by the SMS.

The JVM heap size dictates the maximum amount of memory that can be allocatedto a WebSphere Application Server instance. In the SMS case, it defines the amountof memory allocated to the eXtreme Scale server, and therefore the session tablesize.

NOTE: Servers acting as the catalog service do not maintain SMS sessioninformation but they require a larger heap size than the default 256Mb.

WebSphere Application Server Heap SizeIn order to increase the heap size of a WebSphere Application Server perform thefollowing steps:1. Open the Integrated Solutions Console2. On the left-hand side, expand the Servers heading and click Application

servers.3. Click the name of the WebSphere Application Server you want to modify.4. Under Server Infrastructure, expand the Java and Process Management

heading and click Process Definition.5. Under Additional properties, select Java Virtual Machine.6. In the Maximum Heap Size text box, specify the new maximum heap size.7. Click OK.8. Click Save.9. Restart the application server for the changes to take effect.

WebSphere Application Server Deployment Manager HeapSize

In order to increase the heap size of the WebSphere Application ServerDeployment manager perform the following steps:1. Open the Integrated Solutions Console2. On the left-hand side, expand the System Administration heading and click

Deployment manager.3. Under Server Infrastructure, expand the Java and Process Management

heading and click Process Definition.4. Under Additional properties, select Java Virtual Machine.5. In the Maximum Heap Size text box, specify the new maximum heap size.6. Click OK.7. Click Save.8. Restart the deployment manager for the changes to take effect.


WebSphere Application Server Node Agent Heap SizeIn order to increase the heap size of the WebSphere Application Server Node agentperform the following steps:1. Open the Integrated Solutions Console2. On the left-hand side, expand the System Administration heading and click

Deployment manager.3. Click the name of the node agent you want to modify.4. Under Server Infrastructure, expand the Java and Process Management

heading and click Process Definition.5. Under Additional properties, select Java Virtual Machine.6. In the Maximum Heap Size text box, specify the new maximum heap size.7. Click OK.8. Click Save.9. Restart the deployment manager for the changes to take effect.

32-bit and 64-bit considerationsThere are several limitations on the heap size that you can allocate to a 32-bit JVM.Some of these limitations come from the underlying operating system. Otherlimitations are due to the amount of memory that can be addressed using a 32-bitpointer. Moving to a 64-bit platform permits larger memory addressing and heapsizes, but causes the additional overhead of larger memory pointers and anincreased footprint. The overhead considerations are particularly relevant to aneXtreme Scale environment. Due to the scalable nature of eXtreme Scale andtherefore the SMS, use additional 32-bit JVMs instead of 64-bit JVMs. Using 32-bitJVMs improves memory density compared to 64-bit JVMs. This structure alsoprovides more fault tolerance in terms of the session data stored on each SMSinstance and increases the number of servers able to process requests from SMSclients.

Configuring the Object Request BrokerTo configure the Object Request Broker properties to suit your environment, seethe "Orb properties file" section in the WebSphere eXtreme Scale Administration Guidein the WebSphere eXtreme Scale Version 7.0 information center:


Session Management Server High Availability ConsiderationsWhen deployed, the SMS is a critical Tivoli Access Manager component.Consequently, the SMS must have high availability. Otherwise, failure might causethe client to become unavailable for session operations. Availability improves ifyou run the SMS in a clustered environment consisting of at least two clustermembers. If all cluster members become unavailable, the session data maintainedby the SMS is lost and the SMS is no longer able to service any requests. In thiscase, the Web security clients (such as WebSEAL) cannot create new sessions.

The availability of the SMS is determined by two separate components in theenvironment. The first component consists of the actual WebSphere ApplicationServers running an SMS instance and holding WebSphere eXtreme Scale containers.The second key component is the WebSphere eXtreme Scale catalog service



responsible for maintaining routing information for the SMS servers. It isimportant to consider the high availability of each component as part of an SMSdeployment.

Hard failure detectionIn a clustered environment, the SMS stores session data such that system operationis not affected by the loss of a single SMS server. You must tune the hard failuredetection mechanism in the underlying WebSphere Application Server to optimizefailure detection.

Hard failure detection is a means of detecting a physical computer crash, networkcable disconnect, or OS panic. WebSphere eXtreme Scale uses a heartbeat detectionmechanism to detect hard failure events using the underlying WebSphereApplication Server core group heartbeat functionality. Hard failure detection takesapproximately 200 seconds in a default SMS configuration. This value is too largefor the SMS to function correctly during a hard failure scenario. A hard failuremust be detected in less than 20 seconds for the SMS to function as expected.

Specify the heartbeat interval in seconds on WebSphere Application Server versions6.0 through 6.1.0.12, and in milliseconds starting with version 6.1.0.13. You mustalso specify the number of missed heartbeats. This value indicates how manyheartbeats can be missed before a peer JVM is considered failed. The hard failuredetection time is approximately the product of the heartbeat interval and thenumber of missed heartbeats. Specify these properties using custom properties onthe core group in the WebSphere administrative console. Consider networkperformance and reliability to tune these settings appropriately for the specificenvironment. When these settings are too aggressive, false failures are detected.However, if these settings are not aggressive enough, failures are not detected earlyenough for the system to recover in a suitable time frame.

To update the core group settings for WebSphere Application Server NetworkDeployment Version 6.1:v Set IBM_CS_FD_PERIOD_MILLIS (WebSphere Application Server Network

Deployment version 6.1.0.13 and later)v Set IBM_CS_FD_CONSECUTIVE_MISSED

WebSphere Application Server Network Deployment version 7.0 provides thefollowing two core group settings:v Heartbeat transmission period.v Heartbeat timeout period.

These settings can be adjusted to increase or decrease failover detection.

For further information about heartbeat detection in WebSphere Application Server,see "Core group heartbeat configuration" under the "Configuring failover detection"section in the WebSphere eXtreme Scale Administration Guide in the WebSphereeXtreme Scale Version 7.0 information center:


eXtreme Scale container JVMsThe eXtreme Scale container JVMs are the virtual machines that hold the SMSsession data. The WebSphere Application Servers in the SMS cluster are alsoknown as the eXtreme Scale Container JVMs.



Container failureThe SMS is designed such that when a container fails, any primaries held in thatSMS server are promoted elsewhere in the SMS cluster. The SMS can withstandmultiple container JVM failures before data loss occurs, provided at least one set ofprimaries for all maps remains available. The eXtreme Scale catalog servicepromotes and demotes containers according to the deployment parameters definedin the SMS. It is important however that container JVMs continue to maintain aconnection to the catalog service. If a container JVM loses contact with the catalogservice and then regains contact, the catalog service detects the failure. At thistime, any containers held by the container JVM are dropped and placed on otherservers. Under these conditions, the container JVM continues to act as an eXtremeScale client, but you must manually restart the JVM to hold containers again. Thisbehavior is designed to ensure consistency of the data across the cluster.

eXtreme Scale Catalog serviceA catalog service is the grid of catalog servers you are using. You can run catalogservers inside WebSphere Application Server JVM processes or inside stand-aloneJVM processes. These servers retain topology information for all the containers inyour eXtreme Scale environment, which is the SMS deployment environment inthis case. The catalog service controls balancing and routing for all clients andmanages the promotion and demotion of containers from primaries to replicas. ForeXtreme Scale to operate for the SMS, you must cluster the catalog servers into agrid for high availability.

When the catalog service starts, it selects a master catalog server that is responsiblefor holding the master copy of all data in the catalog service. The master catalogserver accepts Internet Inter-ORB Protocol (IIOP) heartbeats and handles systemdata changes in response to any catalog service or container changes. When clientscontact any of the catalog servers, the routing table for the catalog server grid ispropagated to the clients. This propagation occurs through the Common ObjectRequest Broker Architecture (CORBA) service context.

To ensure high availability, configure at least two catalog servers into a catalogservice cluster. If your configuration has zones, you can configure one catalogserver per zone.

When an eXtreme Scale server and container contacts one of the catalog servers,the routing table for the catalog server grid is also propagated to the eXtreme Scaleserver and container. This propagation occurs through the CORBA service context.If the contacted catalog server is not currently the master catalog server, therequest is automatically rerouted to the current master catalog server. The routingtable for the catalog server is also updated.

Note: A catalog server grid and the container server grid are different. The catalogserver grid is for high availability of the eXtreme Scale system data. The containergrid is meant for high availability, scalability, and workload management of theSMS application. Consequently, two different routing tables exist:v The routing table for the catalog server grid, andv The routing table for the server grid shards.

Running catalog servers inside WebSphere Application ServerJVM processes

You can configure the WebSphere Application Server instances to run WebSphereeXtreme Scale catalog servers. You can configure the catalog service to run in any


process in the WebSphere cell. A single-server catalog service is acceptable fordevelopment environments. For a production environment, use a catalog servicegrid with multiple catalog servers.

For WebSphere Application Server Network Deployment, the catalog service runsin the deployment manager process automatically. However, you can configure thecatalog service to run in one or more application server processes.

The WebSphere eXtreme Scale catalog service configuration is defined using acustom property called catalog.services.cluster in the WebSphere cell. Forrunning the catalog service inside a WebSphere Application Server, use thefollowing format for the value of this property:<serverName>:<hostname>:<clientPort>:<peerPort>:<listenerPort>[,<serverName>:<hostname>:<clientPort>:<peerPort>:<listenerPort> ...]

where

serverNameSpecifies the fully qualified name of the WebSphere process, such as thecellName, nodeName, and serverName of the server that hosts the catalogservice.

hostnameSpecifies the name of the hosting server.

clientPortSpecifies the port that is used for peer catalog grid communication.

peerPortSpecifies the port that is used for peer catalog grid communication and canbe anything you choose in a WebSphere Application Server environment.

listenerPortThe listenerPort must match the BOOTSTRAP_ADDRESS value that isdefined in the WebSphere server configuration.

Example:sms1Cell01\sms1CellManager01\dmgr:sms1.amtest.gc.au.ibm.com:6600:6601:9809,sms1Cell01\sms4Node02\catalogServer1:sms4.amtest.gc.au.ibm.com:6602:6603:2809

For more information, see "Starting the catalog service process in a WebSphereApplication Server environment" in the WebSphere eXtreme Scale AdministrationGuide, which is located in the WebSphere eXtreme Scale Version 7.0 informationcenter:


Running catalog servers inside stand-alone JVMsDepending on the architecture of an SMS deployment, you can choose to run thecatalog servers inside stand-alone JVMs rather than inside WebSphere ApplicationServers.

You must define a WebSphere Application Server cell custom property calledcatalog.services.cluster so that the WebSphere eXtreme Scale container serverscan contact the catalog service. For catalog servers running inside stand-aloneJVMs, use the following format to specify the value of this property:<serverName>:<hostname>:<clientPort>:<peerPort>[,<serverName>:<hostname>:<clientPort>:<peerPort>...]



where

serverNameSpecifies a name to identify the process that you are launching.

hostnameSpecifies the host name of the computer where the server is launched.

clientPortSpecifies the port that you are using for peer catalog grid communication.

peerPortSpecifies the port that you are using for peer catalog grid communication.

Example:cat1:sms-multicell01.vam.gc.au.ibm.com:6602:6603:2809,cat2:sms-multicell02.vam.gc.au.ibm.com:6602:6603:2809

The catalog service can run in a single process or can include multiple catalogservers to form the catalog server grid. For high availability, a productionenvironment requires a catalog server grid. Whether the catalog service is placed ina grid or a single process, you can start the service using the startOgServer script.

For more information, see "Starting the catalog service in a stand-aloneenvironment" in the IBM WebSphere eXtreme Scale Administration Guide, which islocated in the WebSphere eXtreme Scale Version 7.0 information center:


Catalog service failureThe catalog service grid is an eXtreme Scale grid so it uses the core groupingmechanism in the same way as the container failure process. The primarydifference is that the catalog service grid uses a peer election process to define theprimary shard instead of the catalog service algorithm used for containers. Catalogservice members must be contained in the same core group. However, the catalogservice core group need not be the same as the core group where the SMS serversare located.

The catalog service uses replication to make itself fault-tolerant. If a catalog serviceprocess fails, restart the service to restore the system to the desired level ofavailability. If all the processes that are hosting the catalog service fail, eXtremeScale loses critical data. This failure results in a required restart of all thecontainers. The catalog service can run on many processes so this failure is anunlikely event. However, a failure is more likely to occur if you are running all theprocesses on a single box, in a single blade chassis, or from a single networkswitch. Try to remove common failure modes from boxes that are hosting thecatalog service to reduce the possibility of failure.

Catalog service quorum behaviorNormally, the members of the catalog service have full connectivity. The catalogservice grid is a static set of JVMs. WebSphere eXtreme Scale expects all membersof the catalog service to be online at all times. The catalog service only responds tocontainer events while the catalog service has quorum.

If the catalog service loses quorum, it waits for quorum to be reestablished. Whenthe catalog service does not have quorum, it ignores events such as failures fromcontainer servers.



The following message indicates that quorum is lost. Look for this message in yourcatalog service logs.CWOBJ1254W: The catalog service is waiting for quorum.

WebSphere eXtreme Scale expects to lose quorum in the following situations:v Catalog service JVM member failurev Network brownoutv Loss of connectivity between zones

In terms of the SMS, lost quorum in the catalog service does not affect service. TheWeb security server environment continues to operate during quorum lossprovided no container server loss occurs.

Quorum loss from JVM failureA catalog server that fails due to a crash causes quorum to be lost. In this event,manually override quorum as quickly as possible. The failed catalog service cannotrejoin the grid until you manually override quorum.

For further information about overriding quorum, see “Overriding quorum” onpage 47.

Quorum loss from network brownoutWebSphere eXtreme Scale handles the possibility of brownouts. A brownout istemporary loss of connectivity between nodes. This loss of connectivity is generallytransient and brownouts typically clear in a matter of seconds or minutes.WebSphere eXtreme Scale tries to maintain normal operation during a brownoutperiod. However, WebSphere eXtreme Scale regards a brownout as a single failureevent. The failure is expected to be fixed and then normal operation resumes withno WebSphere eXtreme Scale actions necessary. During a brownout, if quorum islost in the catalog service and SMS servers are disconnected from one another,sessions can no longer be stored. After the brownout clears, normal operationresumes.

Catalog service JVM cyclingIf you stop a catalog server by stopping the JVM that it is running in, then thequorum drops to one less server. This means that the remaining servers still havequorum. Restarting the catalog server restores quorum to the previous number.

Consequences of lost quorumIf a container JVM fails while quorum is lost in the catalog service, recovery doesnot take place until the brownout or blackout ends. To recover from a blackout,perform a manual override quorum command. WebSphere eXtreme Scale considersa quorum loss event and a container failure as a double failure, which is a rareevent. Until quorum is restored and normal recovery can take place, applicationssuch as the SMS might lose write access to data that was stored on the failed JVM.In the context of a Tivoli Access Manager Web security server environment, thisdouble failure means that sessions cannot be stored in the SMS.

Similarly, if you attempt to start a container during a quorum loss event, thecontainer does not start. This means that if you try to start an SMS server duringquorum loss, the SMS server does not start properly.

Full client connectivity is allowed during quorum loss. If no container failures orconnectivity issues happen during the quorum loss event, then clients can still


fully interact with the container servers. As a result, the SMS can store and accesssessions during quorum loss provided no SMS servers fail, or becomenoncommunicable, at the same time.

If a brownout occurs, then some clients might not have access to primary or replicacopies of the data until the brownout clears. Under some brownout conditions, theSMS can continue to perform session operations, depending on the primariesavailable to the particular server at the time.

Quorum recoveryIf quorum is lost and reestablished, a recovery protocol is executed by the catalogservice. When the quorum loss event occurs, all liveness checking for core groupsis suspended and failure reports are also ignored. When quorum returns, thecatalog service performs a liveness check of all core groups to immediatelydetermine their membership. Any shards previously hosted on container JVMs thatreportedly failed are recovered. If primary shards were lost then surviving replicasare promoted to primaries. If replica shards were lost, then additional replicas arecreated on the survivors. For the SMS, this recovery process means that no sessiondata is lost. However, a significant number of SMS server failures might cause dataloss.

Failure scenariosThis section describes scenarios where significant failures lead to loss of service forthe SMS and the Web security server environment. The following diagramillustrates an example SMS deployment.


e X t r e m e S c a l e G r i d V i e w

DeploymentManager

Session Index Data

Session Data

Clients

Config

Keys

WebSphere Application Server ND Cell

SMSServer 2

SMSServer 1

DSess

WebSphereApplication

ServerCatalogServer 1

WebSphereApplication

ServerCatalogServer 2

SMS Cluster

Figure 10. Session Management Server Deployment


Multiple container lossMultiple container failures might cause loss of data held in the SMS. Containerfailures can lead to a situation where the SMS cannot store sessions. The likelihoodof losing enough containers to impact service is minimal due to the underlyingreplication and the placement of synchronous and asynchronous replicas thateXtreme Scale provides.

An example of this failure is when both 'SMS Server 1' and 'SMS Server 2' fail. SeeFigure 10 on page 46.

To mitigate the risk of multiple container failures causing service loss, addadditional SMS servers to the cluster. During configuration, you can calculate thenumber of containers needed based on the size of the cluster. Additional servers inthe environment result in the creation of more containers, thus reducing the risk ofcritical data loss.

Loss of all catalog serversIf all catalog servers fail, the SMS continues to function. However, the SMS haslimited ability to cope with container failures. When the catalog service is restoredafter being offline, the SMS JVMs cannot hold containers. Consequently the SMScannot store sessions. It is important that catalog servers are on separate hardwarefrom container servers. This separation prevents the hardware failure of a specificcomputer being a single point of failure.

An example of this failure is when both 'Catalog server 1' and 'Catalog server 2'fail. See Figure 10 on page 46.

Note: The system can continue to operate in this mode. However, when the catalogservice becomes available again, there is no guarantee that data is not lost or thatany SMS servers hold primaries until they are restarted.

Cluster the catalog service to reduce the risk of losing the entire catalog service.

Container & catalog server lossWhile a container server and catalog server are both lost, the SMS cannot servicerequests. It is important that this failure is either mitigated or recovered fromquickly to ensure continual service to the Tivoli Access Manager Web SecurityServers.

An example of this failure is when both 'SMS Server 1' and 'Catalog server 1' fail.See Figure 10 on page 46.

To mitigate this risk, configure separate nodes for each SMS server and catalogservice, and ensure that redundant links exist between nodes.

Recovery proceduresManual intervention is required to recover from a brownout or a blackout where acatalog service member and a container JVM are lost. This process involvesoverriding quorum on one side of the brownout or blackout. After the brownout orblackout clears and service resumes, restart the SMS and catalog servers located onthe other side of the brownout or blackout.

Overriding quorumQuorum is an important concept in an eXtreme Scale environment. When quorumis established, the grid can detect and continue functioning after networkbrownouts.


To enable quorum within the catalog service cluster in a WebSphere ApplicationServer environment:v Create a file objectGridServer.properties in the <WAS_HOME>\profiles\

<profile>\properties directory of each clustered catalog service member.v Specify the following entry in this file:

enableQuorum=true

To enable quorum in the catalog service cluster in a stand-alone JVM environment,you can do either of the following:v Pass the -quorum enabled flag on the startOgServer command.v Add the enableQuorum=true property in the property file passed in to the

startOgServer command.

All the catalog servers must have the same quorum setting.

If a hard failure leads to the loss of a catalog service member and an SMS node,you must manually override quorum to reestablish service. If the loss is due to anetwork brownout, quorum is reestablished without any manual interventionwhen the brownout clears. You must manually intervene if the brownout or loss ispermanent. You can use the xsadmin command-line tool to override quorum. Thisprocess enables the catalog service to promote eXtreme Scale replicas to primariesand enables the SMS to become fully functional again. The command to overridequorum is as follows.

On a catalog server that is not the Deployment Manager:> xsadmin.sh -ch <cathost> -p <port> -overridequorum

where

cathost The host of the catalog server where quorum is to be over-ridden.

port The port of the catalog server (typically 9809 in a WebSphere ApplicationServer Network Deployment environment).

On a catalog server that is the Deployment Manager:> xsadmin.sh -dmgr -overridequorum

For more information about overriding quorum in a clustered catalog service, see"Catalog server quorums" in the WebSphere eXtreme Scale Product Overview, locatedin the WebSphere eXtreme Scale Version 7.0 information center:




Appendix A. SMS pdsmsadmin and pdadmin commands

The pdsmsadmin and pdadmin command line utilities can be installed as part ofthe Tivoli Access Manager package.

Use these interfaces to manage access control lists, groups, servers, users, objects,and other resources in your secure domain.

You can also automate certain management functions by writing API scripts thatuse the pdadmincommands, which include an optional delimiter to specify sessionmanagement server instances.

Reading syntax statementsThe reference documentation uses the following special characters to define syntax:

[ ] Identifies optional syntax. Options not enclosed in brackets are required.

... Indicates that you can specify multiple values for the previous option.

| Indicates mutually exclusive information. You can use the option to the leftof the separator or the option to the right of the separator. You cannot useboth options in a single use of the command.

{ } Delimits a set of mutually exclusive options when one of the options isrequired. If the options are optional, they are enclosed in brackets ([ ]).

\ Indicates that the command line wraps to the next line. It is a continuationcharacter.

The options for each command or utility are listed alphabetically in the Optionssection or Parameters section, respectively. When the order of the options orparameters must be used in a specific order, this order is shown in the syntaxstatements.


loginLogs user in to pdsmsadmin or pdadmin command line. If a password is notprovided, you will be prompted for it.

SyntaxPDSMSADMIN

login username [password]

PDADMINlogin -a username -p [password]

Optionsuser Specifies the user name.

passwordSpecifies the user password.

Return codes0 The command completed successfully.

1 The command failed. When a command fails, the pdsmsadmin commandprovides a description of the error and an error status code in hexadecimalformat (for example, 0x14c012f2).

Refer to the IBM Tivoli Access Manager for e-business: Error Message Reference.This reference provides a list of the Tivoli Access Manager error messagesby decimal or hexadecimal codes.

ExamplesThe following example logs a user named user1 with a password of passw0rd in tothe pdsmsadmin command line:pdsmsadmin> login user1 passw0rd

See alsotrace get


set instanceSets the current instance, allowing you to swap from one instance to another toperform administrative tasks.

SyntaxPDSMSADMIN

set instance instance

PDADMINNot available: the [.instance] delimiter can optionally be specified as part ofpdadmin commands. If not specified, the first available instance is used.

Optionsinstance

Specifies the name of the server instance to be set.




ExamplesThe following example sets instance1 as the current instance:pdsmsadmin> set instance instance1

See alsotrace get

Appendix A. SMS pdsmsadmin and pdadmin commands 51

instances listLists all available instances.

SyntaxPDSMSADMIN

instances list

PDADMINinstances list

OptionsNIL No parameters required.




ExamplesThe following example lists all available instances:pdsmsadmin> instances list

See alsotrace get


server listLists all registered Tivoli Access Manager servers.

Requires authentication (administrator ID and password) to use this command.

SyntaxPDSMSADMIN

Not available.

PDADMINserver list

DescriptionLists all registered Tivoli Access Manager servers. The name of the server for allserver commands, except for the server list command, must be entered in the exactformat as it is displayed in the output of this command.

OptionsNone.


1 The command failed. When a command fails, the pdsmsadmin orpdadmin command provides a description of the error and an error statuscode in hexadecimal format (for example, 0x14c012f2). Refer to the IBMTivoli Access Manager for e-business: Error Message Reference. This referenceprovides a list of the Tivoli Access Manager error messages by decimal orhexadecimal codes.

ExamplesThe following example lists all registered servers if the Tivoli Access Managercomponent is the authorization server:pdadmin> server list

Output is similar to:ivacld-topserverivacld-server2ivacld-server3ivacld-server4


key changeForces the creation of a new session management key.

You might want to forcibly create a new key when you suspect that the existingkey was compromised.

SyntaxPDSMSADMIN

key change

PDADMINserver task server_name–host_name sms[.instance] key change

Optionsserver_name–host_name

Specifies the name of the server or server instance. You must specify theserver name in the exact format as it is shown in the output of the serverlist command.

For example, if the configured name of a single WebSEAL server on hostcruz.dallas.ibm.com is default, the server_name would bedefault-webseald and the host_name would be cruz.dallas.ibm.com. Forthis example, the name of the server would be default-webseald-cruz.dallas.ibm.com.

If there are multiple configured server instances on the same machine, forexample, the host cruz.dallas.ibm.com, and the configured name of theWebSEAL server instance is webseal2-webseald, the server_name would bewebseal2-webseald and the host_name would be cruz.dallas.ibm.com. Forthis example, the name of the server instance would bewebseal2-webseald-cruz.dallas.ibm.com.

The [.instance] delimiter is optional in pdadmin. If not specified, the firstavailable instance is used.



NotesThe pdadmin command is available only when the session management commandline extensions are installed to a hosting authorization server.

ExamplesThe following example forcibly creates a new session management key for theabc.ibm.com server:pdsmsadmin> key change

pdadmin> server task default-webseald-abc.ibm.com key change


See alsoserver listkey show

key change


key showLists detailed information about the current session management key.

SyntaxPDSMSADMIN

key show

PDADMINserver task server_name–host_name sms[.instance] key show









ExamplesThe following example returns detailed information about the current sessionmanagement key for the abc.ibm.com server:pdsmsadmin> key show

pdadmin> server task default-webseald-abc.ibm.com sms key show

Output is similar to:


ID: 1Created: 2004-03-03-09:00:03Expires: 2004-09-03-09:00:03

See alsoserver listkey change

key show


realm listLists all session management realms in the domain.

SyntaxPDSMSADMIN

realm list

PDADMINserver task server_name–host_name sms[.instance] realm list









ExamplesThe following example lists the realms for the abc.ibm.com server:pdsmsadmin> realm list

pdadmin> server task default-webseald-abc.ibm.com sms realm list


See alsoserver listrealm showreplica set listreplica set show

realm list


realm showLists all replica sets in the specified session management realm.

SyntaxPDSMSADMIN

realm show realm_name

PDADMINserver task server_name–host_name sms[.instance] realm show realm_name

Optionsrealm_name

Specifies the name of the realm. When you specify a realm, the outputcontains only those replica sets in that realm.

server_name–host_nameSpecifies the name of the server or server instance. You must specify theserver name in the exact format as it is shown in the output of the serverlist command.







ExamplesThe following example returns the replica sets in the ibm.com realm of theabc.ibm.com server:pdsmsadmin> realm show ibm.com


pdadmin> server task default-webseald-abc.ibm.com sms realm show ibm.com

See alsoserver listrealm listreplica set listreplica set show

realm show


session refresh all_sessionsRefreshes the credential for sessions for a specific user.

SyntaxPDSMSADMIN

session refresh all_sessions user_name –realm realm_name

PDADMINserver task server_name–host_name sms[.instance] session refreshall_sessions user_name –realm realm_name

Options–realm realm_name

Specifies that name of the realm. Only sessions that belong to the specifiedrealm will have credentials refreshed.




user_nameRefreshes the credential for all sessions that are associated with thespecified user. Examples of user names are dlucas, sec_master, and “MaryJones".

[.instance]

This delimiter is optional in pdadmin. If not specified, the first availableinstance is used.


1 The command failed. When a command fails, the pdsmsadmin orpdadmin command provides a description of the error and an error statuscode in hexadecimal format (for example, 0x14c012f2).




ExamplesThe following example refreshes all sessions for user johnq in the ibm.com realm:pdsmsadmin> session refresh all_sessions johnq -realm ibm.com

pdadmin> server task default-webseald-cruz sms session refresh all_sessions johnq-realm ibm.com

See alsosession terminate sessionsession terminate all_sessions

session refresh all_sessions


session refresh sessionRefreshes the credential for a session.

SyntaxPDSMSADMIN

session refresh session session_id –realm realm_name

PDADMINserver task server_name–host_name sms[.instance] session refresh sessionsession_id –realm realm_name


Specifies that name of the realm. Only sessions that belong to the specifiedrealm will have credentials refreshed.





session_idSpecifies the identifier for the session to refresh.






ExamplesThe following example refreshes session 678 in the ibm.com realm:pdsmsadmin> session refresh session 678 -realm ibm.com

pdadmin> server task default-webseald-cruz sms session refresh session 678-realm ibm.com

See alsosession terminate sessionsession terminate all_sessions

session refresh session


replica set listLists all session management replica sets in the domain.

SyntaxPDSMSADMIN

replica set list [–realm realm_name]

PDADMINserver task server_name–host_name sms[.instance] replica set list [–realmrealm_name]


Indicates that the returned list of replica sets is limited to those replica setsin the specified realm.








ExamplesThe following example lists the replica sets in the ibm realm of the abc.ibm.comserver:


pdsmsadmin> replica set list -realm ibm

pdadmin> server task default-webseald-abc.ibm.com sms replica set list -realm ibm

See alsoserver listrealm listrealm showreplica set show

replica set list


replica set showLists all session management replicas in the specified replica set with the time anddate that each joined the realm.

SyntaxPDSMSADMIN

replica set show replica_set_name

PDADMINserver task server_name–host_name sms[.instance] replica set showreplica_set_name

Optionsreplica_set_name

Specifies the name of the replica set.








ExamplesThe following example returns details about the ibm.com replica set of theabc.ibm.com server:


pdsmsadmin> replica set show ibm.com

pdadmin> server task default-webseald-abc.ibm.com sms replica set show ibm.com

See alsoserver listrealm listrealm showreplica set list

replica set show


session listLists all session management sessions.

SyntaxPDSMSADMIN

session list –realm realm_name pattern maximum_return

PDADMINserver task server_name–host_name sms[.instance] session list –realmrealm_name pattern maximum_return


Specifies the name of the session management realm.




maximum_returnSpecifies the maximum number of sessions to return. When there are morematches than designated by this option, the output contains the number ofmatches.

pattern Specifies the pattern for returning user names. The pattern can include acombination of wild card and string constant characters. The pattern iscase-sensitive. For example, you can specify *luca* as the pattern to findall users that contain the substring luca in the user name.

[.instance]

This delimiter is optional in pdadmin. If not specified, the first availableinstance is used.





ExamplesThe following example (entered as one line) lists the user sessions in the ibm.comrealm of the abc.ibm.com server for users that contains the string ons and limits thenumber of matches to 100:pdsmsadmin> session list -realm ibm.com *ons* 100

pdadmin> server task default-webseald-abc.ibm.comsms session list -realm ibm.com *ons* 100

See alsoserver listrealm listrealm showreplica set show

session list


session terminate all_sessionsTerminates all user sessions for a specific user.

SyntaxPDSMSADMIN

session terminate all_sessions user_id –realm realm_name

PDADMINserver task server_name–host_name sms[.instance] session terminateall_sessions user_id –realm realm_name


Specifies that name of the session management realm.





user_id Specifies the name of the user. Examples of user names are dlucas,sec_master, and "Mary Jones".






ExamplesThe following example terminates all sessions for the dlucas user in the ibm.comrealm of the default-webseald-cruz WebSEAL server:pdsmsadmin> session terminate all_sessions dlucas -realm ibm.com

pdadmin> server task default-webseald-cruz sms session terminate \all_sessions dlucas -realm ibm.com

See alsosession refresh sessionsession refresh all_sessionssession terminate session

session terminate all_sessions


session terminate sessionTerminates a user session using a session ID.

SyntaxPDSMSADMIN

session terminate session session_id –realm realm_name

PDADMINserver task server_name–host_name sms[.instance] session terminate sessionsession_id –realm realm_name






session_idSpecifies the ID of a user session.





ExamplesThe following example terminates session 678 in the ibm.com realm of thedefault-webseald-cruz WebSEAL server:pdsmsadmin> session terminate session 678 -realm ibm.com


pdadmin> server task default-webseald-cruz sms session terminate \session 678 -realm ibm.com

See alsosession refresh all_sessionssession terminate all_sessions

session terminate session


trace getDisplays the trace level for the session management server. The recommended wayto do this in version 6.1 is with the ISC, using standard WebSphere tracingfacilities, which provide more fine-grained detail.

SyntaxPDSMSADMIN

trace get

PDADMINserver task server_name–host_name sms[.instance] trace get










ExamplesThe following example returns the tracing level for the ivacld-cruz authorizationserver:pdsmsadmin> trace get

pdadmin> server task ivacld-cruz.dallas.ibm.com sms trace get


See alsotrace set

trace get


trace setSets the trace level for the session management server. The recommended way todo this in version 6.1 is with the ISC, using standard WebSphere tracing facilities,which provide more fine-grained detail.

SyntaxPDSMSADMIN

trace set level

PDADMINserver task server_name–host_name sms[.instance] trace set level

Optionslevel Specifies the level of tracing. A valid setting is an integer between 0 and 3,

with 3 being the most detailed level of trace.









ExamplesThe following example sets the tracing level to 1 on the ivacld-cruz authorizationserver:


pdsmsadmin> trace set 1

pdadmin> server task ivacld-cruz.dallas.ibm.com sms trace set 1

See alsotrace get

trace set


Appendix B. SMS utilities


pdsmsclicfgConfigures the command line administration utility for the session managementserver.

Syntaxpdsmsclicfg –action config [–rspfile response_file] [–interactive {yes|no}][–tam_integration {yes|no}] [–aznapi_app_config_file path_name][–webservice_location host:port[,host:port...]] [–instances name1,name2] [-ssl_enable{yes|no}] [–sslkeyfile path] [–sslkeyfile_stash path] [–sslkeyfile_label label]

pdsmsclicfg –action unconfig

pdsmsclicfg –action name

pdsmsclicfg –action version

pdsmsclicfg –action upgrade

DescriptionThe pdsmsclicfg utility configures or unconfigures the session management servercommand line administration utility. A log of the configuration progress is writtento the msg_pdsmsclicfg.log log file, which is located in the /var/pdsms/logdirectory on Linux and UNIX operating systems and in the installation_directory\log directory on Windows operating systems.

This utility can be run either interactively, where the user is prompted to provideconfiguration information, or silently, where the utility accepts input from aresponse file or the command line.

If integration with Tivoli Access Manager is enabled during configuration, theprogram prompts the user to specify the path to the configuration file for analready configured aznapi application. The program prompts the user to specifythe location of the Web service. The location of the Web service is defined by ahost name and port that are separated by a semicolon. The user can specifymultiple locations, when each location is separated by a comma. If this Web serviceuses a secure connection, the program prompts the user for the SSL options. Youmust also specify the session management server instance(s).

The configuration information is saved to /opt/pdsms/etc/pdsmsclicfg.conf. Thepresence of this configuration file is used to determine the configuration status ofthe utility.

The command line executable on Windows is pdsmsclicfg-cl.exe.

Parameters–action {config|unconfig|upgrade|name|version}

Specifies the action to be performed that is one of the following values:

config Configures the command line administration utility.

unconfigFully unconfigures the command line administration utility. Noother parameters are required.


name Displays the translated "Session Management Command Line"name. No other options are required.

upgradePerforms a configuration upgrade from a previous version.

versionDisplays the version number for the currently installed SMS CLIpackage.

–rspfile response_fileSpecifies the fully qualified path and file name of the response file to useduring silent configuration. A response file can be used for configuration.There is no default response file name. The response file contains stanzasand parameter=value pairs. To use response files, see the procedures in theIBM Tivoli Access Manager for e-business: Installation Guide.

–interactive {yes|no}Indicates whether the configuration is interactive. The default value is yes.

–tam_integration {yes|no}Specifies whether integration with the Tivoli Access Manageradministration framework is required. The default value is no.

–aznapi_app_config_file path_nameSpecifies the fully qualified name of the configuration file for the hostingauthorization server. Only required if Tivoli Access Manager integration isenabled.

–webservice_location host:portSpecifies the location of the session management server AdministrationWeb service. The location is the name of the hosting server and the port onwhich the Web service resides. Multiple locations can be specified. Whenspecifying multiple locations, separate the locations with commas.

–instances name1,name2The session management server instances which are to be administered.The instance names should be separated by a comma. The default value isDSess.

–ssl_enable {yes|no}Indicates whether SSL communication with the Web server should beenabled.

–sslkeyfile pathSpecifies the fully qualified name of the SSL key file to use whencommunicating with the session management server Web service. Use thisparameter only when the –ssl_enable parameter is set to yes.

–sslkeyfile_label labelSpecifies the SSL key file label of the certificate to be used. Use thisparameter only when the –ssl_enable parameter is set to yes.

–sslkeyfile_stash pathSpecifies the fully qualified name of the stash file that contains thepassword for the SSL key file. Use this parameter only when the–ssl_enable parameter is set to yes.

AvailabilityThis utility is located in one of the following default installation directories:v On Linux and UNIX operating systems:

pdsmsclicfg

Appendix B. SMS utilities 83

/opt/pdsms/bin

v On Windows operating systems:c:\Program Files\Tivoli\PDSMS\bin

To invoke the command line under Windows, use pdsmsclicfg-cl.exe. Thepdsmsclicfg command will invoke the wizard.

When an installation directory other than the default is selected, this utility islocated in the /bin directory under the installation directory (for example,installation_directory/bin).

Return codes0 The utility completed successfully.

non-zeroThe utility failed. When a utility fails, a description of the error and anerror status code in hexadecimal format is provided (for example,0x15c3a00c). Refer to the IBM Tivoli Access Manager for e-business: ErrorMessage Reference. This reference provides a list of the Tivoli AccessManager error messages by decimal or hexadecimal codes.

pdsmsclicfg


smsbackupGathers information to help IBM Software Support in problem determination.

Note: This utility is for use by support personnel.

SyntaxFor local mode

smsbackup –local [–was_home path] [–list list] [–path output]

For remote modesmsbackup [–was_home path] [–wsadmin_options options] [–list list][–path output]

DescriptionThe smsbackup gathers information to help IBM Software Support in problemdetermination. It has two modes:

Local modeGathers information from the local system only. Does not require anoperational WebSphere environment. To gather information about allmembers in the cluster, run the utility on each node in the cluster.

Remote modeGathers information about the entire environment. Requires an operationalWebSphere environment.

The utility is provided on Linux and UNIX operating systems as a shell script,smsbackup.sh. On Windows operating systems, it is provided as a batch script,smsbackup.bat.

When running the utility in local mode, you need to copy the following files toeach member in the cluster, maintaining directory structure:v /bin/smsbackup.shv /bin/smsbackup.batv /etc/smsbackup.lstv /lib/smscfg.jarv /nls/java/message.jar

Parameters–local Indicates that the utility runs in local mode.

–list listSpecifies the .lst file that describes the information to gather. If notspecified, the smsbackup.lst file in the sms_installation_directory/etcdirectory is used.

–path outputSpecifies the directory for the created JAR file. The JAR file contains thegathered information.

–was_home pathSpecifies the home directory of the WebSphere Application Server. Thisvalue must be set on the command line or in the WAS_HOMEenvironment variable.


–wsadmin_options optionsSpecifies options to pass directory to the wsadmin utility. Use thisparameter to pass non-default binding information before running thebackup operation through the WebSphere cluster. Examples of non-defaultbinding information include the user name, password, and so forth.


/opt/pdsms/bin





smsbackup


smscfgDeploys and configures the session management server.

Syntaxsmscfg –action {config|unconfig|deploy|undeploy|extract|upgrade|revert|}

Configurationsmscfg –action config [–interactive {yes|no}] [–rsp_file file_name] [–recordfile_name] [–was_port port] [–was_enable_security {yes|no}][–was_admin_id administrator_id] [–was_admin_pwd password][–trust_store file_name] [–trust_store_pwd password] [–keyfile file_name][–key_pwd password] [–instance instance_name][–enable_session_limit_policy {yes|no}] [–session_realmrealm:max_login=replica_set1_name,replica_set2_name,...][–session_realm_remove realm_name] [–enable_tcd {yes|no}] [–tcdfully_qualified_directory_name] [–enable_tam_integration {yes|no}][–policysvr_host host_name] [–policysvr_port port] [–admin_idadministrator_id] [–admin_pwd password] [–domain domain] [–authzsvrhost_name:port:rank] [–cred_refresh_rule rule] [–enable_last_login{yes|no}][–enable_last_login_database {yes|no}] [–last_login_tablelast_login_database_table_name] [–last_login_max_entriesmax_number_memory_entries] [–last_login_jsp_file file_name][–last_login_jsp server_jsp_name][–enable_database_session_storage{yes|no}][–enable_auditing {yes|no}][–auditing_propertiesfile_name][–key_lifetime key_lifetime] [–client_idle_timeout timeout]

Configuration with response filesmscfg –action config –rspfile file_name

Configuration, interactivesmscfg –action config –interactive

Unconfigurationsmscfg –action unconfig [–interactive {yes|no}] [–rspfile file_name][–record file_name] [–was_port port] [–was_enable_security {yes|no}][–was_admin_id administrator_id] [–was_admin_pwd password][–trust_store file_name] [–trust_store_pwd password] [–keyfile file_name][–key_pwd password] [–instance instance_name] [–admin_id administrator_id][–admin_pwd password] [–remove_last_login_db {yes|no}]

Unconfiguration, response filesmscfg –action unconfig –rspfile file_name

Unconfiguration, interactivesmscfg –action unconfig –interactive

Deploymentsmscfg –action deploy [–interactive {yes|no}] [–rspfile file_name] [–recordfile_name] [–was_port port] [–was_enable_security {yes|no}][–was_admin_id administrator_id] [–was_admin_pwd password][–trust_store file_name] [–trust_store_pwd password] [–keyfile file_name][–key_pwd password] [–instance instance_name] [–enable_database_storage{yes|no}][–database_name database_name][–virtual_host host_name][–clustered {yes|no}] [–was_node node_name] [–was_server server_name][–was_cluster cluster_name]

Undeploymentsmscfg –action undeploy [–interactive {yes|no}] [–rspfile file_name]


[–record file_name] [–was_port port] [–was_enable_security {yes|no}][–was_admin_id administrator_id] [–was_admin_pwd password][–trust_store file_name] [–trust_store_pwd password] [–keyfile file_name][–key_pwd password] [–instance instance_name]

Extractsmscfg –action extract [–interactive {yes|no}] [–rspfile file_name] [–recordfile_name] [–was_port port] [–was_enable_security {yes|no}][–was_admin_id administrator_id] [–was_admin_pwd password][–trust_store file_name] [–trust_store_pwd password] [–keyfile file_name][–key_pwd password] [–instance instance_name]

Upgradesmscfg –action upgrade [–interactive {yes|no}] [–rspfile file_name][–record file_name] [–was_port port] [–was_enable_security {yes|no}][–was_admin_id administrator_id] [–was_admin_pwd password][–trust_store file_name] [–trust_store_pwd password] [–keyfile file_name][–key_pwd password] [–instance instance_name]

Revertsmscfg –action revert [–interactive {yes|no}] [–rspfile file_name] [–recordfile_name] [–was_port port] [–was_enable_security {yes|no}][–was_admin_id administrator_id] [–was_admin_pwd password][–trust_store file_name] [–trust_store_pwd password] [–keyfile file_name][–key_pwd password] [–instance instance_name]

Utility helpsmscfg –help option

smscfg –usage

smscfg –?

DescriptionThe smscfg utility deploys, configures or unconfigures session management serverinstances. It can also be used to extract the session management serverconfiguration, or to install and remove fixpack upgrades.

A log of the configuration progress is written to msg_smscfg.log log file that islocated in the /var/pdsms/log directory on Linux and UNIX operating systemsand in the installation_directory\log directory on Windows operating systems.

This utility can be run either interactively, where the user is prompted to provideconfiguration information, or silently, where the utility accepts input from aresponse file.

Parameters–? Displays the syntax and an example for this utility.

–action {deploy|config|unconfig|undeploy|extract}Specifies the action to be performed that is one of the following values:

deployDeploys the session management server instance to a WebSphereApplication Server.

undeployRemoves a session management server instance from a WebSphereApplication Server.

smscfg


config Configures or reconfigures a deployed session management serverinstance.

unconfigUnconfigures a session management server instance.

extract Extracts the configuration information from a session managementserver instance.

upgradeUpgrades to a new session management server fixpack.

revert Reverts to the previous session management server fixpack.

–admin_id administrator_idSpecifies the Tivoli Access Manager administration ID. The default value issec_master. This parameter is required when –enable_tam_integration isset to yes.

–admin_pwd passwordSpecifies the password for the Tivoli Access Manager administrator. Thisparameter is required when you specify the –admin_id parameter.

–auditing_properties file_nameSpecifies the path to the properties file which contains the configuration ofthe auditing component.

–authzsvr host_name:port:rankSpecifies the host name, port number, and rank of the Tivoli AccessManager authorization server. This optional parameter can be specifiedmultiple times.

A Tivoli Access Manager authorization server is required to use thesesession refresh capabilities or to use certificates that are issued by theTivoli Access Manager policy server to authenticate session managementclients.

The default value is localhost:7136:1.

–client_idle_timeout timeoutSpecifies the client idle timeout in seconds after which a client isconsidered idle. A client is considered idle if it is not actively requestingupdates from the session management server. This parameter is optional.

–clustered {yes|no}Whether the application will be deployed to a WebSphere cluster. Thedefault value is no.

–cred_refresh_rule ruleSpecifies rules to preserve when a user's credential is refreshed. The defaultcredential refresh rule set is preserve=tagvalue_*.

–database_name databaseSpecifies the name of the of the WebSphere JDBC data source that thesession management server uses to access the database that it uses to storeits data. There is no default value.

–domain domainSpecifies the name of the Tivoli Access Manager policy domain. Thisparameter is required when –enable_tam_integration is set to yes. Thedefault value is Default.

–enable_auditing {yes|no}Indicates whether or not auditing is required. The default value is no.

smscfg


–enable_database_storage {yes|no}Indicates whether database storage is required. The parameter is onlymeaningful in the context of WebSphere Application Server single serverdeployments. If the application is deployed to a cluster, this parameter isredundant. The default value is no. Setting this parameter to no sets thedatabase configuration to the WebSphere default resource reference,normally jdbc/DataSource.

–enable_database_session_storage {yes|no}Indicates whether storage of session data to a database is required. Thedefault value is no.

–enable_last_login {yes|no}Indicates whether last login information is stored. When set to yes, youmust specify the following parameters or accept their default values:v –last_login_jsp_filev –last_login_max_entriesv –last_login_table

The default value is no (not to enable the recording of last logininformation). The –enable_last_login field is only required if installing intoa stand alone application server. When installing into a cluster this field isnot required.

–enable_last_login_database {yes|no}Indicates whether last login information is stored to a database. Thedefault value is no.

–enable_session_limit_policy {yes|no}Indicates whether to enable session limit and displacement policy. Thedefault value is yes.

–enable_tam_integration {yes|no}Indicates whether to enable integration with Tivoli Access Manager or tochange enablement. When set to yes, you must specify the followingparameters or accept their default values, where applicable:v –policysvr_hostv –policysvr_portv –authzsvrv –admin_idv –admin_pwdv –domain

The default value is no.

–enable_tcd {yes|no}Indicates whether Tivoli Common Directory logging is required. When setto yes, you must specify the –tcd parameter. The default value is no.

–help [options]Lists the name of the utility parameter and a short description. If one ormore options are specified, it lists each parameter and a short description.

–instance instance_nameSpecifies the name of the instance to be administered. The default value isDSess.

–interactive {yes|no}Indicates whether the configuration is interactive. The default value is yes.

–key_lifetime lifecycleSpecifies the lifetime in seconds of the key for the session management

smscfg


server. After the defined lifecycle completes, a new key is generated. If thisvalue is set to zero, keys are not automatically generated. This parameter isoptional.

–key_pwd passwordSpecifies the password to access the server-side certificates. This parameteris required when you specify the –keyfile parameter. Otherwise, thisparameter is optional.

–keyfile file_nameSpecifies the fully qualified name for the key store when making a secureconnection to WebSphere Application Server. The key store holds theserver-side certificates. This parameter is required when you specify the–was_admin_id parameter. Otherwise, this parameter is optional.

–last_login_jsp server_jsp_nameThe server-side path for the last login JSP file. This is an optionalargument.

–last_login_jsp_file file_nameSpecifies the fully qualified name of the last login JSP file to use forrecording last login information. This parameter is required when the–enable_last_login parameter is set to yes. The default value isinstallation_directory/etc/lastLogin.jsp

Note: Configuration of the lastLogin.jsp file can produce a long Webbrowser URL, which could exceed the limits imposed by someproxy servers. To avoid this, access the WebSphere ISC using adirect connection to the Internet.

–last_login_max_entries maximum_entriesSpecifies the maximum number of entries to be stored in the memorycache for recording last login information. This parameter is required whenthe –enable_last_login parameter is set to yes. The default value is 0. The–last_login_max_entries field is only required if installing into a standalone application server. When installing into a cluster this field is notrequired.

–last_login_table table_nameSpecifies the name of the database table to use for recording last logininformation. This parameter is required when the –enable_last_loginparameter is set to yes. The default value is AMSMSUSERINFOTABLE.

–operationsLists each of the parameter names, one after another, without a description.

–policysvr_host host_nameSpecifies the host name of the Tivoli Access Manager policy server. Thisparameter is required when –enable_tam_integration is set to yes.

–policysvr_port portSpecifies the port of the Tivoli Access Manager policy server. Thisparameter is required when you specify the –host parameter.

–record file_nameSpecifies the name of the response file to which configuration parameterswill be recorded.

–remove_last_login_db {yes|no}Indicates whether the last login database should be removed. The defaultvalue is no.

smscfg


–rspfile response_fileSpecifies the fully qualified path and file name of the response file to useduring silent configuration. A response file can be used for configuration.There is no default response file name. The response file contains stanzasand parameter=value pairs. To use response files, see the procedures in theIBM Tivoli Access Manager for e-business: Installation Guide.

–session_realm [realm[:max_logins]=replica_set1, replica_set2,...]A session realm to add to the configuration. If the session realm name orany of the replica set names contain spaces, the entire argument must bespecified within quotes. The max_logins parameter is used to specify themaximum number of concurrent logins which are permitted for the sessionrealm. If the max_logins parameter is not supplied there will be anunlimited number of concurrent logins allowed for the session realm.Replica set names must be separated by commas.

–session_realm_remove realm=set_name[,...][;realm=set_name[,...]...]The name of a session realm which is to be removed. If the session realmname contain spaces, the entire argument must be specified within quotes.

–tcd path_nameSpecifies the fully qualified directory to be used for Tivoli CommonDirectory logging. This parameter is required when –enable_tcd is set toyes. If the Tivoli common directory has already been configured on thetarget system, this option will be ignored.

–trust_store file_nameSpecifies the fully qualified name for the trust store when making a secureconnection to WebSphere Application Server. The trust store holds theclient-side certificates. This parameter is required when you specify the–was_admin_id parameter.

–trust_store_pwd passwordSpecifies the password to access the client-side certificates. This parameteris required when you specify the –trust_store parameter.

–usageDisplays the syntax and an example for this utility.

–virtual_host host_nameSpecifies the name of the WebSphere virtual host to which to deploy thesession management server application. If not specified, the application isdeployed on the default virtual host.

–was_admin_id administrator_idSpecifies the name of the administrator to use when making a secureconnection to WebSphere Application Server. In interactive mode, thisparameter is optional unless you are making a secure connection. Whenyou use this parameter, you must specify the –was_admin_pwd parameter.When not making a secure connection, this parameter is optional.

–was_admin_pwd passwordSpecifies the administrator's password to use when making a secureconnection to WebSphere Application Server.

–was_cluster cluster_nameSpecifies the name of the WebSphere cluster to which to deploy the sessionmanagement server application. This parameter is mutually exclusive withthe –was_server parameter.

smscfg


When using WebSphere Network Deployment and –was_cluster isspecified and there is only one cluster, the application is deployed to thatcluster.

When using WebSphere Network Deployment and –was_cluster isspecified and there is no cluster but there is only one server, theapplication is deployed to that server.

–was_enable_security {yes|no}Indicates whether the communication with the WebSphere server uses asecure connection. When set to yes, you must specify the followingparameters:v –was_admin_idv –was_admin_pwdv –trust_storev –trust_store_pwdv –keyfilev –key_pwd

The default value is no.

–was_node node_nameSpecifies the name of the WebSphere node. This parameter is optional.

–was_port portSpecifies the simple object access protocol (SOAP) port to use on theWebSphere server. This parameter is always required unless the–interactive parameter is set to yes.

–was_server server_nameSpecifies the name of the WebSphere server to which to deploy the sessionmanagement server application. This parameter is mutually exclusive withthe –was_cluster parameter. When using WebSphere Application Server (asingle server deployment) and –was_server is not specified, the applicationis deployed to the server to which this configuration utility is connected.


/opt/pdsms/bin





smscfg


smsservicelevelLists the current service level of the session management server files on the localsystem.

Note: This utility is for use by support personnel.

Syntaxsmsservicelevel [directory [directory] ...] [file [file] ...]

DescriptionThe smsservicelevel utility recursively scans the specified directory and returns tothe standard output device the name and service level for session managementserver files that match Tivoli Access Manager conventions.

The utility is provided on Linux and UNIX operating systems as a shell script,smsservicelevel.sh. On Windows operating systems, it is provided as a batchscript, smsservicelevel.bat.

Parametersdirectory

Specifies the directories that the utility searches for service levelinformation.

files Specifies particular files that the utility searches.


/opt/pdsms/bin






Appendix C. Support information

This section describes the following options for obtaining support for IBMproducts:v “Searching knowledge bases”v “Obtaining fixes”v “Registering with IBM Software Support” on page 96v “Receiving weekly software updates” on page 96v “Contacting IBM Software Support” on page 97

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.

Searching information centersIBM provides extensive documentation in an information center that can beinstalled on your local computer or on an intranet server. You can use the searchfunction of this information center to query conceptual information, instructionsfor completing tasks, reference information, and support documents.

Searching the InternetIf you cannot find an answer to your question in the information center, search theInternet for the latest, most complete information that might help you resolve yourproblem. To search multiple Internet resources for your product, perform thefollowing steps:1. Expand the product folder in the navigation frame on the left.2. Expand Troubleshooting and support.3. Expand Searching knowledge bases.4. Click Web search.

From this topic, you can search a variety of resources, which includes thefollowing resources:v IBM Technotesv IBM downloadsv IBM Redbooks®

v IBM developerWorks®

v Forums and news groupsv Google

Obtaining fixesA product fix might be available to resolve your problem. To determine what fixesare available for your IBM software product, check the product support site byperforming the following steps:1. Go to the IBM Software Support site at the following Web address:


http://www.ibm.com/software/support2. Under Products A - Z, click the letter with which your product starts to open a

Software Product List.3. Click your product name to open the product-specific support page.4. Under Self help, follow the link to All Updates, where you will find a list of

fixes, fix packs, and other service updates for your product. For tips on refiningyour search, click Search tips.

5. Click the name of a fix to read the description.6. Optional, download the fix.

Registering with IBM Software SupportBefore you can receive weekly e-mail updates about fixes and other news aboutIBM products, you need to register with IBM Software Support. To register withIBM Software Support, follow these steps:1. Go to the IBM Software Support site at the following Web address:

http://www.ibm.com/software/support2. Click Register in the upper right-hand corner of the support page to establish

your user ID and password.3. Complete the form, and click Submit.

Receiving weekly software updatesAfter registering with IBM Software Support, you can receive weekly e-mailupdates about fixes and other news about IBM products. To receive weeklynotifications, follow these steps:1. Go to the IBM Software Support site at the following Web address

http://www.ibm.com/software/support2. Click the My support link to open the Sign in page.3. Provide your sign in information, and click Submit to open your support page.4. Click the Edit profile tab.5. For each product about which you want to receive updates, use the filters to

choose your exact interests, and click Add products.6. Repeat step 5 for each additional product.7. After choosing all your products, click the Subscribe to email link.8. For each product category, use the filters and choose which updates you want

to receive, and click Update.9. Repeat step 8 for each additional product category.

For more information about the types of fixes that are available, see the IBMSoftware Support Handbook at the following Web address:

http://techsupport.services.ibm.com/guides/handbook.html


http://www.ibm.com/software/support



http://techsupport.services.ibm.com/guides/handbook.html

Contacting IBM Software SupportIBM Software Support provides assistance with product defects. Before contactingIBM Software Support, the following criteria must be met:v Your company has an active IBM software maintenance contract.v You are authorized to submit problems to IBM Software Support.

The type of software maintenance contract that you need depends on the type ofproduct that you have. Product types are one of the following categories:v For IBM distributed software products (including, but not limited to, Tivoli,

Lotus®, and Rational® products, as well as DB2 and WebSphere products thatrun on Windows, Linux, or UNIX operating systems), enroll in PassportAdvantage® in one of the following ways:

OnlineGo to the IBM Software Passport Advantage site at the following Webaddress and click How to Enroll:

http://www.lotus.com/services/passport.nsf/WebDocs/Passport_Advantage_Home

By phoneFor the phone number to call in your country, go to the IBM SoftwareSupport site at the following Web address and click the name of yourgeographic region:

http://techsupport.services.ibm.com/guides/contacts.htmlv For IBM eServer™ software products (including, but not limited to, DB2 and

WebSphere products that run in System z®, pSeries®, and iSeries® environments),you can purchase a software maintenance agreement by working directly withan IBM sales representative or an IBM Business Partner. For more informationabout support for eServer software products, go to the IBM eServer TechnicalSupport Advantage site at the following Web address:

http://www.ibm.com/servers/eserver/techsupport.html

If you are not sure what type of software maintenance contract you need, call1-800-IBMSERV (1-800-426-7378) in the United States or, from other countries, go tothe contacts page of the IBM Software Support Handbook at the following Webaddress and click the name of your geographic region for phone numbers ofpeople who provide support for your location:

http://techsupport.services.ibm.com/guides/contacts.html

To contact IBM Software support, follow these steps:1. “Determining the business impact”2. “Describing problems and gathering information” on page 983. “Submitting problems” on page 98

Determining the business impactWhen you report a problem to IBM, you are asked to supply a severity level.Therefore, you need to understand and assess the business impact of the problemthat you are reporting. Use the following severity criteria:

Appendix C. Support information 97




http://www.ibm.com/servers/eserver/techsupport.html


Severity 1The problem has a critical business impact. You are unable to use theprogram, resulting in a critical impact on operations. This conditionrequires an immediate solution.

Severity 2The problem has a significant business impact. The program is usable, butit is severely limited.

Severity 3The problem has some business impact. The program is usable, but lesssignificant features that are not critical are unavailable.

Severity 4The problem has minimal business impact. The problem causes little impacton operations, or a reasonable circumvention to the problem wasimplemented.

Describing problems and gathering informationWhen explaining a problem to IBM, be as specific as possible. Include all relevantbackground information so that IBM Software Support specialists can help yousolve the problem efficiently. To save time, know the answers to these questions:v What software versions were you running when the problem occurred?v Do you have logs, traces, and messages that are related to the problem

symptoms? IBM Software Support is likely to ask for this information.v Can you create the problem again? If so, what steps were performed to

encounter the problem?v Was any change made to the system? For example, were there changes to the

hardware, operating system, networking software, and so on.v Are you currently using a workaround for this problem? If so, please be

prepared to explain it when you report the problem.

Submitting problemsYou can submit your problem to IBM Software Support in one of two ways:

OnlineGo to the Submit and track problems page on the IBM Software Supportsite at the following address, and provide your information into theappropriate problem submission tool:


By phoneFor the phone number to call in your country, go to the contacts page ofthe IBM Software Support Handbook at the following Web address and clickthe name of your geographic region:


If the problem you submit is for a software defect or for missing or inaccuratedocumentation, IBM Software Support creates an Authorized Program AnalysisReport (APAR). The APAR describes the problem in detail. Whenever possible,IBM Software Support provides a workaround that you can implement until theAPAR is resolved and a fix is delivered. IBM publishes resolved APARs on theIBM product support Web pages daily, so that other users who experience thesame problem can benefit from the same resolution.




For more information about problem resolution, see “Searching knowledge bases”on page 95 and “Obtaining fixes” on page 95.

Appendix C. Support information 99

Appendix D. Notices

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 on theproducts and services currently available in your area. Any functionally equivalentproduct, program, or service that does not infringe any IBM intellectual propertyright may be used instead. Any reference to an IBM product, program, or service isnot intended to state or imply that only that IBM product, program, or service maybe used. However, it is the user responsibility to evaluate and verify the operationof 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 give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certaintransactions, therefore, this statement might 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 improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.


IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758 U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements, or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility, or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information is for planning purposes only. The information herein is subject tochange before the products described become available.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have not


been thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. You may copy,modify, and distribute these sample programs in any form without payment toIBM for the purposes of developing, using, marketing, or distributing applicationprograms conforming to IBM‘s application programming interfaces.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp.Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rightsreserved.

If you are viewing this information in softcopy form, the photographs and colorillustrations might not be displayed.

TrademarksIBM, the IBM logo, AIX®, DB2, IBMLink, Tivoli, Tivoli Enterprise Console®, andTME are trademarks or registered trademarks of International Business MachinesCorporation in the United States, other countries, or both.

Adobe, the Adobe logo, Acrobat, PostScript® and all Adobe-based trademarks areeither registered trademarks or trademarks of Adobe Systems Incorporated in theUnited States, other countries, or both.

Cell Broadband Engine™ is a trademark of Sony Computer Entertainment, Inc., inthe United States, other countries, or both and is used under license therefrom.

Intel®, Intel logo, Intel Inside®, Intel Inside logo, Intel Centrino®, Intel Centrinologo, Celeron®, Intel Xeon®, Intel SpeedStep®, Itanium®, and Pentium® aretrademarks or registered trademarks of Intel Corporation or its subsidiaries in theUnited States and other countries.

IT Infrastructure Library® is a registered trademark of the Central Computer andTelecommunications Agency which is now part of the Office of GovernmentCommerce.

IT Infrastructure Library is a registered trademark, and a registered communitytrademark of the Office of Government Commerce, and is registered in the U.S.Patent and Trademark Office.

Java and all Java-based trademarks and logos are trademarks orregistered trademarks of Sun Microsystems, Inc. in the United States,other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, orboth.

Microsoft, Windows, Windows NT®, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.

Appendix D. Notices 103

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Other company, product, and service names may be trademarks or service marksof others.


Glossary

This glossary defines the technical terms andabbreviations that are used in Tivoli AccessManager. If you do not find the term orabbreviation for which you are looking, refer tothe IBM Terminology Web site at the followingWeb address:

http://www.ibm.com/ibm/terminology

The following cross-references are used amongterms:

Contrast withRefers the reader to a term that has anopposed or substantively differentmeaning.

See Refers the reader to a term that is theexpanded form of an abbreviation oracronym or to a synonym or morepreferred term.

See alsoRefers the reader to a related term.

ObsoleteIndicates that the term should not be usedand refers the reader to the preferredterm.

Aaccess control. In computer security, the process ofensuring that only authorized users can access theresources of a computer system in authorized ways.

access control list (ACL). In computer security, a listwith an object that identifies all the subjects that canaccess the object and their access rights. For example,an access control list is a list that is associated with afile that identifies the users who can access the file andidentifies the users' access rights to that file.

access decision information (ADI). The data andattributes that are used by the authorization engine toevaluate a rule. Authorization API attributes arename-value pairs, form the basis of all ADI that can bereferenced in a rule or presented to the authorizationengine.

access permission. The access privilege that applies tothe entire object.

account. Information about an identity.

ACL. See access control list.

ACL entry. Data in an access control list that specifiesa set of permissions.

ACL policy. Part of the security policy that containsACL entries that control who can access which domainresources and perform which actions. See alsoauthorization rule and protected object policy.

action. An access control list (ACL) permissionattribute. See also access control list.

action group. A set of actions that are explicitlyassociated with a resource or set of resources.

ADI. See access decision information.

ADK. See application development kit

administration service. An authorization API runtimeplug-in that can be used to perform administrationrequests on a Tivoli Access Manager resource managerapplication. The administration service responds toremote requests from the pdadmin command toperform tasks, such as listing the objects under aparticular node in the protected object tree. Customersmay develop these services using the authorizationADK.

application development kit (ADK). A set of tools,APIs, and documentation to assist with thedevelopment of software in a specific computerlanguage or for a particular operating environment.

attribute. A characteristic or trait of an entity thatdescribes the entity. An attribute can have a type,which indicates the range of information given by theattribute, and a value, which is within a range. In XML,for example, an attribute consists of a name-value pairwithin a tagged element and modifies a feature of anelement.

attribute list. A linked list that contains extendedinformation that is used to make authorizationdecisions. Attribute lists consist of a set of name-valuepairs.

audit event. A record of an operation in the audit logor change history; for example, an audit entry iscreated when a resource is modified.

audit level. The types of user actions that arecurrently being audited for the entire system or forspecific users on the system. Actions that can beaudited include authority failures and restoring objects.A record of each action is written to the audit journal.

audit trail. A chronological record of events thatenables the user to examine and reconstruct a sequence


http://www.ibm.com/software/globalization/terminology

of events. Audit trails are useful for managing securityand for recovering lost transactions.

audit trail file. The file that contains the audit trail.

authentication. In computer security, the process thatverifies identity. Authentication is distinct fromauthorization; authorization is concerned with grantingand denying access to resources. See also multi-factorauthentication, network-based authentication, andstep-up authentication.

authorization. In computer security, the process thatgrants or denies access to resources. Security uses atwo-step process: after authentication has verified theidentity, authorization allows the resource or processaccess to various resources based on its identity.

authorization API. The Tivoli Access Managercomponent that passes requests for authorizationdecisions from the resource manager to theauthorization evaluator. See also authorization serverand authorization service.

authorization evaluator. The decision-making processthat determines whether a client can access a protectedresource based on the security policy. The evaluatormakes its recommendation to the resource manager,which, in turn, responds accordingly.

authorization rule. Part of the security policy thatdefine conditions that are contained in authorizationpolicy. An authorization rule is used to make accessdecisions based on attributes such as user, application,and environment context. See also ACL policy andprotected object policy.

authorization server. The Tivoli Access Managercomponent that runs the authorization service. See alsoauthorization service.

authorization service. A dynamic or shared librarythat can be loaded by the authorization API runtimeclient at initialization time to perform operations thatextend a service interface in the Authorization API.

BBA. See basic authentication.

basic authentication. An authentication method thatverifies identity using a user name and password.

bind. To relate an identifier to another object in aprogram; for example, to relate an identifier to a value,to an address, or to another identifier or to associateformal parameters to actual parameters.

blade. A component that provides application-specificservices and components.

Boolean. A binary numbering system that is namedafter mathematician George Boole in which zero and

one are the only two values that can be returned; avalue of zero represents false while a value of onerepresents true.

business entitlement. The supplemental attribute of auser credential that describes the fine-grainedconditions that can be used in the authorizationprocess.

CCA. See certificate authority.

CDAS. Obsolete. See external authentication C API.

CDMF. See cross domain mapping framework.

certificate. In computer security, a digital documentthat binds a public key to the identity of the certificateowner, thereby enabling the certificate owner to beauthenticated. A certificate is issued by a certificateauthority.

certificate authority (CA). An organization that issuescertificates. A CA creates digital signatures andpublic-private key pairs. The CA guarantees theidentity of the individual who is granted the uniquecertificate and guarantees the services that the owner isauthorized to use, to issue new certificates, and torevoke certificates that belong to users andorganizations who are no longer authorized to use theservices. The role of the CA s to authenticate theentities (users and organizations) involved in electronictransactions. Because the CA guarantees that the twoparties that are exchanging information are really whothey claim to be, the CA is a critical component in datasecurity and electronic commerce.

CGI. See common gateway interface.

cipher. A cryptographic algorithm that is used toencrypt data that is unreadable until it is converted intoplain data (decrypted) with a predefined key.

common gateway interface (CGI). An Internetstandard for defining scripts that pass information froma Web server to an application program, through anHTTP request, and vice versa. A CGI script is a CGIprogram that is written in a scripting language, such asPerl.

configuration. The manner in which the hardwareand software of a system, subsystem, or network areorganized and interconnected.

connection. (1) In data communication, an associationestablished between functional units for conveyinginformation. (2) In TCP/IP, the path between twoprotocol applications that provides reliable data streamdelivery service. In the Internet, a connection extendsfrom a TCP application on one system to a TCPapplication on another system. (3) In system


communication, a line over which data can be passedbetween two systems or between a system and adevice.

console log agent. A log agent that writes events tostandard error or standard output. See also file logagent, pipe log agent, and remote log agent.

container object. A structural designation thatorganizes the object space into distinct functionalregions.

cookie. Information that a server stores on a clientmachine and accesses during subsequent sessions.Cookies allow servers to remember specific informationabout clients.

credentials. Detailed information, acquired duringauthentication, that describes the user, any groupassociations, and other security-related identityattributes. Credentials can be used to perform amultitude of services, such as authorization, auditing,and delegation.

credentials modification service. An authorizationAPI runtime plug-in which can be used to modify aTivoli Access Manager credential. Credentialsmodification services developed externally bycustomers are limited to performing operation to addand remove from the credentials attribute list and onlyto those attributes that are considered modifiable.

cross domain authentication service (CDAS).Obsolete. See external authentication C API.

cross domain mapping framework (CDMF). Aprogramming interface that allows a developer tocustomize the mapping of user identities and thehandling of user attributes when WebSEALe-Community SSO function are used.

Ddaemon. A system process that runs unattended toperform continuous or periodic system-wide functions,such as network control. See also service.

data store. A storage area for data, such as a databasesystem, directory, or file.

delegate. A user who is authorized to work foranother user. The authorization can be made by a useror by an administrator.

demilitarized zone (DMZ). In network security, acomputer or network that uses a firewall to be isolatedfrom, and to serve as a neutral zone between, a trustednetwork (for example, a private intranet) and anuntrusted network (for example, the Internet). One ormore secure gateways usually control access to theDMZ from the trusted or the untrusted network.

digital signature. Information that is encrypted with aprivate key and is appended to a message to assure therecipient of the authenticity and integrity of themessage. The digital signature proves that the messagewas signed by the entity that owns, or has access to,the private key or shared secret symmetric key.

directory schema. The valid attribute types and objectclasses that can appear in a directory. The attributetypes and object classes define the syntax of theattribute values, which attributes are required, andwhich attributes are optional.

distinguished name (DN). (1) The name that uniquelyidentifies an entry in a directory. A distinguished nameis made up of an attribute-value pairs, separated bycommas. (2) A set of name-value pairs (such ascn=common name and c=country) that uniquelyidentifies an entry in a digital certificate.

DMZ. See demilitarized zone.

DN. See distinguished name.

domain. (1) A logical grouping of resources in anetwork that share common administration andmanagement. (2) A part of a network that isadministered with a common protocol. See also domainname.

domain administrator. The administrator for adomain who can assign any of the roles in that domainto subdomains. After assigning roles to subdomains,administrators in that subdomain can assignsubdomain users these roles.

domain name. In the Internet suite of protocols, thename of a host system. A domain name consists of asequence of subnames that are separated by a delimitercharacter. For example, if austin.ibm.com is the fullyqualified domain name (FQDN) of a host system, bothaustin.ibm.com and ibm.com® are domain names.

dynamic group. A group that is defined using asearch expression. When an attribute is added to adirectory entry that causes it to match the searchexpression, the entry automatically becomes a memberof the group.

EEAS. See external authorization service.

encryption. In computer security, the process oftransforming data into a cipher.

entitlement. A data structure that containsexternalized security policy information. Entitlementscontain policy data or capabilities that are formatted ina way that is understandable to a specific application.

entitlement service. An authorization API runtimeplug-in which can be used to return entitlements from

Glossary 107

an external source for a principal or set of conditions.Entitlements are normally application specific data thatwill be consumed by the resource manager applicationin some way or added to the principal's credentials foruse further on in the authorization process. Customersmay develop these services using the authorizationADK.

entity. In object-oriented design, an item that can betreated as a unit and, often, as a member of a particularcategory or type. An entity can be concrete or abstract.

event. Any significant change in the state of a systemresource, network resource, or network application. Anevent can be generated for a problem, for the resolutionto a problem, or for the successful completion of a task.

event pool. A set of events recognized by an activity.Each activity has its own event pool. The event pool isinitialized when the activity is created and is deletedwhen the activity is deleted.

extended attribute. Additional information that thesystem or a program associates with an object. Anextended attribute can be any format, such as text, abitmap, or binary data.

external authentication C API. A C API that enablesyou to write custom authentication modules thatreplace or extend the functionality of the built–inauthentication process. The identity information isreturned through the authentication module interface.Contrast with external authentication HTTP interface.

external authentication HTTP interface. An interfacethat enables you to extend the functionality of thebuilt-in authentication process to allow a remote serviceto handle the authentication process. The identityinformation in the HTTP response headers is used togenerate user credentials. Contrast with externalauthentication C API.

external authorization service (EAS). Anauthorization API runtime plug-in that can be used tomake application- or environment-specific authorizationdecisions as part of the authorization decision chain.Customers can develop these services using theauthorization ADK.

Extensible Markup Language (XML). A standardmeta-language for defining markup languages that isbased on Standard Generalized Markup Language(SGML).

Extensible Stylesheet Language (XSL). A language forspecifying style sheets for XML documents. XSLTransformation (XSLT) is used with XSL to describehow an XML document is transformed into anotherdocument. See also Extensible Stylesheet LanguageTransformation.

Extensible Stylesheet Language Transformation(XSLT). An XML processing language that is used toconvert an XML document into another document inXML, PDF, HTML, or other format. See also ExtensibleStylesheet Language.

Ffile log agent. A log agent that writes events to a file.See also console log agent, pipe log agent, and remotelog agent.

file transfer protocol (FTP). In the Internet suite ofprotocols, a protocol that can use Transmission ControlProtocol (TCP) and Telnet services to transfer filesbetween machines.

FTP. See file transfer protocol

Gglobal sign-on (GSO). A flexible single sign-onsolution that enables the user to provide alternativeuser names and passwords to the back-end Webapplication server. Through a single login, globalsign-on grants users access to the computing resourcesthey are authorized to use. Designed for largeenterprises consisting of multiple systems andapplications within heterogeneous, distributedcomputing environments, GSO eliminates the need forusers to manage multiple user names and passwords.See also single sign-on.

group. A named list of users by which access levels tocorporate directories, databases, and servers areassigned. Two or more individual users who arecategorized for the purpose of assigning databasesecurity settings; for example, administrators mustassign individuals to groups before assigning roles.

GSO. See global sign-on.

Hhost. A computer that is connected to a network andprovides an access point to that network. The host canbe a client, a server, or both a client and a serversimultaneously.

HTTP. See hypertext transfer protocol.

hypertext transfer protocol (HTTP). In the Internetsuite of protocols, the protocol that is used to transferand display documents.

Iinheritance. An object-oriented programmingtechnique that allows the use of existing classes as abasis for creating other classes.


Internet protocol (IP). In the Internet suite ofprotocols, a connectionless protocol that routes datathrough a network or interconnected networks. IP actsas an intermediary between the higher protocol layersand the physical network.

Internet suite of protocols. A set of protocolsdeveloped for use on the Internet and publishedthrough the Internet Engineering Task Force (IETF).

interprocess communication (IPC). (1) The process bywhich programs communicate data to each other andsynchronize their activities. Semaphores, signals, andinternal message queues are common methods ofinterprocess communication. (2) A mechanism of anoperating system that allows processes to communicatewith each other within the same computer or over anetwork.

IP. See Internet protocol.

IPC. See interprocess communication.

Jjunction. A logical connection that is created toestablish a path from one server to another.

KKDC. See key distribution center.

Kerberos. An authentication system that enables twoparties to exchange private information over anotherwise open network. It works by assigning aunique key, called a ticket, to each user that logs on tothe network. The ticket is then embedded in messagesthat are sent over the network. The receiver of amessage uses the ticket to authenticate the sender.

Kerberos ticket. A transparent application mechanismthat transmits the identity of an initiating principal toits target. A simple ticket contains the identity, a sessionkey, a timestamp, and other information that is sealedusing a secret key.

key. In computer security, a sequence of symbols thatis used with a cryptographic algorithm for encryptingor decrypting data. See private key and public key.

key database file (KDC). See key file.

key distribution center. In the Kerberos protocol, thecentral server, which includes the authentication serverand the ticket-granting server. The KDC is sometimesreferred to as the Kerberos server.

key file. In computer security, a file that containspublic keys, private keys, trusted roots, and certificates.

key pair. In computer security, a public key and aprivate key. When the key pair is used for encryption,

the sender uses the public key to encrypt the message,and the recipient uses the private key to decrypt themessage. When the key pair is used for signing, thesigner uses the private key to encrypt a representationof the message, and the recipient uses the public key todecrypt the representation of the message for signatureverification. Because the private key holds more of theencryption pattern than the public key, the key pair iscalled asymmetric.

key ring. See key file.

keystore file. A key file that contains both public keysstored as signer certificates and private keys stored inpersonal certificates.

keytab file. See key table.

key table. In the Kerberos protocol, a file that containsservice principal names and secret keys. The secret keysshould be known only to the services that use the keytable file and the key distribution center (KDC).

key-value pair. Information that is expressed as apaired set.

LLDAP. See lightweight directory access protocol.

leaf node. A node that has no children before it in thedirectory tree.

lightweight directory access protocol (LDAP). Anopen protocol that uses TCP/IP to provide access todirectories that support an X.500 model and that doesnot incur the resource requirements of the morecomplex X.500 Directory Access Protocol (DAP). Forexample, LDAP can be used to locate people,organizations, and other resources in an Internet orintranet directory.

lightweight third party authentication (LTPA). Anauthentication protocol that users cryptography tosupport security across a set of Web servers in adistributed environment.

LTPA. See lightweight third party authentication.

Mmanagement domain. The default domain in whichTivoli Access Manager enforces security policies forauthentication, authorization, and access control. Thisdomain is created when the policy server is configured.See also domain.

management interface. The interface that a domainadministrator can use to manage security policy. InTivoli Access Manager, an administrator can use WebPortal Manager or the pdadmin commands to applysecurity policy to resources.

Glossary 109

management server. Obsolete. See policy server.

master server. In a network environment, the serverthat has permissions to run commands on all othermachines in the environment. The master server isdesigned to manage the network, clients, and resourceobjects in the network database. Contrast with replicaserver

metadata. Data that describes the characteristics ofstored data.

migration. The installation of a new version or releaseof a program to replace an earlier version or release.

MPA. See multiplexing proxy agent.

multi-factor authentication. A protected object policy(POP) that forces a user to authenticate using two ormore levels of authentication. For example, the accesscontrol on a protected resource can require that theusers authenticate with both user name/password anduser name/token passcode.

multiple tenancy server. A server that permits thehosting of multiple customers on a single server insteadof multiple client machines. See also protected objectpolicy.

multiplexing proxy agent (MPA). A gateway thataccommodates multiple client access. These gatewaysare sometimes known as Wireless Access Protocol(WAP) gateways when clients access a secure domainusing a WAP. Gateways establish a single authenticatedchannel to the originating server and tunnel all clientrequests and responses through this channel.

Nnamespace. (1) In XML, a uniform resource identifier(URI) that provides a unique name to associate with allthe elements and type definitions in a schema. (2)Space reserved by a file system to contain the names ofits objects.

network-based authentication. A protected objectpolicy (POP) that controls access to objects based on theInternet protocol (IP) address of the user. See alsoprotected object policy.

notification thread. The synchronization mechanismthat the policy server uses to inform all databasereplicas of a change to the master policy database.

Oobject. (1) In object-oriented design or programming,a concrete realization (instance) of a class that consistsof data and the operations associated with that data.An object contains the instance data that is defined bythe class, but the class owns the operations that areassociated with the data. (2) Any digital content that a

user can manipulate as a single unit and perform atask. An object can appear as text, an icon, or both. (3)A named storage space that consists of a set ofcharacteristics that describe the space and, in somecases, data. An object is anything that occupies space instorage, can be located in a library or directory, can besecured, and on which defined operations can beperformed. Some examples of objects are programs,files, libraries, and stream files.

object space. A virtual representation of the resourcesto be protected. See also namespace.

object type. A categorization or group of objectinstances that share similar behavior and characteristics.

PPAC. See privilege attribute certificate.

PDCA. See Policy Director Certificate Authority

permission. The ability to access a protected object,such as a file or directory. The number and meaning ofpermissions for an object are defined by the accesscontrol list (ACL). See also access control list.

pipe log agent. A log agent that writes events asstandard input to another program. See also console logagent, file log agent, and remote log agent.

policy. A set of rules that are applied to managedresources.

policy database. The database that contains thesecurity policy information for all resources in thedomain. Each domain has its own policy database.

Policy Director Certificate Authority (PDCA). Atrusted certificate that is created during theconfiguration of the policy server and that is used tosign all other Tivoli Access Manager certificates. APDCA certificate is stored in the master policydatabase.

policy enforcer. A component of a resource managerthat directs requests to the authorization service forprocessing after authorization is granted. Traditionalapplications bundle the policy enforcer and theresource manager as one process.

policy server. The Tivoli Access Manager componentthat maintains the master policy database, replicatesthis policy information throughout the secure domain,and updates database replicas whenever a change ismade to the master policy database. The policy serveralso maintains location information about other TivoliAccess Manager and non-Tivoli Access Managerresource managers that are operating in the securedomain.


polling. The process by which databases areinterrogated at regular intervals to determine if dataneeds to be transmitted.

POP. See protected object policy.

portal. A single point of access to diverse informationand applications. Users can customize and personalizea portal.

principal. (1) An entity that can communicate securelywith another entity. (2) An authenticated user. Aprincipal is identified by its associated security context,which defines its access rights.

private key. In computer security, a key that is knownonly to its owner. Contrast with public key.

privilege attribute certificate (PAC). A digitaldocument that contains a principal's authentication andauthorization attributes and a principal's capabilities.

privilege attribute certificate service. Anauthorization API runtime client plug-in whichtranslates a PAC of a predetermined format in to aTivoli Access Manager credential, and vice-versa. Theseservices could also be used to package or marshall aTivoli Access Manager credential for transmission toother members of the secure domain. Customers maydevelop these services using the authorization ADK.See also privilege attribute certificate.

protected object. The logical representation of anactual system resource that is used for applying ACLsand POPs and for authorizing user access. See alsoprotected object policy and protected object space.

protected object policy (POP). A type of securitypolicy that imposes additional conditions on theoperation permitted by the ACL policy to access aprotected object. It is the responsibility of the resourcemanager to enforce the POP conditions. See also ACLpolicy, authorization rule, protected object, andprotected object space.

protected object space. The virtual objectrepresentation of actual system resources that is usedfor applying ACLs and POPs and for authorizing useraccess. See also protected object and protected objectpolicy.

proxy server. A server that receives requests intendedfor another server and that acts on behalf of a client toobtain the requested service. A proxy server is oftenused when the client and the server are incompatiblefor direct connection. For example, a client cannot meetthe security authentication requirements of the serverbut should be permitted some services.

public key. In computer security, a key that is madeavailable to everyone. Contrast with private key.

Qquality of protection. The level of data security,determined by a combination of authentication,integrity, and privacy conditions.

Rrecord. (1) The storage representation of a single rowof a table or other data in a database. (2) A group ofrelated data, words, or fields treated as a unit.

registry. The datastore that contains access andconfiguration information for users, systems, andsoftware.

remote cache mode. An operational mode in which aresource manager uses the functions that are providedby the authorization API to communicate to the remoteauthorization server.

remote log agent. A log agent that sends events to aremote server for recording. See also console log agent,file log agent, and pipe log agent.

replica server. A server that contains a copy of thedirectory or directories of another server. Replicas backup master servers or other replica servers to enhanceperformance or response times and to ensure dataintegrity. Contrast with master server.

resource. A hardware, software, or data entity that ismanaged.

resource group. A group of resources that can includebusiness objects such as contracts or a set of relatedcommands. In access control policies, resource groupsspecify the resource to which the policy authorizesaccess.

resource manager. (1) An application, program, ortransaction that manages and controls access to sharedresources, such as memory buffers and data sets. (2)Any server or application that uses the authorizationAPI to process client requests for access to resources.

resource object. The representation of an actualnetwork resource, such as a service, file, and program.

response file. An ASCII file that can be customizedwith the setup and configuration data that automatesan installation. The setup and configuration data has tobe entered during an interactive installation, but withthe response file, the installation can proceed withoutuser interaction. See also silent installation.

role. A definition of the access permissions that a useror process has and the specific resources that the useror process can modify at those levels. Users andprocesses are limited in how they can access resourceswhen that user or process does not have theappropriate role.

Glossary 111

role activation. The process of applying accesspermissions to a role.

role assignment. The process of assigning a role to auser, such that the user has the appropriate accesspermissions for the object defined for that role.

root container object. The top-level container object inthe hierarchy or resource objects.

root domain. Name servers that have authoritativecontrol of all the top-level domains.

routing file. An ASCII file that contains commandsthat control the configuration of messages.

routing table. A collection of path informationthrough which hosts or networks can communicatewith each other.

RSA. A public-key encryption technology that wasdeveloped by RSA Data Security, Inc., and used byGSKit. The acronym stands for Rivest, Shamir, andAdleman, the inventors of this encryption technique.

RSA encryption. A system for public-keycryptography used for encryption and authentication.The security of the system depends on the difficulty offactoring the product of two large prime numbers.

rule. A set of logical statements that enable a server torecognize relationships among events and to performautomated responses accordingly.

rules evaluator. The component responsible forevaluating an authorization rule.

run time. The time period during which a computerprogram is running.

runtime environment. A subset of an applicationdevelopment kit (ADK) that contains the executablefiles and other supporting files that comprise theoperational environment of the platform.

Sscalability. The ability of hardware, software, or adistributed system to maintain performance levels as itincreases in size and increases in the number of userswho access resources.

schema. The set of statements, expressed in a datadefinition language, that completely describes thestructure of data that is stored in a database, directory,or file.

Secure Sockets Layer (SSL). A security protocol thatprovides communication privacy. SSL enablesclient/server applications to communicate in a way thatis designed to prevent eavesdropping, tampering, andmessage forgery.

security context. The digitally signed token thatidentifies a principal, lists the roles and access rightsfor the principal, and contains information about whenthe token expires.

security management. The software discipline thataddresses how an organization can control access tomission critical applications and data.

security policy. (1) A written document that definesthe security controls that you institute for yourcomputer systems. A security policy describes the risksthat you intend to minimize and the actions thatshould be taken if someone breaches your securitycontrols. (2) In Tivoli Access Manager, the combinationof ACL policies, authorization rules, and protectedobject policies attached to objects to make themprotected objects. See also ACL policy, authorizationrule, and protected object policy.

self-registration. The process by which a user canenter required data and become a registered userwithout the involvement of an administrator.

service. Work performed by a server. A service can bea simple request for data to be sent or stored (as withfile servers, HTTP servers, or e-mail servers), or it canbe for more complex requests (as with print servers orprocess servers). See also daemon.

session. A series of requests to a server or applicationthat originate from the same user at the same browser.

silent installation. An installation that does not sendmessages to the console but instead stores messagesand errors in log files. Also, a silent installation can useresponse files for data input. See also response file.

single sign-on (SSO). The mechanism that allows auser to logon once and access multiple applicationsthrough a single authorization challenge. Using SSO, auser does not need to log on to each applicationseparately. See also global sign-on.

SSL. See Secure Socket Layer.

SSO. See single sign-on.

stanza. A group of lines in an ASCII file that togetherhave a common function or define a part of a system.Stanzas are usually separated by blank lines or colons,and each stanza has a name.

stash file. The local copy of the master key file thatresides in an encrypted format on the local disk.

step-up authentication. A protected object policy(POP) that relies on a preconfigured hierarchy ofauthentication levels and enforces a specific level ofauthentication according to the policy set on a resource.The step-up authentication POP does not force the userto authenticate using multiple levels of authenticationto access any given resource, but it requires the user to


authenticate at a level at least as high as that requiredby the policy protecting a resource. See also protectedobject policy.

suffix. A distinguished name that identifies the topentry in a locally held directory hierarchy. Because ofthe relative naming scheme used in LightweightDirectory Access Protocol (LDAP), this suffix applies toevery other entry within that directory hierarchy. Adirectory server can have multiple suffixes, eachidentifying a locally held directory hierarchy.

Tticket. See Kerberos ticket.

token. A sequence of bits (symbol of authority) that ispassed successively along a transmission medium fromone device to another to indicate the device that istemporarily in control of the transmission medium.Each device can acquire and use the token to controlthe medium.

trusted root. In the Secure Sockets Layer (SSL), thepublic key and associated distinguished name of acertificate authority (CA). See also Secure Socket Layer.

Uuniform resource identifier (URI). The characterstring used to identify an abstract or physical resourceon the Internet. A URI typically describes how to accessthe resource, the computer that contains the resource,and the name of the resource. The most common formof URI is the Web page address, which is a particularsubset or URI called uniform resource locator (URL).See also uniform resource locator.

uniform resource locator (URL). A character stringthat represent resources on a computer or in a network,such as the Internet. The URL includes the abbreviatedname of the protocol used to access the informationresource and the information used by the protocol tolocate the resource.

URI. See uniform resource identifier.

URL. See uniform resource locator.

user. Any person, organization, process, device,program, protocol, or system that uses a serviceprovided by others.

user registry. See registry.

Vvirtual hosting. The capability of a Web server thatallows it to appear as more than one host to theInternet.

WWeb Portal Manager (WPM). A Web-based graphicalapplication used to manage Tivoli Access Managersecurity policy in a secure domain. An alternative tothe pdadmin command line interface, this GUI enablesremote administrator access and enables administratorsto create delegated user domains and assign delegateadministrators to these domains.

Web resource. Any one of the resources that arecreated during the development of a Web application;for example, Web projects, HTML pages, JSP files,servlets, custom tag libraries, and archive files.

WebSEAL. A high performance, multi-threaded Webserver that applies a security policy to a protectedobject space. WebSEAL can provide single sign-onsolutions and incorporate back-end Web applicationserver resources into its security policy.

Web session. See session.

WPM. See Web Portal Manager.

XXML. See Extensible Markup Language.

XML transform. A standard that uses XSL stylesheetsto transform XML documents into other XMLdocuments or fragments or to transform XMLdocuments into HTML documents.

XSL. See Extensible Stylesheet Language.

XSL stylesheet. Code that describes how an XMLdocument should be rendered (displayed or printed).

XSLT. See Extensible Stylesheet LanguageTransformation.

Glossary 113

Index

Aaccessibility ixadministration

session management server 1architecture

session management server 4auditing

configuration files 20authentication 11

credential refresh 32authorization 11, 12

configuring 11server 6

Bbooks

see publications v, viii

Ccertificates 10

configuring 9client idle timeout 20cluster 4

name 20command line extensions

configuring 23considerations 23

commandscommon tasks 27key change 30key show 30policy get 28policy set 28realm list 29realm show 29replica set list 29replica set show 29server commands 49sms session list 27sms terminate all_sessions 28sms terminate session 28

common problemsreporting

describing problem 98determining business impact 97gathering information 98

submitting problems 98configuration utility

running 23configure

smscfg utility 87configuring 23

authorization 11certificates 9instances 24Plug-in for Web Servers 14secure communications 10session management server 17, 19, 20

configuring (continued)SSL 9WebSEAL 14

consistency 3conventions

typeface xcredential refresh

setting rules 32customer support

contacting 97obtaining fixes 95receiving updates from 96registering with 96searching information centers 95searching knowledge bases 95searching the Internet 95submitting problems 98

Ddata storage type 20deploying

considerations 6ISC 18session management server 18, 24

directory names, notation xidomain

cookies 14

Eeducation

see Tivoli technical training ixenvironment variables, notation xiExternal Authentication Interface (EAI) 14

Ffailover 3features

session management server 2fixes, obtaining 95fixpacks

installing 18

GGSKit ikeyman 9

Iinformation centers, searching 95installing

fixpacks 18session management server 17

instancelisting 52setting 51


instancesconfiguring 24multiple 3

interactiveconfiguration 19

interface 11Internet, searching 95introduction

session management server 1ISC

deploying 24

JJ2EE 9, 11

Kkey change command 30key lifetime

configuration 20key show command 30keys

creating, session management server 54displaying details, session management server 56generating, new 30managing 30

knowledge basesinformation centers 95searching 95the Internet 95

Llast login

parameters 20last login activity database

creating 32overview 31schema 31security data 31

LDAP 11, 13Lightweight Third Party Authentication (LTPA) 11limit

session realms 4list

servers 53logging 3

Mmanaging

realms and replica sets 29manuals

see publications v, viii

Nnotation

environment variables xipath names xitypeface xi

Oonline publications

accessing viiiordering publications ix

Ppath names, notation xipdadmin 6, 23

commands 49pdsmsadmin 6, 12

commands 49configuring 23

pdsmsclicfg-action config 23-action unconfig 24configure 82

Plug-in for Web Servers 4configuring 14

policy enforcement 3policy get command 28policy set command 28publications v

accessing online viiiordering ix

Rrealm list command 29realm show command 29realms 4

displaying details, session management server 60limiting 4listing, session management server 58replica sets

managing 29replica set 4replica set list command 29replica set show command 29replica sets

displaying 29displaying details, session management server 68listing 29listing, session management server 66monitoring activity 29

rspfileresponse file 19

Ssecurity 12

configuring 9considerations 9

server commandsinstances list 52login 50server list 53server task sms key change 54server task sms key show 56server task sms realm list 58server task sms realm show 60server task sms refresh all_sessions 62server task sms refresh session 64server task sms replica set list 66server task sms replica set show 68


server commands (continued)server task sms session list 70server task sms trace get 76server task sms trace set 78server task terminate all_sessions 72server task terminate session 74set instance 51

server list command 53server task commands

instances list 52login 50refresh session 64set instance 51terminate all_sessions 72terminate session 74trace get 76trace set 78

server task session commandsrefresh all sessions 62

server task sms key commandchange 54show 56

server task sms realm commandlist 58show 60

server task sms replica commandset list 66set show 68

server task sms session commandlist 70

session management serveradministration

options 1architecture 4configuring 17

requirements 20smscfg 19

creating keys 54deploying 18

additional instances 24displaying details, keys 56displaying details, replica sets 68displaying replica sets in realms 60features 2installing

overview 17introduction 1listing realms 58listing replica sets 66listing sessions 70refreshing credentials 62, 64single sign-on (SSO) 14unconfiguring 24

session realmslisting replica sets

displaying 29monitoring activity 29

sessionsconcurrent

getting policy 28setting policy 28

listing, session management server 70user

ending 28searching 27

single sign-on (SSO) 14sms session list command 27

sms terminate all_sessions command 28sms terminate session command 28sms-administrator 12sms-client 11sms-delegate 12smsbackup utility 85smscfg

-action config 24-action deploy

ISC 18-action unconfig 24configuration utilty

running 23smscfg utility 87smsservicelevel utility 94software updates, receiving 96SSL 9, 10

considerations 23statistics 3, 30support

See customer supportsvrsslcfg 9syntax, reading 49

TTivoli Access Manager

integration 23enabling 20

Plug-in for Web Servers 4WebSEAL 4WebSphere 4

Tivoli Common Directory (TCD)logging 20

Tivoli Information Center viiiTivoli Performance Viewer 30Tivoli technical training ixTivoli user groups xtrace level

displaying 76setting 78

training, Tivoli technical ixTrust Association Interceptor (TAI) 9typeface conventions x

Uunconfiguring

session management server 24user groups, Tivoli xuser sessions

terminating 74terminating all 72

utilitiespdsmsclicfg 82smsbackup 85smscfg 87smsservicelevel 94

Vvariables, notation for xi

Index 117

WWebSEAL 4

configuring 14WebSphere 4, 9, 10, 13

performance pages 30


��

Printed in USA

SC23-6509-01

am611 sms admin

Documents