ibm securityaccess manager forweb version 7 · v ibm security access manager for web installation...

IBM Security Access Manager for WebVersion 7.0

Command Reference

SC23-6512-02

��

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

Edition notice

Note: This edition applies to version 7, release 0, modification 0 of IBM Security Access Manager (productnumber 5724-C87) and to all subsequent releases and modifications until otherwise indicated in new editions.

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

Contents

Tables . . . . . . . . . . . . . . . vii

About this publication . . . . . . . . ixIntended audience . . . . . . . . . . . . ixAccess to publications and terminology . . . . . ix

Related publications . . . . . . . . . . xiiAccessibility . . . . . . . . . . . . . . xiiiTechnical training . . . . . . . . . . . . xivSupport information . . . . . . . . . . . xiv

Chapter 1. pdadmin commands . . . . 1How to read syntax statements . . . . . . . . 1Syntax for pdadmin commands . . . . . . . . 1Command modes. . . . . . . . . . . . . 3

Single command mode . . . . . . . . . . 4Interactive command mode . . . . . . . . 4Multiple command mode . . . . . . . . . 5

Non-English locales . . . . . . . . . . . . 6Error handling. . . . . . . . . . . . . . 6

Return codes for a single command. . . . . . 7Return codes for an interactive command. . . . 7Return codes for multiple commands . . . . . 7

Local or other domain . . . . . . . . . . . 8Command option processing . . . . . . . . . 9Commands by category. . . . . . . . . . . 9

Access control list commands . . . . . . . 10Action commands . . . . . . . . . . . 10Authorization rule commands . . . . . . . 11Configuration commands . . . . . . . . . 11Context commands . . . . . . . . . . . 12Domain commands . . . . . . . . . . . 12Group commands . . . . . . . . . . . 12Login and logout commands . . . . . . . 13Object commands . . . . . . . . . . . 13Object space commands . . . . . . . . . 14Policy commands . . . . . . . . . . . 14Protected object policy commands . . . . . . 15Resource and resource group commands . . . 15Server commands . . . . . . . . . . . 16Session Management Server commands . . . . 17User commands . . . . . . . . . . . . 18WebSEAL commands . . . . . . . . . . 19

acl attach . . . . . . . . . . . . . . . 21acl create . . . . . . . . . . . . . . . 22acl delete . . . . . . . . . . . . . . . 23acl detach . . . . . . . . . . . . . . . 24acl find . . . . . . . . . . . . . . . . 25acl list . . . . . . . . . . . . . . . . 26acl modify . . . . . . . . . . . . . . . 26acl show . . . . . . . . . . . . . . . 30action create . . . . . . . . . . . . . . 31action delete . . . . . . . . . . . . . . 33action group create . . . . . . . . . . . . 34action group delete . . . . . . . . . . . . 34action group list . . . . . . . . . . . . . 35

action list . . . . . . . . . . . . . . . 35admin show conf . . . . . . . . . . . . 36authzrule attach . . . . . . . . . . . . . 37authzrule create . . . . . . . . . . . . . 38authzrule delete . . . . . . . . . . . . . 39authzrule detach. . . . . . . . . . . . . 40authzrule find . . . . . . . . . . . . . 40authzrule list . . . . . . . . . . . . . . 41authzrule modify . . . . . . . . . . . . 42authzrule show . . . . . . . . . . . . . 43config modify . . . . . . . . . . . . . 44config show . . . . . . . . . . . . . . 46context show . . . . . . . . . . . . . . 48domain create . . . . . . . . . . . . . 49domain delete . . . . . . . . . . . . . 51domain list . . . . . . . . . . . . . . 52domain modify . . . . . . . . . . . . . 53domain show. . . . . . . . . . . . . . 54errtext . . . . . . . . . . . . . . . . 54exit or quit . . . . . . . . . . . . . . 55group create . . . . . . . . . . . . . . 56group delete . . . . . . . . . . . . . . 57group import . . . . . . . . . . . . . . 58group list . . . . . . . . . . . . . . . 59group modify. . . . . . . . . . . . . . 61group show . . . . . . . . . . . . . . 62help . . . . . . . . . . . . . . . . . 63login . . . . . . . . . . . . . . . . 65logout . . . . . . . . . . . . . . . . 67object access . . . . . . . . . . . . . . 68object create . . . . . . . . . . . . . . 69object delete . . . . . . . . . . . . . . 71object exists . . . . . . . . . . . . . . 72object list . . . . . . . . . . . . . . . 73object listandshow . . . . . . . . . . . . 74object modify . . . . . . . . . . . . . . 75object show . . . . . . . . . . . . . . 77objectspace create . . . . . . . . . . . . 81objectspace delete . . . . . . . . . . . . 82objectspace list . . . . . . . . . . . . . 83policy get . . . . . . . . . . . . . . . 83policy set . . . . . . . . . . . . . . . 86pop attach . . . . . . . . . . . . . . . 90pop create . . . . . . . . . . . . . . . 91pop delete . . . . . . . . . . . . . . . 92pop detach . . . . . . . . . . . . . . 92pop find . . . . . . . . . . . . . . . 93pop list . . . . . . . . . . . . . . . . 94pop modify . . . . . . . . . . . . . . 95pop show . . . . . . . . . . . . . . . 98rsrc create . . . . . . . . . . . . . . . 99rsrc delete . . . . . . . . . . . . . . 100rsrc list . . . . . . . . . . . . . . . 101rsrc show. . . . . . . . . . . . . . . 102rsrccred create . . . . . . . . . . . . . 102rsrccred delete . . . . . . . . . . . . . 104

© Copyright IBM Corp. 2001, 2012 iii

rsrccred list user . . . . . . . . . . . . 105rsrccred modify . . . . . . . . . . . . 106rsrccred show . . . . . . . . . . . . . 107rsrcgroup create . . . . . . . . . . . . 108rsrcgroup delete . . . . . . . . . . . . 109rsrcgroup list . . . . . . . . . . . . . 110rsrcgroup modify . . . . . . . . . . . . 110rsrcgroup show. . . . . . . . . . . . . 112server list. . . . . . . . . . . . . . . 112server listtasks . . . . . . . . . . . . . 113server replicate . . . . . . . . . . . . . 115server show . . . . . . . . . . . . . . 116server task add . . . . . . . . . . . . . 117server task cache flush all . . . . . . . . . 120server task create . . . . . . . . . . . . 121server task delete . . . . . . . . . . . . 128server task dynurl update . . . . . . . . . 130server task help . . . . . . . . . . . . 131server task jmt . . . . . . . . . . . . . 133server task list . . . . . . . . . . . . . 134server task offline . . . . . . . . . . . . 135server task online . . . . . . . . . . . . 137server task refresh all_sessions . . . . . . . 139server task reload . . . . . . . . . . . . 140server task remove . . . . . . . . . . . 141server task show . . . . . . . . . . . . 143server task sms key change. . . . . . . . . 144server task sms key show . . . . . . . . . 145server task sms realm list . . . . . . . . . 146server task sms realm show . . . . . . . . 147server task sms session refresh all_sessions . . . 148server task sms session refresh session . . . . . 150server task sms replica set list . . . . . . . . 151server task sms replica set show . . . . . . . 152server task sms session list . . . . . . . . . 153server task sms session terminate all_sessions . . 154server task sms session terminate session . . . . 156server task sms trace get . . . . . . . . . 157server task sms trace set . . . . . . . . . . 158server task stats . . . . . . . . . . . . 159server task terminate all_sessions . . . . . . . 162server task terminate session . . . . . . . . 163server task throttle . . . . . . . . . . . 164server task trace . . . . . . . . . . . . 166server task virtualhost add . . . . . . . . . 168server task virtualhost create . . . . . . . . 171server task virtualhost delete . . . . . . . . 177server task virtualhost list . . . . . . . . . 179server task virtualhost offline . . . . . . . . 180server task virtualhost online . . . . . . . . 182server task virtualhost remove. . . . . . . . 184server task virtualhost show . . . . . . . . 186server task virtualhost throttle . . . . . . . . 188server task server restart . . . . . . . . . 190server task server sync . . . . . . . . . . 191server task jdb export . . . . . . . . . . 192server task jdb import . . . . . . . . . . 193server task cfgdb export . . . . . . . . . . 194server task cfgdb import. . . . . . . . . . 195server task file cat . . . . . . . . . . . . 196user create . . . . . . . . . . . . . . 197

user delete . . . . . . . . . . . . . . 199user import . . . . . . . . . . . . . . 200user list . . . . . . . . . . . . . . . 201user modify . . . . . . . . . . . . . . 203user show . . . . . . . . . . . . . . 205

Chapter 2. Security Access Managerutilities . . . . . . . . . . . . . . 209Installation and configuration utilities . . . . . 209Migration utilities . . . . . . . . . . . . 210WebSEAL utilities . . . . . . . . . . . . 211Session management server utilities . . . . . . 211Security Access Manager plug-in for web serversutilities . . . . . . . . . . . . . . . 211Serviceability and problem determination utilities 212adschema_update . . . . . . . . . . . . 212amauditcfg . . . . . . . . . . . . . . 213amwebcfg . . . . . . . . . . . . . . 217amwpmcfg . . . . . . . . . . . . . . 221bassslcfg . . . . . . . . . . . . . . . 226cdsso_key_gen . . . . . . . . . . . . . 229ivacld_setup. . . . . . . . . . . . . . 230ivacld_uninst . . . . . . . . . . . . . 231ivbase_setup. . . . . . . . . . . . . . 233ivbase_uninst . . . . . . . . . . . . . 236ivmgrd_setup . . . . . . . . . . . . . 237ivmgrd_uninst . . . . . . . . . . . . . 240ivrgy_tool . . . . . . . . . . . . . . 242mgrsslcfg . . . . . . . . . . . . . . . 245PDAcld_config . . . . . . . . . . . . . 247PDAcld_unconfig . . . . . . . . . . . . 250pdadmin_host . . . . . . . . . . . . . 251pd_start . . . . . . . . . . . . . . . 252pdbackup . . . . . . . . . . . . . . 254pdconf . . . . . . . . . . . . . . . 258pdconfig . . . . . . . . . . . . . . . 260pdjrtecfg . . . . . . . . . . . . . . . 261pdjservicelevel . . . . . . . . . . . . . 266PDMgr_config . . . . . . . . . . . . . 267PDMgr_unconfig . . . . . . . . . . . . 270pdproxycfg . . . . . . . . . . . . . . 272PDRTE_config . . . . . . . . . . . . . 275PDRTE_unconfig . . . . . . . . . . . . 278pdservicelevel . . . . . . . . . . . . . 278pdsmsclicfg . . . . . . . . . . . . . . 279pdversion . . . . . . . . . . . . . . 282pdweb. . . . . . . . . . . . . . . . 284pdwebpi . . . . . . . . . . . . . . . 285pdwebpi_start . . . . . . . . . . . . . 286pdwpi-version . . . . . . . . . . . . . 287pdwpicfg . . . . . . . . . . . . . . . 288query_contents . . . . . . . . . . . . . 290smsbackup . . . . . . . . . . . . . . 291smscfg. . . . . . . . . . . . . . . . 293smsservicelevel . . . . . . . . . . . . . 300svrsslcfg . . . . . . . . . . . . . . . 301

Appendix A. Password limitations andcharacters allowed in object names. . 307General password policies . . . . . . . . . 307

iv IBM Security Access Manager for Web Version 7.0: Command Reference

Character limitations for passwords and usernames . . . . . . . . . . . . . . . . 308Characters allowed for secure domain names. . . 308Characters disallowed for user and group name 309Characters disallowed for distinguished names . . 310

Characters disallowed for Microsoft ActiveDirectory distinguished names . . . . . . 310

Characters disallowed for GSO names . . . . . 311Characters disallowed for authorization rule names 311

Characters disallowed for ACL policy names . . . 312Characters disallowed for POP names . . . . . 313

Appendix B. Using response files . . 315

Notices . . . . . . . . . . . . . . 317

Index . . . . . . . . . . . . . . . 321

Contents v

vi IBM Security Access Manager for Web Version 7.0: Command Reference

Tables

1. Access control list (ACL) commands . . . . 102. Action commands . . . . . . . . . . 103. Authorization rule commands . . . . . . 114. Config commands . . . . . . . . . . 125. Context commands . . . . . . . . . . 126. Domain commands . . . . . . . . . . 127. Group commands . . . . . . . . . . 138. Logon commands . . . . . . . . . . 139. Object commands . . . . . . . . . . 13

10. Objectspace commands . . . . . . . . 1411. Policy commands . . . . . . . . . . 1412. Protected object policy (POP) commands 1513. Resource commands . . . . . . . . . 15

14. Server commands . . . . . . . . . . 1615. Server task commands . . . . . . . . . 1716. User commands . . . . . . . . . . . 1817. WebSEAL server task commands . . . . . 1918. Security Access Manager installation and

configuration utilities . . . . . . . . . 20919. Security Access Manager migration utilities 21020. WebSEAL utilities . . . . . . . . . . 21121. Session management server utilities . . . . 21122. Security Access Manager for web servers

utilities. . . . . . . . . . . . . . 21123. Serviceability and problem determination

utilities . . . . . . . . . . . . . 212

© Copyright IBM Corp. 2001, 2012 vii

viii IBM Security Access Manager for Web Version 7.0: Command Reference

About this publication

IBM Security Access Manager for Web, formerly called IBM Tivoli Access Managerfor e-business, is a user authentication, authorization, and web single sign-onsolution for enforcing security policies over a wide range of web and applicationresources.

The IBM Security Access Manager for Web Command Reference provides acomprehensive set of procedures and reference information for managing SecurityAccess Manager servers and resources. This guide also provides you with valuablebackground and conceptual information for the wide range of Security AccessManager functions.

Intended audienceThis guide is for system administrators responsible for the deployment andadministration of base Security Access Manager software.

Readers must be familiar with the following systems and concepts:v Microsoft Windows, AIX®, Linux, and Solaris operating systemsv Database architecture and conceptsv Security managementv Internet protocols, including HTTP and TCP/IPv Lightweight Directory Access Protocol (LDAP) and directory servicesv Authentication and authorizationv Security Access Manager security model and its capabilities

You also must be familiar with SSL protocol, key exchange (public and private),digital signatures, cryptographic algorithms, and certificate authorities.

Access to publications and terminologyThis section provides:v A list of publications in the “IBM Security Access Manager for Web library.”v Links to “Online publications” on page xi.v A link to the “IBM Terminology website” on page xii.

IBM Security Access Manager for Web library

The following documents are in the IBM Security Access Manager for Web library:v IBM Security Access Manager for Web Quick Start Guide, GI11-9333-01

Provides steps that summarize major installation and configuration tasks.v IBM Security Web Gateway Appliance Quick Start Guide – Hardware Offering

Guides users through the process of connecting and completing the initialconfiguration of the WebSEAL Hardware Appliance, SC22-5434-00

v IBM Security Web Gateway Appliance Quick Start Guide – Virtual OfferingGuides users through the process of connecting and completing the initialconfiguration of the WebSEAL Virtual Appliance.

© Copyright IBM Corp. 2001, 2012 ix

v IBM Security Access Manager for Web Installation Guide, GC23-6502-02Explains how to install and configure Security Access Manager.

v IBM Security Access Manager for Web Upgrade Guide, SC23-6503-02Provides information for users to upgrade from version 6.0, or 6.1.x to version7.0.

v IBM Security Access Manager for Web Administration Guide, SC23-6504-02Describes the concepts and procedures for using Security Access Manager.Provides instructions for performing tasks from the Web Portal Managerinterface and by using the pdadmin utility.

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

v IBM Security Access Manager for Web Plug-in for Web Servers Administration Guide,SC23-6507-02Provides procedures and reference information for securing your Web domainby using a Web server plug-in.

v IBM Security Access Manager for Web Shared Session Management AdministrationGuide, SC23-6509-02Provides administrative considerations and operational instructions for thesession management server.

v IBM Security Access Manager for Web Shared Session Management Deployment Guide,SC22-5431-00Provides deployment considerations for the session management server.

v IBM Security Web Gateway Appliance Administration Guide, SC22-5432-00Provides administrative procedures and technical reference information for theWebSEAL Appliance.

v IBM Security Web Gateway Appliance Configuration Guide for Web Reverse Proxy,SC22-5433-00Provides configuration procedures and technical reference information for theWebSEAL Appliance.

v IBM Security Web Gateway Appliance Web Reverse Proxy Stanza Reference,SC27-4442-00Provides a complete stanza reference for the IBM® Security Web GatewayAppliance Web Reverse Proxy.

v IBM Security Access Manager for Web WebSEAL Configuration Stanza Reference,SC27-4443-00Provides a complete stanza reference for WebSEAL.

v IBM Global Security Kit: CapiCmd Users Guide, SC22-5459-00Provides instructions on creating key databases, public-private key pairs, andcertificate requests.

v IBM Security Access Manager for Web Auditing Guide, SC23-6511-02Provides information about configuring and managing audit events by using thenative Security 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 Security Access Manager for Web Command Reference, SC23-6512-02

x IBM Security Access Manager for Web Version 7.0: Command Reference

Provides reference information about the commands, utilities, and scripts thatare provided with Security Access Manager.

v IBM Security Access Manager for Web Administration C API Developer Reference,SC23-6513-02Provides reference information about using the C language implementation ofthe administration API to enable an application to perform Security AccessManager administration tasks.

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

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

v IBM Security Access Manager for Web Authorization Java Classes Developer Reference,SC23-6516-02Provides reference information about using the Java language implementation ofthe authorization API to enable an application to use Security Access Managersecurity.

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

v IBM Security Access Manager for Web Error Message Reference, GI11-8157-02Provides explanations and corrective actions for the messages and return code.

v IBM Security Access Manager for Web Troubleshooting Guide, GC27-2717-01Provides problem determination information.

v IBM Security Access Manager for Web Performance Tuning Guide, SC23-6518-02Provides performance tuning information for an environment that consists ofSecurity Access Manager with the IBM Tivoli Directory Server as the userregistry.

Online publications

IBM posts product publications when the product is released and when thepublications are updated at the following locations:

IBM Security Access Manager for Web Information CenterThe http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.isam.doc_70/welcome.html site displays the information centerwelcome page for this product.

IBM Publications CenterThe http://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wss site offers customized search functions to help you find all the IBMpublications that you need.

About this publication xi

http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.isam.doc_70/welcome.html

http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.isam.doc_70/welcome.html

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

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

IBM Terminology website

The IBM Terminology website consolidates terminology for product libraries in onelocation. You can access the Terminology website at http://www.ibm.com/software/globalization/terminology.

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

Note: The following middleware products are not packaged with IBM SecurityWeb Gateway Appliance.

IBM Global Security Kit

Security Access Manager provides data encryption by using Global Security Kit(GSKit) version 8.0.x. GSKit is included on the IBM Security Access Manager for WebVersion 7.0 product image or DVD for your particular platform.

GSKit version 8 includes the command-line tool for key management,GSKCapiCmd (gsk8capicmd_64).

GSKit version 8 no longer includes the key management utility, iKeyman(gskikm.jar). iKeyman is packaged with IBM Java version 6 or later and is now apure Java application with no dependency on the native GSKit runtime. Do notmove or remove the bundled java/jre/lib/gskikm.jar library.

The IBM Developer Kit and Runtime Environment, Java Technology Edition, Version 6and 7, iKeyman User's Guide for version 8.0 is available on the Security AccessManager Information Center. You can also find this document directly at:

http://download.boulder.ibm.com/ibmdl/pub/software/dw/jdk/security/60/iKeyman.8.User.Guide.pdf

Note:

GSKit version 8 includes important changes made to the implementation ofTransport Layer Security required to remediate security issues.

The GSKit version 8 changes comply with the Internet Engineering Task Force(IETF) Request for Comments (RFC) requirements. However, it is not compatiblewith earlier versions of GSKit. Any component that communicates with SecurityAccess Manager that uses GSKit must be upgraded to use GSKit version 7.0.4.42,or 8.0.14.26 or later. Otherwise, communication problems might occur.

IBM Tivoli Directory Server

IBM Tivoli Directory Server version 6.3 FP17 (6.3.0.17-ISS-ITDS-FP0017) is includedon the IBM Security Access Manager for Web Version 7.0 product image or DVD foryour particular platform.

You can find more information about Tivoli Directory Server at:

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

xii IBM Security Access Manager for Web Version 7.0: Command Reference

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

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



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

IBM Tivoli Directory Integrator

IBM Tivoli Directory Integrator version 7.1.1 is included on the IBM Tivoli DirectoryIntegrator Identity Edition V 7.1.1 for Multiplatform product image or DVD for yourparticular platform.

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

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

IBM DB2 Universal Database™

IBM DB2 Universal Database Enterprise Server Edition, version 9.7 FP4 is providedon the IBM Security Access Manager for Web Version 7.0 product image or DVD foryour particular platform. You can install DB2® with the Tivoli Directory Serversoftware, or as a stand-alone product. DB2 is required when you use TivoliDirectory Server or z/OS® LDAP servers as the user registry for Security AccessManager. For z/OS LDAP servers, you must separately purchase DB2.

You can find more information about DB2 at:

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

IBM WebSphere® products

The installation packages for WebSphere Application Server Network Deployment,version 8.0, and WebSphere eXtreme Scale, version 8.5.0.1, are included withSecurity Access Manager version 7.0. WebSphere eXtreme Scale is required onlywhen you use the Session Management Server (SMS) component.

WebSphere Application Server enables the support of the following applications:v Web Portal Manager interface, which administers Security 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 more information about WebSphere Application Server at:

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

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 for more information about IBM's commitmentto accessibility.

About this publication xiii

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

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

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

http://www-03.ibm.com/able/

Technical trainingFor technical training information, see the following IBM Education website athttp://www.ibm.com/software/tivoli/education.

Support informationIBM Support provides assistance with code-related problems and routine, shortduration installation or usage questions. You can directly access the IBM SoftwareSupport site at http://www.ibm.com/software/support/probsub.html.

The IBM Security Access Manager for Web Troubleshooting Guide provides detailsabout:v What information to collect before you contact IBM Support.v The various methods for contacting IBM Support.v How to use IBM Support Assistant.v Instructions and problem-determination resources to isolate and fix the problem

yourself.

Note: The Community and Support tab on the product information center canprovide more support resources.

xiv IBM Security Access Manager for Web Version 7.0: Command Reference

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

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

Chapter 1. pdadmin commands

The pdadmin command-line utility is installed as part of the IBM Security AccessManager runtime package.

Use this interface to manage access control lists, groups, servers, users, objects, andother resources in your secure domain. You can also automate certain managementfunctions by writing scripts that use pdadmin commands.

Use the Web Portal Manager interface, as discussed in the IBM Security AccessManager for Web Administration Guide, to complete remotely similar administrativetasks. When you use Web Portal Manager, no special network configuration isneeded to connect and complete these management tasks.

You can complete many of these tasks by using either:v Administration C API functions: See the IBM Security Access Manager for Web

Administration C API Developer Reference.v Administration Java class functions: See the IBM Security Access Manager for Web

Administration Java Classes Developer Reference.

How to read syntax statementsSyntax diagrams pictorially display the order and parameters for the commandutility.

The reference documentation uses the following special characters to define syntax:

[ ] Identifies optional options. Options that are not enclosed in brackets arerequired.

... 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 are listed alphabetically in the Options section. Theoptions for each utility are listed alphabetically in the Parameters section. Whenthe order of the options or parameters must be used in a specific order, this orderis shown in the syntax statements.

Syntax for pdadmin commandsThe following syntax is used with the pdadmin command:

pdadmin [–I configuration-instance-name] [[–a admin_id [–p password] [–d domain]][–linelen max-linelen] [–histsize history size] [–v] [command]

© Copyright IBM Corp. 2001, 2012 1

pdadmin [–I configuration-instance-name] [[–a admin_id [–p password] [–d domain]][–linelen max-linelen] [–v] [file]

pdadmin [–I configuration-instance-name] [[–a admin_id [–p password] [–m]][–linelen max-linelen] [–v] [command]

pdadmin [–I configuration-instance-name] [[–a admin_id [–p password] [–m]][–linelen max-linelen] [–v] [file]

pdadmin [–l] [–linelen max-linelen] [–v] [command]

pdadmin [–l] [–linelen max-linelen] [–v] [file]

The following list explains the options for the pdadmin utility:

commandSpecifies the single pdadmin command to run. The command is run onetime. The pdadmin utility does not enter interactive mode. The commandoption is mutually exclusive with the file option.

file Specifies the fully qualified name of the file that contains a list ofcommands to run. These commands are run one time. The pdadmin utilitydoes not enter interactive mode. The file option is mutually exclusivewith the command option.

Note: For Windows operating systems, file names cannot contain thebackward slash (\), colon (:), question mark (?), or double quotation markcharacters.

–a admin_idLogs you in as the user admin_id. This administrator must exist in thedomain. If you do not specify this option on the command line, you areconsidered unauthenticated, and your access to other commands is limited.If you specify this option without specify the –p option, you are promptedfor the password.

The –a option is mutually exclusive with the –l option. If you do notspecify either option, you are logged in as an unauthenticated user.Unauthenticated users can use the context, errtext, exit, help, login,logout and quit commands only.

–d domainSpecifies the Security Access Manager secure domain to log in. Log in tothis domain requires authentication. The admin_id user that is specifiedmust exist in this domain. The –d option is mutually exclusive with the –moption. If neither options are specified, the target domain is the localdomain that is configured for the system.

–I configuration-instance-nameSpecifies the pd.conf file instance that the pdadmin command should use.The configuration-instance-name value is the hostname that is provided tothe pdadmin_host command that generated the configuration file. Thisoption allows pdadmin to communicate with multiple policy servers.

–l Specifies a local login operation. When modifications are made to localconfiguration files by using the pdadmin config commands, a local login isrequired before you can run commands.

2 IBM Security Access Manager for Web Version 7.0: Command Reference

The –l option is mutually exclusive with the –a option. If you do notspecify either option, you are logged in as an unauthenticated user.Unauthenticated users can use the context, errtext, exit, help, login,logout and quit commands only.

–linelen max-linelenCurrently, the –linelen option is ignored.

–m Specifies that the login operation must be directed to the managementdomain. Log in to this domain requires authentication. The admin_id userthat is specified must exist in this domain. The –m option is mutuallyexclusive with the –d option. If neither options are specified, the targetdomain is the local domain that is configured for the system.

–p passwordSpecifies the password for the user admin_id. Using this option might showyour password to others because the password is visible on the screen andalso in the process table. If you do not specify this option on the commandline, you are prompted for a password. This option cannot be used unlessthe –a option is used.

–v Prints the version number of the pdadmin utility. If this option is specified,all other valid options are ignored.

The following example is the output that you might see when you use thisoption:Security Access Manager Administrative Tool v7.0.0.0 (Build 111215)Copyright (C) IBM Corporation 2012. All Rights Reserved.

–histsizeSpecifies the command history size. The default command history size is64. The minimum size of the command history is 1 and the maximum sizeis 1024. The command history option is available only in the interactivemode and on operating systems other than Windows.

Note:

1. If you specify the –a and –p options, you are logged in as that user. Using thismethod might show your password to others. For example, one user is usingpdadmin with this command. Another user lists the processes that are running.Then, the full command that includes the password, might be visible to thesecond user.

2. Users can run the pdadmin context show command to view their authenticationinformation.

Command modesYou can use the pdadmin utility in three different command modes: single,interactive, or multiple.

These modes are described in the following sections.v “Single command mode” on page 4v “Interactive command mode” on page 4v “Multiple command mode” on page 5

For details about the command options that are displayed in the followingsections, see “Syntax for pdadmin commands” on page 1.

Chapter 1. pdadmin commands 3

Single command modeIn single command mode, the CLI runs only the specified command, and endsafter it receives the response message for that command.

To run a single pdadmin command, enter one of the following commands:

pdadmin [–a admin_id [–p password] [–d domain]] [–v] [command]

pdadmin [–a admin_id [–p password] [–m]] [–v] [command]

pdadmin [–l] [–v] [command]

For details about the command options, see “Syntax for pdadmin commands” onpage 1.

Interactive command modeInteractive command mode uses an interactive command-line session where, afterthe command starts, you are prompted to enter required information.

To start pdadmin in interactive mode, type the pdadmin command.

This command starts pdadmin without any authentication that is required, whereyour access to other pdadmin commands is limited for unauthenticated users, suchas context, errtext, exit, help, login, logout, and quit.c:\> pdadmin

pdadmin> limited_pdadmin_command

This command starts pdadmin and login authentication is required before you canuse other pdadmin commands. You can be prompted for both the administrator IDand the password:c:\> pdadmin

pdadmin> loginEnter User ID:sec_masterEnter Password: secmstrpw

pdadmin sec_master> pdadmin_command

Or, you can be prompted for just the administrator password:c:\> pdadmin

pdadmin> login -a sec_masterEnter Password: secmstrpw


Or, you can bypass being prompted, which is less secure because your password isvisible:c:\> pdadmin

pdadmin> login -a sec_master -p secmstrpw



To start pdadmin in interactive mode with a login for issuing local configurationcommands, use the local login (pdadmin login –l) command. You can use theconfig show or the config modify commands through the local login. For example:pdadmin login –l

pdadmin local> config_command

To start pdadmin in interactive mode:v With a login to a management or other domain.v Where the ID and password are authenticated before access is permitted.v Where user privileges are verified before users can issue commands.

For example, to log in to the management domain (Default) and authenticate,type:pdadmin login -a admin_id -p password -m

pdadmin sec_master@Default> pdadmin_command

For example, to log in to another domain domain01 and authenticate, type:rpdadmin login -a sec_master -p secmstrpw -d domain01

pdadmin sec_master@domain01> pdadmin_command

At the pdadmin prompt, type the appropriate commands and their associatedoptions. The pdadmin prompt changes, depending on the type of login. See “Loginand logout commands” on page 13 for more information about the logincommand and prompt changes.

Note: In this release, the length of a command line that is used in pdadmininteractive mode is limited to 1023 characters.

Multiple command modeWith multiple command mode, you can create a file that contains multiple pdadmincommands, one per line, that together complete a task or series of tasks.

Login commands can be included in the command file to switch between local andremote login, as needed. Login commands can be included in a command file toswitch between local and remote login, as needed.

To run commands in this file, provide one of the following commands:

pdadmin [–a admin_id [–p password] [–d domain]] file

pdadmin [–a admin_id [–p password] [–m]] file

Login commands can be included in a command file to switch between pdadminlogin –l local login:v Where no authentication is required.v Where authentication is required.

For details about the command options that are displayed in the followingsections, see “Syntax for pdadmin commands” on page 1.


Non-English localesFor Security Access Manager software, you can specify localized behavior bysetting the required locale.

Different operating systems often encode text in different ways. For example,Windows operating systems use SJIS (code page 932) for Japanese text while AIX,Linux, and Solaris operating systems often use eucJP.

The installation guide contains complete information about code pages andglobalization. However, be aware of the following issues when you are running thepdadmin utility in a non-English locale.v On Windows operating systems, you can enter commands to pdadmin through a

command file argument. The command file must be encoded in the system'slocal (ANSI) code page. For example:C:> pdadmin -a sec_master -p password cmds.text

You can determine the local code page of the system by viewing the value of theNls/CodePage/ACP key in the Windows registry. Files that are created bystandard Windows editing tools (such as Notepad or WordPad) are encoded inthis way.On AIX, Linux, and Solaris operating systems, you must run the pdadmincommand in the same locale that was used to create the command file.

v On Windows operating systems, you can enter commands to pdadmin byredirecting a command file. The command file must be encoded in a MicrosoftOriginal Equipment Manufacturer (OEM) code page. The OEM code pagecorresponds to the active code page in the command window in which thepdadmin command is run. For example:C:> pdadmin -a sec_master -p password < cmds.text

The active code page can be determined by issuing the chcp command in thepdadmin command window.Alternatively, you can redirect a file that is encoded in the local code page of thesystem. However, you must change the active code page of the commandwindow to correspond to the encoding of the file. Change the active code pageof the window by using the chcp command. For example, entering the commandchcp 1252 changes the active code page to the ANSI code page for WesternEurope and the United States.On AIX, Linux, and Solaris operating systems, you must run the pdadmincommand in the same locale that was used to create the redirected commandfile.

v Security Access Manager data that is created in one locale might not displaycorrectly on a system that is configured to another locale. Whether data displayscorrectly depends on the configuration of the second system. For example,correct display depends on what the current locale is, and whether the necessarycode pages and fonts are installed.

Error handlingAfter a command finishes processing, a return code is displayed or logged toprovide the success or failure of the command.

The pdadmin command has the following return code values:

0 The command that completed successfully.


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

See the IBM Security Access Manager for Web Error Message Reference. Thisreference provides a list of the Security Access Manager error messages bydecimal or hexadecimal codes.

For information about how to use the message number that is associated with amessage to display only the descriptive text, see “errtext” on page 54.

Return codes for a single commandA single command is normally typed from a command prompt such as a DOScommand prompt, Korn shell prompt, and C shell prompt. Single command modedoes not automatically display the 0 or 1 return code values; the operating systemmust be queried for the return code value.

For command failures, the hexadecimal error code status with its associated errormessage is shown in addition to the error message ID (for example, HPDMG0754W).You can redirect the error that is normally displayed on the screen out to a textfile. When a single command fails, you see an error message that is like the onedisplayed:C:> pdadmin -a admin_id -p password user show oogle

Could not perform the administration request.Error: HPDMG0754WThe entry was not found. If ...(status 0x14c012f2)

To display the 0 or 1 return code values, you must type the pdadmin command,followed by either the AIX, Linux, or Solaris echo or the Windows errorlevelcommand:v For AIX, Linux, and Solaris operating systems:

# pdadmin_command# echo $?

v For Windows operating systems:C:>pdadmin_commandC:>echo %errorlevel%

Return codes for an interactive commandInteractive command mode does not automatically display the 0 or 1 return codevalues. Also, you cannot follow an interactive command with the AIX, Linux, andSolaris echo or the Windows errorlevel command.

For a command failure, you see a message that is like:pdadmin sec_master> user show oogle


Only the hexadecimal exit status code is displayed.

Return codes for multiple commandsYou can use a text file containing pdadmin commands to run those commands in asingle pdadmin invocation.


Consider that an error occurs for a command while the commands run in multiplecommand mode. Then, an error message for the failed command is provided.

Processing of the remaining commands in the file continues after an error. At theend of multiple command processing, a final status is provided. The final statuscode at the termination of multiple command processing is only for the lastcommand that was attempted. For example, if the last command was successful,the final status is 0. If the last command failed, the final status is 1.

For example, a text file might contain these pdadmin commands:user show cwrightuser show oogle

To run the commands, run the following command:pdadmin –a admin_id -p password cmd_filename

The command file would produce results like:cmd> user show cwright

Login ID: cwrightLDAP DN: cn=Claude Wright,ou=Dallas,o=Tivoli,c=usLDAP CN: Claude WrightLDAP SN: WrightDescription:Is SecUser: yesIs GSO user: noAccount valid: yesPassword valid: yesAuthorization mechanism: Default:LDAP

cmd:> user show oogle


Local or other domainUse the pdadmin command to authenticate your user ID and password. You mustauthenticate before you log in to the local domain or to a domain other than thelocal domain.

To authenticate and log in to your local domain, in interactive mode, enter:pdadmin> login -a dlucas -p lucaspwd

pdadmin dlucas>

In the example, user_name logs you in as the authenticated user dlucas to yourown local domain.

To authenticate and log in to a domain with a name that is different from the localdomain, enter:pdadmin> login -a dlucas -p lucaspwd -d domain_a

pdadmin dlucas@domain_a>

In the example, user_name logs you in as the authenticated user dlucas. domain_a isthe domain_name to which you are logging on, in interactive mode.


Command option processingSome pdadmin command options use specific symbols or characters.

Some pdadmin command options begin with a hyphen (-). For example, thefollowing command uses the –gsouser option:pdadmin sec_master> user import –gsouser mlucaser cn=mlucaser,o=Tivoli,c=US

The pdadmin command interprets any token beginning with a hyphen as acommand option, even if the hyphen is placed within double quotation marks.

Occasionally, you might want a token that begins with a – to be interpreted as anargument rather than as a command option. For example, you might want to namethe user –mlucaser or "–mlucaser" by entering:pdadmin sec_master> user import –gsouser –mlucaser cn=mlucaser,o=tivoli,c=us

In this example, the first –gsouser option in the command is still processed.However, because the user name token begins with a hyphen, the user namewould be interpreted as a command option. The command would fail because the—mlucaser command option does not exist.

Specify the single hyphen character to turn off the interpretation of the optionalarguments, by the pdadmin command. Following the single hyphen character,–mlucaser is now interpreted as the user name.

For example:pdadmin sec_master> user import –gsouser – –mlucaser cn=mlucaser,o=Tivoli,c=us

Options on the command line are position-independent. You can change the orderso that all tokens that begin with a hyphen, which are not command options,follow the single hyphen character.

Commands by categoryThe pdadmin commands are listed here by major category.

This section lists the pdadmin commands by the following categories:v “Access control list commands” on page 10v “Action commands” on page 10v “Authorization rule commands” on page 11v “Configuration commands” on page 11v “Context commands” on page 12v “Domain commands” on page 12v “Group commands” on page 12v “Login and logout commands” on page 13v “Object commands” on page 13v “Object space commands” on page 14v “Policy commands” on page 14v “Protected object policy commands” on page 15v “Resource and resource group commands” on page 15v “Server commands” on page 16v “Session Management Server commands” on page 17


v “User commands” on page 18v “WebSEAL commands” on page 19

Access control list commandsUse acl commands to manage access control list (ACL) policies and extendedattributes.

Table 1 lists acl commands.

Table 1. Access control list (ACL) commands

Command Description Page

“acl attach” on page 21 Attaches an ACL policy to a protected object. Ifthe protected object already has an ACLattached, the ACL is replaced with a new one.

“acl attach”on page 21

“acl create” on page 22 Creates an ACL policy in the ACL database. Thiscommand does not create ACL entries.

“acl create” onpage 22

“acl delete” on page 23 Deletes an ACL policy from the ACL database. “acl delete”on page 23

“acl detach” on page 24 Detaches the current ACL policy from aprotected object. This command does not deletethe ACL policy from the ACL database.

“acl detach”on page 24

“acl find” on page 25 Finds and lists all protected objects that have aspecific ACL policy attached.

“acl find” onpage 25

“acl list” on page 26 Lists the names of all defined ACLs. Also liststhe extended attribute keys that are associatedwith a specific ACL.

“acl list” onpage 26

“acl modify” on page 26 Modifies ACLs, their extended attributes, andassociated values.

“acl modify”on page 26

“acl show” on page 30 Lists the complete set of entries for a specificACL policy. Also lists the values of a specificextended attribute that is associated with anACL policy.

“acl show” onpage 30

Action commandsThe action commands define more authorization actions (permissions) and actiongroups.

Table 2 lists action commands.

Table 2. Action commands


“action create” on page31

Creates and adds an action to an action group. “action create”on page 31

“action delete” on page33

Deletes an action from an action group. “action delete”on page 33

“action group create” onpage 34

Creates an action group. “action groupcreate” onpage 34

“action group delete”on page 34

Deletes an action group. “action groupdelete” onpage 34


Table 2. Action commands (continued)


“action group list” onpage 35

Lists all action groups. “action grouplist” on page35

“action list” on page 35 Lists all defined actions in an action group. “action list”on page 35

Authorization rule commandsThe authzrule commands manage authorization rules.

Table 3 lists authzrule commands.

Table 3. Authorization rule commands


“authzrule attach” onpage 37

Attaches an authorization rule to the specifiedprotected object.

“authzruleattach” onpage 37

“authzrule create” onpage 38

Creates an authorization rule. “authzrulecreate” onpage 38

“authzrule delete” onpage 39

Deletes an authorization rule. “authzruledelete” onpage 39

“authzrule detach” onpage 40

Detaches an authorization rule from thespecified protected object.

“authzruledetach” onpage 40

“authzrule find” onpage 40

Finds and lists all the protected objects that havethe specified authorization rule attached.

“authzrulefind” on page40

“authzrule list” on page41

Lists all the registered authorization rules. “authzrulelist” on page41

“authzrule modify” onpage 42

Modifies an authorization rule. “authzrulemodify” onpage 42

“authzrule show” onpage 43

Shows all the attributes of an authorization rule,including description, rule text, and fail reasoncode.

“authzruleshow” onpage 43

Configuration commandsConfiguration commands modify the local configuration files.

Table 5 on page 12 lists config commands that are configuration databasecommands.


Table 4. Config commands


“config modify” onpage 44

Modifies a stanza entry in a configuration file orsets the password for the server user account.

“configmodify” onpage 44

“config show” on page46

Shows the value that is associated with specifiedstanzas or keys in Security Access Managerserver configuration files or in customized serverconfiguration files.

“config show”on page 46

Context commandsContext commands display the context (authentication) information for the userwho is running the pdadmin utility.

Table 5 lists context commands.

Table 5. Context commands


“context show” on page48

Displays the user ID and domain ID used toestablish the current context.

“contextshow” onpage 48

Domain commandsDomain commands manage Security Access Manager secure domains.

Table 6 lists domain commands.

Table 6. Domain commands


“domain create” onpage 49

Creates a Security Access Manager securedomain.

“domaincreate” onpage 49

“domain delete” onpage 51

Deletes the specified Security Access Managersecure domain, and optionally deletes theinformation about the domain from the userregistry.

“domaindelete” onpage 51

“domain list” on page52

Lists all the domains except for the managementdomain.

“domain list”on page 52

“domain modify” onpage 53

Modifies the description of the specified domain. “domainmodify” onpage 53

“domain show” on page54

Displays the specified attributes of the domain,including name and description.

“domainshow” onpage 54

Group commandsGroup commands manage Security Access Manager groups.

A group is a set of Security Access Manager user accounts that have similarattributes. By using groups, you can use a group name in an access control list


(ACL) instead of listing all users individually. When an LDAP-based user registryis used, group names are not case-sensitive.

Table 7 lists group commands.

Table 7. Group commands


“group create” on page56

Creates a group. “group create”on page 56

“group delete” on page57

Deletes the specified Security Access Managergroup and optionally deletes the informationabout the group from the user registry. ACLentries that are associated with the group arealso deleted.

“group delete”on page 57

“group import” on page58

Imports the information about an existingregistry group to create a Security AccessManager group.

“groupimport” onpage 58

“group list” on page 59 Generates a list of all groups, by group names,whose names match the specified pattern.

“group list”on page 59

“group modify” onpage 61

Changes an existing group by adding adescription, or adding or removing a list ofmembers.

“groupmodify” onpage 61

“group show” on page62

Displays details about a specified group. “group show”on page 62

Login and logout commandsLogin and logout commands are used to log in to, and log out of, a SecurityAccess Manager secure domain.

Table 8 lists login and logout commands.

Table 8. Logon commands


“login” on page 65 Authenticates the user to the Security AccessManager policy server as a given administrativeidentity in a domain.

“login” onpage 65

“logout” on page 67 Discards any authentication credentials that arein effect.

“logout” onpage 67

Object commandsObject commands can protect objects by attaching ACLs or protected object policy(POP).

Table 9 lists objects commands.

Table 9. Object commands


“object access” on page68

Confirms whether a specified access is permittedon the named protected object.

“object access”on page 68

“object create” on page69

Creates a protected object. “object create”on page 69


Table 9. Object commands (continued)


“object delete” on page71

Deletes a protected object. “object delete”on page 71

“object exists” on page72

Confirms whether a protected object is in eitherthe policy database or in an object space that ismanaged by an administration service plug-in.

“object exists”on page 72

“object list” on page 73 Lists any objects that are grouped under thespecified protected object. Also lists all theextended attributes that are associated with thespecified protected object.

“object list”on page 73

“object listandshow” onpage 74

Lists any child objects that are grouped underthe specified protected object and shows allvalues that are associated with each of thoseobjects.

“objectlistandshow”on page 74

“object modify” on page75

Modifies an existing object. “objectmodify” onpage 75

“object show” on page77

Shows all values that are associated with aprotected object.

“object show”on page 77

Object space commandsObject space commands allow the creation of more object spaces that containprotected objects that are used by third-party applications.

Table 10 lists objectspace commands.

Table 10. Objectspace commands


“objectspace create” onpage 81

Creates a protected object space under whichprotected objects can be placed.

“objectspacecreate” onpage 81

“objectspace delete” onpage 82

Deletes an existing protected object space and allassociated protected objects.

“objectspacedelete” onpage 82

“objectspace list” onpage 83

Lists all the existing protected object spaces inthe policy server.

“objectspacelist” on page83

Policy commandsPolicy commands manage user password and account policies.

Table 11 lists policy commands.

Table 11. Policy commands


“policy get” on page 83 Displays the policy for user passwords, accountrules, and conditions. Requires authentication(administrator ID and password) to use thiscommand.

“policy get”on page 83


Table 11. Policy commands (continued)


“policy set” on page 86 Sets the policy for user passwords, account rules,and conditions. Requires authentication(administrator ID and password) to use thiscommand.

“policy set”on page 86

Protected object policy commandsProtected object policy commands allow the creation of a protected object policy(POP) and extended attributes for the protected object policies

Table 12 lists pop commands.

Table 12. Protected object policy (POP) commands


“pop attach” on page 90 Attaches a protected object policy to aspecified protected object.

“pop attach”on page 90

“pop create” on page 91 Creates a protected object policy. “pop create”on page 91

“pop delete” on page 92 Deletes the specified protected object policy. “pop delete”on page 92

“pop detach” on page 92 Detaches a protected object policy from thespecified protected object.

“pop detach”on page 92

“pop find” on page 93 Finds and lists all protected objects withprotected object policies attached.

“pop find”on page 93

“pop list” on page 94 Lists all created protected object policies. “pop list” onpage 94

“pop modify” on page 95 Modifies the protected object policy. “pop modify”on page 95

“pop show” on page 98 Shows details about the protected objectpolicy.

“pop show”on page 98

Resource and resource group commandsResource and resource group commands manage resource-related information.

Table 13 lists rsrc, rsrccred, and rsrcgroup commands.

Table 13. Resource commands


“rsrc create” on page 99 Creates and names a server as a resource. “rsrc create”on page 99

“rsrc delete” on page100

Deletes the specified single sign-on resource. “rsrc delete”on page 100

“rsrc list” on page 101 Returns a list of all the single sign-on resourcenames.

“rsrc list” onpage 101

“rsrc show” on page 102 Displays the resource information for the namedresource.

“rsrc show”on page 102


Table 13. Resource commands (continued)


“rsrccred create” onpage 102

Creates and names a resource credential. “rsrccredcreate” onpage 102

“rsrccred delete” onpage 104

Deletes only the resource credential informationfor an existing user.

“rsrccreddelete” onpage 104

“rsrccred list user” onpage 105

Displays the names of all defined resourcecredentials and their type for the specified user.

“rsrccred listuser” on page105

“rsrccred modify” onpage 106

Changes the user ID and password resourcecredential information for the named resource.

“rsrccredmodify” onpage 106

“rsrccred show” onpage 107

Displays the resource credential information fora specified user.

“rsrccredshow” onpage 107

“rsrcgroup create” onpage 108

Creates and names a resource group. “rsrcgroupcreate” onpage 108

“rsrcgroup delete” onpage 109

Deletes the named resource group, including anydescription information.

“rsrcgroupdelete” onpage 109

“rsrcgroup list” on page110

Displays the names of all resource groups thatare defined in the user registry.

“rsrcgrouplist” on page110

“rsrcgroup modify” onpage 110

Adds or removes a single sign-on resource to orfrom a single sign-on resource group.

“rsrcgroupmodify” onpage 110

“rsrcgroup show” onpage 112

Displays the resource group information for thespecified resource group.

“rsrcgroupshow” onpage 112

Server commandsServer commands perform management tasks on Security Access Manager servers.

Table 14 lists server and server task commands, and the admin show configcommand.

Table 14. Server commands


“admin show conf” onpage 36

Displays current policy server configurationinformation.

“admin showconf” on page36

“server list” on page 112 Lists all registered servers. “server list”on page 112

“server listtasks” on page113

Retrieves the list of tasks (commands)available for this server.

“serverlisttasks” onpage 113


Table 14. Server commands (continued)


“server replicate” on page115

Notifies authorization servers to receivedatabase updates.

“serverreplicate” onpage 115

“server show” on page 116 Displays the specified properties of the server. “servershow” onpage 116

“server task help” on page131

Lists detailed help information about aspecific server task command.

“server taskhelp” onpage 131

“server task stats” on page159

Manages the gathering and reporting ofstatistics for Security Access Manager serversand server instances.

“server taskstats” onpage 159

“server task trace” on page166

Enables the gathering of trace information forcomponents of installed Security AccessManager servers or server instances thatsupport debug event tracing.

“server tasktrace” onpage 166

Session Management Server commandsSession Management Server commands perform session management tasks. Thesecommands are available only when a Web security server and Session ManagementServer are installed.

Table 15 lists server task commands.

Table 15. Server task commands


“server task sms keychange” on page 144

Forces the creation of a new sessionmanagement key.

“server tasksms keychange” onpage 144

“server task sms key show”on page 145

Lists detailed information about the currentsession management key.

“server tasksms keyshow” onpage 145

“server task sms realm list”on page 146

Lists all session management server realms inthe domain.

“server tasksms realmlist” on page146

“server task sms realmshow” on page 147

Lists all session management server realmswithin the specified realm.

“server tasksms realmshow” onpage 147

“server task sms sessionrefresh all_sessions” onpage 148

Refreshes the credential for all sessions for aspecified user.

“server tasksms sessionrefreshall_sessions”on page 148


Table 15. Server task commands (continued)


“server task sms sessionrefresh session” on page150

Refreshes the credential for a session. “server tasksms sessionrefreshsession” onpage 150

“server task sms replica setlist” on page 151

Lists all session management replica sets inthe domain.

“server tasksms replicaset list” onpage 151

“server task sms replica setshow” on page 152

Lists all session management replica sets inthe domain with the time and date eachjoined the realm.

“server tasksms replicaset show” onpage 152

“server task sms sessionlist” on page 153

Lists all session management sessions. “server tasksms sessionlist” on page153

“server task sms sessionterminate all_sessions” onpage 154

Terminates all user sessions for a specific user. “server tasksms sessionterminateall_sessions”on page 154

“server task sms sessionterminate session” on page156

Terminates a specific session. “server tasksms sessionterminatesession” onpage 156

“server task sms trace get”on page 157

Displays the trace level for the sessionmanagement server.

“server tasksms traceget” on page157

“server task sms trace set”on page 158

Sets the trace level for the sessionmanagement server.

“server tasksms trace set”on page 158

User commandsUser commands manage Security Access Manager users.

Table 16 lists user commands.

Table 16. User commands


“user create” on page 197 Creates a Security Access Manager useraccount.

“user create”on page 197

“user delete” on page 199 Deletes a Security Access Manager user andoptionally deletes the user information fromthe user registry. ACL entries that areassociated with the user are also deleted.

“user delete”on page 199

“user import” on page 200 Imports the information about an existingregistry user to create a Security AccessManager user.

“user import”on page 200


Table 16. User commands (continued)


“user list” on page 201 Generates a list of all users whose namesmatch the specified pattern, which is listed byuser names.

“user list” onpage 201

“user modify” on page 203 Modifies various user account parameters. “usermodify” onpage 203

“user show” on page 205 Displays details about a specified user. “user show”on page 205

WebSEAL commandsWebSEAL commands perform management tasks on WebSEAL servers andinstances. These commands are available only when WebSEAL is installed.

Table 17 lists server task commands.

Table 17. WebSEAL server task commands


“server task add” on page117

Adds an application server to an existingWebSEAL junction.

“server taskadd” on page117

“server task cache flush all”on page 120

Flushes the HTML document cache. “server taskcache flushall” on page120

“server task create” onpage 121

Creates a WebSEAL junction point. “server taskcreate” onpage 121

“server task delete” onpage 128

Deletes a WebSEAL junction point. “server taskdelete” onpage 128

“server task dynurlupdate” on page 130

Reloads the dynamic URL configuration file. “server taskdynurlupdate” onpage 130

“server task help” on page131

Lists detailed help information about aspecific server task command.

“server taskhelp” onpage 131

“server task jmt” on page133

Clears or loads the junction mapping tabledata.

“server taskjmt” on page133

“server task list” on page134

Lists all junction points on a WebSEAL serveror server instance.

“server tasklist” on page134

“server task offline” onpage 135

Places the server that is at this junction in anoffline operational state.

“server taskoffline” onpage 135

“server task online” onpage 137

Places the server that is at this junction in anonline operational state.

“server taskonline” onpage 137


Table 17. WebSEAL server task commands (continued)


“server task refreshall_sessions” on page 139

Refreshes the credential for all sessions for aspecified user.

“server taskrefreshall_sessions”on page 139

“server task reload” onpage 140

Reloads the junction mapping table from thedatabase.

“server taskreload” onpage 140

“server task remove” onpage 141

Removes the specified installed WebSEALserver or server instance from a WebSEALjunction point.

“server taskremove” onpage 141

“server task show” on page143

Displays detailed information about thespecified WebSEAL junction.

“server taskshow” onpage 143

“server task terminateall_sessions” on page 162

Terminates all user sessions for a specific user. “server taskterminateall_sessions”on page 162

“server task terminatesession” on page 163

Terminates a user session by using a sessionID.

“server taskterminatesession” onpage 163

“server task throttle” onpage 164

Places the server that is at this junction in athrottled operational state.

“server taskthrottle” onpage 164

“server task virtualhostadd” on page 168

Adds an additional installed WebSEAL serveror server instance to an existing virtual hostjunction.

“server taskvirtualhostadd” on page168

“server task virtualhostcreate” on page 171

Creates a virtual host junction. “server taskvirtualhostcreate” onpage 171

“server task virtualhostdelete” on page 177

Deletes a virtual host junction. “server taskvirtualhostdelete” onpage 177

“server task virtualhostlist” on page 179

Lists all configured virtual host junctions bylabel name.

“server taskvirtualhostlist” on page179

“server task virtualhostoffline” on page 180

Places the server that is at this virtual hostjunction in an offline operational state.

“server taskvirtualhostoffline” onpage 180

“server task virtualhostonline” on page 182

Places the server that is at this virtual hostjunction in an online operational state.

“server taskvirtualhostonline” onpage 182

“server task virtualhostremove” on page 184

Removes the specified server from a virtualhost junction.

“server taskvirtualhostremove” onpage 184


Table 17. WebSEAL server task commands (continued)


“server task virtualhostshow” on page 186

Displays information about the specifiedvirtual host junction.

“server taskvirtualhostshow” onpage 186

“server task virtualhostthrottle” on page 188

Places the server that is at this virtual hostjunction in a throttled operational state.

“server taskvirtualhostthrottle” onpage 188

“server task server restart”on page 190

Restarts the WebSEAL instance. “server taskserverrestart” onpage 190

“server task server sync”on page 191

Synchronizes the configuration of the suppliedWebSEAL authorization server to the currentWebSEAL server.

“server taskserver sync”on page 191

“server task jdb export” onpage 192

Exports the current junction database into asingle file.

“server taskjdb export”on page 192

“server task jdb import” onpage 193

Imports the current junction database from asingle file.

“server taskjdb import”on page 193

“server task cfgdb export”on page 194

Exports the current configuration into a singlefile. The export is based on a configured set ofexclude and include rules. It also exports theconfigured list of data files.

“server taskcfgdb export”on page 194

“server task cfgdb import”on page 195

Imports the configuration from the specifiedexported file into the current WebSEALconfiguration file. The import is based on aconfigured set of exclude and include rules. Italso imports the configured list of data files.

“server taskcfgdbimport” onpage 195

“server task file cat” onpage 196

Obtains the string content of the specified file.A flag controls whether the contents of the fileare base64 encoded or not encoded. AWebSEAL configuration item defines themaximum allowable size of the file.

“server taskfile cat” onpage 196

acl attachAttaches an ACL policy to a protected object. If the protected object already has anACL attached, the ACL is replaced with a new one.

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

Syntax

acl attach object_name acl_name

Description

At most, one ACL can be attached to a given protected object. The same ACL canbe attached to multiple protected objects. Ensure that you are familiar with ACLmanagement before you use this function.


Options

acl_nameSpecifies the ACL policy that is applied to the named object. The ACLpolicy must exist, or an error is displayed.

Examples of the ACL names are default-root, test, default-management,and pubs_acl3.

object_nameSpecifies the object to which to apply the named ACL policy. The objectname must exist, or an error is displayed.

Examples of object names are:v /Management/Groups/Travel

v /WebSEAL

v /Management

Return codes

0 The command completed successfully.

1 The command failed. When a command fails, the pdadmin commandprovides a description of the error and an error status code in hexadecimalformat (for example, 0x14c012f2). See the IBM Security Access Manager forWeb Error Message Reference. This reference provides a list of the SecurityAccess Manager error messages by decimal or hexadecimal codes.

Example

The following example attaches the ACL policy, pubs_acl3, to the protected object,/Management:pdadmin sec_master> acl attach /Management pubs_acl3

See also

“acl create”“acl detach” on page 24

acl createCreates an ACL policy in the ACL database. This command does not create ACLentries.


Syntax

acl create acl_name

Options

acl_nameSpecifies the name of the ACL policy that is being created. A valid ACLpolicy name is an alphanumeric string that is not case-sensitive. Stringvalues are expected to be characters that are part of the local code set.Spaces are not allowed. The following characters cannot be used in thename of the ACL policy:


! " # & ( ) * + , ; : < > = @ / \ | .

Examples: default-root, test, default-management, and pubs_acl3

Return codes



Examplesv The following example creates an ACL policy named pubs_acl3:

pdadmin sec_master> acl create pubs_acl3

v The following example creates an ACL policy named Test-ACL:pdadmin sec_master> acl create Test-ACL

See also

“acl attach” on page 21“acl delete”“acl modify” on page 26

acl deleteDeletes an ACL policy from the ACL database.


Syntax

acl delete acl_name

Options

acl_nameSpecifies the name of the ACL policy that is being deleted from the ACLdatabase. The ACL policy must exist, or an error is displayed.

Examples: default-root, test, default-management, and pubs_acl3.

Return codes



Examplesv The following example deletes the ACL policy that is named pubs_acl3:

pdadmin sec_master> acl delete pubs_acl3


v The following example deletes the ACL policy that is named Test-ACL:pdadmin sec_master> acl delete Test-ACL

See also

“acl detach”

acl detachDetaches the current ACL policy from a protected object. This command does notdelete the ACL policy from the ACL database.


Syntax

acl detach object_name

Description

Only one access control list at a time can be attached to an object. Therefore, thecurrently attached access control list is detached. If the object does not have anattached ACL policy, an error is displayed.

Options

object_nameSpecifies the object from which the current ACL policy is being removed.The object must exist and have an ACL attached, or an error is displayed.


v /WebSEAL

v /Management

Return codes



Example

The following example detaches the ACL from the protected object /Management:pdadmin sec_master> acl detach /Management

See also

“acl attach” on page 21“acl delete” on page 23“acl modify” on page 26


acl findReturns a list of protected objects, which have the specified ACL attached.


Syntax

acl find acl_name

Description

A user must have the browse (b) and view (v) permissions for the object to belisted when the pdadmin object show command is issued. Otherwise, an error isreturned:The user is not authorized to view one or more protected objects where therequested acl is attached.

Options

acl_nameSpecifies the name of the ACL policy that you want to find. The ACLpolicy must exist, or an error is displayed.


Return codes



Examplesv The following example lists the protected object that has the default-config

ACL attached:pdadmin sec_master> acl find default-config

Provides output like:/Management/Config

v The following example lists the protected objects that have the user-definedACL, _WebAppServer_deployedResources_CosNamingDelete_admin_ACL, attached:pdadmin sec_master> acl find_WebAppServer_deployedResources_CosNamingDelete_admin_ACL

Provides output like:/WebAppServer/deployedResources/CosNamingDelete/admin

See also

“acl list” on page 26“acl show” on page 30


acl listLists the names of all defined access control lists. Alternatively, lists the extendedattribute keys that are associated with a specific ACL.


Syntax

acl list

acl list [acl_name attribute]

acl list [pattern max-return]

Options

acl_name attributeSpecifies the ACL policy for which to list the attributes. The ACL policymust exist, or an error is displayed. (Optional)

Examples: default-root, test, default-management and pubs_acl3.

pattern max-returnSpecifies the pattern and the maximum number of access control lists to bereturned. (Optional)

Return codes



Example

The following example lists ACL policies:pdadmin sec_master> acl list

The output is like:default-websealdefault-roottestdefault-replicadefault-management

See also

“acl find” on page 25“acl show” on page 30

acl modifyModifies access control list (ACL) policies.



Syntax

acl modify acl_name delete attribute attribute_name [attribute_value]

acl modify acl_name description description

acl modify acl_name remove any-other

acl modify acl_name remove group group_name

acl modify acl_name remove unauthenticated

acl modify acl_name remove user user_name

acl modify acl_name set any-other [permissions]

acl modify acl_name set attribute attribute_name attribute_value

acl modify acl_name set description description

acl modify acl_name set group group_name [permissions]

acl modify acl_name set unauthenticated [permissions]

acl modify acl_name set user user_name [permissions]

Options

acl_nameSpecifies the ACL policy that you want to be modified. The ACL policymust exist, or an error is displayed.


delete attribute attribute_name [attribute_value]Deletes the specified extended attribute name and value from the specifiedACL. The attribute must exist, or an error is displayed.

The attribute_value deletes the specified value from the specifiedextended attribute key in the specified ACL. (Optional)

Examples of extended attribute names and values:Dept_No 445Employee_Name "Diana Lucas"

description descriptionSets or modifies the description for the specified ACL. This option isequivalent to the acl modify set description command. Use the aclmodify description command instead of the acl modify set descriptioncommand.

A valid description is an alphanumeric string that is not case-sensitive.String values are expected to be characters that are part of the local codeset. Spaces are allowed.

If the description contains a space, ensure that you enclose the descriptionin double quotation marks. You can specify an empty string ("") to clear anexisting description.

Example of description: "Department number of employee"


permissionsSecurity Access Manager uses a set of default actions (known as primaryaction tasks and permissions) that cover a wide range of operations. Youcan also create your own action tasks and permissions. Primarypermissions and procedures for entering custom permissions into ACLentries are described in the IBM Security Access Manager for WebAdministration Guide.

A complete list of primary action tasks and their associated permissionsincludes:TTraverseBasecControlBasegDelegationBasemModifyGenericdDeleteGenericbBrowseBasesServer AdminGenericvViewGenericaAttachBaseBBypass POPBasetTraceBaserReadWebSEALxExecuteWebSEALlList DirectoryWebSEALNCreateBaseWPasswordBaseAAddBaseRBypass AuthzRuleBase

remove any-otherRemoves the ACL entry for the any-other user category from the specifiedACL.

remove group group_nameRemoves the ACL entry for the specified group from the specified ACL.The group must exist, or an error is displayed.

Examples of group names are Credit, Sales, and Test-group.

remove unauthenticatedRemoves the ACL entry for the unauthenticated user category from thespecified ACL.

remove user user_nameRemoves the ACL entry for the specified user from the specified ACL. Theuser must exist, or an error is displayed.

Examples of user names are dlucas, sec_master, and "Mary Jones".

set any-other [permissions]Sets or modifies the ACL entry for the any-other user category in the ACL.Valid actions, or permissions, are represented by single alphabetic ASCIIcharacters (a-z, A-Z).

set attribute attribute_name attribute_valueSets the extended attribute value for the specified extended attribute key inthe specified ACL. The attribute must exist, or an error is displayed. If theattribute exists, the attribute value is added as an additional value if thesame value does not exist for this attribute. If the same value exists for thisattribute, it does not get added again (duplicate values are not allowed),and no error is returned.

The optional attribute_value sets the specified value from the specifiedextended attribute key in the specified ACL.


Examples of extended attribute names and values:Dept_No 445Employee_name "Diana Lucas"

set description descriptionSets or modifies the description for the specified ACL. This option isequivalent to the acl modify description command. Use the acl modifydescription command instead of the acl modify set descriptioncommand.

set group group_name [permissions]Sets or modifies the ACL entry for the specified group in the specifiedACL. The group must exist, or an error is displayed.


Security Access Manager uses a set of default actions that cover a widerange of operations. Valid actions, or permissions, are represented by singlealphabetic ASCII characters (a-z, A-Z). See set any-other [permissions] forthe list of possible permissions.

set unauthenticated [permissions]Sets or modifies the ACL entry for the unauthenticated user category inthe specified ACL.

Security Access Manager uses a set of default actions that cover a widerange of operations. Valid actions, or permissions, are represented by singlealphabetic ASCII characters (a-z, A-Z). See set any-other [permissions] forexamples of permissions.

set user user_name [permissions]Sets permissions that the user is permitted to perform. The user must existor an error is displayed.


Security Access Manager uses a set of default actions that cover a widerange of operations. Valid actions, or permissions, are represented by singlealphabetic ASCII characters (a-z, A-Z). See set any-other [permissions] forexamples of permissions.

Return codes



Examplesv The following example sets the any-other user entry in the pubs ACL to have r,

the Read (WebSEAL) permission:pdadmin sec_master> acl modify pubs set any-other r

v The following example sets the sales group entry in the pubs ACL to have theTr permissions, which are the Traverse and Read (Base) permissions:pdadmin sec_master> acl modify pubs set group sales Tr

v The following example sets the unauthenticated user entry in the docs ACL tohave the r permission, which is the Read (WebSEAL) permission:


pdadmin sec_master> acl modify docs set unauthenticated r

v The following example sets the peter user entry in the pubs ACL to have the Trpermissions, which are the Traverse (Base) and Read (WebSEAL) permissions:pdadmin sec_master> acl modify pubs set user peter Tr

v The following example sets the kathy user entry in the test ACL to have Tbrpermissions, which are the Traverse (Base), Browse (Base) and Read (WebSEAL)permissions. It also sets custom permissions PS for the existing test-group actiongroup. It then displays the results.pdadmin sec_master> acl modify test set user kathy Tbr[test-group]PS

pdadmin sec_master> acl show test

ACL Name: testDescription:Entries:User sec_master TcmdbsvaBlGroup ivmgrd-servers TlAny-other rUser kathy Tbr[test-group]PS

v The following example sets the kathy user entry in the test ACL to have Tbrpermissions, which are the Traverse (Base), Browse (Base), and Read (WebSEAL)permissions. It then displays the results.pdadmin sec_master> acl modify test set user kathy Tbr

pdadmin sec_master> acl show test

ACL Name: testDescription:Entries:User sec_master TcmdbsvaBlGroup ivmgrd-servers TlAny-other rUser kathy Tbr

See also

“acl attach” on page 21“acl create” on page 22

acl showLists the complete set of entries for a specific access control list (ACL) policy.Alternatively, lists the values of a specific extended attribute that is associated withan ACL policy.


Syntax

acl show acl_name [attribute attribute_name]

Options

acl_nameSpecifies the name of the ACL policy for which the extended attributevalues are displayed. The ACL policy must exist, or an error is displayed.

Examples of ACL names are default-root, test, default-management, andpubs_acl3.


attribute attribute_nameSpecifies the name of the extended attribute whose values are displayed.(Optional) The system handles this command as follows:v If the ACL either has an attribute or had an attribute in the past, no

error is displayed.v If the ACL never had an attribute, then an error is displayed.

Examples of extended attribute names are Dept_No and Employee_Name.

Return codes



Example

The following example shows details about ACL test-acl:pdadmin sec_master> acl show test-acl

ACL Name: test-aclDescription:Entries:User sec_master TcmdbvaGroup ivmgrd-servers TlAny other r

See also

“acl find” on page 25“acl list” on page 26

action createCreates and adds an action (permission) to an action group.


Syntax

action create action_name action_label action_type [action_group_name]

Description

Action codes (permissions) consist of one alphabetic character (a-z or A-Z) and arecase-sensitive. Each action code can be used only once within an action group.Ensure that you do not attempt to redefine the default action codes when you addcustom codes to the primary group.

Options

action_group_nameSpecifies the name of the action group to which the action code is to beadded. If no action group is specified, the action is added to the primary


action group. Supports a maximum of 32 action groups. Examples of actiongroup names are primary and test-group. (Optional)

action_labelSpecifies the label or description for the action. Each default permission isdisplayed with a label that describes the operation that it governs. Inaddition, the ACLs are grouped in one of the following ways, according totheir use:v In a particular part of the objectspace, such as, WebSEAL.v Across the entire objectspace, such as, Base, Generic.

For example, time is the action label in the following example:k time Ext-Authzn

A valid action label is an alphanumeric string that is not case-sensitive.String values are expected to be characters that are part of the local codeset. Spaces are not allowed.

Examples of action labels: time, Generic, Base, and WebSEAL

action_nameSpecifies the new single-character permission that is being created, whichcan be specified by using any case.

Security Access Manager uses a set of default actions that cover a widerange of operations. Valid actions, or permissions, are represented by singlealphabetic ASCII characters (a-z, A-Z).

For example, k is the action name in the following example:k time Ext-Authzn

action_typeSpecifies the organizational category for this action within a specifiedaction group. The action type can be a description of the action, such aswhat application the action is specific to. The action type isapplication-specific and typically refers to:v The application that defined the action, such as, WebSEAL.v The function that uses the action, such as, Ext-Authzn, for extended

authorization checks.

A valid action type is an alphanumeric string that is not case-sensitive.String values are expected to be characters that are part of the local codeset. Spaces are not allowed.

For example, Ext-Authzn is the action type in the following example:k time Ext-Authzn

Return codes



Examplesv The following example creates an action code named k with an action label of

time and an action type of Ext-Authzn within the primary action group:


pdadmin sec_master> action create k time Ext-Authzn

v The following example creates a customized action named P and an action labelof Test-Action with an action type of Special within the test-group actiongroup:pdadmin sec_master> action create P Test-Action Special test-group

See also

“action delete”

action deleteDeletes an action (permission) from an action group.


Syntax

action delete action_name [action_group_name]

Options

action_group_nameSpecifies the name of the action group from which the specified actionmust be deleted. Examples of action group names are primary andtest-group. (Optional)

action_nameSpecifies the name of the action to be deleted. The action code must exist,or an error is displayed.

Security Access Manager uses a set of default actions that cover a widerange of operations. Valid actions, or permissions, are represented by singlealphabetic ASCII characters (a-z, A-Z). For example, k is the action name inthe following example:k time Ext-Authzn

Return codes



Examplesv The following example deletes action k from the primary action group:

pdadmin sec_master> action delete k

v The following example deletes the action z from the agz action group:pdadmin sec_master> action delete z agz

See also

“action create” on page 31


action group createCreates an action group.


Syntax

action group create action_group_name

Options

action_group_nameSpecifies the name of the action group to create. Supports a maximum of32 action groups. The action group must not exist, or an error is displayed.

A valid action group name is an alphanumeric string that is notcase-sensitive. String values are expected to be characters that are part ofthe local code set. Spaces are not allowed.

Examples of action group names are primary and test-group.

Return codes



Example

The following example creates the test action group:pdadmin sec_master> action group create test

action group deleteDeletes an action group.


Syntax

action group delete action_group_name

Options

action_group_nameSpecifies the name of the action group to delete. All the actions that belongto the specified group are also deleted. The action group must exist, or anerror is displayed. Examples of action group names are primary andtest-group.

Return codes


1 The command failed. When a command fails, the pdadmin command


provides a description of the error and an error status code in hexadecimalformat (for example, 0x14c012f2). See the IBM Security Access Manager forWeb Error Message Reference. This reference provides a list of the SecurityAccess Manager error messages by decimal or hexadecimal codes.

Example

The following example deletes the test action group:pdadmin sec_master> action group delete test

action group listLists all action groups.


Syntax

action group list

Description

The action group list command lists all the defined names of action groups

Options

None.

Return codes



Example

The following example lists the names of all defined action groups:pdadmin sec_master> action group list

primarytest-group

action listLists all actions (permissions) in an action group.


Syntax

action list [action_group_name]


Options

action_group_nameSpecifies the name of the action group for which all actions are displayed.If this option is not specified, actions that are defined in the primary actiongroup are listed. The action group must exist, or an error is displayed.

Examples of action group names are primary and test-group. (Optional)

Return codes



Example

The following example displays all existing actions in the primary action group:pdadmin sec_master> action list

TTraverseBasecControlBasegDelegationBasemModifyGenericdDeleteGenericbBrowseBasesServer AdminGenericvViewGenericaAttachBaseBBypass POPBasetTraceBaserReadWebSEALxExecuteWebSEALlList DirectoryWebSEALNCreateBaseWPasswordBaseAAddBaseRBypass AuthzRuleBase

admin show confDisplays the current policy server configuration information, such as the type ofregistry or whether global sign-on is enabled.


Syntax

admin show conf

Options

None.

Return codes




Example

The following example displays the current server configuration information:pdadmin sec_master> admin show conf

LDAP: yessecAuthorityGSO: yes

authzrule attachAttaches an authorization rule to the specified protected object.


Syntax

authzrule attach protobjid ruleid

Description

At most, one rule can be attached to a given protected object. If the object alreadyhas a rule that is attached to it, the specified rule replaces the existing one. Thesame rule can be attached to multiple protected objects. Ensure that the protectedobject exists in the protected object space before you attach a rule.

Options

protobjidSpecifies the fully qualified name of the protected object to which theauthorization rule is attached. The object must exist, or an error isdisplayed.

ruleid Specifies the name of the authorization rule to attach. The rule must exist,or an error is displayed.

Return codes



Example

The following example attaches the r1 rule to the /Test-Space/folder1 protectedobject named:pdadmin sec_master> authzrule attach /Test-Space/folder1 r1


See also

“authzrule create”“authzrule detach” on page 40

authzrule createCreates an authorization rule.


Syntax

authzrule create rule_id –rulefile file_name [–desc description] [–failreasonfail_reason]

authzrule create rule_id rule_text [–desc description] [–failreasonfail_reason]

Description

You can attach an authorization rule to a protected object. To authorize access tothe protected object, the user credential and application context attributes arecompared against the rule.

Note: Quotation marks within an authorization rule must be escaped by using thebackward slash (\) character when the rule is entered without using the –rulefileoption.

Options

–desc descriptionSpecifies the description of the authorization rule. (Optional)

A valid description is an alphanumeric string that is not case-sensitive.String values are expected to be characters that are part of the local codeset. If the description contains a space, ensure that you enclose thedescription in double quotation marks. You can specify an empty string ("")to clear an existing description.

Example of description: "time-of-day rule for engineering objectspace"

–failreason fail_reasonSpecifies the message that is returned if the rule denies access to aprotected object. Consider that the authorization is denied as a result of theevaluation of this rule. However, other authorization checks succeed. Inthis case, the reason code is returned to the application that makes theauthorization check. (Optional)

–rulefile file_nameSpecifies the file from which to read the XSL rule text. The rule file mustexist, or an error is displayed.

rule_idSpecifies the name of the authorization rule to create.

A valid authorization rule is an alphanumeric string that is notcase-sensitive. String values are expected to be characters that are part of


the local code set. Spaces are not allowed. The following characters cannotbe used in the name of an authorization rule:! " # & ( ) * + , ; : < > = @ / \ | .

rule_textSpecifies the rule policy that is used to evaluate the rule in XSL format.The rule must be enclosed in double quotation mark (") character. If therule specifies a double quotation mark as part of the rule text, precede thedouble quotation mark with a backward slash (\) character. Doing soinstructs the system to ignore the double quotation mark.

Return codes



Example

The following example creates the r1 rule with the r1.xsl rule file that implementsthe time-of-day rule for the marketing object space and returns a fail reason code:pdadmin sec_master> authzrule create r1 -rulefile r1.xsl-desc "time-of-day rule for engineering object space"-failreason "An error occurred during r1 creation"

See also

“authzrule delete”

authzrule deleteDeletes an authorization rule.


Syntax

authzrule delete rule_id

Options

rule_idSpecifies the name of the authorization rule to delete. The authorizationrule must exist, or an error is displayed.

Return codes




Examples

The following example deletes the eng-test rule:pdadmin sec_master> authzrule delete eng-test

The following example deletes the myRule rule:pdadmin sec_master> authzrule delete myRule

See also

“authzrule create” on page 38“authzrule detach”

authzrule detachDetaches an authorization rule from the specified protected object.


Syntax

authzrule detach protobjid

Options

protobjidSpecifies the name of the protected object from which the authorizationrule is detached. The object must exist and have an authorization rule thatis attached, or an error is displayed.

Return codes



Example

The following example detaches a rule from the /WebSEAL/tivoli.com/w3junction/index.html protected object:pdadmin sec_master> authzrule detach /WebSEAL/tivoli.com/w3junction/index.html

See also

“authzrule attach” on page 37“authzrule delete” on page 39

authzrule findFinds and lists all protected objects that have the specified authorization ruleattached.



Syntax

authzrule find rule_id

Description

A user must have the browse (b) and view (v) permissions for the object to belisted when the pdadmin object show command is issued. Otherwise, an error isreturned:The user is not authorized to view one or more protected objects where therequested authzrule is attached.

Options

rule_idSpecifies the name of the authorization rule to find. The authorization rulemust exist, or an error is displayed.

Return codes



Example

The following example finds protected objects that are attached to the r2 rule:pdadmin sec_master> authzrule find r2

/Marketing/Folder1

See also

“authzrule list”

authzrule listLists all the authorization rules.


Syntax

authzrule list

Options

None.

Return codes


1 The command failed. When a command fails, the pdadmin commandprovides a description of the error and an error status code in hexadecimal


format (for example, 0x14c012f2). See the IBM Security Access Manager forWeb Error Message Reference. This reference provides a list of the SecurityAccess Manager error messages by decimal or hexadecimal codes.

Example

The following example lists authorization rules:pdadmin sec_master> authzrule list

r1r2r3r4

See also

“authzrule find” on page 40

authzrule modify

Changes an authorization rule.


Syntax

authzrule modify rule_id ruletext rule_text

authzrule modify rule_id –rulefile file_name

authzrule modify rule_id description description

authzrule modify rule_id failreason fail_reason

Options

description descriptionSpecifies the new description of the rule.

A valid description is an alphanumeric string that is not case-sensitive.String values are expected to be characters that are part of the local codeset. Spaces are allowed. If the description contains a space, ensure that youenclose the description in double quotation marks. You can specify anempty string ("") to clear an existing description.

Example of description: "time-of-day access"

failreason fail_reasonSpecifies the fail reason code. Consider that authorization is denied as aresult of the evaluation of this rule. However, other authorization checkssucceed. In this case, the reason code is returned to the application thatmakes the authorization check. You can specify an empty string ("") toclear an existing fail reason.

rule_idSpecifies the name of the authorization rule to change. The authorizationrule must exist, or an error is displayed.


–rulefile file_nameSpecifies the file from which to read the XSL rule text. The –rulefileoption must be used when you specify a file that contains the rule text.

A valid file name is an alphanumeric string that is not case-sensitive. Stringvalues are expected to be characters that are part of the local code set.

ruletext rule_textSpecifies the new rule text in XSL format. Do not use the –rulefile optionwhen you specify rule text directly.

Return codes



Example

The following example changes the description of a rule named r2:pdadmin sec_master> authzrule modify r2 description "time-of-day access"

See also

“authzrule attach” on page 37“authzrule create” on page 38

authzrule showShows all the attributes of an authorization rule, including description, rule text,and fail reason code.


Syntax

authzrule show rule_id

Options

rule_idSpecifies the name of the authorization rule to show. The rule must exist,or an error is displayed.

Return codes




Example

The following example shows attributes for a rule named r2:pdadmin sec_master> authzrule show r2

The output is like:Authorization Rule Name: r2Description: time-of-day accessRule Text: <xsl:if test="/XMLADI/session[contains(status,’login’)]"><xsl:for-each select="/XMLADI/userid/level"><xsl:if test=". = ’administrator’"><xsl:choose><xsl:when test="../paid = ’in-full’">!TRUE!</xsl:when><xsl:when test="../paid = ’partial’">!FALSE!</xsl:when><xsl:when test="../paid = ’introductory’">!TRUE!</xsl:when><xsl:otherwise>!FALSE!</xsl:otherwise></xsl:choose></xsl:if></xsl:for-each></xsl:if>Fail Reason:Error when creating R2

See also

“authzrule find” on page 40“authzrule list” on page 41

config modifyModifies a stanza entry in a configuration file or sets the password for the serveruser account.

Syntax

config modify keyvalue append [–obfuscate] config_file stanza key value

config modify keyvalue remove [–obfuscate] config_file stanza key [value]

config modify keyvalue set [–obfuscate] config_file stanza key value

config modify svrpassword config_file password

Description

The config modify command either modifies a stanza entry in a configuration fileor sets the password for the application server user account. Depending on whichconfiguration operation you want, you must either perform a local login or aremote login.v To set the password for the server user account by using the svrpassword option,

perform a remote login by using:– The login command.


– The login command with the –d option.– The login command with the –m option.

v To modify the value of a stanza entry in a configuration file by using thekeyvalue option, perform a local login. Use the login command with the –loption.

Note: If you attempt to run one of the configuration operations that requires alocal login, an error is displayed.Error: HPDMS4061ELocal authentication (local login) is required to performthis operation (status 0x14c52fdd)

To use the svrpassword option, you must:v Be defined in the ACL policy.v Have the Password permission - W action bit.v Have the necessary operating system permissions to modify the local

configuration file.

To use the keyvalue options, you must have the necessary operating systempermissions to read and modify the configuration file.

For key values that are not obfuscated, use the config show command to displaymodified values.

For information and guidelines about the stanzas and stanza entries inconfiguration files, see the IBM Security Access Manager for Web Stanza Reference.

Options

–obfuscateIndicates that the stanza entry must be written to or removed from theobfuscated (.obf file) version of the configuration file, which is specifiedby config_file. (Optional)

config_fileSpecifies the fully qualified name of the configuration file, unless theconfiguration file is in the current directory. When used with the–obfuscate option, do not specify the .obf extension as part of theconfiguration file name.

key Specifies the key portion of the stanza entry.

keyvalue appendAdds a value to a stanza entry in the configuration file stanza. If youattempt to append a duplicate value to a key, the duplicate value isignored.

keyvalue removeRemoves a value from a stanza entry in the configuration file stanza. Ifyou do not specify the value option, the key is removed from theconfiguration file.

keyvalue setDefines a stanza entry (key value pair) or changes the value of a key in theconfiguration file stanza.

passwordSpecifies the password for the application server account.

stanza Specifies the name of stanza that contains the stanza entry.


svrpasswordSets the password for the application server account. This password isupdated in the registry and in the obfuscated version of the localconfiguration file.

value Specifies the configuration value for the key.

Authorization

No authentication is required, except for the svrpassword option. The svrpasswordoption requires authentication (administrator ID and password).

Return codes


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


Examplesv The following example provides a local login:

pdadmin> login -l

After a local login, the prompt changes from pdadmin> to pdadmin local>.v After a local login, the following example changes the value of the version key

in the [meta-info] stanza of the d:\temp\my.conf configuration file to 6798:pdadmin local> config modify keyvalue set d:\temp\my.conf \meta-info version 6798

v After a local login, the following example adds the new key mynewvalue to the[meta-info] stanza of the d:\temp\my.conf.obf configuration file. The examplesets the value of the new key to 14 in a new obfuscated stanza entry:pdadmin local> config modify keyvalue set -obfuscate d:\temp\my.conf \meta-info mynewkey 14

Note: In the config modify command above, the name of the configuration filedoes not have the .obf file extension.

See also

“config show”“login” on page 65

config showShows the value that is associated with the specified stanza and key in the SecurityAccess Manager server configuration files or in customized server configurationfiles. The stanza and key must exist, or an error is displayed.

Requires a local login to use this command. No authentication is required.


Syntax

config show config_file stanza key

Options

config_fileSpecifies the Security Access Manager or custom configuration file to use.Unless the configuration file is in the current directory, the configurationfile name must be a fully qualified path name. The necessary operatingsystem permissions are required to read and update the configuration file.The default names for the configuration files are documented in theSecurity Access Manager administration guides.

key Specifies the configuration value to associate with the key in the specifiedconfiguration file stanza. Valid key-value pairs are documented in theSecurity Access Manager administration guides.

stanza Specifies the name of a Security Access Manager or custom stanza thatcontains the input key. A valid stanza name is an alphanumeric string thatis not case-sensitive. String values are expected to be characters that arepart of the local code set. Valid stanzas are documented in the SecurityAccess Manager administration guides.

Return codes


1 The command failed. When a command fails, the pdadmin commandprovides a description of the error and an error status code in hexadecimalformat (for example, 0x14c012f2). See the IBM Security Access Manager forWeb: Error Message Reference. This reference provides a list of the SecurityAccess Manager error messages by decimal or hexadecimal codes.

Examplesv The following example provides a local login and requests the value of the

version key for the [meta-info] stanza. The value is 1296. The prompt changesto show that the login is local:pdadmin> login -l

pdadmin local> config show "c:\Program Files\Tivoli\PolicyDirectory\etc\activedir.conf" meta-info version

Provides output like:1296

v The following example provides a local login and requests the value of theenabled key for the [ldap] stanza. The output provides a key value of yes. Theprompt changes to show that the login is local:pdadmin>login -l

pdadmin local> config show "C:\Program Files\Tivoli\Policy Director\etc\ldap.conf"ldap enabled

Provides output like:yes


See also

“config modify” on page 44“login” on page 65

context showDisplays the user ID and domain ID used to establish the current authenticationcontext. Also, specifies whether the domain is the management domain or adomain other than the management domain.

This command does not require a login or authentication to use.

Syntax

context show

Options

None.

Return codes



Examplesv The following example shows that no login and no authentication are being

performed:c:\> pdadmin

context show

The output is like:No login information

v The following example shows local authentication before the context showcommand is issued:c:\> pdadmin -lpdadmin local> context show

The output is like:The user is logged in to the local system

v The following example shows local authentication, like the previous example,except the command in issued interactively:pdadmin sec_master> login -l

pdadmin local> context show

The output is like:The user is logged in to the local system


v The following example shows authentication context information for a user whois logged in to the management domain (non-local authentication).c:\> pdadmin -a sec_master -p mypwd -m

pdadmin sec_master> context show

The output is like:User: sec_masterDomain: DefaultThe user is logged into the management domain

v The following example shows authentication context information for thetestdomain_admin administrator who logs in interactively to a domain(testdomain) other than the management domain:pdadmin> login -a testdomain_admin -p testpwd -d testdomain

pdadmin testdomain_admin@testdomain_admin> context show

The output is like:User: testdomain_adminDomain: testdomainThe user is not logged in to the management domain

See also

“domain show” on page 54“user show” on page 205“login” on page 65“logout” on page 67

domain createCreates a domain, including an administrator ID and password to log in to thespecified domain. You must log in to the management domain as an administratorto perform this command.


This command applies to LDAP registries only.

Syntax

domain create domain domain_admin_id domain_admin_password [–descdescription]

Description

An initial domain is created when the policy server is configured. This domain,called the management domain, is the default domain in which Security AccessManager enforces security policies for authentication, authorization, and accesscontrol. You must log in to the management domain to create more policydomains.

When you create a domain, you must specify an administrative ID and passwordfor the domain. The administrator of the management domain later assigns thenew ID and password. The new credentials are assigned to the administrator


responsible for handling policy management tasks for the specific domain. Theadministrator of the domain is responsible for updating the security policy for thatparticular domain if:v Users change.v Groups change.v Resources change.

This domain administrator can also delegate administration tasks to others withinthat specific domain. For more information about managing domains, see the IBMSecurity Access Manager for Web: Administration Guide.

Options

–desc descriptionSpecifies an optional description for the domain. A valid description is analphanumeric string that is not case-sensitive. String values are expected tobe characters that are part of the local code set. If the description containsa space, ensure that you enclose the description in double quotation marks.You can specify an empty string ("") to clear an existing description.Examples of description: "accounting area". (Optional)

domain Specifies the name of the domain to be created. Characteristics of the nameare:v Limited to 64 characters in length.v Case sensitive.v Can contain a-z, A–Z, 0–9, hyphen (-), underscore (_), period (.), at sign

(@), or ampersand(&).v Can contain any character from a double-byte character set.

The underlying user registry might also restrict certain characters. Someregistries are not case-sensitive.

domain_admin_idSpecifies an administrator ID, which is created in the specified domain.

domain_admin_passwordSpecifies the password for the domain_admin_id user.

Return codes



Examplesv The following example creates a domain named Marketing, a domain

administrator ID Admin1, and an initial password to log in to the domain:pdadmin sec_master> domain create Marketing Admin1 password

v The following example creates a domain named Finance, a domainadministrator ID Admin2, a password, and a domain description:pdadmin sec_master> domain create Finance Admin2 password-desc "accounting area"


See also

“domain delete”“domain list” on page 52“domain modify” on page 53“domain show” on page 54

domain deleteDeletes a domain, excluding the management domain. Optionally deletes the userand group information of the domain, from the user registry. To perform thiscommand, you must log in to the management domain as an administrator.



Syntax

domain delete domain [–registry]

Description

A domain can be deleted within the management domain only by an administratorwith the appropriate privileges.

Options

–registrySpecifies that the information of the domain, including user and groupdata, be deleted from the user registry. (Optional) If this option is notselected, user and group data for the specified domain:v Remains in the registry.v Can be used again if the domain is re-created.

domain Specifies the name of the domain to be deleted. The domain must exist, oran error is displayed.

Return codes



Examplesv The following example deletes a domain named Marketing:

pdadmin sec_master> domain delete Marketing

v The following example deletes a domain named Finance and removes any userand group information in the user registry:pdadmin sec_master> domain delete Finance -registry


See also

“domain create” on page 49“domain list”“domain modify” on page 53“domain show” on page 54

domain listLists all domains, excluding the management domain. You must log in to themanagement domain as an administrator to perform this command.



Syntax

domain list

Options

None.

Return codes



Example

The following example lists existing domains other than the management domain(Default):pdadmin sec_master> domain list

The output is like:MarketingFinanceAdvertisingReceiving

See also

“domain create” on page 49“domain delete” on page 51“domain modify” on page 53“domain show” on page 54


domain modifyChanges the description of a domain. You must log in to the management domainas an administrator to perform this command.



Syntax

domain modify domain description description

Options

description descriptionSpecifies a new description for the domain.


Example of description: "marketing and advertising areas"

domain Specifies the name of the domain to modify.

Return codes



Example

The following example changes the description that is specified for the Marketingdomain:pdadmin sec_master> domain modify Marketing description "marketing andadvertising areas"

See also

“domain create” on page 49“domain delete” on page 51“domain list” on page 52“domain show” on page 54


domain showDisplays the properties of a domain. You must log in to the management domainas an administrator to perform this command.



Syntax

domain show domain

Options

domain Specifies the name of the domain for which to display properties. Thedomain must exist, or an error is displayed.

Return codes



Example

The following example displays properties for the Marketing domain:pdadmin sec_master> domain show Marketing

The output is like:Domain Name: MarketingDescription: marketing and advertising areas

See also

“domain create” on page 49“domain delete” on page 51“domain list” on page 52“domain modify” on page 53

errtextDisplays the error message of a specific error number.

For detailed information about messages, see the IBM Security Access Manager forWeb Error Message Reference.


Syntax

errtext error_number


Description

The message ID is also displayed (for example, HPDMS4047E) The message IDconsists of 10 alphanumeric characters that uniquely identify the message. Themessage ID is composed of the following pieces:v A three-character product identifier (for example, HPD indicates that this message

is for Security Access Manager base or Web Portal Manager)v A two-character component or subsystem identifierv A four-digit message numberv A one-character type code indicates the severity of the message (I for

informational, W for warning, and E for error)

Options

error_numberSpecifies the number, in either decimal or hexadecimal, of the error forwhich to generate the error text.

Return codes



Examplesv The following example displays the error message that is associated with a

specific hexadecimal number:pdadmin sec_master> errtext 0x14c52fcf

The output is like:HPDMS4047E:Non-local authentication (login) is required to performthis operation (status 0x14c52fcf)

v The following example displays the error message that is associated with aspecific decimal number:pdadmin> errtext 268808652

The output is like:HPDAC0460E The protected object space specified already exists in theauthorization policy database (status 0x1005b1cc)

exit or quitExits from the pdadmin utility interactive command-line mode.


Syntax

exit

quit


Options

None.

Examplesv The following example displays how to exit the pdadmin utility:

pdadmin> exit

v The following example displays how to quit the pdadmin utility:pdadmin> quit

See also

“login” on page 65“logout” on page 67“context show” on page 48

group createCreates a Security Access Manager group.

Requires authentication of administrator ID and password to use this command.

Groups that are created in the Active Directory Lightweight Directory Service (ADLDS) user registry must be created in the same AD LDS partition where the AccessManager Management Domain information is stored.

Syntax

group create group_name dn cn [group_container]

Options

cn Specifies the common name that is assigned to the group that is beingcreated. For example, cwright.

dn Specifies the registry identifier that is assigned to the group that is beingcreated.

The format for a distinguished name is like:cn=credit,ou=Austin,o=Tivoli,c=US

group_containerSpecifies the group container object that is assigned to the group that isbeing created. If this option is not specified, the group by default is placedin the object space under /Management/Groups. (Optional)

Examples of group containers are Credit and Sales_Teams.

group_nameSpecifies the name of the group that is being created. This name must beunique within the domain.

A valid group name is an alphanumeric string that is not case-sensitive.String values are expected to be characters that are part of the local codeset. Spaces are not allowed.



Return codes



Examplesv The following example creates a group named credit1 with a common name of

credit01 within the Credit group container object:pdadmin sec_master> group create credit1 "cn=credit01,o=Tivoli,c=US"credit01 Credit

v The following example creates a group named salesteam with a common nameof sales within the Sales_Teams group container:pdadmin sec_master> group create salesteam "cn=sales,o=tivoli,c=us"sales Sales_Teams

See also

“group delete”“group import” on page 58

group deleteDeletes the specified Security Access Manager group. Optionally deletes theinformation of the group, from the user registry. ACL entries that are associatedwith the group are also deleted.


Syntax

group delete [–registry] group_name

Options

–registryDeletes the entire group object from the user registry. (Optional)

group_nameSpecifies the name of the Security Access Manager group to be deleted.The group must exist, or an error is displayed.


Return codes




Examplesv The following example deletes the existing engineering group:

pdadmin sec_master> group delete engineering

v The following example deletes the group object from the user registry and alsodeletes the existing Test-group group:pdadmin sec_master> group delete -registry Test-group

See also

“group create” on page 56“group import”

group importCreates a Security Access Manager group by importing group data that exists inthe user registry.

You can import an Active Directory dynamic group under this condition:

The name of the Security Access Manager group (excluding the @domain suffix) isthe same as the common name (CN) of the Active Directory dynamic group.

If Active Directory Lightweight Directory Service (AD LDS) is the user registry,import groups from the AD LDS partition where the Security Access Managermanagement domain information is stored.


Syntax

group import group_name dn [group_container]

Options

dn Specifies the registry identifier of the group to import. The distinguishedname must exist, or an error is displayed. The format for a distinguishedname is like "cn=engineering,ou=Austin,o=Tivoli,c=us"

group_containerSpecifies the group container object that is assigned to the group that isbeing created. By default, the group is placed in the object space under/Management/Groups. If the container object does not currently exist, it isautomatically created. (Optional)

group_nameSpecifies the name of the group to create. A valid group name is analphanumeric string that is not case-sensitive. String values are expected tobe characters that are part of the local code set. Spaces are not allowed.Examples of group names are Credit, Sales, and Test-group.

Return codes


1 The command failed. When a command fails, the pdadmin commandprovides a description of the error and an error status code in hexadecimalformat (for example, 0x14c012f2). See the IBM Security Access Manager for


Web Error Message Reference. This reference provides a list of the SecurityAccess Manager error messages by decimal or hexadecimal codes.

Examplesv The following example creates a Security Access Manager group by importing a

group that exists in the user registry:pdadmin sec_master> group import engineering "cn=engineering,o=Tivoli,c=US"

v This example:– Creates a Security Access Manager group named sales.– Places the sales group in the Sales2003 group container object by importing

a group that exists in the user registry.pdadmin sec_master> group import sales "cn=sales,o=tivoli,c=us" Sales2003

v This example creates a group named dyngroup1 by importing the group from anActive Directory dynamic group with the following characteristics:

cn dyngroup1

distinguishedName

cn=dyngroup1,cn=AzGroupObjectContainer-myAuthorizationStore,cn=myAuthorizationStore,cn=ProgramData,dc=domain,dc=com

pdadmin sec_master> group import dyngroup1 "cn=dyngroup1,cn=AzGroupObjectContainer-myAuthorizationStore,cn=myAuthorizationStore,cn=ProgramData,dc=domain,dc=com"

If Security Access Manager is configured in an environment that usesmultiple Active Directory domains, enter the following command tocreate the same group:pdadmin sec_master> group import [email protected] "cn=dyngroup1,cn=AzGroupObjectContainer-myAuthorizationStore,cn=myAuthorizationStore,cn=ProgramData,dc=domain,dc=com"

See also

“group create” on page 56

group listGenerates a list of all groups, by group names, whose names match the specifiedpattern.


Syntax

group list pattern max_return

group list-dn pattern max_return


Options

list pattern max_returnSpecifies the pattern for the group name for which to be searched. Thepattern can include a mixture of wildcard and string constants, and is notcase-sensitive (for example, *austin*).

The max_return option specifies the limit of how many entries must bereturned for a single request; for example, 2. The number that is returnedis also governed by the server configuration. The configuration specifiesthe maximum number of results that can be returned as part of a searchoperation. The actual maximum returned entries is the minimum ofmax_return and the configured value on the server.

list-dn pattern max_returnLists user registry identifiers whose user registry common name attributematches the pattern specified. The returned list contains groups, which aredefined in the user registry. The groups might not necessarily be SecurityAccess Manager groups. You can import groups that are not SecurityAccess Manager groups into Security Access Manager by using the groupimport command.

Return codes



Examplesv The following example lists 3 groups that match the specified pattern of a group

name that contains the letter a:pdadmin sec_master> group list *a* 3

The output is like:SalesMarketingAlex

v The following example lists 2 groups that match the specified pattern of adistinguished name that contains the letter t:pdadmin sec_master> group list-dn *t* 2

The output is like:cn=credit,ou=Austin,o=Tivoli,c=US Salescn=marketing,ou=Boston,o=Austin Sale,c=US Marketing

See also

“group show” on page 62


group modifyChanges an existing group by adding or changing a group description, addingmembers to the group, or removing members from the group.


Syntax

group modify group_name add user

group modify group_name add (user_1 user_2 [... user_n])

group modify group_name description description

group modify group_name remove user

group modify group_name remove (user_1 user_2 [... user_n])

Options

add user or add (user_1 user_2 [... user_n])Adds a user or a list of users to the group. For a single user, do notinclude the user name in parentheses. For multiple users, the format of theuser list is a parenthesized list of user names, which are separated byspaces.

The following list shows examples of user names:v dlucasv "Bob Smith"v (dlucas "Mary Jones" mlucaser)

description descriptionChanges the description for the specified group. A valid description is analphanumeric string that is not case-sensitive. String values are expected tobe characters that are part of the local code set. Spaces are allowed. If thedescription contains a space, ensure that you enclose the description indouble quotation marks. You can specify an empty string ("") to clear anexisting description. For example, you can specify "Credit, Dept HCUS" asthe description.

group_nameSpecifies the name of the group. The group must exist, or an error isdisplayed.


remove user or remove (user_1 user_2 [... user_n])Removes a user or a list of users from the group. For a single user, do notinclude the user name in parentheses. For multiple users, the format of theuser list is a parenthesized list of user names, which are separated byspaces. The following list shows examples of user names:v dlucasv "Bob Smith"v (dlucas "Mary Jones" mlucaser)

Return codes




Examplesv The following example adds a user dlucas to the engineering group:

pdadmin sec_master> group modify engineering add dlucas

v The following example adds three new users to the engineering group:pdadmin sec_master> group modify engineering add ("Mary Jones" dsmith mlucaser)

v The following example deletes three existing users from the engineering group:pdadmin sec_master> group modify engineering remove ("Mary Jones"dlucas mlucaser)

v The following example changes the description of the credit group:pdadmin sec_master> group modify credit description "Credit, Dept HCUS"

See also

“group create” on page 56“group import” on page 58

group showShows the properties of the specified group.


Syntax

group show group_name

group show-dn dn

group show-members group_name

Options

show group_nameShows the properties of the group that is specified by group_name. Thegroup must exist, or an error is displayed.


show-dn dnShows the group that is specified by the group identifier in the userregistry. The returned group is defined in the user registry, but it is notnecessarily a Security Access Manager group. Groups that are not SecurityAccess Manager groups can be imported into Security Access Manager byuse of the group import command. For example, the format for adistinguished name is like "cn=engineering,ou=Austin,o=Tivoli,c=us".

show-members group_nameLists the user names of the members of the specified group. The groupmust exist, or an error is displayed.



Return codes



See the IBM Security Access Manager for Web: Error Message Reference. Thisreference provides a list of the Security Access Manager error messages bydecimal or hexadecimal codes.

Examplesv The following example displays properties of the credit group:

pdadmin sec_master> group show credit

The output is like:Group ID: creditLDAP dn: cn=credit,ou=Austin,o=Tivoli,c=USDescription: Credit, Dept HCUSLDAP cn: creditIs SecGroup: yes

v The following example displays properties that are specified by the identifier ofthe group, cn=credit,ou=Austin,o=Tivoli,c=US in the user registry:pdadmin sec_master> group show-dn cn=credit,ou=Austin,o=Tivoli,c=US

The output is like:Group ID: creditLDAP dn: cn=credit,ou=Austin,o=Tivoli,c=USDescription: Credit, Dept HCUSLDAP cn: creditIs SecGroup: yes

v The following example lists the user names of the members of the credit group:pdadmin sec_master> group show-members credit

The output is like:dlucasmlucaser

See also

“group list” on page 59

helpObtains system help for pdadmin commands and options.


Syntax

help {topic | command}

Options

commandSpecifies the miscellaneous command for which help is needed.

topic Specifies the help command topic for which help is needed.


Return codes



Examplesv The following example lists help topics and commands:

pdadmin> help

The output is like:Type ’help <topic>’ or ’help <command> for more information

Topics:aclactionadminauthzruleconfigcontextdomainerrtextexitgrouphelploginlogoutobjectobjectspacepolicypopquitrsrcrsrccredrsrcgroupserveruser

Miscellaneous Commands:exithelpquit

v The following example lists the options and descriptions that are availablewhether you specify the topic action or action create:pdadmin> help action

Or:pdadmin> help action create

The output is like:action create <action-name> <action-label> <action-type>Creates a new ACL action definitionaction create <action-name> <action-label> <action-type> <action-group-name>Creates a new ACL action definition in a group...


loginEstablishes authentication credentials that are used for communication with theSecurity Access Manager policy server. These credentials are used to determineaccess privileges for the user to policy server data. Most commands cannot beperformed unless an explicit login is done.


Syntax

login –a admin_id [–p password] [–d domain]

login –a admin_id [–p password] [–m]

login –l

Description

Credentials are used to determine user access privileges to policy server data.Except the context, errtext, exit, help, login, logout, and quit commands, andthe local configuration commands, a user ID, and a password are needed forauthentication.

Credentials are not accumulated or stacked. A login command completely replacesany existing credentials.

In interactive mode, the pdadmin prompt changes, depending on how the user logsin:v Not interactive mode. This command starts the pdadmin utility. In interactive

mode, the login commands are entered from the pdadmin> prompt.c:\> pdadminpdadmin>

v A user local login that is performed for local configuration. No authentication isrequired.pdadmin> login -lpdadmin local>

v An administrator login that is performed to the local domain. In some cases, thelocal domain might be the management domain, which is named Default.Authentication is required.pdadmin> login -a sec_master -p secmstrpwpdadmin sec_master>

v A user login that is performed to the local domain. Authentication is required.pdadmin> login -a dlucas -p lucaspwpdadmin dlucas>

v A user login that is performed to another domain other than their local domain.Authentication is required.pdadmin> login -a dlucas -p lucaspw -d domain_apdadmin dlucas@domain_a>

v A user login that is performed to the management domain. Authentication isrequired.pdadmin> login -a dlucas -p lucaspw -mpdadmin dlucas@Default>


Options

–a admin_idSpecifies an administrator ID.

–d domainSpecifies the Security Access Manager secure domain for the login. Theadmin_id user must exist in this domain.

–m Specifies that the login operation must be directed to the managementdomain. The admin_id user must exist in this domain.

Note: Only one of the following domain options can be specified: –ddomain or –m. If neither option is specified, the target domain is the localdomain that is configured for the system. The admin_id user must exist inthe target domain, whether it is explicitly specified.

–p passwordSpecifies the password for the admin_id user. If this option is not specified,the user is prompted for the password. The password cannot be specifiedif the admin_id is not specified.

–l Specifies a local login operation. When modifications are made to localconfiguration files by using the config commands, a local login is requiredbefore you can run commands. The user can run the context showcommand to view more authentication information.

Return codes



Examplesv The following example logs the sec_master user in to the management domain

and then displays the authentication context for the user:pdadmin> login -a sec_master -p pa55w0rd -m

pdadmin sec_master> context show

User: sec_masterDomain: DefaultThe user is logged in to the management domain.

v The following example logs in a user to the domain1 domain and then displaysthe authentication context for the user:pdadmin> login -a domain1_admin -p d0main1pwd -d domain1

pdadmin domain1_admin@domain1> context show

User: domain1_adminDomain: domain1The user is not logged in to the management domain

v The following example interactively logs in the user to their local domain that isconfigured for the system. The domain name is testdomain. The example thendisplays the authentication context of the user:


pdadmin> loginEnter User ID: testdomain_adminEnter password: adminpwd

pdadmin testdomain_admin> context show

User: testdomain_adminDomain: testdomainThe user is not logged in to the management domain

v The following example of a local login demonstrates how the prompt changes,depending on the type of interactive login:c:\> pdadmin login -l

Provides this prompt:pdadmin local>

logoutDiscards any authentication credentials that are in effect.


Syntax

logout

Options

None.

Return codes



Examplesv The following example first shows a local login and then demonstrates how the

prompt changes:pdadmin login -lpdadmin local>

The following example demonstrates the logout command:pdadmin local> logout

v The following example displays:– Context information about the user ID.– Context information about the domain ID.– Whether the domain is a management domain.pdadmin domain1_admin@domain1> context showUser: domain1_adminDomain: domain1The user is not logged in to the management domain.


The following example shows a logout command, and then displays contextinformation after the logout command was issued:pdadmin domain1_admin@domain1> logoutThe user has been logged out and credentials have been discarded.

pdadmin>context showNo login information.

See also

“exit or quit” on page 55“login” on page 65“context show” on page 48

object accessConfirms whether the specified access is permitted on the specified object. Theaccess is determined based on the permissions of this user.


Syntax

object access object_name permissions

Options

object_nameSpecifies the protected object, which is the fully qualified name of theobject, including the object space within which it is located.


v /WebSEAL

v /Management

permissionsSpecifies the permission or permissions to check. Security Access Manageruses a set of default actions that cover a wide range of operations. Actionsare represented by single alphabetic ASCII characters (a-z, A-Z).

For example, a list of primary action tasks and associated permissions forthe user sec_master, with WebSEAL as the web server, might include:TTraverseBasecControlBasegDelegationBasemModifyGenericdDeleteGenericbBrowseBasesServer AdminGenericvViewGenericaAttachBaseBBypass POPBasetTraceBaserReadWebSEALxExecuteWebSEALlList DirectoryWebSEAL


NCreateBaseWPasswordBaseAAddBaseRBypass AuthzRuleBase

Return codes



Examplesv The following example confirms whether the user who is running pdadmin has

the Bypass POP (B) permission on the object named /Management:pdadmin sec_master> object access /Management B

The output is like:Access: No

v The following example confirms whether the user who is running pdadmin hasaction Password (W) permission on the object named /Management/test-object:pdadmin sec_master> object access /Management/test-object W

The output is like:Access: Yes

See also

“object listandshow” on page 74“object show” on page 77

object createCreates a protected object.

Authentication (administrator ID and password) required to use this command.

Syntax

object create object_name object_description type ispolicyattachable {yes|no}

Options

object_descriptionSpecifies any text string that describes the object that is being created.


An example of a description is "Travel Groups".


ispolicyattachable {yes|no}Specifies whether an ACL, a protected object policy, or an authorizationrule can be attached to this object. Valid values are yes or no.

object_nameSpecifies the name for the protected object that is being created. This nameis the fully qualified name of the object, including the object space withinwhich it is located. This name must be unique.

A valid object name is an alphanumeric string that is not case-sensitive.String values are expected to be characters that are part of the local codeset.


v /WebSEAL

v /Management

type Specifies the type of object to be created. Types range from 0 to 17. Forexample, types 10 or 16 are appropriate for container objects. Object typesare described in the IBM Security Access Manager for Web: AdministrationGuide.

You can assign any of the following types:0 Unknown1 Secure domain2 File3 Executable program4 Directory5 Junction6 WebSEAL server7 Unused8 Unused9 HTTP server10 Nonexistent object11 Container object12 Leaf object13 Port14 Application container object15 Application leaf object16 Management object17 Unused

Return codes



Examplesv The following example creates the object named /Management/test-object that

has a description of Test Object and is an application container object (14). AnACL or a protected object policy can be attached to this object:


pdadmin sec_master> object create /Management/test-object "Test Object" 14ispolicyattachable yes

v The following example creates the object named /Management/Groups/Travel thathas a description of Travel Container Object and is an application containerobject (14). An ACL or a protected object policy cannot be attached to this object:pdadmin sec_master> object create /Management/Groups/Travel "TravelContainer Object" 14 ispolicyattachable no

See also

“object exists” on page 72“object delete”

object deleteDeletes a protected object.


Syntax

object delete object_name

Options

object_nameSpecifies the protected object to be deleted, which is the fully qualifiedname of the object, including the object space in which it is located. Theobject must exist, or an error is displayed.


v /WebSEAL

v /Management

Return codes



Examplesv The following example deletes the object named /Management/test-object:

pdadmin sec_master> object delete /Management/test-object

v The following example deletes the object named /Management/Groups/Travel:pdadmin sec_master> object delete /Management/Groups/Travel

See also

“object exists” on page 72“object create” on page 69


object existsIndicates whether a protected object exists.

The protected object might be located either in:v The policy database, or inv An object space that is managed by an administration service plug-in.

The administration service plug-in might be registered by an authorizationapplication, such as WebSEAL. Use this command to determine whether thespecified object was created.

Authentication (administrator ID and password) is required to use this command.

Syntax

object exists object_name

Options

object_nameSpecifies the protected object, which is the fully qualified name of theobject, including the object space within which it is located.


v /WebSEAL

v /Management

Return codes



Examplesv The following example confirms whether the object named /Management/

protected_object1 exists:pdadmin sec_master> object exists /Management/protected_object1

The output is like:Exists: Yes

v The following example confirms whether the object named /Management/notAnObject exists:pdadmin sec_master> object exists /Management/notAnObject

The output is like:Exists: No


See also

“object listandshow” on page 74“object show” on page 77

object listLists any objects that are grouped under the specified protected object.Alternatively, lists all the extended attributes that are associated with the specifiedprotected object.


Syntax

object list

object list object_name

object list object_name attribute

Options

object listLists all protected objects. The output is the same as if you issued theobjectspace list command.

object list object_nameLists all objects that are grouped under the specified protected object. Thespecified object is the fully qualified name of the object, including theobject space within which it is located.

object list object_name attributeLists all extended attributes that are associated with the specified protectedobject. The object must exist, or an error is displayed.

Return codes




Examplesv The following example lists all the protected object spaces under the root of the

object namespace (/):pdadmin sec_master> object list

Displays a list like:/Management/MyObjectSpace_1.../WebSEAL


v The following example lists all the protected objects under the protected objectnamed /Management. In this example, both /Management and /Management/ACL areobject spaces:pdadmin sec_master> object list /Management

Displays a list like:/Management/ACL/Management/Action/Management/Config.../Management/test-object

v The following example lists the extended attributes for the object named/Management/test-object:pdadmin sec_master> object list /Management/test-object attribute

Displays a list of attributes like:test1

See also

“object listandshow”“object show” on page 77

object listandshowLists any child objects that are grouped under the specified protected object anddisplays all values that are associated with each object. Shows all values that areassociated with the protected object, including the attached ACLs, POPs, andauthorization rules. Also shows any policies that are inherited from protectedobjects higher in the hierarchy.


Syntax

object listandshow object_name

Options

object_nameSpecifies the protected object for which the child objects and associatedvalues are to be displayed. The specified protected object is the fullyqualified name of the object, including the object space within which it islocated.


v /WebSEAL

v /Management

Return codes





Examplesv The following example lists the object named /Management/Groups/Travel and

also automatically lists extended attributes, if any:pdadmin sec_master> object listandshow /Management/Groups/Travel

Displays information like:Name : /Management/Groups/TravelDescription : Travel Container ObjectType : <Application Container Object> : 14Is Policy Attachable : noExtended Attributes :test11111

v The following example displays the object named /Management/test-object andlists any attached policies (myrule) and effective policies (myacl and mypop):pdadmin sec_master> object listandshow /Management/test-object

Displays information like:Name : /Management/test-objectDescription : Test ObjectType : <Application Container Object> : 14Is Policy Attachable : yesAttached ACL :Attached Policy :Attached AuthzRule : myruleEffective ACL : myaclEffective Policy : mypopEffective AuthzRule : myrule

See also

“object list” on page 73“object show” on page 77

object modifyModifies an existing object.


Syntax

object modify object_name delete attribute attribute_name [attribute_value]

object modify object_name set attribute attribute_name attribute_value

object modify object_name set description description

object modify object_name set ispolicyattachable {yes|no}

object modify object_name set type type


Options

delete attribute attribute_name [attribute_value]Deletes the specified extended attribute (name and value) from thespecified protected object. The attribute must exist, or an error is displayed.When you delete the last value for an attribute, it also deletes the attributefrom the specified protected object. The optional attribute_value deletesthe specified value from the specified extended attribute key in thespecified protected object. Examples of attribute names and values:test11111Dept_No445Employee_name"Diana Lucas"

object_nameSpecifies the protected object to be modified. The specified protected objectis the fully qualified name of the object, including the object space withinwhich it is located. The object must exist, or an error is displayed.


v /WebSEAL

v /Management

set attribute attribute_name attribute_valueCreates an extended attribute, with the specified name and value, andadds it to the specified protected object. If the attribute exists, the attributevalue is added as an additional value if the same value does not exist forthis attribute. If the same value exists for this attribute, it does not getadded again (duplicate values are not allowed), and no error is returned.

The optional attribute_value sets the specified value from the specifiedextended attribute key in the specified protected object. The attribute valuemust exist, or an error is displayed.

Examples of extended attribute names and values:attr1valueAattr1valueBattr2valueC

set description descriptionSets the description field of the specified protected object.


Example of description: "Travel Group aaa"

set ispolicyattachable {yes|no}Sets whether the protected object can have an ACL, a POP, or anauthorization rule attached or not. Valid values are yes or no.

set type typeSpecifies the type of the object space to be created. Types range from 0 to17. For example, types 10 or 16 are appropriate for objects.

You can assign any of the following types:0 Unknown1 Secure domain2 File


3 Executable program4 Directory5 Junction6 WebSEAL server7 Unused8 Unused9 HTTP server10 Nonexistent object11 Container object12 Leaf object13 Port14 Application container object15 Application leaf object16 Management object17 Unused

Return codes



Examplesv The following example sets the ispolicyattachable option for the

/Management/Groups/Travel object:pdadmin sec_master> object modify /Management/Groups/Travel setispolicyattachable yes

v The following example sets the attributes for the /Management/test-objectobject:pdadmin sec_master> object modify /Management/test-object set attributetest1 1111

See also

“object create” on page 69

object showShows values for the protected object.

If the protected object name specified does not exist, default values are shown. Todetermine whether a protected object exists, use the object show command.


Syntax

object show object_name [attribute attribute_name]


Description

The object show command shows values that are associated with the protectedobject.

The object values shown can include:v ACLs.v POPs.v Authorization rules.v Extended attributes, such as attribute named value pairs.

These extended attributes can be attached directly to the object or inherited fromprotected objects in the hierarchy of this object.

When the attribute option is specified, the attribute_name value or values areshown if the attribute is attached to the protected object specified.

This command limits the output for POPs, ACLs, and authorization rules, whichare based on the permissions of the user. A user must have the view (v) permissionon the object to show it.

Options

object_nameSpecifies the protected object. The specified protected object is the fullyqualified name of the object, including the object space within which it islocated.


v /WebSEAL

v /Management

attribute attribute_nameSpecifies the name of the extended attribute whose values are to bedisplayed. (Optional) The extended attribute must exist for the object namethat is specified, or an error is displayed. In the example that is listed forthe /object-text object in “Examples,” the following extended attributesare shown:v test1

v test2

v abc

Return codes



Examplesv The following example displays the /object-test object and lists all attached

and effective ACLs, POPs, authzrules, and extended attributes:


pdadmin sec_master> object show /object-test

Displays information like:Name: /object-testDescription: Test objectType: 12 <Leaf Object>Is Policy Attachable : YesExtended Attributes:Name:test1Value(s): 1111Name:test2Value(s): abc2222secondAttached ACL:Attached POP:Attached AuthzRule:

Effective Extended Attributes:Protected Object Location: /object-testName:test1Value(s): 1111Name:test2Value(s): abc2222secondEffective ACL: default-rootEffective POP:Effective AuthzRule:

v The following example displays the /object-test/child1 object and lists allattached and effective ACLs, POPs, AuthzRules, and extended attributes:pdadmin sec_master> object show /object-test/child1

Displays information like:Name: /object-test/child1Description: Child 1Type: 12 <Leaf Object)>Is Policy Attachable : YesExtended Attributes:Attached ACL:Attached POP:Attached AuthzRule:

Effective Extended Attributes:Protected Object Location: /object-testName:test1Value(s): 1111Name:test2Value(s): abc2222secondEffective ACL: default-rootEffective POP:Effective AuthzRule:

v The following example displays information about the test1 attribute that islisted for object/object-test/child1:pdadmin sec_master> object show /object-test/child1 attribute test1

Because the test1 attribute is an extended attribute of the /object-test object,the command returns the following message:


Could not perform the administration requestError: HPDAC0463E There are no extended attributes associated with thespecified protected object or authorization policy object. (status0x1005b1cf)

To view the information about the test1 attribute of the /object-test object,enter the following command:pdadmin sec_master> object show /object-test attribute test1

Displays information like:test11111

v The following example displays the /Management/test-object object, which listsany attached (myrule) and effective (myacl and mypop) policies:pdadmin sec_master> object show /Management/test-object

Displays information like:Name: /Management/test-object/Description : Test objectType: 14 <Application Container Object>Is Policy Attachable: YesExtended Attributes:Attached ACL: myaclAttached Policy: mypopAttached AuthzRule: myrule

Effective Extended Attributes:Effective ACL: myaclEffective Policy: mypopEffective AuthzRule: myrule

v The following example creates a protected object and then performs an objectshow of that protected object. An object show is then performed for an objectthat has not been created. Then the object exist command is issued for both ofthese objects.pdadmin sec_master> object create /Management/new_object1" "0ispoly

pdadmin sec_master> object show /Management/new_object1Name: /Management/new_object1Description:Type: 0 (Unknown)Is Policy Attachable: YesExtended Attributes:Attached ACL:Attached POP:Attached AuthzRule:

Effective Extended Attributes:Effective ACL: default-managementEffective POP:Effective AuthzRule:

pdadmin sec_master> object show /Management/not_there_objectName: /Management/not_there_objectDescription:Type: 0 (Unknown)Is Policy Attachable: YesExtended Attributes:Attached ACL:Attached POP:Attached AuthzRule:

Effective Extended Attributes:


Effective ACL: default-managementEffective POP:Effective AuthzRule:

pdadmin sec_master> object exist /Management/new_object1Exists: Yespdadmin sec_master> object exist /Management/not_there_objectExists: No

See also

“object list” on page 73“object list” on page 73“object listandshow” on page 74

objectspace createCreates a protected object space under which protected objects can be placed.


Syntax

objectspace create objectspace_name description type

Description

The root of the new protected object space automatically has theispolicyattachable option that is set to true.

Options

descriptionSpecifies the description of the new object space.


An example description is "Accounting".

objectspace_nameSpecifies the name of the object space to be created.

A valid object space name is an alphanumeric string that is notcase-sensitive. String values are expected to be characters that are part ofthe local code set.

Examples of object space names are /Management and /WebSEAL.

type Specifies the type of the object space to be created. Types range from 0 to17. For example, types 10 or 16 are appropriate for objects and objectspaces.

You can assign any of the following types:0 Unknown1 Secure domain2 File3 Executable program


4 Directory5 Junction6 WebSEAL server7 Unused8 Unused9 HTTP server10 Nonexistent object11 Container object12 Leaf object13 Port14 Application container object15 Application leaf object16 Management object17 Unused

Return codes



Examplesv The following example creates an object space named /Test-Space that is an

application container object (type 14):pdadmin sec_master> objectspace create /Test-Space "New Object Space" 14

v The following example creates an object space named /Dept4D4 that is amanagement object (type 16):pdadmin sec_master> objectspace create /Dept4D4 "Department 4D4" 16

See also

“objectspace delete”

objectspace deleteDeletes the specified protected object space.


Syntax

objectspace delete objectspace_name

Options

objectspace_nameSpecifies the name of the object space to be deleted. The object space mustexist or an error is displayed.

Examples of object space names are /Management and /WebSEAL.

Return codes




Examplesv The following example deletes the object space named /Test-Space:

pdadmin sec_master> objectspace delete /Test-Space

v The following example deletes the object space named /Dept4D4:pdadmin sec_master> objectspace delete /Dept4D4

See also

“objectspace create” on page 81

objectspace listLists all the existing protected object spaces in the policy server.


Syntax

objectspace list

Options

None.

Return codes



Example

The following example lists all the protected object spaces:pdadmin sec_master> objectspace list

Displays a list like:/Management/MyObjectSpace_1.../WebSEAL

policy getDisplays the policy for user passwords, account rules, and conditions. Requiresauthentication (administrator ID and password) to use this command.


Syntax

policy get account-expiry-date [–user user_name]

policy get disable-time-interval [–user user_name]

policy get max-concurrent-web-sessions [–user user_name]

policy get max-login-failures [–user user_name]

policy get max-password-age [–user user_name]

policy get max-password-repeated-chars [–user user_name]

policy get min-password-alphas [–user user_name]

policy get min-password-length [–user user_name]

policy get min-password-non-alphas [–user user_name]

policy get password-spaces [–user user_name]

policy get tod-access [–user user_name]

Options

–user user_nameSpecifies the user whose policy information is to be displayed. If thisoption is not specified, the general policy is displayed. For any specifiedpolicy, if a user has a specific policy that is applied, this specific policytakes precedence over any general policy that might also be defined. Theprecedence applies regardless of whether the specific policy is more or lessrestrictive than the general policy. Examples of user names are dlucas,sec_master, and "Mary Jones". (Optional)

account-expiry-dateDisplays the account expiration date.

disable-time-intervalDisplays the time, in seconds, to disable user accounts when the maximumnumber of login failures is exceeded.

max-concurrent-web-sessionsDisplays the maximum number of concurrent web sessions. The value is anumber equal to or greater than 1 or one of the following values:

displaceAll existing web sessions end when the user starts a new websession.

unlimitedThe user can start an unlimited number of web sessions.

unset The web session policy is not set.

This policy applies only to certain components. A web session is a usersession that is maintained by a web security solution, such as WebSEAL orthe plug-in for web servers. See component administration guides todetermine whether this setting is applicable and whether specificconfiguration options are required to enforce this policy.


max-login-failuresDisplays the maximum number of login failures. To enforce maximumlogin failures, the disable-time-interval parameter must be set. For moreinformation, see the disable time interval section.

max-password-ageDisplays the maximum time that a password is valid. The time is indicatedin days, expressed as 000–00:00:00. For example, 31-08:30:00 for 31 days,8 hours, 30 minutes, 0 seconds. This time is relative to the last time thepassword was changed.

max-password-repeated-charsDisplays the maximum number of repeated characters that are allowed in apassword.

min-password-alphasDisplays the minimum number of alphabetic characters that are required ina password.

min-password-lengthDisplays the minimum password length.

min-password-non-alphasDisplays the minimum number of non-alphabetic characters that arerequired in a password.

password-spacesDisplays whether spaces are allowed in passwords.

tod-accessDisplays the time of day access policy.

Return codes



Examplesv The following example returns the account expiration date of unlimited for the

specified user dlucas:pdadmin sec_master> policy get account-expiry-date -user dlucasAccount expiry date: unlimited

v The following example returns the maximum time of 0 days, where zeroindicates unlimited, that the password is valid for the specified user dlucas:pdadmin sec_master> policy get max-password-age -user dlucas

For unlimited password age, returns information like:Maximum password age: 0-0:0:0

See also

“policy set” on page 86


policy setSets the policy for user passwords, account rules, and conditions. Requiresauthentication (administrator ID and password) to use this command.

Syntax

policy set account-expiry-date {unlimited|absolute_time|unset} [–useruser_name]

policy set disable-time-interval {number|unset|disable} [–user user_name]

policy set max-concurrent-web-sessions {number|displace|unlimited|unset}[–user user_name]

policy set max-login-failures {number|unset} [–user user_name]

policy set max-password-age {unset|relative_time} [–user user_name]

policy set max-password-repeated-chars {number|unset} [–user user_name]

policy set min-password-alphas {unset|number} [–user user_name]

policy set min-password-length {unset|number} [–user user_name]

policy set min-password-non-alphas {unset|number} [–user user_name]

policy set password-spaces {v|no|unset} [–user user_name]

policy set tod-access {{anyday|weekday|day_list}:{anytime|time_spec}[:{utc|local}]|unset} [–user user_name]

Description

The valid range for numbers can be any number. However, use a reasonablenumber for the task that you want to complete. For example, a minimumpassword length must be long enough to protect your system. In addition, thepassword must not be so short as to make it easy for someone to determine yourpassword by trying different combinations.

When you define the password policy, ensure that this definition complies with thepassword policy of the underlying operating systems and user registries.

Options

account-expiry-date {unlimited|absolute_time|unset}Sets the account expiration date. The absolute_time format is specified inthe following format:YYYY-MM-DD-hh:mm:ss

The hours must be entered by using a 24-hour clock (for example, 09 for 9a.m. or 14 for 2 p.m.). The default value is unset.

If you set the account expiration date, it is set for all accounts that do notuse the –user user_name option. By default, the sec_master user account


has a per-user account expiration date of unlimited. If you set the accountexpiration date to unlimited, do the following actions:v Set max-password-age to 0 for unlimited.v Set tod-access to anyday:anytime:local.v Use the –user user_name option.

disable-time-interval {number|unset|disable}Sets the time, in seconds, to disable each user account when the maximumnumber of login failures is exceeded. Security Access Manager does notimpose an upper limit for the maximum number allowed. Use a rangefrom 0 (unlimited) to a number that represents the value that is mostlogical for the parameter you are trying to set. The default value is 180seconds.

max-concurrent-web-sessions {number|displace|unlimited|unset}Sets the maximum number of concurrent web sessions. This policy appliesonly to certain components. A web session is a user session that ismaintained by a web security solution, such as WebSEAL or the plug-in forweb Servers. See component administration guides to determine whetherthis setting is applicable and whether specific configuration options arerequired to enforce this policy.

This option supports the following values:

numberSpecifies the maximum number of concurrent web sessions thatcan be established. This value is a number that is equal to orgreater than one.

displaceSpecifies that if a user starts a new web session, any existing websession ends.

unlimitedAllows unlimited concurrent web sessions.

unset Specifies to unset concurrent web session policy.

max-login-failures {number|unset}Sets the maximum number of login failures allowed. Security AccessManager does not impose an upper limit for the maximum numberallowed. Instead, use a range from zero to a number that represents thevalue that is most logical for the parameter you are trying to set. If thenumber is too large, it might render the login policy ineffective. Thedefault value is 10.

To enforce maximum login failures, the disable-time-interval parametermust be set. See disable-time-interval for more information aboutdisable-time-interval.

max-password-age {unset|relative_time}Sets the maximum time, in days, that a password is valid. This policy is aglobal password policy as opposed to the individual user policy. Theindividual user policy:v Is set by using the user modify command with the user_name

password-valid option.v Enables or disables the validity of a password for the specified user

account.


The relative_time option is relative to the number of days since the lastpassword change occurred. The relative_time format is specified in thefollowing format:DDD-hh:mm:ss

The valid range is from 000–00:00:00 to 999–23:59:59. A value of zero(000–00:00:00) indicates that the password never expires. The defaultvalue is 91 days. This value is expressed as 91–00:00:00.

max-password-repeated-chars {number|unset}Sets the maximum number of consecutively, repeated characters that areallowed in a password. Security Access Manager does not impose an upperlimit on the maximum number allowed. Instead, use a range from 0 to anumber that represents the most logical value for the parameter you aretrying to set. If the number is too large, it might render the passwordpolicy ineffective. The default value is 2.

Example: If max-password-repeated-chars is set to 2, then password andpspassword are both valid values. However, passsword is not valid becausethe character s occurs three times consecutively.

min-password-alphas {unset|number}Sets the minimum number of alphabetic characters that are required in apassword. Security Access Manager does not impose an upper limit for theminimum number allowed. Instead, use a number that represents the valuethat is most logical for the parameter you are trying to set. If the number istoo small, it might render the password policy ineffective. The defaultvalue is 4.

min-password-length {unset|number}Sets the minimum password length. Security Access Manager does notimpose an upper limit for the minimum number allowed. Instead, use anumber that represents the value that is most logical for the parameter youare trying to set. If the number is too large, the password policy might bedifficult to adhere to. The default value is 8.

min-password-non-alphas {unset|number}Sets the minimum number of non-alphabetic characters that are required ina password. Security Access Manager does not impose an upper limit forthe minimum number allowed. Instead, use a number that represents thevalue that is most logical for the parameter you are trying to set. If thenumber is too large, the password policy might be difficult to adhere to.The default value is 1.

password-spaces {v|no|unset}Sets the policy of whether spaces are allowed in passwords. The defaultvalue is unset.

tod-access {{anyday|weekday|day_list}:{anytime|time_spec} [:{utc|local}]|unset}Sets the time of day access policy.

The day_list is a comma-separated list of days of the week, each of whichis represented by a three-character value (for example, mon,wed,fri). Theday_list specifies which days of the week you can log in to the account. Ifyou want to list every day of the week, specify anyday; if you do not wantto include the weekend days, specify weekday.

The time_spec format is specified in the following format:hhmm


The format is expressed by using a 24-hour clock. For example, 0900 for 9a.m. or 1430 for 2:30 p.m. The default value is unset, and the optional timezone is local by default. The time_spec value and time zone specify thetime of day when you can log in to the account.

Note:

v utc=GMT

v When you modify a password policy, you provide a list of days, starttime, and end time. The start time and end time apply to each day onthe list. If the specified start time is greater than the specified end time,then the access is allowed until the specified end time of the next day.

–user user_nameSpecifies the user whose policy information is to be set. If this option is notspecified, the general policy is set. For any specified policy, if a user has aspecific policy that is applied, this specific policy takes precedence overany general policy that might also be defined. The precedence appliesregardless of whether the specific policy is more or less restrictive than thegeneral policy.

A valid user name is an alphanumeric string that is not case-sensitive.String values are expected to be characters that are part of the local codeset.

Examples of user names are dlucas, sec_master, and "Mary Jones".(Optional)

Return codes



Examplesv The following example sets the account expiration date of December 30, 1999, at

11:30 p.m. for the specified user dlucas:pdadmin sec_master> policy set account-expiry-date 1999-12-30-23:30:00-user dlucas

v The following example sets the maximum password age of 31 days, 8 hours, 30minutes, and 0 seconds for the specified user dlucas:pdadmin sec_master> policy set max-password-age 031-08:30:00 -user dlucas

v The following example sets the maximum of 12 concurrent web sessions:pdadmin sec_master> policy set max-c 12

See also

“policy get” on page 83


pop attachAttaches a protected object policy (POP) to the specified protected object. The POPmust be created before it can be attached.


Syntax

pop attach object_name pop_name

Description

At most, one POP can be attached to a given protected object. If the object alreadyhas a POP attached to it, the specified POP replaces the existing one. The samePOP can be attached to multiple protected objects. Ensure that the protected objectexists in the protected object space before you attempt to attach a POP.

Options

object_nameSpecifies the name of the protected object to which the protected objectpolicy is attached. The object must exist, or an error is displayed.


v /WebSEAL

v /Management

pop_nameSpecifies the name of the protected object policy to be attached. The POPmust exist, or an error is displayed.

Examples of POP names are poptest and pop1.

Return codes



Examplesv The following example attaches the POP pop1 to the protected object named

/Management/test-object:pdadmin sec_master> pop attach /Management/test-object pop1

v The following example attaches the POP poptest to the protected object named/Test-Space:pdadmin sec_master> pop attach /Test-Space poptest

See also

“pop create” on page 91“pop detach” on page 92


pop createCreates a protected object policy (POP).


Syntax

pop create pop_name

Options

pop_nameSpecifies the name of the POP to be created. A valid protected object policyname is an alphanumeric string that is not case-sensitive. String values areexpected to be characters that are part of the local code set. Spaces are notallowed. Avoid the following characters in the POP name:! " # & ( ) * + , ; : < > = @ / \ | .

Note: Although a POP name can contain 1 or more of these characters, theresults of using such a POP are undefined.


Return codes



Example

The following example shows how to create and display a POP:pdadmin sec_master> pop create test

The new POP contains new POP settings like:pdadmin sec_master> pop show test

Protected object policy:testDescription:Warning:noAudit Level:noneQuality of protection: noneTime of day access: sun, mon, tue, wed, thu, fri, sat:anytime: localIP Endpoint Authentication Method PolicyAny Other Network 0

See also

“pop attach” on page 90“pop delete” on page 92


pop deleteDeletes the specified protected object policy (POP).


Syntax

pop delete pop_name

Options

pop_nameSpecifies the name of the POP to be deleted. The POP must exist, or anerror is displayed. Examples of POP names are poptest and pop1.

Return codes



Examplesv The following example deletes the POP pop1:

pdadmin sec_master> pop delete pop1

v The following example deletes the POP poptest:pdadmin sec_master> pop delete poptest

See also

“pop create” on page 91“pop detach”

pop detachDetaches a protected object policy (POP) from the specified protected object.


Syntax

pop detach object_name

Options

object_nameSpecifies the protected object from which the POP is to be detached. Theobject must exist and have a POP attached, or an error is displayed.


v /WebSEAL

v /Management


Return codes



Examplesv The following example detaches all POPs from the protected object named

/Management/test-object:pdadmin sec_master> pop detach /Management/test-object

v The following example detaches all POPs from the protected object named/Test-Space:pdadmin sec_master> pop detach /Test-Space

See also

“pop attach” on page 90“pop delete” on page 92

pop findFinds and lists all protected objects that have a protected object policy (POP)attached.


Syntax

pop find pop_name

Description

A user must have the browse (b) and view (v) permissions for the object to belisted when the object show command is issued. Otherwise, an error is returned:The user is not authorized to view one or more protected objects where therequested acl is attached.

Options

pop_nameSpecifies the name of the POP for which to search. The POP must exist, oran error is displayed. Examples of POP names are poptest and pop1.

Return codes




Examplesv The following example finds all objects to which the POP pop1 is attached:

pdadmin sec_master> pop find pop1

/Management/test-object

v The following example finds all objects to which the POP poptest is attached:pdadmin sec_master> pop find poptest

/Test-Space

See also

“pop list”

pop listLists all protected object policies that are created. Alternatively, lists all extendedattributes that are associated with a protected object policy.


Syntax

pop list [pop_name attribute]

Options

pop_name attributeSpecifies the POP for which to list the attributes. The POP must exist, or anerror is displayed. (Optional)


Return codes



Examplesv The following example shows how to list all POPs:

pdadmin sec_master> pop list

testpop1poptest

v The following example shows how to list all the attributes for the POP namedpop1:pdadmin sec_master> pop list pop1 attribute

attr1


See also

“pop find” on page 93

pop modifyModifies protected object policies.


Syntax

pop modify pop_name delete attribute attribute_name [attribute_value]

pop modify pop_name set attribute attribute_name attribute_value

pop modify pop_name set audit-level {all|none|audit_level_list}

pop modify pop_name set description description

pop modify pop_name set ipauth add network netmask level

pop modify pop_name set ipauth anyothernw level

pop modify pop_name set ipauth remove network netmask

pop modify pop_name set qop {none|integrity|privacy}

pop modify pop_name set tod-access{anyday|weekday|day_list}:{anytime|time_spec-time_spec}[:{utc|local}]

pop modify pop_name set warning {yes|no}

Description

The pop modify command modifies a protected object policy (POP). When you usethe set ipauth add or set ipauth remove options, you can specify the IP addresses.The values for the network and netmask options are TCP/IP addresses. These IPaddresses can be specified by using either version 4 (IPv4) or version 6 (IPv6)notation. Both the network and netmask options must be specified in the same IPversion.

Note: When you use IPv6 notation, do not use prefix notation when you specify IPaddresses.

When you specify IP addresses, be aware of the following restrictions:v For administration commands, IPv4 clients must provide addresses in IPv4

format even with IPv6 servers.v For C APIs, IPv4 clients must provide addresses in IPv4 format even with IPv6

servers.v For C APIs, IPv6 clients can provide addresses in IPv4 or IPv6 format to IPv6

servers.v For Java methods, IPv4 and IPv6 clients must provide addresses in IPv4 format

to IPv4 servers.


v For Java methods, IPv4 clients can provide addresses in IPv4 or IPv6 format toIPv6 servers.

For an IPv6 address to be accepted (commands, C APIs, and Java methods), theserver must be IPv6. You cannot provide an IPv6 address to an IPv4 server.

The operating system functions that are provided to Security Access Manager havecertain limitations. Regardless of C or Java clients, IPv4 addresses must be in IPv4format when you add addresses to a POP.

Options

delete attribute attribute_name [attribute_value]Deletes the specified value from the specified extended attribute key in thespecified POP. The attribute must exist, or an error is displayed.

The optional attribute_value deletes the specified value from the specifiedextended attribute key in the specified POP.

Examples of extended attribute names and values:Dept_No445Employee_Name"Diana Lucas"

pop_nameSpecifies the name of the protected object policy to be modified. The POPmust exist, or an error is displayed.

set attribute attribute_name attribute_valueSets or modifies the specified value from the specified extended attributekey in the specified POP. If the attribute exists, the attribute value is addedas an additional value if the same value does not exist for this attribute. Ifthe same value exists for this attribute, it does not get added again(duplicate values are not allowed), and no error is returned.

The attribute_value sets the specified value from the specified extendedattribute key in the specified POP.

Example: "Credit Card"

set audit-level {all|none|audit_level_list}Sets the audit level for the specified POP. The format of anaudit_level_list is a comma-separated list that contains one or more ofthese audit levels: permit,deny,error,admin.

set description descriptionSets the description of the specified POP.


Example of description: "Policies of Jenson Corp."

set ipauth add network netmask levelSets the IP endpoint authentication settings in the specified POP. Thevalues for the network and netmask options are TCP/IP addresses. These IPaddresses can be specified by using either version 4 (IPv4) or version 6(IPv6) addresses. Both the network and netmask options must be specifiedin the same IP version.

The following values are supported for level:


forbiddenA value that prohibits object access.

integer_valuesApplication-specific integer values that define the step-upauthentication levels. All integer values, except 1000, aresupported. For more information about step-up authentication, theIBM Security Access Manager for Web: Administration Guide.

set ipauth anyothernw levelSets the anyothernw (any other network setting) for the IP authenticationlevel in the specified POP. If you are controlling access by IP address is notimportant, use the anyothernw option to set the authentication level for:v All IP addresses, andv IP address ranges not listed explicitly in the POP.

The following values are supported for level:

forbiddenA value that prohibits object access.

integer_valuesApplication-specific integer values that define the step-upauthentication levels. All integer values, except 1000, aresupported. For more information about step-up authentication, theIBM Security Access Manager for Web: Administration Guide.

set ipauth remove network netmaskRemoves the IP endpoint authentication settings from the specified POP.The values for the network and netmask options are TCP/IP addresses.These IP addresses can be specified by using either version 4 (IPv4) orversion 6 (IPv6) notation. Both the network and netmask options must bespecified in the same IP version.

set qop {none|integrity|privacy}

Sets the quality of protection level for the specified POP. The followingstring values are supported:v nonev integrityv privacy

set tod-access {anyday|weekday|day_list}:{anytime|time_spec-time_spec}[:{utc|local}]

Sets the time of day range for the specified protected object policy.

The day_list is a comma-separated list of days of the week, each of whichis represented by a three-character value (for example, mon,wed,fri). Theday_list specifies which days of the week the object can be accessed. Ifyou want to list every day of the week, specify anyday; if you do not wantto include the weekend days, specify weekday.

The time_spec format is specified as hhmm and is expressed by using a24-hour clock (for example, 0900 for 9 a.m. or 1430 for 2:30 p.m.). Thedefault value is not defined, and the optional time zone is local bydefault. The time_spec value and time zone specify the time of day theobject can be accessed.

Note: utc=GMT


set warning {yes|no}Sets the warning mode for the specified protected object policy. Validvalues are yes or no.

Return codes



Examplesv This example shows how to modify the description for the POP named test:

pdadmin sec_master> pop modify test description "Test POP"

v This example shows how to turn on the warning mode or the POP named test:pdadmin sec_master> pop modify test set warning yes

v This example shows how to set the audit level to audit all requests on aprotected object that result in successful:– Access by using permit.– Denial of access by using deny.pdadmin sec_master> pop modify test set audit-level permit,deny

v This example shows how to set an attribute named attr1 with a value of valueAfor the POP named pop1:pdadmin sec_master> pop modify pop1 set attribute attr1 valueA

See also

“pop attach” on page 90“pop create” on page 91

pop showShows details about the protected object policy (POP). Alternatively, displays thevalues for the specified extended attribute from the specified protected objectpolicy.


Syntax

pop show pop_name [attribute attribute_name]

Options

attribute attribute_nameSpecifies the name of the extended attribute whose values you want todisplay. The attribute must exist, or an error is displayed. Examples ofattribute names are Dept_No and Employee_Name. (Optional)

pop_nameSpecifies the POP to display. The POP must exist, or an error is displayed.Examples of POP names are poptest and pop1.


Return codes



Examplesv The following example shows how to show POP information, including the

description:pdadmin sec_master> pop show test

Protected object policy:testDescription:Test POPWarning:noAudit level:noneQuaility of protection:noneTime of day access: sun, mon, tue, wed, thu, fri, sat:anytime: localIP Endpoint Authentication Method PolicyAny Other Network 0

v The following example shows attribute attr1 information for the POP namedpop1:pdadmin sec_master> pop show pop1 attribute attr

attr1valueA

See also

“pop find” on page 93“pop list” on page 94

rsrc createCreates and names a web server single sign-on resource.


Syntax

rsrc create resource_name [–desc description]

Description

A web resource is a web server that serves as the back-end of a WebSEALGSO-enabled junction. The web resource name must be specified with the –Toption when the GSO-enabled WebSEAL junction is created.

Options

–desc descriptionSpecifies a description for the resource. Descriptions containing a spacemust be enclosed in double quotation marks. (Optional)


A valid description is an alphanumeric string that is not case-sensitive.String values are expected to be characters that are part of the local codeset. If the description contains a space, ensure that you enclose thedescription in double quotation marks.

Examples of descriptions are “Engineering Web server – Room 4807” and“Printer in room 345, Bldg 2”.

resource_nameSpecifies the name of the resource to be created.

A valid resource name is an alphanumeric string that is not case-sensitive.If the resource is a GSO resource, certain characters are not allowed. See“Characters disallowed for GSO names” on page 311 for the list of thesecharacters.

Examples of resource names are engwebs01 and JonesData.

Return codes



Examplesv The following example is entered as one line. This example creates and names a

web resource engwebs01 with an associated description "Engineering Web server– Room 4807":pdadmin sec_master> rsrc create engwebs01 –desc "Engineering Webserver – Room 4807"

v The following example is entered as one line. This example creates and names aprinter resource "Mary Jones Printer" with an associated description "Printerin room 345, Bldg 2":pdadmin sec_master> rsrc create "Mary Jones Printer" –desc "Printer inroom 345, Bldg 2"

See also

“rsrc delete”

rsrc deleteDeletes the specified single sign-on resource.


Syntax

rsrc delete resource_name

Options

resource_nameSpecifies the name of the resource to be deleted. The resource must exist,or an error is displayed.



Return codes



Examplesv The following example deletes the named resource engwebs01:

pdadmin sec_master> rsrc delete engwebs01

v The following example deletes the named resource "Mary Jones Printer":pdadmin sec_master> rsrc delete "Mary Jones Printer"

See also

“rsrc create” on page 99

rsrc listReturns a list of all the single sign-on resource names.


Syntax

rsrc list

Options

None.

Return codes



Example

The following example returns a list of all the single sign-on web resource names:pdadmin sec_master> rsrc list

The output is like:engwebs01Mary Jones Printer


See also

“rsrc create” on page 99

rsrc showDisplays the resource information for the named resource.


Syntax

rsrc show resource_name

Options

resource_nameSpecifies the name of the resource for which information is shown. Theresource must exist, or an error is displayed.


Return codes



Examplesv The following example returns information for the specified resource engwebs01:

pdadmin sec_master> rsrc show engwebs01

The output is like:Web Resource Name: engwebs01Description: Engineering Web server - Room 4807

v The following example returns information for the specified resource "MaryJones Printer":pdadmin sec_master> rsrc show "Mary Jones Printer"

Output is like:Web Resource Name: Mary Jones PrinterDescription: Printer in room 345, Bldg 2

See also

“rsrc list” on page 101

rsrccred createCreates a single sign-on credential.



Syntax

rsrccred create resource_name rsrcuser resource_userid rsrcpwdresource_password rsrctype {web|group} user user_name

Description

A resource credential is a credential that is used to identify the authenticationinformation of a user. WebSEAL uses the authentication information when itaccesses a back-end web resource or resource group through a GSO-enabledjunction. WebSEAL accesses these resources on behalf of that user.

For example, a user dlucas might require the authentication identity 4807ws01 andpassword pwd4lucas when accessing the engwebs01 web resource that is junctionedthrough WebSEAL.

A resource credential can be created with this authentication information. Then,WebSEAL automatically uses this information to access the engwebs01 serverwhenever the user dlucas accesses that resource.

Options

resource_nameSpecifies the name that is given to the resource or resource group when theresource or resource group was created. The resource or resource groupmust exist to create the resource credential. If the resource or resourcegroup does not exist or is not specified, an error message is displayed.

Examples of resource names are engwebs01 and "Mary Jones Printer".

rsrcpwd resource_passwordSpecifies the password for a user at the web server.

rsrctype {web|group}Specifies whether the resource type named is web (resource) or group(resource group).

rsrcuser resource_useridSpecifies the unique user identification (user ID) for the user at the webserver.

Examples of user identifications are 4807ws01 and userD4D.

user user_nameSpecifies the name of the user for whom the resource credentialinformation applies. If the user does not exist or is not specified, an errormessage is displayed.


Return codes




Examplesv The following example creates the web resource credential named engwebs01 for

the resource user ID 4807ws01 and password pwd4lucas given to user dlucas:pdadmin sec_master> rsrccred create engwebs01 rsrcuser 4807ws01rsrcpwd pwd4lucas rsrctype web user dlucas

v The following example creates the group resource credential namedprinterusers for the resource user ID userD4D and password pwd4mjones givento user "Mary Jones":pdadmin sec_master> rsrccred create printerusers rsrcuser userD4D rsrcpwdpwd4mjones rsrctype group user "Mary Jones"

See also

“rsrccred delete”“rsrccred modify” on page 106

rsrccred deleteDeletes a single sign-on credential.


Syntax

rsrccred delete resource_name rsrctype {web|group} user user_name

Options

resource_nameSpecifies the name that is given to the resource or resource group when theresource was created. The resource or resource group must exist, or anerror is displayed.


rsrctype {web|group}Specifies whether the resource type named is web (resource) or group(resource group) for the single sign-on resource that is associated with thecredential. The type of resource must match the resource type that isassigned when the resource or resource group was first created.

user user_nameSpecifies the name of the user for whom the resource credentialinformation applies. The user must exist, or an error is displayed.


Return codes




Examplesv The following example deletes the resource credential information for the

resource engwebs01, resource type web, and user name dlucas:pdadmin sec_master> rsrccred delete engwebs01 rsrctype web user dlucas

v The following example deletes the resource credential information for theresource printerusers, resource type group, and user name "Mary Jones":pdadmin sec_master> rsrccred delete printerusers rsrctype groupuser "Mary Jones"

See also

“rsrccred create” on page 102

rsrccred list userReturns the list of single sign-on credentials for the specified user. The user mustexist, or an error is displayed.


Syntax

rsrccred list user user_name

Options

user_nameSpecifies the name of the user for whom the resource credentialinformation applies. The user must exist, or an error is displayed.Examples of user names are dlucas, sec_master and "Mary Jones".

Return codes



Example

The following example returns the list of single sign-on credentials for thespecified user dlucas:pdadmin sec_master> rsrccred list user dlucas

The output is like:Resource Name: engwebs01Resource Type: web

See also

“rsrccred show” on page 107


rsrccred modifyChanges a single sign-on credential.


Syntax

rsrccred modify resource_name rsrctype {web|group} set [–rsrcusernew_resource_userid [–rsrcpwd new_resource_password]] user user_name

Options

–rsrcpwd new_resource_passwordSpecifies the new password for a user at the web server. To change or resetthe password information, this optional command must be preceded by adash (-). Specifying this option without specifying the –rsrcpwd optionclears both the resource user ID and the resource password from theresource credential. To set the resource password, you must specify boththe resource user ID and the resource password. (Optional)

–rsrcuser new_resource_useridSpecifies the new unique user identification (user ID) for the user at theweb server. To change or reset the resource user ID of the user, thisoptional command must be preceded by a dash (-). (Optional)

A valid new resource user ID is an alphanumeric string that is notcase-sensitive. String values are expected to be characters that are part ofthe local code set. Spaces are not allowed.

Examples of user identifications are 4807ws01 and userD4D.

resource_nameSpecifies the name that is given to the resource or resource group when theresource was created. The resource or resource group must exist, or anerror is displayed.


rsrctype {web|group}Specifies whether the resource type named is web (resource) or group(resource group) for the single sign-on resource that is associated with thecredential. The type of resource must match the resource type that isassigned when the resource or resource group credential was first created.

user user_nameSpecifies the name of the user for whom the resource credentialinformation applies. The user must exist, or an error is displayed.


Return codes




Examplesv The following example modifies the password of the user dlucas to newrsrpw for

the specified resource engwebs01:pdadmin sec_master> rsrccred modify engwebs01 rsrctype web set-rsrcuser 4807ws01 -rsrcpwd newrsrpw user dlucas

v The following example, entered as one line, modifies the group resource user IDto user888 for the specified resource printerusers:pdadmin sec_master> rsrccred modify printerusers rsrctype group set-rsrcuser user888 user "Mary Jones"

See also

“rsrccred create” on page 102

rsrccred showDisplays the attributes of a single sign-on credential. The credential identifier iscomposed of a resource name, a resource type, and a user name.


Syntax

rsrccred show resource_name rsrctype {web|group} user user_name

Options

resource_nameSpecifies the name of the single sign-on resource or resource group that isassociated with the credential. The resource or resource group must exist,or an error is displayed.

Examples of resource names are engwebs01 and printerusers.

rsrctype {web|group}Specifies whether the resource type named is web (resource) or group(resource group) for the single sign-on resource that is associated with thecredential. The type of resource must match the resource type that isassigned when the resource or resource group was first created.

user user_nameSpecifies the name of the user that is associated with this credential. Theuser must exist, or an error is displayed.


Return codes




Examplesv The following example displays the specified single sign-on credential:

pdadmin sec_master> rsrccred show engwebs01 rsrctype web user dlucas

The output is like:Resource Name: engwebs01Resource Type: webResource User Id: dlucas

v The following example displays the specified single sign-on credential:pdadmin sec_master> rsrccred show user888 rsrctype group user "Mary Jones"

The output is like:Resource Name: printerusersResource Type: groupResource User Id: Mary Jones

See also

“rsrccred list user” on page 105

rsrcgroup createCreates and names a resource group.


Syntax

rsrcgroup create resource_group_name [–desc description]

Description

You can use a resource group to represent a set of web servers when the sign-oncredential for the set of web servers is the same. In this case, web servers areconsidered resources.

For example, if the user dlucas has the same identity for web servers engwebs01and engwebs02, these resources can be added to a resource group called webs4807.Use the rsrcgroup modify command to add the resources to the group.

Then, you can create a single sign-on credential for the webs4807 resource groupfor dlucas. Then, that single sign-on credential can be used to access all the webservers in the webs4807 group.

Options

–desc descriptionSpecifies the description to identify this resource group. This parameter isoptional. A valid description is an alphanumeric string that is notcase-sensitive. String values are expected to be characters that are part ofthe local code set. If the description contains a space, ensure that youenclose the description in double quotation marks. (Optional)

Examples of descriptions are "Engineering Web server – Room 4807" and"Printer in room 345, Bldg 2".


resource_group_nameSpecifies the name of the resource group. A valid resource group name isan alphanumeric string that is not case-sensitive. If the resource is a GSOresource, certain characters are not allowed. See “Characters disallowed forGSO names” on page 311 for the list of these characters.

Examples of resource group names are webs4807, engwebs01, andIBMprinters.

Return codes



Examplesv The following example creates and names a web resource group IBMprinters:

pdadmin sec_master> rsrcgroup create IBMprinters

v The following example creates and names a web resource group namedwebs4807 and provides a description ("Web servers, Room 4807") for thatresource:pdadmin sec_master> rsrcgroup create webs4807 –desc "Web servers, Room 4807"

See also

“rsrcgroup delete”

rsrcgroup deleteDeletes a single sign-on resource group.


Syntax

rsrcgroup delete resource_group_name

Options

resource_group_nameSpecifies the name of the resource group. The resource must exist, or anerror is displayed.


Return codes




Example

The following example deletes the named resource group and its associateddescription information:pdadmin sec_master> rsrcgroup delete webs4807

See also

“rsrcgroup create” on page 108

rsrcgroup listDisplays the names of all resource groups that are defined in the user registry.


Syntax

rsrcgroup list

Options

None.

Return codes



Example

The following example returns a list of all single sign-on resource group names:pdadmin sec_master> rsrcgroup list

The output is like:webs4807websbld3

See also

“rsrcgroup show” on page 112

rsrcgroup modifyAdds or removes a single sign-on resource to or from a single sign-on resourcegroup.



Syntax

rsrcgroup modify resource_group_name add rsrcname resource_name

rsrcgroup modify resource_group_name remove rsrcname resource_name

Options

add rsrcname resource_nameAdds a single sign-on resource to the specified single sign-on resourcegroup.

A valid resource name is an alphanumeric string that is not case-sensitive.If the resource is a GSO resource, certain characters are not allowed. See“Characters disallowed for GSO names” on page 311 for the list of thesecharacters.


remove rsrcname resource_nameRemoves a single sign-on resource from the specified single sign-onresource group.


Note: Depending on the LDAP server in your environment, any attempt toremove a non-existing resource from a group, might generate an error.

resource_group_nameSpecifies the name of the resource group to be modified. The resourcegroup must exist, or an error is displayed.


Return codes



Examplesv The following example adds the resource named engwebs02 to the existing web

resource group webs4807:pdadmin sec_master> rsrcgroup modify webs4807 add rsrcname engwebs02

v The following example deletes the resource named engwebs02 from the existingweb resource group webs4807:pdadmin sec_master> rsrcgroup modify webs4807 remove rsrcname engwebs02

See also

“rsrcgroup create” on page 108


rsrcgroup showDisplays the resource group information for the specified resource group.


Syntax

rsrcgroup show resource_group_name

Description

The resource group name, the resource group description, and a list of all resourcegroup members names are displayed. The resource group members are theindividual web resources (servers).

Options

resource_group_nameSpecifies the name of the resource group.


Return codes



Example

The following example returns the specified single sign-on resource group namedwebs4807:pdadmin sec_master> rsrcgroup show webs4807

The output is like:Resource Group Name: webs4807Description: Web servers, Room 4807Resource Members:engwebs01engwebs02engwebs03

See also

“rsrcgroup list” on page 110

server listLists all registered Security Access Manager servers.



Syntax

server list

Description

Lists all registered Security Access Manager servers. The name of the server for allserver commands must be entered in the exact format as it is displayed in theoutput of this command. The server list command does not have such arequirement.

Options

None.

Return codes



Example

The following example lists registered servers:pdadmin> server list

The output is as follows:ivmgrd-masterivacld-server1ivacld-server2

where ivmgrd-master represents the Policy server; ivacld-server2 andivacld-server1 represent Authorization server instances.

server listtasksRetrieves the list of tasks (commands) available for the specified installed SecurityAccess Manager server or server instance.


Syntax

server listtasks server_name-host_name

Options

server_name-host_nameSpecifies the name of the installed Security Access Manager server orserver instance. You must specify the server_name in the exact format asdisplayed in the output of the server list command.


For example, if the configured name of a single WebSEAL server isdefault, the server_name is default-webseald followed by -host_name. Thefull server name–host name is default-webseald-cruz.dallas.ibm.com.

For multiple server instances on the same computer, if the configuredname of a WebSEAL server instance is webseal2-webseald, theinstance_name is followed by -host_name. The full server instancename–host name is webseal2-webseald-cruz.dallas.ibm.com.

Return codes



Examplesv The following example displays the list of tasks available from the authorization

server:pdadmin sec_master> server listtasks ivacld-mogman.admogman.com

The output is like:trace set component level [file path=file|other-log-agent-config]trace show [component]trace list [component]stats show [component]stats liststats on [component] [interval] [count][file path= file|other-log-agent-config]stats off [component]stats reset [component]stats get [component]

Note: You can run the command server listtasks ivmgrd-master to view thelist of tasks available from the Policy server. The output is similar to the outputlisted for the authorization server.

v The following example displays the list of tasks available from the WebSEALserver default-webseald-cruz:pdadmin sec_master server listtasks default-webseald-cruz

The output is like:dynurl updatejmt loadjmt clearcache flush allcreateaddremovedelete <junction point>listshow <junction point>reloadterminate all_sessions <user_id>terminate session <user_session_id>refresh all_sessions <user_id>help commandtrace set component level [file path=file|


other-log-agent-config]trace show [component]trace list [component]stats show [component]stats liststats on [component][interval][count][file path= file|other-log-agent-config]stats off [component]stats reset [component]stats get [component]

See also

“server list” on page 112“server show” on page 116

server replicateNotifies the installed Security Access Manager authorization server or serverinstance to receive database updates.


Syntax

server replicate [–server server_name-host_name]

Options

–server server_name-host_nameSpecifies the name of the installed Security Access Manager server orserver instance. You must specify the server_name in the exact format asdisplayed in the output of the server list command. (Optional)



Return codes



Example

Here is an example of this command when the server name is specified:pdadmin sec_master> server replicate -server ivacld-topserver


See also

“server list” on page 112“server show”

server showDisplays the properties for the specified installed Security Access Manager serveror server instance. The server must exist, or an error is displayed.


Syntax

server show server_name-host_name

Options

server_name-host_nameSpecifies the name of the installed Security Access Manager server orserver instance. You must specify the server_name in the exact format asdisplayed in the output of the server list command.



Return codes



Examplesv The following example displays the specified properties for the authorization

server (ivacld) on the mogman computer:pdadmin sec_master> server show ivacld-mogman

The output is like:ivacld-mogmanDescription: ivacld/mogmanHostname: mogmanPrincipal: ivacld/mogmanAdministration Request Port: 7137Listening for authorization database update notifications: yesAZN Administration Services:AZN_ADMIN_SVC_TRACE

v The following example displays the properties of the WebSEAL serverdefault-webseald-cruz:pdadmin sec_master> server show default-webseald-cruz


The output is like:default-webseald-cruzDescription: default-webseald-cruzHostname: cruz.dallas.ibm.comPrincipal: default-webseald/cruzAdministration Request Port: 7234Listening for authorization database update notifications: yesAZN Administration Services:webseal-admin-svcazn_admin_svc_trace

v The following example displays the ivmgrd-master policy server properties:pdadmin sec_master> server show ivmgrd-master

The output is like:ivmgrd-masterDescription: ivmgrd-masterHostname: localhostPrincipal:Administration Request Port: 7135Listening for authorization database update notifications: noAZN Administration Services:azn_admin_svc_trace

Note: The Administration Request Port, 7135 in the output, is the same port thatis set for the policy server during policy server configuration.

See also

“server list” on page 112“server task show” on page 143

server task addAdds an application server to an existing WebSEAL junction.


Syntax

server task instance_name-webseald-host_name add –h host_name [options]junction_point

Options

–h host_nameSpecifies the DNS host name or IP address of the target application server.Valid values for host_name include any valid IP host name. For example:www.example.com

instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance.You must specify this full server name in the exact format as displayed inthe output of the server list command.

The instance_name specifies the configured name of the WebSEAL serverinstance. The webseald designation indicates that the WebSEAL serviceperforms the command task. The host_name is the name of the physicalcomputer where the WebSEAL server is installed.


For example, the configured name of a single WebSEAL server instance isdefault. The host computer name where the WebSEAL server is installedis abc.ibm.com. Then, the full WebSEAL server name isdefault-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2,the full WebSEAL server name is web2-webseald-abc.ibm.com.

junction_pointSpecifies the name of the directory in the WebSEAL protected object spacewhere the document space of the server is mounted.

optionsSpecifies the options that you can use with the server task add command.(Optional) These options include:

–D "dn"Specifies the distinguished name of the server certificate. Thisvalue, matched with the actual certificate DN, enhancesauthentication and provides mutual authentication over SSL. Forexample, the certificate for www.example.com might have thefollowing DN:"CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin,ST=Texas,C=US"

This option is valid only with junctions that were created with thetype of ssl or sslproxy.

–H host_nameSpecifies the DNS host name or IP address of the proxy server.Valid values for host_name include any valid IP host name. Forexample:www.example.com

This option is used for junctions that were created with the type oftcpproxy or sslproxy.

–i Indicates that the WebSEAL server does not treat URLs ascase-sensitive. This option is used for junctions that were createdwith the type of tcp or ssl.

–p portSpecifies the TCP port of the server. The default value is 80 forTCP junctions and 443 for SSL junctions. This option is used forjunctions that were created with the type of tcp or ssl.

–P portSpecifies the TCP port of the HTTP proxy server. The default valueis 7138. Use this option for junctions that were created with thetype of tcpproxy or sslproxy.

For port, use any valid port number. A valid port number is anypositive number that is allowed by TCP/IP and that is notcurrently being used by another application. Use the default portnumber value, or use a port number that is greater than 1000 thatis not being used.

This option is also valid for mutual junctions to specify the HTTPSport of the back-end third-party server.

–q url Specifies the relative path for the query_contents script. By default,


Security Access Manager looks for this script in the /cgi_binsubdirectory. If this directory is different or the query_contents fileis renamed, use this option to indicate to WebSEAL the new URLto the file. Required for Windows servers.

This option is used for junctions that were created with the type oftcp or ssl.

–u uuidSpecifies the UUID of this server when connected to WebSEALover a stateful junction that was using the –s option. This option isused for junctions that were created with the type of tcp or ssl.

–v virtual_hostnameSpecifies the virtual host name that is represented on the server.This option supports a virtual host setup on the server. Use thisoption when the junction server expects a host name header,because you are junctioning to one virtual instance of that server.

The default HTTP header request from the browser does not knowthat the server has multiple names and multiple virtual servers.

You must configure WebSEAL to supply that extra headerinformation in requests that are destined for a server that is set upas a virtual host.


–V virtual_hostnameSpecifies the virtual host name that is represented on the back-endserver. This option:v Supports a virtual host setup on the back-end server.v Is used only for mutual junctions.v Corresponds to the virtual host that is used for HTTPS requests.

You can use –V when the back-end junction server expects a hostname header and you are junctioning to one virtual instance ofthat server. The default HTTPS header request from the browserdoes not know that the back-end server has multiple names andmultiple virtual servers. You must configure WebSEAL to supplythat extra header information. This header information applies torequests destined for a back-end server that is set up as a virtualhost.

–w Indicates Microsoft Windows 32 bit (Win32) file system support.


Authorization

Users and groups that require access to this command must be given the c(control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrativeuser is given this permission by default.

Return codes

0 The command completed successfully. For WebSEAL server taskcommands, the return code is 0 when the command is sent to the


WebSEAL server without errors. However, even after the command wassuccessfully sent, the WebSEAL server might not be able to successfullycomplete the command, and returns an error message.


Note: This command is available only when WebSEAL is installed.

For more information about how to add servers to existing junctions, see the IBMSecurity Access Manager for Web WebSEAL Administration Guide.

Example

The following example creates a junction for the WebSEAL server named WS1 to theserver named APP1. The example adds another server named APP2 to the samejunction point:pdadmin> server task default-webseald-WS1 create -t tcp -h APP1 -s /mnt

pdadmin> server task default-webseald-WS1 add -h APP2 /mnt

See also

“server task create” on page 121“server task delete” on page 128“server task remove” on page 141“server task show” on page 143

server task cache flush allFlushes the HTML document cache.


Syntax

server task instance_name-webseald-host_name cache flush all

Options






Authorization

Users and groups that require access to this command must be given the s (serveradministration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is giventhis permission by default.

Return codes


Note: For WebSEAL server task commands, the return code is 0 when thecommand is sent to the WebSEAL server without errors. However, evenafter the command was successfully sent, the WebSEAL server might notbe able to successfully complete the command. The WebSEAL serverreturns an error message.



Note:

v This command is available only when WebSEAL is installed.v For more information about the WebSEAL content caching, see the IBM Security

Access Manager for Web WebSEAL Administration Guide.

Example

The following example flushes all web document caches:pdadmin> server task default-webseald-abc.ibm.com cache flush all

server task createCreates a WebSEAL junction point.


Syntax

For local junctions:server task instance_name-webseald-host_name create –t type –d dir[options] junction_point

For non-local junctions:server task instance_name-webseald-host_name create –t type –hhost_name [options] junction_point

Options

–d dir Specifies the local directory to the junction. This option is required if thejunction type is local.


This option is valid only with junctions that were created with the type oflocal.

–h host_nameSpecifies the DNS host name or IP address of the target server. This optionis valid only for non-local junctions; local junctions do not need a hostname. Valid values for host_name include any valid IP host name. Forexample:www.example.com

–T {resource | resource_group}Specifies the name of the resource or resource group. This option isrequired only when the –b gso option is used. This option is valid for alljunctions except for the type of local.


The instance_name specifies the configured name of the WebSEAL serverinstance. The webseald designation indicates that the WebSEAL serviceperforms the command task. The host_name is the name of the physicalmachine where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance isdefault. The host machine name where the WebSEAL server is installed isabc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.



optionsSpecifies the options that you can use with the server task createcommand. (Optional) These options include:

–a addressSpecifies the local IP address that WebSEAL uses to communicatewith the target back-end server. If this option is not provided,WebSEAL uses the default address as determined by the operatingsystem.

If an address is supplied for a particular junction, WebSEAL ismodified to bind to this local address for all communication withthe junctioned server.

–A Enables or disables lightweight third-party authenticationmechanism (LTPA) junctions. This option requires the –F and –Zoptions. The –A, –F, and –Z options all must be used together.

This option is valid for all junctions except for the type of local.

–2 You can use this option with the –A option to specify that LTPAversion 2 cookies (LtpaToken2) are used. The –A option without the–2 option specifies that LTPA version 1 cookies (LtpaToken) areused.


–b BA_valueDefines how the WebSEAL server passes the HTTP BAauthentication information to the server, which is one of thefollowing values:v filter (default)v ignorev supplyv gso


–B Indicates that WebSEAL uses the BA header information toauthenticate to the server and to provide mutual authenticationover SSL. This option requires the –U and –W options.


–c header_typeInserts the Security Access Manager client identity in HTTPheaders across the junction. The header_type argument can includeany combination of the Security Access Manager HTTP headertypes:v {iv_user|iv_user-l}v iv_groupsv iv_credsv all

The header types must be comma-separated, and cannot have aspace between the types. For example: -c iv_user,iv_groups

Specifying –c all is the same as specifying –civ_user,iv_groups,iv_creds.


–C Indicates single sign-on from a front-end WebSEAL server to aback-end WebSEAL server. The –C option is not mutualauthentication.


–D "dn"Specifies the distinguished name of the server certificate. Thisvalue, matched with the actual certificate DN, enhancesauthentication and provides mutual authentication over SSL. Forexample, the certificate for www.example.com might have a DN of"CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin,ST=Texas,C=US"


–e encoding_typeSpecifies the encoding to use when HTTP headers are generatedfor junctions. This encoding applies to headers that are generatedwith both the –c junction option and tag-value. The followingvalues for encoding are supported:

utf8_binWebSEAL sends the headers in UTF-8.


utf8_uriWebSEAL sends the headers in UTF-8 but URI alsoencodes them. This behavior is the default behavior.

lcp_binWebSEAL sends the headers in the local code page of theWebSEAL server.

lcp_uriWebSEAL sends the headers in the local code page of theWebSEAL server, but URI also encodes them.


–f Forces the replacement of an existing junction.

This option is used for junctions that were created with anyjunction type.

–F keyfileSpecifies the location of the key file that is used to encrypt LTPAcookie data.

The –F option requires –A and –Z options. The –A, –F, and –Zoptions all must be used together.


–H host_nameSpecifies the DNS host name or IP address of the proxy server. The–P option also supports proxy server junctions. Valid values forhost_name include any valid IP host name. For example,proxy.www.example.com

This option is valid only with junctions that were created with thetype of tcpproxy or sslproxy.

–i Indicates that the WebSEAL junction does not treat URLs ascase-sensitive. To correctly authorize requests for junctions that arenot case-sensitive, WebSEAL does the authorization check on alowercase version of the URL. For example, a Web server that isrunning on a Windows operating system treats requests forINDEX.HTM and index.htm as requests for the same file.

Junctions to such a Web server must be created with the –i or –woption. ACLs or POPs that are attached to objects beneath thejunction point must use the lowercase object name. An ACLattached to /junction/index.htm applies to all the followingrequests if the –i or –w option is used:

/junction/INDEX.HTM/junction/index.htm/junction/InDeX.HtM

This option is valid for all junctions except for the type of local.Local junctions are not case-sensitive only on Win32 platforms; allother platforms are case-sensitive.

–I Ensures a unique Set-Cookie header name attribute when the –joption is used to modify server-relative URLs in requests.



–j Supplies junction identification in a cookie to handlescript-generated server-relative URLs.


–J trailer,inhead,onfocus,xhtml10Controls the junction cookie Java™Script block.

Use –J trailer to append the junction cookie JavaScript to HTMLpage returned from back-end server.

Use –J inhead to insert the Javascript block between <head></head> tags for HTML 4.01 compliance.

Use –J onfocus to use the onfocus event handler in the JavaScriptto ensure that the correct junction cookie is used in amultiple-junction/multiple-browser-window scenario.

Use –J xhtml10 to insert a JavaScript block that is HTML 4.01 andXHTML 1.0 compliant.

–k Sends WebSEAL session cookies to the junction server. By default,cookies are removed from requests that are sent to the server.


–K "key_label"Specifies the key label of the client personal certificate thatWebSEAL must present to the server. Use of this option allows thejunction server to authenticate the WebSEAL server by using clientcertificates.

This option is valid only with junctions that were created with thetype of ssl and sslproxy.

–l percentDefines the soft limit for consumption of worker threads.


–L percentDefines the hard limit for consumption of worker threads.


–n Indicates that no modifications of the names of non-domaincookies are to be made. Use when client side scripts depend on thenames of cookies.

WebSEAL modifies the names of non-domain cookies that arereturned from the junction to prefix with AMWEBJCT!junction_point.WebSEAL does this action by default, if a junction is listed in theJMT or if the –j junction option is used.


–p portSpecifies the TCP port of the back end third-party server. Thedefault value is 80 for TCP junctions and 443 for SSL junctions.


–P portFor proxy junctions that were created with the type of tcpproxy orsslproxy this option specifies the TCP port number for the HTTPproxy server. The –P option is required when the –H option is used.


This option is also valid for mutual junctions to specify the HTTPSport of the back-end third-party server.

–q pathSpecifies the relative path for the query_contents script. By default,Security Access Manager looks for the query_contents script in the/cgi_bin directory. If this directory is different or thequery_contents file name is renamed, this option indicates toWebSEAL the new URL to the file. Required for back end Windowsservers.


–r Inserts the incoming IP address into the HTTP header across thejunction. This option is valid for all junctions except for the type oflocal.

–R Allows the request to proceed but provides the rule failure reasonto the junction in an HTTP header. If the –R option is not used anda rule failure occurs, WebSEAL does not allow the request toproceed. This option is valid for all junctions except for the type oflocal.

–s Indicates that the junction support stateful applications. By default,junctions are not stateful. This option is valid for all junctionsexcept for the type of local.

–S pathSpecifies the location of the forms single sign-on configuration file.This option is valid for all junctions except for the type of local.

–t typeSpecifies the type of junction; must be one of the following types:v tcpv tcpproxyv sslv sslproxyv local

–u uuidSpecifies the Universally Unique Identifier (UUID) of a server thatis connected to WebSEAL by using a stateful junction (–s option).This option is valid for all junctions except for the type of local.

–U "user_name"Specifies the WebSEAL server user name. This option requires the–B and –W options. WebSEAL uses the BA header information toauthenticate to the server and to provide mutual authenticationover SSL. This option is valid only with junctions that were createdwith the type of ssl or sslproxy.

–v virtual_hostname[:HTTP-port]Specifies the virtual host name for the server. This option supportsmultiple virtual hosts that are served from the same Web server.Use –v when the junction server expects a host name headerdifferent from the DNS name of the server. This option is valid forall junctions except for the type of local. For mutual junctions, thisvalue corresponds to the virtual host that is used for HTTPrequests.


–V virtual_hostname[:HTTPS-port]Specifies the virtual host name for the back-end server. This optionsupports multiple virtual hosts that are served from the same Webserver. Use –V when the back-end junction server expects a hostname header that is different from the DNS name of the server.This option is used only for mutual junctions and corresponds tothe virtual host that is used for HTTPS requests.

–w Indicates Microsoft Windows 32-bit (Win32) file system support.This option:v Provides all the functionality that is provided by the –i junction

option.v Disallows requests that contain file names that might be

interpreted as Win32 file name aliases.

The option is valid for all junctions except for the type of local.Local junctions prohibit URLs that contain Win32 file name aliaseson Win32 but allow such URLs on other platforms.

–W "password"Specifies the WebSEAL server password. This option requires the–B and –U options. WebSEAL uses the BA header information toauthenticate to the server and to provide mutual authenticationover SSL. This option is valid only with junctions that were createdwith the type of ssl or sslproxy.

–x Creates a path junction that is not apparent.


–Y Enables Tivoli® Federated Identity Manager single sign-on (SSO)for the junction.

Indicates that Kerberos SSO is enabled for the junction. Before youuse this command, configure the WebSEAL configuration file tosupport Kerberos single-signon over junctions.

–Z keyfile_pwdSpecifies the password of the key file that is used to encrypt LTPAcookie data. This option requires the –A and –F options. The –A, –F,and –Z options all must be used together. This option is valid forall junctions except for the type of local.

Authorization

Users and groups that require access to this command must be given the s (serveradministration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrativeuser is given this permission by default.

Return codes

0 The command completed successfully. For WebSEAL server taskcommands, the return code is 0 when the command is sent to theWebSEAL server without errors. However, even after the command wassuccessfully sent, the WebSEAL server might not be able to successfullycomplete the command. The WebSEAL server returns an error message.

1 The command failed. See the IBM Security Access Manager for Web Error


Message Reference. This reference provides a list of the Security AccessManager error messages by decimal or hexadecimal codes.

Note:

v This command is available only when WebSEAL is installed.v For more information about creating a junctioned server, see IBM Security Access

Manager for Web WebSEAL Administration Guide.v For more information about gathering statistics, see the IBM Security Access

Manager for Web Auditing Guide.

Examplesv The following example creates a basic WebSEAL junction /pubs on the

default-webseald-cruz WebSEAL server. The junction type is TCP, and the hostname is doc.tivoli.com:pdadmin> server task default-webseald-cruz create -t tcp \-h doc.tivoli.com /pubs

Output is like:Created junction at /pubs

v The following example creates a new local junction / to replace the currentjunction point. The –f option is required to force a new junction that overwritesan existing junction at the /tmp/docs directory:pdadmin> server task default-webseald-cruz create -t local \-f -d /tmp/docs /

Output is like:Created junction at /

v The following example limits worker thread consumption on a per junction basiswith a:– Soft thread limit of 60.– Hard thread limit of 80.

The junction in this example is /myjunction.pdadmin> server task default-webseald-cruz create -t tcp \-h cruz.dallas.ibm.com -l 60 -L 80 /myjunction

See also

“server task add” on page 117“server task delete”“server task remove” on page 141“server task show” on page 143

server task deleteDeletes a WebSEAL junction point.


Syntax

server task instance_name-webseald-host_name delete junction_point


Options






Authorization


Return codes


1 The command failed. See the IBM Security Access Manager for Web ErrorMessage Reference. This reference provides a list of the Security AccessManager error messages by decimal or hexadecimal codes.

Note:

v This command is available only when WebSEAL is installed.v For more information about how to delete WebSEAL junctions, see the IBM

Security Access Manager for Web WebSEAL Administration Guide.

Example

The following example deletes the junction point /pubs from the WebSEAL serverdefault-webseald-abc.ibm.com:pdadmin> server task default-webseald-abc.ibm.com delete /pubs


See also

“server task add” on page 117“server task create” on page 121“server task remove” on page 141“server task show” on page 143

server task dynurl updateReloads the dynamic URL configuration file.


Syntax

server task instance_name-webseald-host_name dynurl update

Options





Authorization


Return codes







For more information about how WebSEAL handles dynamic URLs, see the IBMSecurity Access Manager for Web WebSEAL Administration Guide.

Example

The following example reloads the dynamic URL configuration file:pdadmin> server task default-webseald-abc.ibm.com dynurl update

server task helpLists detailed help information about a specific server task command.


Syntax

server task instance_name-webseald-host_name help task

Options





task Lists detailed help for the specified task, such as the command syntax, thedescription, and the valid options.

Authorization

No special authorization required.

Return codes





Examplesv The following example displays output after help is requested for the server

task add command at the abc.ibm.com WebSEAL server:pdadmin> server task default-webseald-abc.ibm.com help add

Output is like:Command:add <options> <junction point>Description:Adds an additional server to a junctionUsage:TCP and SSL Junction Flags-iServer treats URLs as case insensitive.-h <hostname>Target host (required flag).-p <port>TCP port of server.Default is 80 for TCP junctions443 for SSL junctions.-H <hostname>Proxy hostname.-P <port>Port of proxy server.-D <"DN">The Distinguished Name of the server-q <relative url> URL for query_contents script.-u <UUID>(stateful junctions only).-v <hostname>Virtual hostname for server.-wWin32 file system support.-jScripting support for junction.Common Flags<junction point>Where to create the junction

v The following example displays the output after help is requested for the servertask create command at the abc.ibm.com WebSEAL server:pdadmin> server task default-webseald-abc.ibm.com help create

Output is like:Command:create -t <type> <options> <junction point>Description:Creates a new junctionUsage:create -t <type> <options> <junction point>

TCP and SSL Junction Flags...Common Flags-t <type>Type of junction.One of: tcp, tcpproxy, ssl, sslproxy, local.-fForce the creation: overwrite existing junction.-RWebSEAL will send the Boolean Rule Header to thesejunctions when a rule failure reason is provided.<junction point>Where to create the junction

See also

“help” on page 63


server task jmtClears or loads the junction mapping table data.


Syntax

server task instance_name-webseald-host_name jmt load

server task instance_name-webseald-host_name jmt clear

Options

clear Clears the junction mapping table data.





load Loads the junction mapping table data, which is in the jmt.conf file. Thisfile does not exist by default, so you must create the file and add data.

Authorization


Return codes







For more information about the WebSEAL junction mapping table, see the IBMSecurity Access Manager for Web WebSEAL Administration Guide.

Example

The following example loads the junction mapping table data from the jmt.conffile. As a result, WebSEAL has the new information:pdadmin> server task default-webseald-abc.ibm.com jmt load

Output is like:JMT table successfully loaded.

See also

“server task reload” on page 140

server task listLists all junction points on a WebSEAL server or server instance.


Syntax

server task instance_name-webseald-host_name list

Options



For example, if the configured name of a single WebSEAL server instanceis default. The host computer name where the WebSEAL server isinstalled is abc.ibm.com. Then, the full WebSEAL server name isdefault-webseald-abc.ibm.com.


Authorization

Users and groups that require access to this command must be given the l (list)permission in the ACL that governs the /WebSEAL/host_name-instance_name/per_junction_point object. For example, the sec_master administrative user isgiven this permission by default.


Return codes


Note: For WebSEAL server task commands, the return code is 0 when thecommand is sent to the WebSEAL server without errors. However, evenafter the command was successfully sent, the WebSEAL server might notbe able to successfully complete the command, and returns an errormessage.




For more information about WebSEAL junctions, see the IBM Security AccessManager for Web WebSEAL Administration Guide.

Example

The following example lists all junction points on the default-webseald-cruzWebSEAL server:pdadmin> server task default-webseald-cruz list

Output is like://ssljct/tcpjct

See also

“server task add” on page 117“server task create” on page 121“server task delete” on page 128“server task remove” on page 141“server task show” on page 143

server task offlinePlaces the server that is at this junction in an offline operational state.

Syntax

server task instance_name-webseald-host_name offline [–i server_uuid]junction_point

Description

The server task offline command places the server that is at this junction in anoffline operational state. No additional requests are sent to the specified server. If aserver is not specified, all servers that are at this junction are placed in an offlineoperational state.


Options

–i server_uuidSpecifies the UUID of the server to place in an offline operational state. If aserver is not specified, all servers that are at this junction are placed in anoffline operational state. Use the server task show command to determinethe ID of a specific server. (Optional)






Authorization


Return codes







Example

The following example places the backappl server at the /pubs junction point in anoffline operational state. To determine the UUID of this junctioned server, run theserver task show command:pdadmin> server task default-webseald-cruz show /pubs

Output is like:Junction point: /pubs...Server 1:ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77Server State: runningOperational State: ThrottledThrottled at: 2005-03-01-17:07:24Hostname: backapp1.diamond.example.com...Current requests: 0...

Place this server in an offline operational state:pdadmin> server task default-webseald-cruz offline \-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

See also

“server task online”“server task throttle” on page 164“server task virtualhost offline” on page 180“server task virtualhost online” on page 182“server task virtualhost throttle” on page 188

server task onlinePlaces the server that is at this junction in an online operational state.

Syntax

server task instance_name-webseald-host_name online [–i server_uuid]junction_point

Description

The server task online command places the server that is at this junction in anonline operational state. The server now resumes normal operation. If a server isnot specified, all servers that are at this junction are placed in an online operationalstate.

Options

–i server_uuidSpecifies the UUID of the server to place in an online operational state. If aserver is not specified, all servers that are at this junction are placed in anonline operational state. Use the server task show command to determinethe ID of a specific server. (Optional)

instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance.


You must specify this full server name in the exact format as displayed inthe output of the server list command.





Authorization


Return codes






Example

The following example places the backappl server at the /pubs junction point in anonline operational state. To determine the UUID of this junctioned server, run theserver task show command:pdadmin> server task default-webseald-cruz show /pubs

Output is like:Junction point: /pubs...Server 1:ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77Server State: running


Operational State: OfflineHostname: backapp1.diamond.example.com...Current requests: 0...

Place this server in an online operational state:pdadmin> server task default-webseald-cruz online \-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

See also

“server task offline” on page 135“server task throttle” on page 164“server task virtualhost offline” on page 180“server task virtualhost online” on page 182“server task virtualhost throttle” on page 188

server task refresh all_sessionsRefreshes the credential for all sessions for a specified user.


Syntax

server task instance_name-webseald-host_name refresh all_sessions user_id

Options

instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You mustspecify this full server name in the exact format as displayed in the outputof the server list command.

The instance_name specifies the configured name of the WebSEAL instance.The webseald designation indicates that the WebSEAL service performs thecommand task. The host_name is the name of the physical computer wherethe WebSEAL server is installed.

For example, the configured name of a single WebSEAL instance isdefault. The host computer name where the WebSEAL server is installedis abc.ibm.com. Then, the full WebSEAL server name isdefault-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the fullWebSEAL server name is web2-webseald-abc.ibm.com.

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

Authorization




Return codes





Note: For more information about the WebSEAL credential refresh, see the IBMSecurity Access Manager for Web WebSEAL Administration Guide.

Example

The following example refreshes all sessions for the test_user user:pdadmin> server task default-webseald-cruz refresh all_sessions test_user

See also

“server task terminate session” on page 163“server task terminate all_sessions” on page 162

server task reloadReloads the junction mapping table from the database.


Syntax

server task instance_name-webseald-host_name reload

Options






Authorization


Return codes






For more information about the WebSEAL junction mapping table, see the IBMSecurity Access Manager for Web WebSEAL Administration Guide.

Example

The following example reloads the junction mapping table from the database:pdadmin> server task default-webseald-abc.ibm.com reload

See also

“server task jmt” on page 133

server task removeRemoves the specified installed WebSEAL server or server instance from aWebSEAL junction point.


Syntax

server task instance_name-webseald-host_name remove –i server_uuidjunction_point


Options

–i server_uuidSpecifies the UUID of the server to be removed from the junction point.See the server task show command for details about obtaining the UUID.






Authorization


Return codes



Note: For more information about how to remove a server from a WebSEALjunction, see the IBM Security Access Manager for Web WebSEAL AdministrationGuide.

This command is available only when WebSEAL is installed.

Example

The following example removes the backappl junctioned server from the /pubsjunction point. To determine the UUID of the server to be removed, run the servertask show command:pdadmin> server task default-webseald-cruz show /pubs


Output is like:Junction point: /pubs...Server 1:ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77Server State: running...Hostname: backapp1.cruz.ibm.com...

Remove the server from the junction:pdadmin> server task default-webseald-cruz remove \-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

See also

“server task add” on page 117“server task create” on page 121“server task delete” on page 128“server task show”

server task showDisplays detailed information about the specified WebSEAL junction.


Syntax

server task instance_name-webseald-host_name show junction_point

Options






Authorization

Users and groups that require access to this command must be given the l (list)permission in the ACL that governs the /WebSEAL/host_name-instance_name/


junction_point object. For example, the sec_master administrative user is giventhis permission by default.

Return codes




For more information about WebSEAL junctions, see the IBM Security AccessManager for Web WebSEAL Administration Guide.

Example

The following example shows information for the local root junction point / on theWebSEAL server abc.ibm.com:pdadmin> server task default-webseald-abc.ibm.com show

Output is like:Junction point: /Type: LocalJunction hard limit: 0 - using global valueJunction soft limit: 0 - using global valueActive worker threads: 0Root Directory: /opt/pdweb/www-default/docs...Server 1:ID: 78a1eb8c-074a-11d9-abda-00096bda9439...

See also

“server task add” on page 117“server task create” on page 121“server task delete” on page 128“server task remove” on page 141

server task sms key changeForces the creation of a new session management key.

You might want to forcibly create a key when you suspect that the existing keywas compromised.

Syntax

server task server_name–host_name sms key change


Options

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.

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 example.dallas.ibm.com.For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

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

Return codes



Note: This command is available only when the session managementcommand-line extensions are installed to a hosting authorization server.

Example

The following example forcibly creates a session management key for theabc.ibm.com server:pdadmin> server task default-webseald-abc.ibm.com key change

See also

“server list” on page 112“server task sms key show”

server task sms key showLists detailed information about the current session management key.

Syntax

server task server_name–host_name sms key show

Options



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

If multiple server instances are configured on the same machine, forexample:v The host is cruz.dallas.ibm.com.v The configured name of the WebSEAL server instance is

webseal2-webseald.

Then,v The server_name would be webseal2-webseald.v The host_name would be example.dallas.ibm.com.v The name of the server instance would be webseal2-webseald-

example.dallas.ibm.com.

Return codes




Example

The following example returns detailed information about the current sessionmanagement key for the abc.ibm.com server:pdadmin> server task default-webseald-abc.ibm.com sms key show

Output is like:ID: 1Created: 2004-03-03-09:00:03Expires: 2004-09-03-09:00:03

See also

“server list” on page 112“server task sms key change” on page 144

server task sms realm listLists all session management realms in the domain.

Syntax

server task server_name–host_name sms realm list


Options



If there are multiple configured server instances on the same computer, forexample:v The host is example.dallas.ibm.com.v The configured name of the WebSEAL server instance is

webseal2-webseald.

Then,v The server_name is webseal2-webseald.v The host_name is example.dallas.ibm.com.v The name of the server instance is webseal2-webseald-


Return codes




Example

The following example lists the realms for the abc.ibm.com server:pdadmin> server task default-webseald-abc.ibm.com sms realm list

See also

“server list” on page 112“server task sms realm show”“server task sms replica set list” on page 151“server task sms replica set show” on page 152

server task sms realm showLists all replica sets in the specified session management realm.

Syntax

server task server_name–host_name sms realm show realm_name


Options

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



If multiple server instances are configured on the same computer, forexample:v The host is example.dallas.ibm.com.v The configured name of the WebSEAL server instance is

webseal2-webseald.



Return codes




Example

The following example returns the replica sets in the ibm.com realm of theabc.ibm.com server:pdadmin> server task default-webseald-abc.ibm.com sms realm show ibm.com

See also

“server list” on page 112“server task sms realm list” on page 146“server task sms replica set list” on page 151“server task sms replica set show” on page 152

server task sms session refresh all_sessionsRefreshes the credential for sessions for a specific user.


Syntax

server task server_name–host_name sms session refresh all_sessions user_name–realm realm_name

Options

–realm realm_nameSpecifies that name of the realm. The credentials of only those sessions thatbelong to the specified realm are refreshed.



If multiple server instances are configured on the same computer, forexample:v The host isexample.dallas.ibm.com.v The configured name of the WebSEAL server instance is

webseal2-webseald.



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

Return codes





Example

The following example refreshes all sessions for user johnq in the ibm.com realm:pdadmin> server task default-webseald-cruz sms session refresh all_sessions johnq \-realm ibm.com


See also

“server task sms session terminate session” on page 156“server task sms session terminate all_sessions” on page 154

server task sms session refresh sessionRefreshes the credential for a session.

Syntax

server task server_name–host_name sms session refresh session session_id–realm realm_name

Options

–realm realm_nameSpecifies that name of the realm. The credentials of only those sessions thatbelong to the specified realm are refreshed.




webseal2-webseald.



session_idSpecifies the identifier for the session to refresh.

Return codes






Example

The following example refreshes session 678 in the ibm.com realm:pdadmin> server task default-webseald-cruz sms session refresh session 678 \-realm ibm.com

See also

“server task sms session terminate session” on page 156“server task sms session terminate all_sessions” on page 154

server task sms replica set listLists all session management replica sets in the domain.

Syntax

server task server_name–host_name sms replica set list [–realm realm_name]

Options

–realm realm_nameIndicates that the returned list of replica sets is limited to those replica setsin the specified realm. (Optional)




webseal2-webseald.



Return codes






Example

The following example lists the replica sets in the ibm realm of the abc.ibm.comserver:pdadmin> server task default-webseald-abc.ibm.com sms replica set list -realm ibm

See also

“server list” on page 112“server task sms realm list” on page 146“server task sms realm show” on page 147“server task sms replica set show”

server task sms replica set showLists all session management replicas in the specified replica that is set with thetime and date that each joined the realm.

Syntax

server task server_name–host_name sms replica set show replica_set_name

Options

replica_set_nameSpecifies the name of the replica set.




webseal2-webseald.




Return codes




Example

The following example returns details about the ibm.com replica that is set of theabc.ibm.com server:pdadmin> server task default-webseald-abc.ibm.com sms replica set show ibm.com

See also

“server list” on page 112“server task sms realm list” on page 146“server task sms realm show” on page 147“server task sms replica set list” on page 151

server task sms session listLists all session management sessions.

Syntax

server task server_name–host_name sms session list –realm realm_name patternmaximum_return

Options

–realm realm_nameSpecifies the name of the session management realm.




webseal2-webseald.

Then,


v The server_name is webseal2-webseald.v The host_name is example.dallas.ibm.com.v The name of the server instance is webseal2-webseald-


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

patternSpecifies the pattern for returning user names. The pattern can include acombination of wildcard 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 within the user name.

Return codes




Example

The following example is entered as one line. The example:v Lists the user sessions in the ibm.com realm of the abc.ibm.com server.v Lists sessions for users that contain the string ons.v Limits the number of matches to 100.pdadmin> server task default-webseald-abc.ibm.comsms session list -realm ibm.com *ons* 100

See also

“server list” on page 112“server task sms realm list” on page 146“server task sms realm show” on page 147“server task sms replica set show” on page 152

server task sms session terminate all_sessionsTerminates all user sessions for a specific user.

Syntax

server task server_name–host_name sms session terminate all_sessions user_id–realm realm_name


Options

–realm realm_nameSpecifies that name of the session management realm.




webseal2-webseald.



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

Return codes





Example

The following example terminates all sessions for the dlucas user in the ibm.comrealm of the default-webseald-cruz WebSEAL server:pdadmin> server task default-webseald-cruz sms session terminate \all_sessions dlucas -realm ibm.com

See also

“server task sms session refresh session” on page 150“server task sms session refresh all_sessions” on page 148“server task sms session terminate session” on page 156


server task sms session terminate sessionTerminates a user session by using a session ID.

Syntax

server task server_name–host_name sms session terminate session session_id–realm realm_name

Options




webseal2-webseald.



session_idSpecifies the ID of a user session.

Return codes





Example

The following example terminates session 678 in the ibm.com realm of thedefault-webseald-cruz WebSEAL server:pdadmin> server task default-webseald-cruz sms session terminate \session 678 -realm ibm.com


See also

“server task sms session refresh all_sessions” on page 148“server task sms session terminate all_sessions” on page 154

server task sms trace getDisplays the trace level for the session management server.

Syntax

server task server_name–host_name sms trace get

Options




webseal2-webseald.



Return codes





Example

The following example returns the tracing level for the ivacld-cruz authorizationserver:pdadmin> server task ivacld-cruz.dallas.ibm.com sms trace get


See also

“server task sms trace set”

server task sms trace setSets the trace level for the session management server.

Sets the trace level for the session management server.

Syntax

server task server_name–host_name sms trace set level

Options

level Specifies the level of tracing. A valid setting is an integer between 0 and 3,with 3 being the most detailed level of trace.




webseal2-webseald.



Return codes






Example

The following example sets the tracing level to 1 on the ivacld-cruz authorizationserver:pdadmin> server task ivacld-cruz.dallas.ibm.com sms trace set 1

See also

“server task sms trace get” on page 157

server task statsManages the gathering and reporting of statistics for Security Access Managerservers and server instances.


Syntax

server task server_name–host_name stats get [component]

server task server_name–host_name stats list

server task server_name–host_name stats off [component]

server task server_name–host_name stats on component [interval [count]][destination]

server task server_name–host_name stats reset [component]

server task server_name–host_name stats show [component]

Description

The server task stats command manages the gathering and reporting of statisticsfor Security Access Manager servers and server instances. You can use the statscommands with configuration setting that are defined by the stanza entries in theserver configuration file to manage statistics.

Statistics gathering is enabled through:v The stats on command.v The defined configuration settings.

Then, you can use the stats on commands to modify the behavior for gatheringand reporting statistics.

For example, statistics are enabled to create five statistics reports with each reportgenerated each day. You can use the stats on command to change the frequencyto every 12 hours. For this example, assume that the following command startedstatistics gathering:pdadmin sec_master> server task PDWebPI-linuxweb.wasp.ibm.com stats on \pdwebpi.stats 86400 5 file path=/tmp/stats.log

To modify the interval to 12 hours and create 10 reports, issue the followingcommand:


pdadmin sec_master> server task PDWebPI-linuxweb.wasp.ibm.com stats on \pdwebpi.stats 43200 10

Although the destination is not specified, the statistics infrastructure assumes anypreexisting value. Entering the previous command does disable statistics frombeing written to the previously defined log file. However, if you specified adifferent destination, statistics reports would be written to the new destinationonly. You cannot use the stats on command to write statistics reports to more thanone destination.

For more information about gathering statistics, see the IBM Security AccessManager for Web Auditing Guide.

Options

componentSpecifies the component about which to gather or report statistics.

count Specifies the number of reports to send to a log file. When you use thecount option, you must specify the interval option. If you specify theinterval option without the count option, the duration of reporting isindefinite.

After the count value is reached, reporting to a log file stops. Althoughstatistics are no longer sent to a log file, the statistic component is stillenabled. You can obtain reports from memory by using the stats getcommand.

destinationSpecifies where the gathered statistics are written, where destination canbe one of the following options:

file path=file_nameSpecifies the fully qualified name of the log file.

log_agentSpecifies a directory where statistics information is gathered. Formore information about logging events, see the IBM Security AccessManager for Web Troubleshooting Guide.

get Displays the current report for a specific component or for all enabledcomponents. If you specify the component option, displays the currentreport for that component; otherwise, displays the current report for allenabled components.

intervalSpecifies the interval in seconds when statistics are sent from memory to alog file. When this option is specified, statistics are sent, by default, to theserver-specific log file designated by the logcfg entry in the serverconfiguration file. You can specify another location by using thedestination option. If an interval is not specified, statistics are not sent toa log file, but remain in memory.

Although statistics are not sent to a log file, the statistic component is stillenabled. You can obtain reports from memory by using the stats getcommand.

list Lists all components that are available to gather and report statistics.

off Disables gathering of statistics for a specific component or for all


components. If you specify the component option, disables gathering ofstatistics for that component; otherwise, disables gathering of statistics forall components.

on Enables gathering of statistics for a specific component. When you enablegathering of statistics, you can also set the reporting frequency, count, andlog file.

reset Resets gathering of statistics for a specific component or for all enabledcomponents. If you specify the component option, resets gathering ofstatistics for that component; otherwise, resets gathering of statistics for allcomponents.




webseal2-webseald.



show Lists all enabled components or indicates whether a specific component isenabled. If you specify the component option and the component isenabled, the output lists that component; otherwise, no output isdisplayed. If you do not specify the component option, the output lists allenabled components.

Return codes



Examplesv The following example uses the stats list command to lists all enabled

components on the ivacld-mogman.admogman.com authorization server:#pdadmin sec_master> server task ivacld-mogman.admogman.com stats list

pd.ras.stats.monitorpd.log.EventPool.queue

v The following example:


– Uses the status on command to enable gathering of statistics for thepd.log.EventPool.queue component on the ivacld-mogman.admogman.comauthorization server.

– Sets the reporting frequency to 30 days, that is, 2592000 seconds.– Sets the destination to the c:\myEPstats.log log file.#pdadmin sec_master> server task ivacld-mogman.admogman.com stats on \pd.log.EventPool.queue 2592000 file path=c:\myEPstats.log

See also

“server list” on page 112

server task terminate all_sessionsTerminates all user sessions for a specific user.


Syntax

server task instance_name-webseald-host_name terminate all_sessions user_id

Options



For example,v The configured name of a single WebSEAL instance is default.v The host computer name that has the WebSEAL server that is installed is

abc.ibm.com.

Then, the full WebSEAL server name is default-webseald-abc.ibm.com.


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

Authorization




Return codes





Note: For more information about the WebSEAL server tasks and junction points,see the IBM Security Access Manager for Web WebSEAL Administration Guide.

Example

The following example terminates all sessions for the dlucas user on thedefault-webseald-cruz WebSEAL server:pdadmin> server task default-webseald-cruz terminate all_sessions dlucas

See also

“server task terminate session”“server task refresh all_sessions” on page 139

server task terminate sessionTerminates a user session by using a session ID.


Syntax

server task instance_name-webseald-host_name terminate session session_id

Options



For example:v The configured name of a single WebSEAL instance is default.v The host computer name where the WebSEAL server is installed is

abc.ibm.com.




session_idSpecifies the ID of a user session.

Authorization



Return codes





Note: For more information about the WebSEAL server tasks and junction points,see the IBM Security Access Manager for Web WebSEAL Administration Guide.

Example

The following example (entered as one line) terminates a specific session on thedefault-webseald-cruz WebSEAL server:pdadmin> server task default-webseald-cruz terminatesession 6fc3187a-ea1c-11d7-8f4e-09267e38aa77

See also

“server task refresh all_sessions” on page 139“server task terminate all_sessions” on page 162

server task throttlePlaces the server that is at this junction in a throttled operational state.

Syntax

server task instance_name-webseald-host_name throttle [–i server_uuid]junction_point


Description

The server task throttle command places the server that is at this junction in athrottled operational state. Users can create a session with WebSEAL before theinvocation of this command. Only requests from such users are processed by thespecified server. If a server is not specified, all servers that are at this junction areplaced in a throttled operational state.

Options

–i server_uuidSpecifies the UUID of the server to throttle. If a server is not specified, allservers that are at this junction are placed in a throttled operational state.Use the server task show command to determine the ID of a specificserver. (Optional)



For example:v The configured name of a single WebSEAL server instance is default.v The host computer name where the WebSEAL server is installed is

abc.ibm.com.




Authorization


Return codes







Example

The following example places the backappl server that is located at the /pubsjunction point in a throttled operational state. To determine the UUID of thisjunctioned server, run the server task show command:pdadmin> server task default-webseald-cruz show /pubs

Output is like:Junction point: /pubs...Server 1:ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77Server State: runningOperational State: OnlineHostname: backapp1.diamond.example.com...Current requests: 0...

Place this server in a throttled operational state:pdadmin> server task default-webseald-cruz throttle \-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

See also

“server task offline” on page 135“server task online” on page 137“server task virtualhost offline” on page 180“server task virtualhost online” on page 182“server task virtualhost throttle” on page 188

server task traceEnables the gathering of trace information for components of installed SecurityAccess Manager servers or server instances.


Syntax

server task server_name–host_name trace list [component]

server task server_name–host_name trace set component level [destination]

server task server_name–host_name trace show [component]

Description

The server task stats command enables the gathering of trace information forcomponents of installed Security Access Manager servers or server instances thatsupport debug event tracing. The content of trace messages is undocumented and


is intended to be used for debugging purposes only. The format and content oftrace messages might vary between product releases.

Options

list [component]Lists all enabled trace components that are available to gather and reporttrace information. If you specify the component option and the componentis enabled, the output lists that component; otherwise, no output isdisplayed. If you do not specify the component option, the output lists allenabled components.




webseal2-webseald.



set component level [destination]Sets the trace level and trace message destination for a specific componentand its subordinates. The value for the level option is a single integerfrom 1 to 9, with 9 reporting the most detailed level of information. Thedestination option specifies where the gathered trace information iswritten and can be one of the following options:

file path=file_nameSpecifies the fully qualified file name.

log_agentSpecifies a destination for the statistics information that is gatheredfor the specified component. For more information about loggingevents, see the IBM Security Access Manager for Web AdministrationGuide.

show [component]Shows the names and levels for all enabled trace components. If youspecify the component option, the output lists the name and level for thespecified component.

Return codes




Examplesv The following example enables the pdweb.debug trace component to level 2 and

then displays the output for all enabled components. WebSEAL–specificcomponents are prefixed with pdweb.pdadmin sec_master> server task webseald-instance_name trace setpdweb.debug 2

pdadmin sec_master> server task webseald-instance_name trace show

Output from the trace show command is like:pdweb.debug 2

v The following example enables the pdwebpi.module.session-cookie tracecomponent to level 9. Then, the output for all enabled components is displayed.Components that are specific to the web server plug-ins are prefixed withpdwebpi.pdadmin sec_master> server task pdwpi-tivoli.com trace setpdwebpi.module.session-cookie 9

pdadmin sec_master> server task pdwpi-tivoli.com trace show

Output from the trace show command is like:pdwebpi.module.session-cookie 9

See also

“server list” on page 112

server task virtualhost addAdds an additional installed WebSEAL server or server instance to an existingvirtual host junction.


Syntax

server task instance_name-webseald-host_name virtualhost add –h host_name[options] vhost_label

Options

–h host_nameSpecifies the DNS host name or IP address of the target server. Validvalues for host_name include any valid IP host name. This option isrequired. For example:www.example.com






optionsSpecifies the options that you can use with the server task virtualhostadd command. (Optional) These options include:



–H host_nameSpecifies the DNS host name or IP address of the proxy server.

Valid values for host_name include any valid IP host name. Forexample:proxy.www.example.com


–i Indicates that the WebSEAL server does not treat URLs ascase-sensitive.


–p portSpecifies the TCP port of the server. The default value is 80 forTCP junctions and 443 for SSL junctions. This option is used forjunctions that were created with the type of tcp or ssl.

–P portSpecifies the TCP port of the proxy server. The default value is7138.

For port, use any valid port number. A valid port number is anypositive number that is allowed by TCP/IP and that is notcurrently being used by another application. Use the default portnumber value, or use a port number that is greater than 1000 thatis not being used.



–q pathSpecifies the relative path for the query_contents script. By default,Security Access Manager looks for this script in the /cgi_binsubdirectory. If this directory is different or the query_contents fileis renamed, use this option to indicate to WebSEAL the new URLto the file. Required for Windows virtual hosts.

This option is valid for all junction types except localtcp andlocalssl.

–u uuidSpecifies the UUID of this server when connected to WebSEALover a stateful junction that was using the –s option. This option isused for junctions that were created with the type of tcp or ssl.

–w Indicates Microsoft Windows 32 bit (Win32) file system support.


vhost_labelSpecifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the c(control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrativeuser is given this permission by default.

Return codes




Example

The following example adds a server with host name xyz.ibm.com to an existingvirtual host junction with the label support-vhost-http, on the WebSEAL serverabc.ibm.com:pdadmin> server task default-webseald-abc.ibm.com virtualhost add \-h xyz.ibm.com support-vhost-http

See also

“server task virtualhost create” on page 171“server task virtualhost delete” on page 177“server task virtualhost list” on page 179


“server task virtualhost remove” on page 184“server task virtualhost show” on page 186

server task virtualhost createCreates a virtual host junction.


Syntax

For local junctions:server task instance_name-webseald-host_name virtualhost create –ttype –d dir –v virtual-host-name [options] vhost_label

For non-local junctions:server task instance_name-webseald-host_name virtualhost create –ttype –h host_name [options] vhost_label

Options

–d dir Specifies the local directory for a local virtual host junction.

This option is required for localtcp and localssl junction types.

–h host_nameSpecifies the DNS host name or IP address of the target server. This optionis valid only for non-local junctions; local junctions do not need a hostname. Valid values for host_name include any valid IP host name. Forexample:www.example.com

–t typeSpecifies the type of virtual host junction. This option is required and mustbe one of the following types:v tcpv tcpproxyv sslv sslproxyv localtcpv localssl

–v virtual-host-name[:port]

WebSEAL selects a virtual host junction to process a request if the HTTPHost header of the request matches:v The virtual host name by the -v option andv The port number that is specified by the -v option.v

The –v option is also used to specify the value of the Host header of therequest sent to the server.

The port number is required if the virtual host uses a non-standard portfor the protocol. Standard port for TCP is 80; standard port for SSL is 443.

If –v is not specified for tcp, ssl, tcpproxy, and sslproxy type junctions,the junction is selected from the information that is contained in the –hhost_name and –p port options.

The –v option is required for localtcp and localssl type junctions






optionsSpecifies the options that you can use with the server task virtualhostcreate command. (Optional) These options include:

–A Enables a virtual host junction to support the lightweightthird-party authentication mechanism (LTPA). This option requiresthe –F and –Z options. The –A, –F, and –Z options all must be usedtogether.


–2 You can use this option with the –A option to specify that LTPAversion 2 cookies (LtpaToken2) are used. The –A option without the–2 option specifies that LTPA version 1 cookies (LtpaToken) areused.

–b BA_valueDefines how the WebSEAL server passes client identity informationin HTTP basic authentication (BA) headers to the virtual host,which is one of the following values:v filterv ignorev supplyv gso

This option is valid for all junction types except localtcp andlocalssl. The default value is filter.

–B Indicates that WebSEAL uses the BA header information toauthenticate to the virtual host and to provide mutualauthentication over SSL. This option requires the –U and –Woptions.


–c header_typeInserts the Security Access Manager client identity in HTTPheaders across the virtual host junction. The header_type argumentcan include any combination of the listed Security Access ManagerHTTP header types:v {iv-user|iv-user-l}v iv-groups


v iv-credsv all

The header types must be comma-separated, and cannot have aspace between the types. For example: -c iv_user,iv_groups

Specifying –c all is the same as specifying –civ-user,iv-groups,iv-creds.


–C Supports mutual authentication by enabling the front-endWebSEAL server to pass its identity information to the back-endWebSEAL server. The front-end WebSEAL server passesinformation in a Basic Authentication (BA) header. Additionally,the –C option enables the single sign-on functionality that isprovided by the –c option.




–e encoding_typeSpecifies the encoding to use when HTTP headers is generated forvirtual host junctions. This encoding applies to headers that aregenerated with both the –c junction option and tag-value. Possiblevalues for encoding are as follows:

utf8_binWebSEAL sends the headers in UTF-8.

utf8_uriWebSEAL sends the headers in UTF-8 but URI alsoencodes them. This behavior is the default behavior.

lcp_binWebSEAL sends the headers in the local code page of theWebSEAL server.

lcp_uriWebSEAL sends the headers in the local code page of theWebSEAL server, but URI also encodes them.


–f Forces the replacement (overwrite) of an existing virtual hostjunction.

This option is used for junctions that were created with anyjunction type.


–F "keyfile"Specifies the location of the key file that is used to encrypt LTPAcookie data.

The –F option requires –A and –Z options. The –A, –F, and –Zoptions all must be used together.


–g vhost_labelThe –g option causes a second more virtual host junction to share aprotected object space as the initial virtual host junction.

This option is appropriate for junction pairs only (two junctions byusing complementary protocols). The option does not support theassociation of more than two junctions.

–H host_nameSpecifies the DNS host name or IP address of the proxy server. The–P option also supports proxy server junctions. Valid values forhost_name include any valid IP host name. For example:proxy.www.example.com


–i Indicates that the WebSEAL junction does not treat URLs ascase-sensitive. To correctly authorize requests for junctions that arenot case-sensitive, WebSEAL does the authorization check on alowercase version of the URL. For example, a web server that isrunning on a Windows operating system treats requests forINDEX.HTM and index.htm as requests for the same file.

Junctions to such a web server must be created with the –i or –woption. ACLs or POPs that are attached to objects beneath thejunction point must use the lowercase object name. An ACLattached to /junction/index.htm applies to all the followingrequests if the –i or –w option is used:

/junction/INDEX.HTM/junction/index.htm/junction/InDeX.HtM

This option is valid for all junction except for the type of localtcpand localssl. Local junctions are not case-sensitive only on Win32platforms; all other platforms are case-sensitive.

–k Sends WebSEAL session cookies to the back-end virtual host. Bydefault, cookies are removed from requests that are sent to theserver.


–K "key_label"Specifies the key label of the client-side certificate that WebSEALmust present to the server. Use of this option allows the virtualhost to authenticate the WebSEAL server by using clientcertificates.

This option is valid only with junctions that were created with thetype of ssl and sslproxy.


–l percentDefines the soft limit for consumption of worker threads.


–L percentDefines the hard limit for consumption of worker threads.


–p portSpecifies the TCP port of the third-party server. The default valueis 80 for TCP junctions and 443 for SSL junctions.


–P portSpecifies the TCP port number for the HTTP proxy server. The –Poption is required when the –H option is used.


–q –S Specifies the relative path for the query_contents script. By default,Security Access Manager looks for the query_contents script in the/cgi_bin directory. If this directory is different or thequery_contents file name is renamed, this option indicates toWebSEAL the new URL to the file. Required for Windows virtualhosts.


–r Inserts the incoming IP address into the HTTP header across thejunction.


–R Allows the request to proceed but provides the rule failure reasonto the junction in an HTTP header. If the –R option is not used anda rule failure occurs, WebSEAL does not allow the request toproceed.


–s Indicates that the virtual host junction support statefulapplications. By default, virtual host junctions are not stateful.


–S Indicates the location of the forms single sign-on configuration file.


–T {resource | resource_group}Specifies the name of the GSO resource or resource group. Thisoption is required only when the –b gso option is used.



–u uuidSpecifies the Universally Unique Identifier (UUID) of a server thatis connected to WebSEAL by using a stateful virtual host junction(–s option).


–U "user_name"Specifies the WebSEAL server user name. This option requires the–B and –W options. WebSEAL uses the BA header information toauthenticate to the virtual host and to provide mutualauthentication over SSL.


–w Indicates Microsoft Windows 32 bit (Win32) file system support.This option provides all the functionality that is provided by the –ijunction option. The option disallows requests that contain filenames that might be interpreted as Win32 file name aliases.

This option is valid for all junction types except localtcp andlocalssl. Local junctions prohibit URLs that contain Win32 filename aliases on Win32 but allow such URLs on other platforms.

–W "password"Specifies the WebSEAL server password. This option requires the–B and –U options. WebSEAL uses the BA header information toauthenticate to the virtual host and to provide mutualauthentication over SSL.


–Y Enables Tivoli Federated Identity Manager single-signon (SSO) forthe junction.

Note: Before you use this option, you must first configure theWebSEAL configuration file to support Tivoli Federated IdentityManager single-signon over junctions.

–z replica_setSpecifies the replica set, as follows:

For SMS environments:Sessions on the virtual host junction are managed underthe specified replica set. Used to group or separate loginsessions among multiple virtual hosts.

For non-SMS environments:Sessions on the virtual host junction are managed underthe specified replica set. Controls the partitioning of theWebSEAL session cache. The virtual host can be part of thesame replica that is set as any standard junction that isassigned to that same replica set. Standard junctions areassigned to replica sets through the standard-junction-replica-set entry of the [session] stanza.


–Z keyfile_pwdSpecifies the password of the key file that is used to encrypt LTPAcookie data. This option requires the –A and –F options. The –A, –F,and –Z options all must be used together.



Authorization

Users and groups that require access to this command must be given the s (serveradministration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrativeuser is given this permission by default.

Return codes




For more information about gathering statistics, see the IBM Security AccessManager for Web Troubleshooting Guide.

Example

The following example creates an SSL type virtual host junction with thevhost-xy-https label. This junction serves the virtual host x.y.com on thejunctioned server cruz1.ibm.com. WebSEAL responds to the Host: x.y.com headerin SSL (HTTPS) requests by forwarding the requests across this virtual hostjunction:pdadmin> server task default-webseald-abc.ibm.com virtualhost create \-t ssl -h cruz1.ibm.com -v x.y.com vhost-xy-https

See also

“server task virtualhost add” on page 168“server task virtualhost delete”“server task virtualhost list” on page 179“server task virtualhost remove” on page 184“server task virtualhost show” on page 186

server task virtualhost deleteDeletes a virtual host junction.



Syntax

server task instance_name-webseald-host_name virtualhost delete vhost_label

Description

The server list virtualhost delete command deletes a virtual host junction. Avirtual host junction cannot be deleted if a second virtual host junction refers to itthrough the –g option. An error message is returned at such an attempt.

Options






Authorization


Return codes




Example

The following example deletes the virtual host junction support-vhost-https fromthe WebSEAL server abc.ibm.com:


pdadmin> server task default-webseald-abc.ibm.com virtualhost delete \support-vhost-https

See also

“server task virtualhost add” on page 168“server task virtualhost create” on page 171“server task virtualhost list”“server task virtualhost remove” on page 184“server task virtualhost show” on page 186

server task virtualhost listLists all configured virtual host junctions by label name.


Syntax

server task instance_name-webseald-host_name virtualhost list

Options





Authorization

Users and groups that require access to this command must be given the l (list)permission in the ACL that governs the /WebSEAL/host_name-instance_name/@per_vhost_label object. For example, the sec_master administrative user is giventhis permission by default.

Return codes







Example

The following example lists the label names of all virtual host junctions that areconfigured on the abc.ibm.com WebSEAL server:pdadmin> server task default-webseald-abc.ibm.com virtualhost list

Output is like:pubs-vhost-httpsales-vhost-httpssupport-vhost-http

See also

“server task virtualhost add” on page 168“server task virtualhost create” on page 171“server task virtualhost delete” on page 177“server task virtualhost remove” on page 184“server task virtualhost show” on page 186

server task virtualhost offlinePlaces the server that is at this virtual host junction in an offline operational state.


Syntax

server task instance_name-webseald-host_name virtualhost offline [–iserver_uuid] vhost_label

Description

The server task virtualhost offline command places the server that is at thisvirtual host junction in an offline operational state. No additional requests are sentto the specified server. If a server is not specified, all servers that are at this virtualhost junction are placed in an offline operational state.

Options

–i server_uuidSpecifies the UUID of the server to place in an offline operational state. If aserver is not specified, all servers that are at this virtual host junction areplaced in an offline operational state. Use the server task virtualhostshow command to determine the ID of a specific server. (Optional)

instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance.


You must specify this full server name in the exact format as displayed inthe output of the server list command.





Authorization


Return codes






Examples

In the following example:v The virtual host junction:

– Has the label support-vhost-https.– Is configured on the WebSEAL server abc.ibm.com.– Supports the virtual host support.ibm.com.

v The virtual host support.ibm.com is on the junctioned server int3.ibm.com.

There is a requirement to place the int3.ibm.com server in an offline operationalstate. To determine the UUID of this junctioned server, run the server taskvirtualhost show command:


pdadmin> server task default-webseald-abc.ibm.com \virtualhost show support-vhost-https

Output is like:Virtual Host label: support-vhost-httpsType: SSL...Virtual hostname: support.ibm.comAlias: ibm.comAlias: supportVirtual Host junction protocol partner: support-vhost-httpServer 1:ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77Server State: runningOperational State: ThrottledThrottled at: 2005-03-01-17:07:24Hostname: int3.ibm.comPort: 443Server DN:Query_contents URL: /cgi-bin/query_contentsQuery-contents: unknownCase insensitive URLs: noAllow Windows-style URLs: yesCurrent requests: 0Total requests: 1

Place this server in an offline operational state by using the following command:pdadmin> server task default-webseald-cruz virtualhost offline \-i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https

See also

“server task offline” on page 135“server task online” on page 137“server task throttle” on page 164“server task virtualhost online”“server task virtualhost throttle” on page 188

server task virtualhost onlinePlaces the server that is at this virtual host junction in an online operational state.


Syntax

server task instance_name-webseald-host_name virtualhost online [–iserver_uuid] vhost_label

Description

The server task virtualhost online command places the server that is at thisvirtual host junction in an online operational state. The server now resumes normaloperation. If a server is not specified, all servers that are at this virtual hostjunction are placed in an online operational state.

Options

–i server_uuidUUID of the server to place in an online operational state. If a server is not


specified, all servers that are at this virtual host junction are placed in anonline operational state. Use the server task virtualhost show commandto determine the ID of a specific server. (Optional)






Authorization


Return codes






Example

In the following example:v The virtual host junction:

– Has the label support-vhost-https.– Is configured on the WebSEAL server abc.ibm.com.– Supports the virtual host support.ibm.com


v The virtual host support.ibm.com is on the junctioned server int3.ibm.com.

There is a requirement to place the int3.ibm.com server in an online operationalstate. To determine the UUID of this junctioned server, run the server taskvirtualhost show command:pdadmin> server task default-webseald-abc.ibm.com \virtualhost show support-vhost-https

Output is like:Virtual Host label: support-vhost-httpsType: SSL...Virtual hostname: support.ibm.comAlias: ibm.comAlias: supportVirtual Host junction protocol partner: support-vhost-httpServer 1:ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77Server State: runningOperational State: OfflineHostname: int3.ibm.comPort: 443Server DN:Query_contents URL: /cgi-bin/query_contentsQuery-contents: unknownCase insensitive URLs: noAllow Windows-style URLs: yesCurrent requests: 0Total requests: 1

Place this server in an online operational state by using the following command:pdadmin> server task default-webseald-cruz virtualhost online \-i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https

See also

“server task offline” on page 135“server task online” on page 137“server task throttle” on page 164“server task virtualhost offline” on page 180“server task virtualhost throttle” on page 188

server task virtualhost removeRemoves the specified server from a virtual host junction.


Syntax

server task instance_name-webseald-host_name virtualhost remove –iserver_uuid vhost_label

Options

–i server_uuidSpecifies the UUID of the server to be removed from the virtual hostjunction. For this command, the –i option, normally used to treat URLs as


case-sensitive, operates like the –u option. See the server task showcommand for details about obtaining the UUID.






Authorization


Return codes




Example

The following example removes the junctioned server int4.ibm.com from thevirtual host junction support-vhost-https. To determine the UUID of the server tobe removed, run the server task virtualhost show command:pdadmin> server task default-webseald-abc.ibm.com \virtualhost show support-vhost-https

Output is like:Virtual Host label: support-vhost-httpsType: SSLJunction hard limit: 0 - using global valueJunction soft limit: 0 - using global valueActive worker threads: 0Basic authentication mode: filter


Forms based SSO: disabledAuthentication HTTP header: do not insertRemote Address HTTP header: do not insertStateful junction: noBoolean Rule Header: noDelegation support: noMutually authenticated: noInsert WebSphere LTPA cookies: noInsert WebSEAL session cookies: noRequest Encoding: UTF-8, URI EncodedVirtual hostname: support.ibm.comAlias: ibm.comAlias: supportVirtual Host junction protocol partner: support-vhost-httpServer 1:ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77Server State: runningHostname: int3.ibm.comPort: 443Server DN:Query_contents URL: /cgi-bin/query_contentsQuery-contents: unknownCase insensitive URLs: noAllow Windows-style URLs: yesTotal requests: 1Server 2:ID: xycecc77-19ve-81y5-4h0a-90267hj5nn57Server State: runningHostname: int4.ibm.comPort: 444Server DN:Query_contents URL: /cgi-bin/query_contentsQuery-contents: unknownCase insensitive URLs: noAllow Windows-style URLs: yesTotal requests: 1

Remove the server from the virtual host junction:pdadmin> server task default-webseald-abc.ibm.com \virtualhost remove -i xycecc77-19ve-81y5-4h0a-90267hj5nn57 support-vhost-https

See also

“server task virtualhost add” on page 168“server task virtualhost create” on page 171“server task virtualhost delete” on page 177“server task virtualhost list” on page 179“server task virtualhost show”

server task virtualhost showDisplays information about the specified virtual host junction. The virtual hostjunction must exist, or an error is displayed.


Syntax

server task instance_name-webseald-host_name virtualhost show vhost_label


Options






Authorization

Users and groups that require access to this command must be given the l (list)permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given thispermission by default.

Return codes




Example

The example shows information for the virtual host junction:v With the label support-vhost-https.v Configured on the WebSEAL server abc.ibm.com.v That supports the virtual host support.ibm.com.

The virtual host support.ibm.com is on the junctioned server int3.ibm.com.pdadmin> server task default-webseald-abc.ibm.com \virtualhost show support-vhost-https

Output is like:


Virtual Host label: support-vhost-httpsType: SSLJunction hard limit: 0 - using global valueJunction soft limit: 0 - using global valueActive worker threads: 0Basic authentication mode: filterForms based SSO: disabledAuthentication HTTP header: do not insertRemote Address HTTP header: do not insertStateful junction: noBoolean Rule Header: noDelegation support: noMutually authenticated: noInsert WebSphere LTPA cookies: noInsert WebSEAL session cookies: noRequest Encoding: UTF-8, URI EncodedVirtual hostname: support.ibm.comAlias: ibm.comAlias: supportVirtual Host junction protocol partner: support-vhost-httpServer 1:ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77Server State: runningHostname: int3.ibm.comPort: 443Server DN:Query_contents URL: /cgi-bin/query_contentsQuery-contents: unknownCase insensitive URLs: noAllow Windows-style URLs: yesTotal requests: 1

See also

“server task virtualhost add” on page 168“server task virtualhost create” on page 171“server task virtualhost delete” on page 177“server task virtualhost list” on page 179“server task virtualhost remove” on page 184

server task virtualhost throttlePlaces the server that is at this virtual host junction in a throttled operational state.


Syntax

server task instance_name-webseald-host_name virtualhost throttle [–iserver_uuid] vhost_label

Description

The server task virtualhost throttle command places the server that is at thisvirtual host junction in a throttled operational state. Users can create a session withWebSEAL before the invocation of this command. Only requests from such userscontinue to be processed by the specified server. If a server is not specified, allservers that are at this virtual host junction are placed in a throttled operationalstate.


Options

–i server_uuidSpecifies the UUID of the server to throttle. If a server is not specified, allservers that are at this virtual host junction are placed in a throttledoperational state. Use the server task virtualhost show command todetermine the ID of a specific server. (Optional)






Authorization


Return codes






Example

In the following example, the virtual host junction:v Has the label support-vhost-https.


v Is configured on the WebSEAL server abc.ibm.com.v Supports the virtual host support.ibm.com.

The virtual host support.ibm.com is on the junctioned server int3.ibm.com.

There is a requirement to place the int3.ibm.com server in a throttled operationalstate. To determine the UUID of this junctioned server, run the server taskvirtualhost show command:pdadmin> server task default-webseald-abc.ibm.com \virtualhost show support-vhost-https

Output is like:Virtual Host label: support-vhost-httpsType: SSL...Virtual hostname: support.ibm.comAlias: ibm.comAlias: supportVirtual Host junction protocol partner: support-vhost-httpServer 1:ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77Server State: runningOperational State: OnlineHostname: int3.ibm.comPort: 443Server DN:Query_contents URL: /cgi-bin/query_contentsQuery-contents: unknownCase insensitive URLs: noAllow Windows-style URLs: yesCurrent requests: 0Total requests: 1

Place this server in a throttled operational state by using the following command:pdadmin> server task default-webseald-cruz virtualhost throttle \-i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https

See also

“server task throttle” on page 164“server task offline” on page 135“server task online” on page 137“server task virtualhost offline” on page 180“server task virtualhost online” on page 182

server task server restartRestarts a WebSEAL server by using the Security Access Manager server taskframework.

This command requires authentication of administrator ID and password.

Syntax

server task server_name server restart


Options

server_nameSpecifies the name of the Security Access Manager authorization serverrestart.

Authorization

Users and groups that require access to this command must have the s(administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name object. For example, the sec_master administrative user has thispermission by default.

Return codes

0 The command completed successfully. For WebSEAL server taskcommands, the return code is 0 when the command is sent to theWebSEAL server without errors. However, even after the command wassuccessfully sent, the WebSEAL server might not successfully complete thecommand. The WebSEAL server returns an error message.

1 The command failed. When a command fails, the pdadmin commandprovides a description of the error and an error status code in hexadecimalformat, for example, 0x14c012f2. See the IBM Security Access Manager forWeb Error Message Reference for a list of the Security Access Manager errormessages by decimal or hexadecimal codes.

Note: The restart is successful only if the WebSEAL server was started by usingthe pdweb_start script. The script must be running as a daemon on AIX, Linux, orSolaris, or as a service on Windows). The restart command does not work if theWebSEAL server is running in the foreground.

The result of the restart is not displayed on the administration console. You mustexamine the WebSEAL log files to confirm that the server restart was successful.

Example

The following example restarts server03:pdadmin> server task server03 server restart

server task server syncSynchronizes configuration data between two WebSEAL servers by using theSecurity Access Manager server task framework.


Syntax

server task webseal_server server sync server_name

Options

webseal_serverSpecifies the fully qualified server name of the installed WebSEAL instance.

server_nameSpecifies the name of the Security Access Manager authorization server


from which data is extracted. Configuration data on the host system isbacked up and then synchronized with this data.

Authorization


Return codes



Example

The following example synchronizes configuration data with serverdefault-webseald-abc.ibm.com:pdadmin> server task default-webseald-abc.ibm.com server syncmaster-webseald-abc.ibm.com

server task jdb export

Exports a junction database to a specified file.


Syntax

server task server jdb export file path=file_name

Options

server Specifies the fully qualified server name of the installed WebSEAL instance.You must specify this server name in the exact format as displayed in theoutput of the server list command.

path=file_nameAbsolute path of the file on the WebSEAL server to which the junctiondatabase is exported.

Authorization

Users and groups that require access to this command must have the s (serveradministration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user has thispermission by default.



Return codes


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

See the IBM Security Access Manager for Web Error Message Reference for alist of the Security Access Manager error messages by decimal orhexadecimal codes.

Note: This command can be used with the jdb import command to replicate livejunction databases.

Example

The following example exports the junction database from thedefault-webseald-abc-2.ibm.com server to a file named junction-db.xml in theWebSEAL server tmp directory:pdadmin> server task default-webseald-abc-2.ibm.com jdb export filepath=/tmp/junction-db.xml

server task jdb import

Imports a junction database from a specified file.


Syntax

server task server jdb import file path=file_name

Options

server Specifies the fully qualified server name of the installed WebSEAL instance.You must specify this server name in the exact format as displayed in theoutput of the server list command.

path=file_nameAbsolute path of the file on the WebSEAL server, from which the junctiondatabase is imported.

Authorization




Return codes




Note: This command can be used with the jdb export command to replicate livejunction databases.

Example

The following example imports the junction database from thedefault-webseald-abc-1.ibm.com server to a file named junction-db.xml in theWebSEAL server tmp directory:pdadmin> server task default-webseald-abc-1.ibm.com jdb import filepath=/tmp/junction-db.xml

server task cfgdb exportExports the current configuration to a named file.

Use this command with the cfgdb import command to migrate the configurationof a WebSEAL instance. The configuration database includes the WebSEALconfiguration and pre-configured data files, for example, the WebSEAL key files.

The [cfg-db-cmd:entries] and [cfg-db-cmd:files] stanzas stipulate which dataand files to include in (or exclude from) the configuration database.


Syntax

server task server_name cfgdb export file path=file_name

Options

server_nameSpecifies the name of the Security Access Manager authorization server onwhich the configuration data is located.

file_nameSpecifies the absolute path to and the file name of the new configurationdata file.

Authorization

Users and groups that require access to this command must have the s (serveradministration) permission in the ACL that governs the /WebSEAL/host_name-


instance_name/ object. For example, the sec_master administrative user has thispermission by default.


Return codes




Example

The following example exports configuration data to a file named /tmp/config.db:server task default-webseald-srvr3.ibm.com cfgdb export file path=/tmp/config.db

server task cfgdb importImports the configuration database from a specified file and applies thisconfiguration to the specified WebSEAL instance.

Use this command with the cfgdb export command to migrate the configuration ofa WebSEAL instance. The configuration database includes the WebSEALconfiguration and pre-configured data files, for example, the WebSEAL key files.

The [cfg-db-cmd:entries] and [cfg-db-cmd:files] stanzas stipulate what data toinclude in (or exclude from) the configuration database.

The cfgdb import command also creates a backup of the current configuration dataand stores it on the WebSEAL server, under the /etc/archive/instance directory.


Syntax

server task server_name cfgdb import file path=file_name

Options

server_nameSpecifies the name of the Security Access Manager Authorization Server onwhich the configuration data is located.

file_nameSpecifies the absolute path to and the file name of the new configurationdata file.


Authorization



Return codes




Example

The following example imports configuration data from a file named/tmp/config.db:server task default-webseald-srvr3.ibm.com cfgdb import file path=/tmp/config.db

server task file catReturns the contents of a specified file to the administration console. Thiscommand requires authentication of administrator ID and password.

Syntax

server task server_name file cat file_name byte_offset [-max bytes] [-encode]

Options

server_nameSpecifies the name of the Security Access Manager authorization server onwhich the file is hosted.

file_nameSpecifies the fully qualified name of the file which is to be retrieved.

byte_offsetSpecifies the offset in bytes from the start of the file at which the data isretrieved.

-max bytesSpecifies the maximum number of bytes to be returned from the file. If youdo not specify this parameter, the maximum number of bytes returned iscontrolled by the max-file-cat-command-length value in the [server]stanza. The max-file-cat-command-length value takes precedence over the


-max bytes value. If the specified file is larger than themax-file-cat-command-length value, the returned data is truncated.

--encodeDesignates that the contents of the file must be base-64 encoded before it isreturned. (Optional)

Authorization


Return codes



Note: For more information about WebSEAL junctions, see the IBM Security AccessManager for Web WebSEAL Administration Guide.

This command is available only when WebSEAL is installed.

Example

The following example requests the first 512 bytes of data (base-64 encoded) fromthe readme.txt file. The file is in the /temp/ folder on server03:pdadmin> server task server03 file cat /temp/readme.txt 0 -max 512 -encode

The output is the content of the specified file.

user createCreates a Security Access Manager user.


Syntax

user create [–gsouser] [–no-password-policy] user_name dn cn sn password[groups]

Description

A user is a registered participant of the secure domain. A GSO user is a SecurityAccess Manager user that additionally has the authority to use single sign-on towork with web resources.


You can create users in the Active Directory Lightweight Directory Service (ADLDS) user registry. You must create such users in the same AD LDS partitionwhere the Access Manager Management Domain information is stored.

The –gsouser option enables global sign-on capabilities. Users that are created inan Active Directory are automatically given the capability to own single sign-oncredentials. This capability cannot be removed. When you use an LDAP userregistry, this capability must be explicitly granted. After this capability is granted,it can be removed.

The –no-password-policy option allows the administrator to create the user withan initial password that is not checked by the existing global password policies. Ifthis option is not present in the command, the password that is provided ischecked against the global password policies. In this case, the user createcommand fails if the password is invalid, and the error message includesinformation about what conditions were not met.

However, if the administrator applies the password option on the user modifycommand, the -no-password-policy option is not available. Therefore, themodified password is always checked against the global password policy settings.

Options

–gsouserEnables the global sign-on (GSO) capabilities for the user. Applies only tousers created in an LDAP user registry. Users that are created in a URAFuser registry are automatically granted this capability. (Optional)

–no-password-policyIndicates that password policy is not enforced during the creation of theuser account. The non-enforcement does not affect password policyenforcement after user creation. (Optional)

cn Specifies the common name that is assigned to the user that is beingcreated. For example: "Mary"

dn Specifies the registry identifier that is assigned to the user that is beingcreated. The registry identifier must be known before a new user accountcan be created. The registry identifier must be unique within the userregistry. If the user registry is Active Directory, certain characters are notallowed. See “Characters disallowed for distinguished names” on page 310for the list of these characters.

The format for a distinguished name is like:"cn=Mary Jones,ou=Austin,o=Tivoli,c=us"

groups Specifies a list of groups to which the new user is assigned. The format ofthe group list is a parenthesized list of group names, which are separatedby spaces. The groups must exist, or an error is displayed. Examples ofgroups: deptD4D and printerusers. (Optional)

passwordSpecifies the password that is set for the new user. Passwords must adhereto the password policies set by the administrator.

sn Specifies the surname of the user that is being created. For example:"Jones"

user_nameSpecifies the name for the user to create. This name must be unique. A


valid user name is an alphanumeric string that is not case-sensitive. If theuser registry is Active Directory, certain characters are not allowed. See“Characters disallowed for user and group name” on page 309 for the listof these characters. If the user is a GSO user, certain characters are notallowed. See “Characters disallowed for GSO names” on page 311 for thelist of these characters.

Note: Consider that you did not change the 7 - bit checking default valueduring configuration of the Sun web server. In this case, turn off checkingso that non-ASCII characters can be stored in attributes.

Examples of user names are dlucas, sec_master, "Mary Jones".

Return codes



Examplesv The following example, entered as one line, creates user dlucas:

pdadmin sec_master> user create –gsouser dlucas "cn=DianaLucas,ou=Austin,o=Tivoli,c=US" "Diana Lucas" Lucas lucaspwd

v The following example, entered as one line, creates user maryj:pdadmin sec_master> user create –gsouser maryj "cn=Mary Jones,o=tivoli,c=us"Mary Jones maryjpwd

To make the user accounts valid, you must use the user modify command to setthe account-valid option to yes.

See also

“user delete”“user import” on page 200“user modify” on page 203

user deleteDeletes the specified Security Access Manager user. Optionally deletes theinformation of the user in the user registry.


Syntax

user delete [–registry] user_name

Options

–registryDeletes the information of the user from the user registry. If this option is


not specified, the registry user information can be used to create anotherSecurity Access Manager user by using the user import command.(Optional)

user_nameSpecifies the name of the account to be deleted. Any resource credentialsthat are associated with a user account are automatically removed at thesame time the user account is deleted. The user must exist, or an error isdisplayed.


Return codes




Example

The following example deletes the dlucas user:pdadmin sec_master> user delete dlucas

See also

“user create” on page 197“user import”

user importCreates a Security Access Manager user by importing user data that exists in theuser registry.


If the user registry is Active Directory Lightweight Directory Service (AD LDS),import within the AD LDS partition where the Security Access Managermanagement domain information is stored.

Syntax

user import [–gsouser] user_name dn [group_name]

Description

Imported user accounts are created invalid by default. To make the user accountvalid, you must use the user modify command to set the account-valid option toyes.

Options

–gsouserSpecifies that the user has single sign-on capabilities. (Optional)


dn Specifies the registry identifier of the user that is being imported. Thisidentifier must exist in the user registry and must not be associated withanother user in the same Security Access Manager secure domain. Theformat for a distinguished name is like:cn=Claude Wright,ou=Austin,o=Tivoli,c=us

group_nameSpecifies an optional group to which the user is being added. The groupmust exist, or an error is displayed. (Optional)


user_nameSpecifies a unique Security Access Manager user name. This user is createdfrom information that exists in the user registry. For URAF-based registries,the user name must correspond to a short name already defined for theuser that is being imported from the user registry. An example of aURAF-based registry is Active Directory. A valid user name is analphanumeric string that is not case-sensitive. If the user is a GSO user,certain characters are not allowed. See “Characters disallowed for GSOnames” on page 311 for the list of these characters.


Return codes



Example

The following example creates the user mlucaser by importing information fromthe registry user cn=Mike Lucaser,ou=Austin,o=Tivoli,c=US:pdadmin sec_master> user import –gsouser mlucaser"cn=Mike Lucaser,ou=Austin,o=Tivoli,c=US"

See also

“user create” on page 197“user modify” on page 203

user listLists users by Security Access Manager user name or by registry identifier.


Syntax

user list pattern max_return

user list-dn pattern max_return


Options

list pattern max_returnSpecifies the pattern for the principal name. The pattern can include amixture of wildcard and string constants. The specified pattern iscase-sensitive. For example: *luca*

The pattern max_return options specify the maximum number of entriesthat are found and returned for a single request. The number that isreturned is also governed by the server configuration, which specifies themaximum number of results that can be returned as part of a searchoperation.

The actual maximum returned entries is the minimum number of resultsbetween the pattern max_return and the configured value on the server.The configured value is taken from the max-search-size=[0|num_entries]entry in the [ldap] stanza. The [ldap] stanza is in the ldap.confconfiguration file.

For a discussion of how to limit the number of users that are returnedfrom the user list command, see the IBM Security Access Manager for Web:Performance Tuning Guide.

list-dn pattern max_returnSpecifies the pattern for the common name (CN) portion of the registryidentifier of the user. When you specify the pattern, you can exclude thecn= component. The pattern can include a mixture of wildcard and stringconstants, and is case-sensitive. For example, *luca*.

The returned list contains users that are defined in the user registry but arenot necessarily Security Access Manager users. Users that are not SecurityAccess Manager users can be imported into Security Access Manager byusing the user import command.

Note: When the user registry contains many user definitions, use wildcardcharacters with discretion. When a pattern includes one or more wildcardcharacters, the command attempts to find all user definitions that match thespecified pattern. However, the command displays only the specified number ofmatching definitions in the user registry.

For example, if the user registry contains 10,000 definitions, specifying a singlewildcard (user list * 100) displays only the first 100 matching definitions butfinds all 10,000 definitions.

Return codes




Examplesv The following example lists the users that match the specified pattern:

pdadmin sec_master> user list *luca* 2


The output is like:dlucasmlucaser

v The following example lists the users that match the specified registry identifier:pdadmin sec_master> user list-dn *luca* 2

The output is like:cn=Diana Lucas,ou=Austin,o=Tivoli,c=UScn=Mike Lucaser,ou=Austin,o=Tivoli,c=US

See also

“user show” on page 205

user modifyChanges various user account attributes.


Syntax

user modify user_name account-valid {yes|no}

user modify user_name password password

user modify user_name password-valid {yes|no}

user modify user_name description description

user modify user_name gsouser {yes|no}

Options

account-valid {yes|no}Enables or disables the specified user account. A user cannot log in with adisabled account. Valid values are yes and no.

password passwordModifies the user password. The new password must comply withpassword policies in effect.

When a password is set or changed, the password must comply to:v The defined Security Access Manager password policy andv The password policies for any underlying operating systems or user

registry.v

When the password policy is enforced, Security Access Manager firstvalidates compliance against the Security Access Manager password policycurrently in effect. Then, Security Access Manager validates complianceagainst the underlying user registry. Although a password complies to thedefined Security Access Manager policy, it might fail against the passwordpolicy of the underlying user registry.

Note: Old passwords can still be used after a password change when:


v You are using Active Directory as your user registry.v The Active Directory server is running on Windows 2003 SP1 or later.

For more information, see the following web page:

http://support.microsoft.com/?id=906305

password-valid {yes|no}Validates or invalidates the password for the specified user account. Validvalues are yes and no. If the value is no, the password seems expired andthe user cannot log in using the password. For a user to log in, anadministrator must set the valid state to yes. The user can also authenticateby using another method, such as using a certificate.

Another reason a user might not be able to authenticate with a specifiedpassword is because the maximum password age was exceeded. If youcheck and find that the password-valid is set to yes, then try changing thevalue for the policy set max-password-age parameter. Only anadministrator or a user that has the authority can set the max-password-agepolicy on a user account. A user cannot set this policy on their ownaccount. This policy sets the maximum time, in days, that a password isvalid. Time is relative to the last time the password was changed.

When you change the value for password-valid or reset policy setmax-password-age, you do not have to change the password.

If you reset a password, the password-valid parameter automaticallyswitches to back to yes, and the max-password-age parameter resets the ageto expire. For example, if the maximum password age is set to 30 days,another 30 days begins from the time you reset the password.

user_nameSpecifies the name of the account to be modified. The user must exist, oran error is displayed. A valid user name is an alphanumeric string that isnot case-sensitive. If the user is a GSO user, certain characters are notallowed. See “Characters disallowed for GSO names” on page 311 for thelist of these characters. Examples of user names are dlucas, sec_master,and "Mary Jones"

description descriptionSpecifies any text string that describes the user that is being created.Examples of user description are "Head of department" and "Departmentnumber of employee".

gsouser {yes|no}Enables global sign-on (GSO) capabilities for the specified user. Validvalues are yes and no. This property cannot be changed for users that arecreated in a URAF user registry.

Return codes




http://support.microsoft.com/?id=906305

Examplesv The following example enables the specified user account:

pdadmin sec_master> user modify dlucas account-valid yes

v The following example changes the password for a user account:pdadmin sec_master> user modify dlucas password newpasswd

See also

“user create” on page 197“user import” on page 200

user showDisplays the properties of the specified user.


Syntax

user show user_name

user show-dn dn

user show-groups user_name

Options

show user_nameSpecifies the name of the user to display. The user must exist, or an error isdisplayed.

Based on the Policy Server and WebSEAL configuration settings, thefollowing information is displayed:Last login: YYYY-mm-dd-HH:MM:SSLast Password Change: YYYY-mm-dd-HH:MM:SS

The system displays the local time of the computer where pdadmin wasrun. For more information about the last login and last password changeconfiguration settings, see the Appendix C. Configuration file stanzareference in the IBM Security Access Manager for Web: Administration Guide.


show-dn dnDisplays the user that is specified by the identifier of the user in the userregistry. The returned user is defined in the user registry, but it is notnecessarily a Security Access Manager user. Users that are not SecurityAccess Manager users can be imported into Security Access Manager byuse of the user import command. The format for a distinguished name islike:cn=Claude Wright,ou=Austin,o=Tivoli,c=us

Based on the Policy Server and WebSEAL configuration settings, thefollowing information is displayed:Last login: YYYY-mm-dd-HH:MM:SSLast Password Change: YYYY-mm-dd-HH:MM:SS


The system displays the local time of the computer where pdadmin wasrun. For more information about last login and last password changeconfiguration settings, see the Appendix C. Configuration file stanzareference in the IBM Security Access Manager for Web Administration Guide.

show-groups user_nameDisplays the groups in which the specified user is a member. The usermust exist, or an error is displayed.


Return codes



Examplesv The following example displays the user account information for testuser:

pdadmin sec_master> user show testuser

The output is like:Login ID: testuserLDAP DN: cn=testuser,o=tivoli,c=usLDAP CN: testLDAP SN: testDescription: a test userIs SecUser: yesIs GSO user: noAccount valid: noPassword valid: yesLast login: 1999-09-05-01:08:55Last Password Change: 1999-09-04-05:06:45

v The following example displays the groups of which the specified user is amember:pdadmin sec_master> user show-groups dlucas

The output is like:salescreditengineering

v The following example provides more information about the user when theregistry identifier is specified:pdadmin sec_master> user show-dn "cn=Diana Lucas,ou=Austin,o=Tivoli,c=US"

The output is like:Login ID: dlucasLDAP dn: cn=Diana Lucas,ou=Austin,o=TivoliInc,c=USLDAP cn: Diana LucasLDAP sn: LucasDescription: Diana Lucas, Credit Dept HCUSIS SecUser: trueIS GSO user: falseAccount valid: true


Password valid: trueLast login: 1999-09-05-01:08:55Last Password Change: 1999-09-04-05:06:45Authentication mechanism: Default:LDAP

See also

“user list” on page 201


Chapter 2. Security Access Manager utilities

In addition to the commands provided for the pdadmin utility, Security AccessManager provides the following utilities for your use.

These utilities are separated into the following categories, with some utilitiesdefined in multiple categories:v “Installation and configuration utilities”v “Migration utilities” on page 210v “WebSEAL utilities” on page 211v “Session management server utilities” on page 211v “Security Access Manager plug-in for web servers utilities” on page 211v “Serviceability and problem determination utilities” on page 212

Installation and configuration utilitiesInstallation and configuration utilities are listed together in the following table forreference.

Table 18 lists the installation and configuration utilities.

Table 18. Security Access Manager installation and configuration utilities

Utility Description

“amauditcfg” on page 213 Configures or unconfigures the Common Auditing andReporting Service client.

“amwebcfg” on page 217 Configures or unconfigures a WebSEAL server.

“amwpmcfg” on page 221 Configures or unconfigures the Web Portal Managercomponent of Security Access Manager.

“bassslcfg” on page 226 Configures or modifies the configuration information of theIBM Security Access Manager runtime.

“ivacld_setup” on page 230 Configures the authorization server on Windows platforms.

“ivacld_uninst” on page 231 Unconfigures the authorization server on Windowsplatforms.

“ivbase_setup” on page 233 Configures the Security Access Manager runtime onWindows platforms.

“ivbase_uninst” on page 236 Unconfigures the Security Access Manager runtime onWindows platforms.

“ivmgrd_setup” on page 237 Configures the policy server on Windows platforms.

“ivmgrd_uninst” on page 240 Unconfigures the policy server on Windows platforms.

“mgrsslcfg” on page 245 Creates or modifies the SSL certificates of the policy server.

“pdconf” on page 258 Displays and modifies Security Access Managerconfiguration files.

“pdconfig” on page 260 Configures and unconfigures Security Access Managercomponents.

“pdjrtecfg” on page 261 Configures the IBM Security Access Manager Runtime forJava.

“pdproxycfg” on page 272 Configures and unconfigures a policy proxy server.


Table 18. Security Access Manager installation and configuration utilities (continued)

Utility Description

“PDAcld_config” on page 247 Configures an Authorization server on AIX, Linux, andSolaris platforms.

“PDAcld_unconfig” on page250

Unconfigures an Authorization server on AIX, Linux, andSolaris platforms.

“PDMgr_config” on page 267 Configures a Policy server on AIX, Linux, and Solarisplatforms.

“PDMgr_unconfig” on page270

Unconfigures a Policy server on AIX, Linux, and Solarisplatforms.

“PDRTE_config” on page 275 Configures the Security Access Manager Runtime on AIX,Linux, and Solaris platforms.

“PDRTE_unconfig” on page278

Unconfigures the Security Access Manager Runtime onAIX, Linux, and Solaris platforms.

“pdsmsclicfg” on page 279 Configures the command-line utility plug-in for the sessionmanagement server.

“pdwpicfg” on page 288 Configures or unconfigures the plug-in for web servers.

“smscfg” on page 293 Configures the session management server.

“svrsslcfg” on page 301 Configures, unconfigures, or modifies the configurationinformation of a resource manager to use an SSL connectionfor communicating with the policy server.

This utility is used for C application servers only. For Javaapplication servers, use the equivalentcom.tivoli.pd.jcfg.SvrSslCfg Java class.

For information about this class, see the IBM Security AccessManager for Web: Authorization Java Classes DeveloperReference.

Migration utilitiesMigration utilities are listed together in the following table for reference.

Table 19 lists the utilities that can be used to migrate Security Access Manager userregistry data.

Table 19. Security Access Manager migration utilities

Utility Description

“adschema_update” on page212

Adds the new attribute for recording maximum concurrentweb sessions.

“ivrgy_tool” on page 242 Completes either of these actions:

v Updates the Security Access Manager schema on thespecified LDAP server.

v Applies the required ACLs to suffixes added to theLDAP server after the policy server was configured.

“pdbackup” on page 254 Backs up, restores, and extracts Security Access Managerdata.


WebSEAL utilitiesWebSEAL utilities are listed together in the following table for reference.

Table 20 lists the WebSEAL utilities.

Table 20. WebSEAL utilities

Utility Description

“amwebcfg” on page 217 Configures or unconfigures a WebSEAL server.

“cdsso_key_gen” on page 229 Generates a key that is used during encrypting anddecrypting authentication tokens for Security AccessManager WebSEAL cross-domain single sign-on.

“pdweb” on page 284 Starts, stops, or restarts a WebSEAL server or displaysserver status.

“query_contents” on page 290 Returns the contents of the root directory of a web space ona third-party web server.

Session management server utilitiesSession management server utilities are listed together in the following table forreference.

Table 21 lists the session management server (SMS) utilities. These utilities requirethe installation of SMS. SMS provides a unified view of WebSEAL and plug-in forweb servers current sessions.

Table 21. Session management server utilities

Utility Description

“pdsmsclicfg” on page 279 Configures the command-line utility plug-in for the sessionmanagement server.

“smsbackup” on page 291 Gathers information to help IBM Software Support inproblem determination.

“smscfg” on page 293 Configures the session management server.

“smsservicelevel” on page300

Lists the current service level of the session managementserver files on the local system.

Security Access Manager plug-in for web servers utilitiesSecurity Access Manager plug-in for web servers utilities are listed together in thefollowing table for reference.

Table 22 lists the Security Access Manager plug-in for web Servers utilities.

Table 22. Security Access Manager for web servers utilities

Utility Description

“pdwebpi” on page 285 Specifies the plug-in for web servers version information.Also, determines whether to run plug-in for web Servers asa daemon or run it in the foreground.

“pdwebpi_start” on page 286 Starts, restarts, and stops the plug-in for web serversprocess on AIX, Linux, and Solaris installations. Also,displays the status of all web servers.

Chapter 2. Security Access Manager utilities 211

Table 22. Security Access Manager for web servers utilities (continued)

Utility Description

“pdwpi-version” on page 287 Lists the version and copyright information for plug-in forweb servers.

“pdwpicfg” on page 288 Configures or unconfigures the plug-in for web servers.

“query_contents” on page 290 Returns the contents of the root directory of a web space ona third-party web server.

Serviceability and problem determination utilitiesServiceability and problem determination utilities are listed together in thefollowing table for reference.

Table 23 lists the serviceability and problem determination utilities.

Table 23. Serviceability and problem determination utilities

Utility Description

“pdbackup” on page 254 Backs up, restores, and extracts Security Access Managerdata.

“pdjservicelevel” on page 266 Returns the service level of installed Security AccessManager files that use the IBM Security Access ManagerRuntime for Java package.

“pdservicelevel” on page 278 Returns the service level of installed Security AccessManager files that use the Security Access ManagerRuntime package.

“pdversion” on page 282 Lists the current version of Security Access Managercomponents that are installed on the system.

“pdwebpi” on page 285 Specifies the plug-in for web servers version information.Also, determines whether to run plug-in for web servers asa daemon or run it in the foreground.

“pdwpi-version” on page 287 Lists the version and copyright information for plug-in forweb servers.

“smsbackup” on page 291 Gathers information to help IBM Software Support inproblem determination.

“smsservicelevel” on page300

Lists the current service level of the session managementserver files on the local system.

adschema_updateModifies the Microsoft Active Directory schema to work with the current versionof Security Access Manager.

Syntax

adschema_update [–f schema_file] –u active_directory_administrator_id [–o[g[ui]]] –p active_directory_administrator_pwd [–r response_file]

Description

Use the adschema_update utility to modify the Microsoft Active Directory schemafor the current version of Security Access Manager.


Run this utility on the Active Directory domain controller against which the policyserver is configured after you upgrade to IBM Security Access Manager for Web,version 7.0.

Parameters

–f schema_fileSpecifies the name of the Active Directory schema file. By default, theadschema.def file is in installation_directory\etc directory. (Optional)

–o [g[ui]]

–o Specifies to output messages to STDERR. (Optional)

–o g Specifies to display messages in a pop-up message box (GUI).(Optional)

–o gui Specifies to display messages in a pop-up message box (GUI).(Optional)

–p active_directory_administrator_pwdSpecifies the password for the Active Directory administrator.

–r response_fileSpecifies the fully qualified path and file name of the response file to useduring silent configuration. There is no default response file name. Theresponse file contains stanzas and key=value pairs. For information aboutusing response files, see the "Using response files" appendix in the IBMSecurity Access Manager for Web Command Reference. (Optional)

–u active_directory_administrator_idSpecifies the Active Directory administrator ID.

Availability

This utility is in the following default installation directory:c:\Program Files\Tivoli\Policy Director\sbin

Note: Run this utility on the system where the Security Access Manager policyserver is installed and configured.

Return codes

0 The utility completed successfully.

1 The utility failed. When a utility fails, a description of the error and anerror status code in hexadecimal format is provided (for example,0x15c3a00c). See the IBM Security Access Manager for Web Error MessageReference. This reference provides a list of the Security Access Managererror messages by decimal or hexadecimal codes.

amauditcfgConfigures or unconfigures the Common Auditing Service client.

Syntax

amauditcfg –action config –srv_cfg_file configuration_file –audit_srv_url url–enable_ssl no –disk_cache_mode never


amauditcfg –action config –srv_cfg_file configuration_file –audit_srv_url url–enable_ssl no –disk_cache_mode {always|auto} –disk_cache_file cache_file

amauditcfg –action config –srv_cfg_file configuration_file –audit_srv_url url–enable_ssl yes –audit_key_file key_file –audit_stash_file stash_file–enable_pwd_auth no –disk_cache_mode never

amauditcfg –action config –srv_cfg_file configuration_file –audit_srv_url url–enable_ssl yes –audit_key_file key_file –audit_stash_file stash_file–enable_pwd_auth no –disk_cache_mode {always|auto} –disk_cache_filecache_file

amauditcfg –action –srv_cfg_file configuration_file –audit_srv_url url–enable_ssl yes config key_file –audit_stash_file stash_file –enable_pwd_authyes –audit_id audit_id –audit_pwd audit_password –disk_cache_mode never

amauditcfg –action config –srv_cfg_file configuration_file –audit_srv_url url–enable_ssl yes –audit_key_file key_file –audit_stash_file stash_file–enable_pwd_auth yes –audit_id audit_id –audit_pwd audit_password–disk_cache_mode {always|auto}–disk_cache_file cache_file–temp_storage_full_timeout number_of_seconds

amauditcfg –action unconfig –srv_cfg_file configuration_file

amauditcfg –operations

amauditcfg –help [options]

amauditcfg –rspfile response_file

amauditcfg –usage

amauditcfg –?

Description

Use the amauditcfg utility to configure or unconfigure the Common AuditingService client from the command line. The utility can be run in command-linemode or response file mode.

In command-line mode, all parameters must be specified from the command line.

In response file mode, the utility obtains the necessary parameters from theresponse file. You must manually create the response file, and the response filerequires all parameters.

Parameters

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

–action {config|unconfig}This parameter takes one of the following arguments:

config Configures the client.

unconfigUnconfigures the client.


–audit_id administrator_idSpecifies the WebSphere administrator who has the EventSource role that ismapped to the CommonAuditService. This ID is authenticated throughWebSphere by using HTTP basic authentication. This parameter is validwhen the –enable_pwd_auth parameter is set to yes.

–audit_key_file key_fileSpecifies the fully qualified name of the key file that is required for securecommunication with the web service. This parameter is required when the–enable_ssl parameter is set to yes.

–audit_pwd audit_id_passwordSpecifies the password for the WebSphere administrator who has theEventSource role that is mapped to the CommonAuditService. Thisparameter is valid when the –enable_pwd_auth parameter is set to yes.

–audit_srv_url urlSpecifies the URL of the web service. For secure communication, use thefollowing URL:

https://hostname:9443/CommonAuditService/services/Emitter

For nonsecure communication, use the following URL:http://hostname:9080/CommonAuditService/services/Emitter

–audit_stash_file stash_fileSpecifies the fully qualified name of the stash file that is required forsecure communication with the Common Audit web service. Thisparameter is required when the –enable_ssl parameter is set to yes.

–disk_cache_file cache_fileSpecifies the fully qualified name of the disk cache file. This parameter isrequired when the –disk_cache_mode parameter is set to always or auto.

–disk_cache_mode {always|never|auto}Specifies whether to enable disk caching, and, when enabled, indicateshow to handle disk caching. The following values are valid:

always Indicates that audit events are always written directly to the diskcache.

never Indicates that audit events are written to the event queue. There isno disk cache.

auto Indicates that audit events are written to the event queue exceptwhen the server is down or the event queue is full. Under theseconditions, the audit events are written to disk cache.

The default value is auto.

–temp_storage_full_timeout {0|-1| number_of_seconds}Specifies the number of seconds that the common auditing and reportingservices client waits before cached events are discarded. The services clientmight discard cached events when the temporary disk cache storage isfilled.

Valid values are -1, 0, number of seconds. A value of -1 indicates thatcached events are not discarded.

A value of 0 indicates that cached events are discarded immediately. Aspecified number of seconds indicates that cached events are not discardeduntil the specified number of seconds passes. The default value is -1.(Optional)


This parameter takes effect only when –disk_cache_mode is set to always orauto.

–enable_pwd_auth {yes|no}Specifies whether password authentication is used. Valid values are yes orno. This parameter is valid when the –enable_ssl parameter is set to yes.The default value is no. (Optional)

–enable_ssl {yes|no}Specifies whether to enable SSL communication between the CommonAudit client (the security server) and the Common Audit web service.Valid values are yes or no. The default value is no. (Optional)

–help [parameters]Lists all parameters and their descriptions when specified withoutparameters. When one or more parameters are specified, lists the specifiedparameters and their descriptions.

–operationsPrints all the valid parameters.

–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 key=value pairs. For information about using response files, see the"Using response files" appendix in the IBM Security Access Manager for WebCommand Reference. (Optional)

–srv_cfg_file configuration_fileSpecifies the name of the configuration file that is associated with thesecurity server (the Common Audit client). During configuration, entriesare set to enable auditing. During an unconfiguration, the doAudit stanzaentry is set to no in the [cars-client] stanza of the server-specificconfiguration file. For more information about entries in configuration files,see the IBM Security Access Manager for Web Command Reference.

–usage Displays the syntax and an example for this utility.

Availability

This utility is in one of the following default installation directories:v On AIX, Linux, and Solaris operating systems:

/opt/policyDirector/sbin/

v On Windows operating systems:c:\Program Files\Tivoli\PolicyDirector\sbin

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

Return codes




Examples

The following example configures an authorization server by using SSL andpassword authentication:amauditcfg -action config \-srv_cfg_file /opt/PolicyDirector/etc/pdaudit.pdacld.conf \-srv_url https://hostname:9443/CommonAuditService/services/Emitter \-enable_ssl yes -audit_key_file /certs/WSclient.kdb \-audit_stash_file /certs/WSclient.sth -enable_pwd_auth yes \-audit_id administrator_id -auditpwd password

amwebcfgConfigures or unconfigures a WebSEAL server.

Syntax

amwebcfg –action config –host host_name –listening_port am_listening_port–inst_name instance_name –nw_interface_yn {yes|no} admin –admin_pwd password–ip_address ip_address –domain am_domain –ssl_yn {yes|no} –key_file key_file–key_file_pwd password –cert_label label –ssl_port ssl_port –http_yn {yes|no}–http_port http_port –https_yn {yes|no} –https_port https_port –doc_rootdoc_root

amwebcfg –action config –rspfile response_file

amwebcfg –action config –interactive

amwebcfg –action unconfig –inst_name instance_name –admin_id admin –admin_pwdpassword

amwebcfg –action unconfig –interactive

amwebcfg –operations

amwebcfg –help [options]

amwebcfg –usage

amwebcfg –?

Description

Use the amwebcfg utility to configure a WebSEAL instance from the command line.The utility can be run in interactive mode, command-line mode, or response filemode.

In interactive mode, you are prompted to supply the necessary values.

In command-line mode, all parameters must be specified from the command line.

In response file mode, the utility obtains the necessary options from the responsefile. The response file requires all parameters. The response file must be createdmanually.


Parameters


–action {config|name|status|unconfig}This parameter takes one of the following arguments:

config Configures a WebSEAL instance.

name Retrieves the Security Access Manager WebSEAL package nameand returns the name value to the pdconfig utility. This parameteris used only by pdconfig. Do not use this parameter from thecommand line.

status Returns the status value to the pdconfig utility. This parameter isused only by pdconfig. Do not use this parameter from thecommand line.

unconfigUnconfigures a WebSEAL instance.

–admin_id adminSpecifies the name of the Security Access Manager administrative user. Thedefault value is sec_master.

–admin_pwd passwordSpecifies the Security Access Manager administrative user password (theadministrative user is normally sec_master).

–cert_label labelSpecifies the LDAP client certificate label. This parameter is used onlywhen SSL communication is enabled between WebSEAL and an LDAPserver (–ssl_yn yes).

When SSL communication is enabled between WebSEAL and the LDAPserver, SSL does not require an LDAP client certificate label. Thus this labelfile is optional, even amwebcfg is called with –ssl_yn yes. When the clientlabel is not specified, SSL uses default certificate that is contained in thekeyfile.

Used with –action config.

–doc_root doc_rootSpecifies the web document root directory. The directory must exist. Usedwith –action config.

When this parameter is not supplied on the command line, amwebcfgcreates a default directory. The default directory path includes the instancename, prefixed by www-. For example, when the instance name is web1, andthe doc_root is not specified on the command line, the following directoryis created:

On AIX, Linux, and Solaris operating systemsopt/pdweb/www-web1/docs

On Windows operating systemsinstallation_directory\pdweb\www-web1\docs

amwebcfg creates the following web document root directory when:v The first WebSEAL instance is configured.v The default server instance name of default is accepted.v No value for –doc-root is supplied.


On AIX, Linux, and Solaris operating systemsopt/pdweb/www-default/docs

On Windows operating systemsinstallation_directory\pdweb\www-default\docs

–help [options]Lists each parameter and a one line description of it when specifiedwithout an argument. When one or more arguments are specified,WebSEAL lists each specified parameter and a one line description of it.

–host host_nameSpecifies the host name that is used by the Security Access Manager policyserver to contact a WebSEAL server. This parameter is required for –actionconfig.

Valid values include any valid IP host name. For example:libra.dallas.ibm.com

–http_yn {yes|no}Specifies whether HTTP access is allowed to the WebSEAL instance. Thisparameter is required for –action config. The valid Boolean indicators areyes or no. There is no default value.

–http_port http_portSpecifies the port number for unsecure HTTP access. This parameter isrequired for –action config when –http_yn is set to yes. You can use port80 for HTTP. There is no default value.

–https_yn {yes|no}Specifies whether HTTPS access is allowed to the WebSEAL instance. Thisparameter is required for –action config. The valid Boolean indicators areyes or no. There is no default value.

–https_port https_portSpecifies the port number for secure HTTP access. This parameter isrequired for –action config when –https_yn is set to yes. You can use port443 for HTTPS. There is no default value.

–inst_name instance_nameSpecifies the name of the WebSEAL instance as a string. For example, web1.This string does not include the host name. This parameter is required for–action config.

The following characters are allowed:v Any ASCII character (A-Z or a-z)v Numeric character (0-9)v Period (.)v Hyphen (–)v Underscore (_)

When you use the GUI to configure the first WebSEAL instance, amwebcfgsupplies a default instance name of default. This instance name can bechanged to another name (for example, webseal1).

–interactiveSpecifies that the configuration is to be done interactively by theadministrator. WebSEAL displays a text-based menu and presents a seriesof prompts to obtain the necessary configuration information from theadministrator.


Note: Interactive mode is supported only on AIX, Linux, and Solarisoperating systems. When this parameter is used on Windows operatingsystems, an error message states that the parameter is not supported.

–domain am_domainSpecifies the name of the Security Access Manager management domain.When this value is not supplied, the default value of default applies.

–ip_address ip_addressSpecifies the logical network interface that is the IP address for theWebSEAL server. This parameter is required with –action config onlywhen –nw_interface_yn is set to yes.

–key_file key_fileSpecifies the LDAP SSL key file. This parameter is required with –actionconfig only when SSL communication is enabled between the WebSEALserver and an LDAP server.

–key_file_pwd passwordSpecifies the LDAP SSL key file password. This parameter is required with–action config only when SSL communication is enabled between theWebSEAL server and the LDAP server.

–listening_port am_listening_portSpecifies the listening port number for the Security Access Manager policyserver. This listening port is the port on which the WebSEAL server andthe policy server communicate. The port must be greater than 1024, andmust be available for use. This parameter is required with –action config.

–nw_interface_yn {yes|no}Specifies whether to use a logical network interface. The valid Booleanindicators are yes or no. This parameter is required with –action configwhen you add a WebSEAL instance. There is no default value.

–operationsPrints all the valid command-line options.

–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 key=value pairs. For information about using response files, see the"Using response files" appendix in the IBM Security Access Manager for Web:Command Reference.

–ssl_port ssl_portSpecifies the port number on which SSL communication takes placebetween the WebSEAL server and the LDAP server. This parameter isrequired only when –ssl_yn is set to yes as part of –action config. Theknown port for SSL is 636. There is no default value.

–ssl_yn {yes|no}Specifies whether to enable SSL communication between the WebSEALserver and the LDAP server. The valid Boolean indicators are yes or no.This parameter is required with –action config. There is no default value.

–usage Displays the syntax and an example for this utility.


Availability


/opt/pdweb/bin

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

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

Return codes



Examplesv The following example configures the default WebSEAL instance with SSL

communication enabled with an LDAP server:amwebcfg –action config –inst_name default –host diamond.subnet2.ibm.com–listening_port 7234 –nw_interface_yn no –admin_id sec_master–admin_pwd mypassw0rd –ssl_yn yes –key_file /tmp/client.kdb–keyfile_pwd mypassw0rd –cert_label ibm_cert –ssl_port 636 –http_yn yes–http_port 80 –https_yn yes –https_port 443 –doc_root /usr/docs

v The following example configures a WebSEAL instance named web1 to use alogical network interface, and to not enable SSL communication with an LDAPserver:amwebcfg –action config –host emerald.subnet2.ibm.com –listening_port 7235–inst_name web1 –nw_interface_yn yes –ip_address 111.222.333.222–admin_id sec_master –admin_pwd mypassw0rd –http_yn yes –http_port 81–https_yn yes –https_port 444

v The following example unconfigures the default WebSEAL instance:amwebcfg -action unconfig -inst_name default -admin_id sec_master-admin_pwd mypassw0rd

v The following example unconfigures a WebSEAL instance named web1:amwebcfg -action unconfig -inst_name web1 -admin_id sec_master-admin_pwd mypassw0rd

amwpmcfgConfigures or unconfigures the Web Portal Manager component of Security AccessManager.

Syntax

amwpmcfg –action {config | unconfig} –policysvr policy_server_host[–policysvr_port policy_server_port] –waspath websphere_installation_path[–was_host websphere_host] [–was_port websphere_port] [–was_admin_idwebsphere_admin] [–was_admin_pwd websphere_admin_password] [–trust_storetrust_store] [–trust_store_pwd trust_store_password] [–keyfile key_file]


[–key_pwd key_file_password] [–authzsvr authorization_server_host][–authzsvr_port authorization_server_port] [–admin_id sam_admin] [–admin_pwdsam_admin_password] [–domain domain]

amwpmcfg –action {config | unconfig} –interactive

amwpmcfg –action config –rspfile properties_file

amwpmcfg –action name

amwpmcfg –action status

amwpmcfg –help [{–operations | –? | –usage}]

Description

The amwpmcfg utility configures or unconfigures the Web Portal Managercomponent of Security Access Manager. You can use the amwpmcfg utility in thefollowing ways:v Manually from the command line (–action {config | unconfig})v Interactively with a graphical interface (–action {config | unconfig}

–interactive)v Unattended with a response file (–action config –rspfile properties_file)

Before you configure Web Portal Manager, you must configure Security AccessManager Runtime for Java to WebSphere Application Server, version 8. After youconfigure Security Access Manager Runtime for Java to WebSphere ApplicationServer, version 8, you can use the amwpmcfg utility to configure Web PortalManager.

Certain amwpmcfg parameters are required for the following situations:v When a secure connection to WebSphere Application Server is used, the

following parameters are required:– –was_admin_id– –was_admin_pwd– –trust_store– –trust_store_pwd

v When the Security Access Manager authorization server is already configured,the following parameters are required:– –authzsvr– –authzsvr_port

v When you use the unconfig option, the following parameters are required.– –admin_id– –admin_pwd

All other parameters are optional unless WebSphere Application Server securityis enabled. If security is enabled, you must also use the following parameters:– –was_admin_id– –was_admin_pwd– –trust_store– –trust_store_pwd

v When you use interactive configuration (amwpmcfg -action config-interactive), use the -waspath parameter or specify Java in the path. The Javaexecutable file in the path must be compatible with WebSphere ApplicationServer 8.0. You can use the WebSphere Application Server 8.0 JRE or the Java 6supplied with IBM Security Access Manager 7.0.


The amwpmcfg utility sets the pd.cfg.home property in the following configurationproperty file: /opt/IBM/WebSphere/AppServer/systemApps/isclite.ear/iscwpm.war/WEB-INF/classes/amconf.properties.

Parameters

–action {config|name|status|unconfig}Specifies the action to take. Actions include:

config Configures Web Portal Manager for Security Access Manager.

name Retrieves the package name of Web Portal Manager and returnsthe name value to the pdconfig utility. Only pdconfig uses thisparameter. Do not use this parameter from the command line.

status Determines the configuration status of Web Portal Manager andreturn status to the pdconfig utility. Only pdconfig uses thisparameter. Do not use this parameter from the command line.

unconfigUnconfigure Web Portal Manager for Security Access Manager.

–admin_id sam_adminSpecifies the name of the Security Access Manager administrator with theappropriate administrative privileges. If you do not specify this parameterduring interactive mode, you are prompted to do so.

–admin_pwd sam_admin_passwordSpecifies the password for the Security Access Manager administrator. Thisparameter is required. If you do not specify this parameter duringinteractive mode, you are prompted to do so.

–authzsvr authorization_server_hostSpecifies the host name of the Security Access Manager authorizationserver. Valid values include any valid IP host name. (Optional) Forexample:example.dallas.ibm.com

–authzsvr_port authorization_server_portSpecifies the port number for the Security Access Manager authorizationserver. The default value is 7136. (Optional)

–domain domainSpecifies the name of the domain. The domain must exist. Any securitypolicy that is a domain affects only those objects in that domain. Userswith authority to run tasks in one domain do not necessarily haveauthority to run those same tasks in other domains. The default domain isDefault, which indicates the management domain.

–help [{–operations | –? | –usage}]Provides online help for this utility. If you do not specify a parameter, theentire usage statement displays Definite parameter.

–? Provides the usage statement for this utility.

–operationsPrints all the valid command-line options.

–usage Provides the usage statement for this utility.


–interactiveSpecifies interactive mode, which is a graphical interface, to configure orunconfigure Web Portal Manager. If you do not specify a mode, the utilityruns in silent mode.

–key_pwd key_file_passwordSpecifies the existing password that is associated with the specified clientkey file. This password was set when the key file was created. Thisparameter is required when you use a secure connection to WebSphereApplication Server.

–keyfile key_fileSpecifies the fully qualified file name of the key file. This key file holds theclient-side certificates for secure communication. This parameter is requiredfor a secure connection to WebSphere Application Server.

–policysvr policy_server_hostSpecifies the host name of the Security Access Manager policy server. Validvalues include any valid IP host name. For example:example.dallas.ibm.com

–policysvr_port policy_server_portSpecifies the port number for the Security Access Manager policy server.The default value is 7135. (Optional)

–rspfile response_fileSpecifies the fully qualified path and file name of the silent configurationresponse file. You can use a response file for configuration. There is nodefault response file name. The response file contains stanzas andkey=value pairs. For information about using response files, see the "Usingresponse files" appendix in the IBM Security Access Manager for Web:Command Reference. The following rules apply to response files:v All slashes in the keyfile, trust_store, or waspath parameters path

must be either:– Escaped with a second back slash (\)– A single front slash (/)

For example:waspath=c:\\Program Files\\IBM\\WAS_HOME

orwaspath=c:/Program Files/IBM/WAS_HOME

v The path must not include quotation marks.

–trust_store trust_storeSpecifies the fully qualified file name of the truststore. This trust filehandles the server-side certificates for secure communication. Thetruststore verifies the certificate that is presented by the server. The signerof the certificate must be a trusted certificate authority (CA). Thisparameter is required for a secure connection to WebSphere ApplicationServer.

–trust_store_pwd trust_store_passwordSpecifies the existing password that protects the truststore file. Thispassword was set when the truststore was created. This parameter isrequired for a secure connection to WebSphere Application Server.

–was_admin_id websphere_adminSpecifies the name of the WebSphere administrator with the appropriateadministrative privileges. This parameter is required for a secure


connection to WebSphere Application Server. If you do not specify aparameter, you are prompted to do so.

–was_admin_pwd websphere_admin_passwordSpecifies the password for the WebSphere administrator. This parameter isrequired for a secure connection to WebSphere Application Server. If youdo not specify a parameter, you are prompted to do so.

–was_host websphere_hostSpecifies the host name or IP address of the system where WebSphereApplication Server is installed. (Optional)

–was_port websphere_portSpecifies the SOAP port number for the WebSphere Application Server. Thedefault value is 8879 for Deployment Manager in a cluster environmentand 8880 for an application server in a single server environment.(Optional)

–waspath websphere_installation_pathSpecifies the full path to the installation directory for IBM WebSphereApplication Server. This directory is validated by checking for the wsadminscript in the /bin directory. The configuration fails if a required version ofWebSphere Application Server is not installed.

Availability


/opt/PolicyDirector/sbin

v On Windows operating systems:c:\Program Files\Tivoli\Policy Director\sbin

When you select an installation directory other than the default, this utility is inthe /sbin directory under the installation directory. For example,installation_directory/sbin.

Return codes



Examples

The following example manually configures Web Portal Manager into WebSphereApplication Server, Version 8:

# . /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/bin/setupCmdLine.sh# amwpmcfg -action config -admin_id sec_master \

-admin_pwd mysecmasterpassword -policysvr mypolicyserverhostname -policysvr_port 7135 \-authzsvr myauthserverhostname -authzsvr_port 7136 -waspath /opt/IBM/WebSphere/AppServer \-was_port 8880 -was_host tam611 -was_admin_id wasadmin \-was_admin_pwd passw0rd \-trust_store /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/etc/trust.p12 \-trust_store_pwd WebAS


bassslcfgConfigures or modifies the configuration information of the IBM Security AccessManager runtime.

Syntax

bassslcfg –chgpwd –e password_life [–rspfile response_file]

bassslcfg –config –c cert_file [–C compliance] –h host_name [–p server_port] [–epassword_life] [–t ssl_timeout] [–d primary_domain] [–a {yes|no}] [–rspfileresponse_file]

bassslcfg –getcacert –c cert_file –h host_name [–p server_port] [–rspfileresponse_file]

bassslcfg –getmgtdomain –h host_name [–p server_port] [–rspfile response_file]

bassslcfg –modify [–h host_name] [–e password_life] [–p server_port] [–tssl_timeout] [–d primary_domain] [–a {yes|no}] [–rspfile response_file]

bassslcfg –ping –h host_name [–p server_port] [–rspfile response_file]

Parameters

–a {yes|no}Sets the key file password ssl-auto-refresh entry in the pd.confconfiguration file. The value must be yes or no. (Optional)

–c cert_fileSpecifies the name of the policy server base-64 encoded, self-signedcertificate.

–C complianceSpecifies the compliance value for the [ssl] ssl-compliance configurationfile setting. This parameter is only required when the policy server is notaccessible (such as when regenerating certificates on the policy serversystem). If not specified, the setting is retrieved from the policy server. Thecompliance value must be one of the following settings:

fips Enforces FIPS 140-2 protocols and algorithms. Security AccessManager servers and applications generate and use SHA1 with2048-bit RSA certificates. Only TLS versions 1.0, 1.1 and 1.2 areavailable. SSL versions 2 and 3 are disabled and unavailable. Thissetting option is equivalent to the previous release setting [ssl]ssl-enable-fips = yes. This value is compatible with previousTivoli Access Manager releases.

none Specifies that no special compliance criteria are applied to TLScommunication. Security Access Manager servers and applicationsgenerate and use SHA1 with 2048-bit RSA certificates. This settingoption is equivalent to the previous release setting [ssl]ssl-enable-fips = no. This value is compatible with previousTivoli Access Manager releases.

sp800-131-strictEnables strict NIST SP800-131a support. This conformanceenforcement is required by some agencies and businesses startingin the year 2014. Security Access Manager servers and applications


generate and use SHA256 with 2048-bit RSA certificates. This valueis not compatible with prior releases of Tivoli Access Manager.Older Tivoli Access Manager clients cannot interact with SecurityAccess Manager 7.0 running with this compliance setting. OnlyTLS version 1.2 is available; all others are disabled.

sp800-131-transitionEnables NIST SP800-131a support at the transition level. This valueis valid until the end of the year 2013. This value has fewerrestrictions than the strict enforcement. Only TLS versions 1.0, 1.1and 1.2 are available. SSL versions 2 and 3 are disabled andunavailable.

Security Access Manager servers and applications generate and useSHA256 with 2048-bit RSA certificates. This value is at a higherlevel than is required by the standard and was chosen as it is alevel that is permitted by the strict enforcement that allows easymigration from transition to strict. This value is not compatiblewith previous Tivoli Access Manager releases. Older Tivoli AccessManager clients cannot interact with Security Access Manager 7.0running with this compliance setting.

suite-b-128Enables NSA Suite B at 128-bit support. Security Access Managerservers and applications generate, and use, SHA256 with 256-bitECDSA certificates. This value is not compatible with previousTivoli Access Manager releases. Older Tivoli Access Managerclients cannot interact with Tivoli Access Manager 7.0 running withthis compliance setting. Only TLS version 1.2 is available; all othersare disabled.

suite-b-192Enables NSA Suite B at 192-bit support. Security Access Managerservers and applications generate, and use, SHA384 with 384-bitECDSA certificates. This value is not compatible with previousTivoli Access Manager releases. Older Tivoli Access Managerclients cannot interact with Security Access Manager 7.0 runningwith this compliance setting. Only TLS version 1.2 is available; allothers are disabled.

–chgpwdChanges the key database password. A new random password is generatedand saved in the stash file.

–configConfigures the IBM Security Access Manager runtime so that pdadmincommands and the svrsslcfg utility can communicate with the policyserver. Also creates a key and stash file.

–d primary_domainSpecifies the local domain name. During a configuration action:v This domain must exist.v The administrator ID and password must be valid for the domain.

If not specified, the local domain that is specified during configuration ofthe IBM Security Access Manager runtime is used. The local domain valueis retrieved from the configuration file.


A valid local domain name is an alphanumeric, case-sensitive string. Stringcharacters are expected to be characters that are part of the local code set.You cannot use a space in the domain name. (Optional)

–e password_lifeSets the key file password expiration time in days. (Optional)

During a configuration action, the default value is 7299.

If you modify this option:v Specify 0 if you want to use the currently configured value.v Specify 7299 days if the currently configured value cannot be

determined.v Otherwise, specify a valid value from 1 to 7299.

–getcacertDownloads the root CA certificate to a file.

–getmgtdomainPrints the name of the management domain from the policy server tostandard out (stdout).

–h host_nameSpecifies the TCP host name of the policy server. Valid values include anyvalid IP host name. For example:host = librahost = libra.dallas.ibm.com

–modifyModifies the policy server configuration.

–p server_portSpecifies the listening port of the policy server. The default value is 7135.For a ping action, specify the listening port of that server. If not specified,the default listening port is 7135. (Optional)

–ping Pings a Security Access Manager server.

–rspfile response_fileSpecifies the fully qualified path and file name of the response file to useduring silent configuration. There is no default response file name. Theresponse file contains stanzas and key=value pairs. For information aboutusing response files, see the "Using response files" appendix in the IBMSecurity Access Manager for Web Command Reference. (Optional)

–t ssl_timeoutSpecifies the SSL session timeout in seconds. The value must be from 1 to86400. During a configuration action, the default value is 7200. (Optional)

Availability



v On Windows operating systems:C:\Program Files\Tivoli\Policy Director\sbin



Return codes



cdsso_key_genGenerates a key for use during encrypting and decrypting authentication tokensfor WebSEAL cross-domain single sign-on.

Syntax

cdsso_key_gen path

Description

This utility generates a triple DES 192-bit key file. The key file is used as part ofthe cross-domain single sign-on solution for WebSEAL.

This authentication solution uses authentication tokens. Authentication informationabout a user in a WebSEAL domain is collected by the built-in single sign-onauthentication mechanism library. This information is placed in a token. This tokenmust be encoded before it can be sent to a second WebSEAL domain. When it isreceived in the second WebSEAL domain, the token is decoded, and theauthentication information about the user is accessed.

The tokens are encoded by use of a key file. The key file is generated by thecdsso_key_gen utility.

When a key file is generated, it must be manually copied to each WebSEAL serverin each domain. The assumption is that each specified domain participates in thecross-domain single sign-on solution.

Parameters

path Specifies the fully qualified path to the key file.

Availability


/opt/pdwebrte/bin

v On Windows operating systems:C:\Program Files\Tivoli\pdweb\bin


Return codes




Example

The following example generates a key and places it in the /tmp/keyfile file:cdsso_key_gen /tmp/keyfile

ivacld_setupConfigures the Security Access Manager authorization server for Windowsplatforms.

Syntax

ivacld_setup.exe [–?] [–a adminid] [–d domain_name] [–h host_name] [–iinstance_name] –p password [–q] [–r port] [–rspfile response_file] [–t port]–policysvr host_port_rank

Description

The ivacld_setup utility configures the Security Access Manager authorizationserver on Windows platforms. You can run this utility directly from the commandline.

Parameters

–? Prints a usage statement. (Optional)

–a adminidSpecifies the ID for the administrator of the management domain. Thedefault administrator ID is sec_master. (Optional)

–d domain_nameSpecifies the domain name. The default value is Default, which indicatesthe management domain. (Optional)

–h host_nameSpecifies the fully qualified name of the host system for the authorizationserver. The default value is the local host name. (Optional)

–i instance_nameSpecifies the authorization server instance name. The default authorizationserver instance name is always empty. Enter a unique name to configureeach additional authorization server. Instance names can contain allalphanumeric characters; they also can use the hyphen (-) and underscore (_ ) characters. An instance name cannot begin with a hyphen (-) character.(Optional)

–p passwordSpecifies the password for the administrator ID, adminid. This parameter isrequired.

–policysvr host_port_rankSpecifies the policy server host name, port, and rank. The policy serverhost name is the name of the host on which the policy server runs. The


port is the port on which the policy server listens for requests. The rank isan integer value that denotes priority. These three inputs are provided in astring as hostname:port:rank for this value. This value would typically bePOLICYSVR_HOST:7135:1 where POLICYSVR_HOST is the host name of thepolicy server.

–q Runs the command in silent mode and does not output any messageboxes. Writes messages only to stderr. (Optional)

–r portSpecifies the administration request port. The default port is 7137.(Optional)


–t portSpecifies the port number for the policy server. The default value is 7136.(Optional)

Availability

By default, this utility is in the following directory on Windows operating systems:C:\Program Files\Tivoli\Policy Director\sbin

When you select an installation directory other than the default, this utility is inthe \sbin directory under the installation directory (for example:installation_directory\sbin).

Return codes


1 The utility failed. When a utility fails, the software displays a descriptionof the error.

See the IBM Security Access Manager for Web Error Message Reference. This referenceprovides a list of the Security Access Manager error messages by decimal orhexadecimal codes.

Example

The following example configures the authorization server with the defaultmanagement domain:ivacld_setup -a sec_master -p password -r 7137 -t 7136 -h libra.austin.example.com-policysvr libra.austin.example.com:7135:1 -d Default

ivacld_uninstUnconfigures the Security Access Manager authorization server for Windowsplatforms.


Syntax

ivacld_uninst [ –?] [–a admin_id] –deconfig [ –i instance] –p admin_pwd–policysvr host_port_rank [–q] [–rspfile response_file]

Description

The ivacld_uninst utility unconfigures the Security Access Manager authorizationserver on Windows platforms. You can run this utility directly from the commandline.

Parameters


–a admin_idSpecifies the ID for the administrator of the management domain. Thedefault administrator ID is sec_master. (Optional)

–deconfigUnconfigure the authorization server.

–i instanceSpecifies the authorization server instance name. The default authorizationserver instance name is always empty. Enter a unique name to configureeach additional authorization server. Instance names can contain allalphanumeric characters; they also can use the hyphen (-) and underscore (_ ) characters. An instance name cannot begin with a hyphen (-) character.(Optional)

–p admin_pwdSpecifies the password for the administrator ID, admin_id. This parameteris required.

–policysvr host_port_rankSpecifies the policy server host name, port, and rank. The policy serverhost name is the name of the host on which the policy server runs. Theport is the port on which the policy server listens for requests. The rank isan integer value that denotes priority. These three inputs are provided in astring as hostname:port:rank for this value. This value would normally bePOLICYSVR_HOST:7135:1 where POLICYSVR_HOST is the host name of thepolicy server.

–q Runs in silent mode and do not output any message boxes. Writes only tostderr. (Optional)


Availability



When an installation directory other than the default is selected, this utility is inthe \sbin directory under the installation directory (for example:installation_directory\sbin).

Return codes




Example

The following example unconfigures the authorization server by using the defaultmanagement domain:ivacld_uninst.exe -deconfig -a sec_master -p password -i instance-policysvr libra.austin.example.com:7135:1

ivbase_setupConfigures the Security Access Manager runtime server for Windows platforms.

Syntax

ivbase_setup.exe [–?] [–a admin_ID] –c mgr_certfile [–d distinguished_name] [–Ddistinguished_name] [–G] [–h host_name] –H hostname [–K key_file] [–llocal_domain_name] [–N key_file_dn] [–o global_catalog_port] [–p port] [–Pldap_port] [–q] [–rspfile response_file] [–S ldap_port] –t reg_type [–T path] [–u][–v global_catalog_host] [–w admin_pwd] [–W key_file_password] [–Z]

Description

The ivbase_setup utility configures the Security Access Manager runtime server onWindows platforms. You can run this utility directly from the command line.

Certain user registries require specific parameters. For an explanation of whichparameters are required for certain user registries, see the following parameterdescriptions.

Parameters


–a admin_IDSpecifies the Administrator ID to use during communication with theActive Directory. This parameter is required if the -t parameter isactive_directory.

–c mgr_certfileSpecifies the base-64 encoded, self-signed certificate of the policy server.For example, C:\Progra~1\Tivoli\Policy~1\keytab\pdcacert_download.b64. When the certificate file is not specified, thecertificate is downloaded from the policy server. This parameter is requiredif the Security Access Manager policy server is not on this computer.


–d distinguished_nameSpecifies the Distinguished Name of the Active Directory domain. Thisparameter is required if the -t parameter is active_directory.

For example:dc=ibm,dc=com

–D distinguished_nameSpecifies the Distinguished Name (DN) of the data location on the ActiveDirectory server in which to store Security Access Manager data. Thisparameter is required if the -G parameter is not used. If the -G parameter isused, then the default value is the value of the -d parameter.

–G Configures Security Access Manager with the Active Directory multipledomain environment. Use this parameter to configure multiple domains.(Optional)

–h host_nameSpecifies the host name of the policy server. This parameter is required ifthe Security Access Manager policy server is not on this computer. You canspecify any valid IP host name.

For example:host_name = libra.dallas.example.com

–H hostnameSpecifies the IP address or host name of the LDAP server or ActiveDirectory server. This parameter is required if reg_type is ldap oractive_directory. You can specify any valid IP host name.

For example:hostname = librahostname = libra.us.example.com

–K key_fileSpecifies the fully qualified file name of the key file. This key file holds theclient-side certificates for secure communication. This parameter is requiredif the -Z parameter is used.

–l local_domain_nameSpecifies the local domain name for the runtime that is being configured. Alocal domain is a Security Access Manager secure domain that is used byprograms when no explicit domain is specified. A valid local domain nameis an alphanumeric, case-sensitive string. String characters are expected tobe characters that are part of the local code set. You cannot use a space inthe domain name. (Optional)

For example:local_domain_name = Default

–N key_file_dnSpecifies the Distinguished Name for accessing the keyfile. This parameteris required if the -Z parameter is used.

–o global_catalog_portSpecifies the port number for the Active Directory Global Catalog Serverwhen the -u parameter is used.

–p portSpecifies the port number for the Security Access Manager policy server.This parameter is required if the Security Access Manager policy server isnot on this computer. The default value is 7135. (Optional)


–P ldap_portSpecifies the port number of the LDAP server when Secure Socket Layer(SSL) is not used. Use the LDAP server-configured port number. Thedefault port number is 389. (Optional)

–q Runs the command in silent mode and does not output any messageboxes. Write only to stderr. (Optional)


–S ldap_portSpecifies the port number of the LDAP server when Secure Socket Layer(SSL) is used. Use the LDAP server-configured port number. The defaultport number is 636. (Optional)

–t reg_type {ldap | active_directory}Specifies the type of registry server to set up. Valid responses are ldap, andactive_directory.

–T pathEnables logging and specifies the fully qualified path for common logging.When enabled, all message log files are placed in this common location.(Optional)

For example:path = C:\Program Files\ibm\tivoli\common

–u Specifies an email address (alternative format) for the userPrincipalNameattribute of the Active Directory user object as its user ID. If not used, onlythe default format of the userPrincipalName can be used as the user ID.(Optional)

–v global_catalog_hostSpecifies the Global Catalog server host name when the -u parameter isused. (Optional)

For example:gc_host = gcserver.us.ibm.com

–w admin_pwdSpecifies the Administrator password to use to communicate with ActiveDirectory. This parameter is required if the -t parameter isactive_directory.

–W key_file_passwordSpecifies the existing password that is associated with the specifiedkey_file. This password was set when the key file was created. Thisparameter is required if the -Z parameter is used.

–Z Specifies whether to enable SSL communication between the runtime andthe registry server. This parameter does not display with non-SSLcommunication. (Optional)


Availability



Return codes


1 The utility failed. When a utility fails, a description of the error displays.


Example

The following example configures the runtime by using LDAP as the user registry.The policy server is installed on the same computer.ivbase_setup.exe -t ldap -H libra.austin.example.com -P 389

ivbase_uninstUnconfigures the Security Access Manager runtime for Windows platforms.

Syntax

ivbase_uninst [ –?] –deconfig [–q] [–rspfile response_file]

Description

The ivbase_uninst utility unconfigures the Security Access Manager runtime onWindows platforms. You can run this utility directly from the command line.

Parameters


–deconfigUnconfigures the runtime. This parameter is required.

–q Runs in silent mode and does not output any message boxes. Writes onlyto stderr. (Optional)



Availability



Return codes




Examples

The following example unconfigures the runtime:ivbase_uninst.exe -deconfig

ivmgrd_setupConfigures the Security Access Manager policy server for Windows platforms.

Syntax

ivmgrd_setup.exe [ –?] [–a ldap_dn] [–C compliance] [ –d dn_ldap-admin] [–D{yes|no}] [–f {yes|no}] [–l certificate_life] [–m password] [–q] [–r port][–rspfile response_file] [–s ldap_suffix] [–t ssl_timeout] [–v {yes|no}] –wpassword [–y {yes|no}] [–Y restore_directory]

Description

The ivmgrd_setup utility configures the Security Access Manager policy server onWindows platforms. You can run this utility directly from the command line.

Parameters


–a ldap_dnSpecifies the name of the management domain. Configuring the policyserver in the management domain creates the initial administrativedomain. The management domain name must be unique in the LDAPserver. The name must be an alphanumeric string up to 64 characters longand is not case-sensitive. The default value is Default. (Optional)

–C complianceSpecifies the compliance value for the [ssl] ssl-compliance configurationfile setting. This parameter defaults to none, if not provided. (Optional) Thecompliance value must be one of the following settings:

fips Enforces FIPS 140-2 protocols and algorithms. Security AccessManager servers and applications generate and use SHA1 with


2048-bit RSA certificates. Only TLS versions 1.0, 1.1 and 1.2 areavailable. SSL versions 2 and 3 are disabled and unavailable. Thissetting option is equivalent to the previous release setting [ssl]ssl-enable-fips = yes. This value is compatible with previousTivoli Access Manager releases.


sp800-131-strictEnables strict NIST SP800-131a support. This conformanceenforcement is required by some agencies and businesses that startin the year 2014.

Security Access Manager servers and applications generate and useSHA256 with 2048-bit RSA certificates. This value is not compatiblewith prior releases of Tivoli Access Manager. Older Tivoli AccessManager clients cannot interact with Security Access Manager 7.0running with this compliance setting. Only TLS version 1.2 isavailable; all others are disabled.

sp800-131-transitionEnables NIST SP800-131a support at the transition level. This valueis valid until the end of the year 2013. This value has fewerrestrictions than the strict enforcement. Only TLS versions 1.0, 1.1and 1.2 are available. SSL versions 2 and 3 are disabled andunavailable.

Security Access Manager servers and applications generate and useSHA256 with 2048-bit RSA certificates. This value is at a higherlevel than is required by the standard and was chosen as it is alevel permitted by the strict enforcement that allows easymigration from transition to strict. This value is not compatiblewith previous Tivoli Access Manager releases. Older Tivoli AccessManager clients cannot interact with Security Access Manager 7.0running with this compliance setting.

suite-b-128Enables NSA Suite B at 128-bit support. Security Access Managerservers and applications generate, and use, SHA256 with 256-bitECDSA certificates. This value is not compatible with previousTivoli Access Manager releases. Older Tivoli Access Managerclients cannot interact with Tivoli Access Manager 7.0 running withthis compliance setting. Only TLS version 1.2 is available; all othersare disabled.

suite-b-192Enables NSA Suite B at 192-bit support. Security Access Managerservers and applications generate, and use, SHA384 with 384-bitECDSA certificates. This value is not compatible with previousTivoli Access Manager releases. Older Tivoli Access Managerclients cannot interact with Security Access Manager 7.0 runningwith this compliance setting. Only TLS version 1.2 is available; allothers are disabled.


–d dn_ldap-adminSpecifies the distinguished name of the LDAP administrator. The defaultvalue is cn=root. (Optional)

–D {yes|no}Specifies whether to enable the downloading of the root CA certificate forthe secure domain. Valid values are yes and no. The default value is no.(Optional)

–f {yes|no}Specifies whether to enable Federal Information Processing Standards(FIPS). If FIPS is enabled, the IBM Tivoli Directory Server is configured touse the appropriate FIPS secure communications protocol. The validresponse values are yes or no. The default value is no. (Optional)

–l certificate_lifeSpecifies the number of days that the SSL certificate file is valid. Thedefault number of days is 1460. (Optional)

–m passwordSpecifies the password for the administrator ID. The default administratorID is sec_master. This parameter is required when you use LDAP.

–q Runs the command in silent mode and does not output any messageboxes. Writes only to stderr. (Optional)

–r portSpecifies the port number for the policy server. The default value is 7135.(Optional)


–s ldap_suffixCreates the secAuthorityInfo object entry on the LDAP server when youcreate:v An Security Access Manager domainv The initial management domain

This object represents the domain and is named by the secAuthorityattribute which uses the name of the domain as its value. For example:secAuthority=<domain_name>.

If you do not provide a different name, the default name of themanagement domain is Default, making the secAuthorityInfo object namesecAuthority=Default. (Optional)

–t ssl_timeoutSpecifies the SSL connection timeout in seconds. The default value is 7200.(Optional)

–v {yes|no}Selects the LDAP data format for user and group tracking informationduring the configuration of the policy server. The two LDAP data formatsare minimal and standard. The valid response values are yes or no. Thedefault value is no. (Optional)


–w passwordSpecifies the password for the dn_ldap_admin. This parameter is requiredwhen you use LDAP.

–y {yes|no}Specifies that you can configure a second policy server to a registry serverfor migration purposes. The valid response values are yes or no. Thedefault value is no. (Optional)

–Y restore_directorySpecifies the fully qualified path for the directory where the extractedpdbackup files are located. This parameter is required when -y is set to yeswhich specifies a second policy server to configure.

Availability



Return codes


1 The utility failed. When a utility fails, the software shows a description ofthe error.


Example

The following example configures the policy server with LDAP as the user registryand the default management domain. SSL communication with the LDAP server isnot enabled:ivmgrd_setup.exe -f no -d "cn=root" -w password -v yes -m password -r 7135

ivmgrd_uninstUnconfigures the Security Access Manager policy server for Windows platforms.

Syntax

ivmgrd_uninst [–?] [–d bind_dn] –deconfig [–q] [–R] [–rspfile response_file] [–wbind_pwd]

Description

The ivmgrd_uninst utility unconfigures the Security Access Manager policy serveron Windows platforms. You can run this utility directly from the command line.

Parameters



–d bind_dnSpecifies the distinguished name of the LDAP administrator. The defaultvalue is cn=root. (Optional)

–deconfigUnconfigures the policy server.

–q Runs in silent mode and does not output any message boxes. Writes onlyto stderr. (Optional)

–R Specifies whether to permanently remove domain information from theregistry. Using this parameter removes all domain, user, and groupinformation. When this parameter is not used:v User and group information is retained.v Domain information is removed.

The domain can be re-created later if needed. (Optional)


–w bind_pwdSpecifies the password for the bind_dn. This parameter is required whenyou use LDAP.

Availability


When you select an installation directory other than the default, this utility is inthe \sbin directory under the installation directory. For example:installation_directory\sbin.

Return codes




Example

The following example unconfigures the policy server by using the defaultmanagement domain:ivmgrd_uninst.exe -deconfig -d cn=root -w password -R


ivrgy_toolUpdates the Security Access Manager schema on an LDAP server. It also appliesthe required access control lists (ACLs) to suffixes added to the LDAP server afterpolicy server configuration.

This utility is not supported with the Active Directory Lightweight DirectoryService (AD LDS) user registry. See the IBM Security Access Manager for WebInstallation Guide for information about updating the AD LDS schema for use withSecurity Access Manager.

Syntax

Using add-acls:ivrgy_tool –h host_name [–p port] [–D admin_dn] [F] [–g name] –wadmin_password [–d] [–r response_file] add-acls domain_name

Using add-acls with SSL communication:ivrgy_tool –h host_name [–p port] [–D admin_dn] [F] [–g name] –wadmin_password [–d] –Z –K keyfile –P keyfile_password [–N keyfile_label][–r response_file] add-acls domain_name

Using schema:ivrgy_tool –h host_name [–p port] [–D admin_dn] –w admin_password [–d] [–rresponse_file] schema

Using schema with SSL communication:ivrgy_tool –h host_name [–p port] [–D admin_dn] –w admin_password [–d] –Z–K keyfile –P keyfile_password [–N keyfile_label] [–r response_file]schema

Description

You can perform the following actions with the ivrgy_tool and add-aclsparameter:v Apply the required ACLs to suffixes that were added to the LDAP server after

the policy server was configured.v Apply ACLs to the servers in a Tivoli Directory Server proxy environment.v Set the necessary ACLs on servers so that Security Access Manager manages the

partition suffix.

In a proxy environment, the server enforces access control. When the ACLs existon the top-level object of a partition split, you must create the correct ACLs oneach server.

With the ivrgy_tool and schema parameter, you can update the Security AccessManager schema on a supported LDAP server.

The schema is defined in a set of files specific to the type of LDAP server. Thesefiles are installed during IBM Security Access Manager runtime installation. Thesefiles provide input to the automatic schema update process when you configurethe policy server.

Typically, the schema is updated when the policy server is configured. When youmigrate an existing installation of Security Access Manager, you must upgrade theschema on the LDAP server to the current version with the ivrgy_tool utility.

The following files contain the LDAP schema:


secschema.defUsed for Tivoli Directory Server.

nsschema.defUsed for Sun Java System Directory Server.

novschema.defUsed for Novell eDirectory Server.

An administrator can apply and update the schema with one of these files as theLDAP Data Interchange Format (LDIF) input to the ldapmodify utility. Theldapmodify tool is a Tivoli Directory Server utility.

When an LDAP server is not supported by Security Access Manager, you cannotuse the ivrgy_tool utility to update the schema. In these cases, an administratormust manually update the schema on the generic LDAP server.

When manually updating the schema, administrators must use the LDIFdefinitions that are defined in the nsschema.def schema file as the basis for theschema definitions. Administrators must modify the definitions in the schema fileto meet the requirements of their generic LDAP server.

Parameters

–d Runs in verbose output mode for debugging purposes. (Optional)

–D admin_dnSpecifies the distinguished name of the LDAP administrator. The formatfor a distinguished name is like cn=root. (Optional)

–F Forces the addition of ACLs even if the domain is not defined on thisserver. This parameter is valid only with the add-acls command. Thedefault value is not to force the addition of ACLs. (Optional)

–g nameSpecifies Daemon type [acld-server or remote-acl-user]. The defaultvalue is acld-server. (Optional)

–h host_nameSpecifies the IP address or host name of the LDAP server. Valid valuesinclude any valid IP host name. For example:host = librahost = libra.example.ibm.com

When used in a Tivoli Directory Server proxy environment, the value is theserver IP address or host name where you want to set the ACLs.

–K keyfileSpecifies the fully qualified path and file name of the SSL key database.This parameter is required only when the –Z parameter is specified. Usethe SSL key file to handle certificates in LDAP communication. The filetype can be anything, but the extension, as shown in the followingexample for the policy server, is typically .kdb.

Policy server on WindowsC:\Program Files\Tivoli\Policy Director\keytab\ivmgrd.kdb

Policy server on AIX, Linux, or Solaris/opt/PolicyDirector/keytab/ivmgrd.kdb


–N key_nameSpecifies the private key name for the keyfile.

–p portSpecifies the port number of the LDAP server. Use the LDAPserver-configured port number. The default port number is 636 if SecureSockets Layer (SSL) is used and 389 if SSL is not used. If not specified, thedefault LDAP port is used. (Optional)

In a Tivoli Directory Server proxy environment, the value is the portnumber of the server.

–P keyfile_passwordSpecifies the password for the SSL key database. This parameter isrequired only if the –Z parameter is specified.

–r response_fileSpecifies the fully qualified path and file name of the response file forsilent configuration. A response file can be used for configuration. There isno default response file name. The response file contains stanzas andkey=value pairs. For information about using response files, see the "Usingresponse files" appendix in the IBM Security Access Manager for WebCommand Reference. (Optional)

–R Removes from registry for the uninstall command. The default value isfalse. (Optional)

–s suffixSpecifies the LDAP suffix under which to create the Management Domain.

–S nameSpecifies the Security Master Principal Name. The default is sec_master.(Optional)

–v versionSpecifies the data model version to use for the install command. Thedefault value is 6. (Optional)

–w admin_passwordSpecifies the password of the LDAP administrator.

–Z Specifies to use SSL for a secure LDAP connection. (Optional)

add-acls domain_nameIndicates that the required access control lists (ACLs) must be applied toall suffixes that are defined on the LDAP server for the specified domain.When the policy server is configured, the management domain is createdwith the default name of Default. When you use the add-acls parametersin a Tivoli Directory Server proxy environment, always apply the ACLs tothe management domain at a minimum.

This option is useful for adding access control to suffixes that are added tothe LDAP server after the policy server is configured.

schema Updates the Security Access Manager schema. Use this parameter whenyou are using:v A version of Tivoli Directory Server earlier than version 6.0, such as

Tivoli Directory Server version 5.2.v An LDAP server other than Tivoli Directory Server. For example, you

are using Novell eDirectory Server.


Return codes


1 The utility failed. When a utility fails, a description of the error and anerror is provided.

mgrsslcfgCreates or modifies the SSL certificates of the policy server.

Syntax

mgrsslcfg –chgcert [–l cert_life] [–rspfile response_file]

mgrsslcfg –chgpwd [–e password_life] [–rspfile response_file]

mgrsslcfg –config [–C compliance] [–e password_life] [–l cert_life] [–tssl_timeout] [–a {yes|no}] [–rspfile response_file]

mgrsslcfg –modify [–e password_life] [–l cert_life] [–t ssl_timeout] [–a{yes|no}] [–rspfile response_file]

Description

Stop the Security Access Manager policy server before you run this utility.

Parameters

–a {yes|no}Sets the key file password ssl-auto-refresh entry in the ivmgrd.confconfiguration file. The value must be yes or no. The default value is yes.(Optional)

–C complianceSpecifies the compliance value for the [ssl] ssl-compliance configurationfile setting. For example, –C sp800-131-transition. When not provided,the setting defaults to none. (Optional) The compliance value must be oneof the following settings:

fips Enforces FIPS 140-2 protocols and algorithms. Security AccessManager servers and applications generate and use SHA1 with2048-bit RSA certificates. Only TLS versions 1.0, 1.1, and 1.2 areavailable. SSL versions 2 and 3 are disabled and unavailable.

This setting option is equivalent to the previous release setting[ssl] ssl-enable-fips = yes. This value is compatible withprevious Tivoli Access Manager releases.





sp800-131-transitionEnables NIST SP800-131a support at the transition level. This valueis valid until the end of the year 2013. This value has fewerrestrictions than the strict enforcement. Only TLS versions 1.0, 1.1,and 1.2 are available. SSL versions 2 and 3 are disabled andunavailable.


suite-b-128Enables NSA Suite B at 128-bit support. Security Access Managerservers and applications generate and use SHA256 with 256-bitECDSA certificates. This value is not compatible with previousTivoli Access Manager releases. Older Tivoli Access Managerclients cannot interact with Tivoli Access Manager 7.0 running withthis compliance setting. Only TLS version 1.2 is available; all othersare disabled.

suite-b-192Enables NSA Suite B at 192-bit support. Security Access Managerservers and applications generate and use SHA384 with 384-bitECDSA certificates. This value is not compatible with previousTivoli Access Manager releases. Older Tivoli Access Managerclients cannot interact with Security Access Manager 7.0 runningwith this compliance setting. Only TLS version 1.2 is available; allothers are disabled.

–chgcertRenews the SSL certificate. A new public-private key pair and certificateare created and stored in the key database.

–chgpwdChanges the key database password. A new random password is generatedand saved in the stash file.

Before you run this action, stop the policy server.

–configCreates new key and stash files and generates new certificates for thepolicy server.

–e password_lifeSets the key file password expiration time in days. (Optional)

During a configuration action (–config), the default value is 183.

If you modify this value:


v Specify 0 to use the currently configured value.v Specify 183, if the currently configured value cannot be determined.v Otherwise, specify a valid value from 1 to 7299.

–l cert_lifeSets the maximum certificate expiration time in days. The actual time thatis used is the lesser of this value and the number of days before the CAcertificate for the policy server expires. The CA certificate lifetime is set to7300 days at initial configuration of the policy server. (Optional)

During a configuration action (–config), the default value is 1460.

If you modify this value:v Specify 0 to use the currently configured value.v Specify 1460, if the currently configured value cannot be determined.v Otherwise, specify a valid value from 1 to 7299.

–modifyModifies the current configuration.


–t ssl_timeoutSpecifies the SSL session timeout in seconds. The ssl_timeout value mustbe in the range from 1 to 86400. During configuration, the default value is7200. (Optional)

Availability





Return codes



PDAcld_configConfigures the Security Access Manager authorization server.


Syntax

PDAcld_config [–a adminid] [–D domain] [–f response_file] [–h host] –H host [–iinstance] [–k key_file] [–K key_file_password] [–L port] [–N key_file_label] [–Oport] –p password [–P port] [–r port] [–s silent{yes|no}] [–Z {yes|no}]

Description

The PDAcld_config utility configures the Security Access Manager authorizationserver on AIX, Linux, and Solaris platforms. You can run this utility directly fromthe command line.

Parameters

–a adminidSpecifies the ID for the Security Access Manager administrator of themanagement domain. The default administrator ID is sec_master.(Optional)

–D domainSpecifies the domain name. The default value is Default, which indicatesthe management domain. (Optional)

–f 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 key=value pairs. For information about using response files, see the"Using response files" appendix in the IBM Security Access Manager for WebCommand Reference. (Optional)

–h hostSpecifies the valid host name or valid IP of the system on which Policyserver runs. The default value is the host name of the local system.(Optional)

–H hostSpecifies the fully qualified name or valid IP of the host system for theauthorization server.

–i instanceSpecifies the authorization server instance name. The default authorizationserver instance name is always empty. Enter a unique name to configureeach additional authorization server. Instance names can contain charactersa-z, 0-9, -, and _. An instance name cannot begin with a hyphen (-)character. (Optional)

–k key_fileSpecifies the fully qualified file name of the client-side key file. This keyfile holds the server-side certificates that are used in securecommunication. This parameter is required when -Z is set to yes, whichmeans that SSL communication is enabled. (Optional)

–K key_file_passwordSpecifies the existing password that is associated with the specifiedkey_file. This password was set when the key file was created. Thisparameter is required if -Z is set to yes, which means that SSLcommunication is enabled. (Optional)


–L portSpecifies the Secure Sockets Layer (SSL) port number of the LDAP server.Use the LDAP server-configured port number. The default port number is636. (Optional)

–N key_file_labelSpecifies the server certificate label name that is in the key_file. The labelwas set when the server certificate was imported in the client-side key file.This parameter is required when -Z is set to yes, which means that SSLcommunication is enabled. (Optional)

–O portSpecifies the administration request port. The default port is 7137.(Optional)

–p passwordSpecifies the password for the Security Access Manager administrator ID,adminid.

–P portSpecifies the authorization request port number. The default port numberis 7136. (Optional)

–r portSpecifies the port number on which the policy server listens for requests.The default port number is 7135. (Optional)

–s silent{yes|no}Specifies silent configuration. The valid responses are yes or no. If set toyes, the utility runs in silent mode. If set to no, the utility runs ininteractive mode. (Optional)

–Z {yes|no}Specifies whether to enable SSL communication between the authorizationserver and the registry server. The valid responses are yes or no. Thedefault value is no. (Optional)

Availability

This utility is in /opt/PolicyDirector/sbin, the default installation directory onAIX, Linux, and Solaris operating systems.

Return codes

0 The utility ran successfully.

1 The utility failed. When a utility fails, the software displays a descriptionof the error. See the IBM Security Access Manager for Web Error MessageReference. This reference provides a list of the Security Access Managererror messages by decimal or hexadecimal codes.

Example

The following example configures the Security Access Manager AuthorizationServer by using the default management domain. SSL communication with theLDAP server is not enabled../PDAcld_config -Z no -H libra.austin.ibm.com -O 7139 -P 7138 -a sec_master-p password -h libra.austin.ibm.com -r 7135 -D Default -s yes


PDAcld_unconfigUnconfigures the Security Access Manager authorization server.

Syntax

PDAcld_unconfig [–a adminid] [–f response_file] [–h host] [–i instance] –ppassword [–r port] [–s {yes|no}]

Description

The PDAcld_unconfig utility unconfigures the Security Access Managerauthorization server on AIX, Linux, and Solaris platforms. You can run this utilitydirectly from the command line.

Parameters

–a adminidSpecifies the identifier for the Security Access Manager administrator of themanagement domain. The default administrator ID is sec_master.(Optional)


–h hostSpecifies the host name that is used by the policy server to contact thisserver. The default value is the host name of the local system. (Optional)

–i instanceSpecifies the authorization server instance name. The default authorizationserver instance name is always empty. Enter a unique name to unconfigureeach additional authorization server. Instance names can contain charactersa-z, 0-9, -, and _. An instance name cannot begin with a hyphen (-)character. (Optional)

–p passwordSpecifies the password for the Security Access Manager administrator ID,adminid.

–r portSpecifies the port number on which the policy server listens for requests.The default port number is 7135. (Optional)

–s {yes|no}Specifies silent configuration. The valid responses are yes or no. If set toyes, the utility runs in silent mode. If set to no, the utility runs ininteractive mode. (Optional)

Availability



Return codes



Examples

The following example unconfigures the Security Access Manager authorizationserver:./PDAcld_unconfig -a sec_master -p password -h libra.example.ibm.com -r 7135 -s yes

pdadmin_hostGenerates configuration files that allow a single instance of the IBM SecurityAccess Manager runtime to run the pdadmin utility against multiple policy servers.

Syntax

pdadmin_host –h hostname [–d | [–r port] [–c certfile] [–l domain]]

Description

This utility generates a configuration file and associated key files; one for eachpolicy server:v /opt/PolicyDirector/etc/pd-hostname.conf (includes the location of the key

files that are used to hold the policy server certificate)v /var/PolicyDirector/keytab/pd-hostname.kdb

v /var/PolicyDirector/keytab/pd-hostname.sth

The configuration file that is generated by this utility is only to be used with thepdadmin command and the ivadmin_context_create3() administration API. Use thepdadmin command option -I to specify the pd-hostname.conf file that you want touse.

When the tool creates the /opt/PolicyDirector/etc/pd-hostname.conf file, a newconfiguration item is added to the .conf file: [ssl] pdadmin-standalone = yes.

Use only one generated pd-hostname.conf per API process. A single SecurityAccess Manager API application cannot communicate simultaneously to multiplepolicy servers.

You are not required to configure the IBM Security Access Manager runtime forthis feature to operate; however, then the PolicyDirector/etc/routing file is notcreated. You can manually create one, or, if no routing file is present, then bydefault NOTICE and NOTICE_VERBOSE messages are discarded (routed to DISCARD:).Other types of messages are sent to standard error (routed to STDERR:). You canoverride these defaults by setting environment variables such as SVC_FATAL tospecify where to route various types of messages.

Tivoli Common Directory for logging is not set by pdadmin_host. To enable loggingin the Tivoli Common Directory location, manually update the generated


configuration file. See the [pdrte] tivoli_common_dir setting in thepd-hostname.conf file.

Parameters

–h hostnameSpecifies the host name of the system that has a policy server.

–d Removes the previous configuration for a policy server host. (Optional)

–r portSpecifies the port on which the policy server is listening. When notprovided, the default is 7135. (Optional)

–c certfileSpecifies the file that contains the certificate authority certificate for thepolicy server. When not provided, the utility contacts the policy server forthe value. For security purposes, you can choose an alternate securemethod to place the file on the system before you use this option.(Optional)

–l domainSpecifies the default domain to use with the policy server. When notprovided, the utility uses Default. If an empty string is provided, the toolcontacts the policy server to request the management domain name.(Optional)

Availability


/opt/PolicyDirector/bin/

v On Windows operating systems:C:\Program Files\Tivoli\Policy Director\bin


Return codes



pd_startStops, starts, and restarts servers on AIX, Linux, and Solaris operating systems.Also displays server status.

Note: On Windows operating systems, use the Services folder.


Syntax

pd_start start

pd_start stop

pd_start restart

pd_start status

Description

In an AIX, Linux, or Solaris environment, use the pd_start utility to manuallystart, stop, or restart all the configured server processes on the local computer.After invocation, the script waits until the servers are started or stopped before thecommand prompt is returned.

On AIX, Linux, and Solaris operating systems, server processes are normallyenabled and disabled through scripts that run at system startup and during systemshutdown. This technique is useful when you must customize an installation ortroubleshoot a problem.

To individually start the server process on the local AIX, Linux, or Solarisoperating system, enter the process name from the command line, as follows:For the policy server

installation_directory/bin/pdmgrdFor the policy proxy server

installation_directory/bin/pdmgrproxydFor each authorization server instance

installation_directory/bin/pdacld -routing instance-pdacld_routing-config installation_directory/etc/instance-ivacld.conf

where instanceis the name of the authorization server instance (excluding thetrailing '-' character). For the empty instance name, do not add the instance-. Forthe empty instance name, the -routing and -config parameters are optional.

Start the server processes in the following sequence:1. Policy server2. Policy proxy server3. One or more authorization server instances

Stop the server processes in the following sequence:1. All authorization server instances2. Policy proxy server3. Policy server

Note: To control the server processes in a Windows environment, use the ServicesControl Panel.

Parameters

restart Stops and restarts all the Security Access Manager server processes on thelocal computer.

start Starts the Security Access Manager server processes that are not currentlyrunning on the local system.

status Displays the state of each of the Security Access Manager server processes.


stop Stops the Security Access Manager server processes that are running on thelocal system.

Availability

By default on AIX, Linux, and Solaris operating systems, this utility is in the/opt/PolicyDirector/bin directory.


Return codes



Examplesv To stop and restart all server processes on the local computer, enter the

following command:pd_start restart

v To display the status of the server processes on the local computer, enter thefollowing command:pd_start status

Sample output:

Server Enabled Running Instance

pdmgrd yes yes

pdacld yes yes inst1

pdacld yes yes inst2

pdacld yes yes

pdmgrproxyd no no

pdbackup

Backs up, restores, and extracts Security Access Manager data.

Syntax

pdbackup –action backup –list list_file [–path path] [–file filename]

pdbackup –action restore –file filename [–path path]

pdbackup –action extract –file filename –path path

pdbackup –usage


pdbackup –?

Description

Use the pdbackup utility to back up and restore Security Access Manager data. Asan alternative to a restore action, you can extract all archived files into a singledirectory. This utility is most commonly used for backing up, restoring, andextracting Security Access Manager component files.

Note: Before performing backup and restore actions, stop the Security AccessManager servers on the target machine to ensure a consistent snapshot, orreplacement, of files. Stopping the Security Access Manager servers prevents theservers from updating, and possibly overwriting, the files that you want to backupor restore.

Note: On Windows 2008 systems with Tivoli Access Manager 6.0, 6.1, or 6.1.1:The pdbackup utility on Windows 2008 may hang while waiting for user input. Ifyou encounter this issue, use either of the following approaches to continuerestoring the policy server:v Type an "A" in the command window. The utility resumes normally.v Apply the following fix pack for your respective Tivoli Access Manager release,

then rerun the pdbackup utility:– Tivoli Access Manager 6.0: Fixpack 28 or later– Tivoli Access Manager 6.1: Fixpack 08 or later– Tivoli Access Manager 6.1.1: Fixpack 04 or later

Parameters

You can shorten a parameter name, but the abbreviation must be unambiguous.For example, you can type –a for –action or –l for –list. However, values forparameters cannot be shortened.


–action [backup|restore|extract]Specifies to action to be performed. This parameter supports one of thefollowing values:

backupBacks up the data, service information, or migration information toan archive file. The archive file has a tar extension on AIX, Linux,and Solaris operating systems and a dar extension on Windowsoperating systems.

extract Extracts the data from an archive file to a specified directory. Thisaction is used during a two-machine migration only.

restoreRestores the data from the archive file.

–file filenameSpecifies the name of the archive file. When this parameter is required, itsvalue must be the fully qualified name of the archive file. When thisparameter is optional, its value must be the name of the archive file only.For the extract and restore actions, this parameter is required. For thebackup action, this parameter is optional.


When using the backup action, specifies a file name other than the defaultname. The default name is the name of the service list file with a date andtime of the file creation. On AIX, Linux, and Solaris operating systems, thedefault file name is list_file_ddmmmyyyy.hh_mm.tar. On Windowsoperating systems, the default file name islist_file_ddmmmyyyy.hh_mm.dar.

–list list_fileSpecifies the fully qualified name of the list file. The list file is an ASCIIfile that contains the information about the various files and data to backup. These files are located in the /etc directory under thecomponent-specific installation directory. The following list contains thedefault file name and location of each component-specific list file byoperating system. The assumption is that the default installation directorywas used during installation:Security Access Manager data

On AIX, Linux, and Solaris operating systems:/opt/PolicyDirector/etc/pdbackup.lst

On Windows operating systems:C:\Program Files\Tivoli\Policy Director\etc\pdbackup.lst

Security Access Manager service informationOn AIX, Linux, and Solaris operating systems:

/opt/PolicyDirector/etc/pdinfo.lstOn Windows operating systems:

C:\Program Files\Tivoli\Policy Director\etc\pdinfo.lstWebSEAL data

On AIX, Linux, and Solaris operating systems:/opt/pdweb/etc/amwebbackup.lst

On Windows operating systems:C:\Program Files\Tivoli\pdweb\etc\amwebbackup.lst

WebSEAL service informationOn AIX, Linux, and Solaris operating systems:

/opt/pdweb/etc/pdinfo-amwebbackup.lstOn Windows operating systems:

C:\Program Files\Tivoli\pdweb\etc\pdinfo-amwebbackup.lst

Plug-in for web servers dataOn AIX, Linux, and Solaris operating systems:

/opt/pdwebpi/etc/pdwebpi.lstOn Windows operating systems:

C:\Program Files\Tivoli\pdwebpi\etc\pdwebpi.lstPlug-in for web servers service information

On AIX, Linux, and Solaris operating systems:/opt/pdwebpi/etc/pdinfo-pdwebpi.lst

On Windows operating systems:C:\Program Files\Tivoli\pdwebpi\etc\pdinfo-pdwebpi.lst

–path pathSpecifies the target directory for the specified action. This parameter isrequired with the extract action, but is optional with the backup andrestore actions.

When specified with the backup action, specifies the target directory forthe archive file. When not specified, the command uses the defaultdirectory for the component. The following list contains the defaultdirectory for each component by operating system:


On AIX, Linux, and Solaris operating systems/var/PolicyDirector/pdbackup/

On Windows operating systems:C:\Program Files\Tivoli\Policy Director\pdbackup\

With the extract action, specifies the directory where the files that areextracted from the archive file are stored. There is no default value for the–path parameter when used for an extract action.v On AIX, Linux, and Solaris operating systems only, when specified with

the restore action, specifies the directory where the files from the archivefile are restored. By default, this path is one used during the backupprocess. On Windows operating systems, the restore process does notsupport the –path parameter. On Windows operating systems, the filesare restored to their original directory.

–usageDisplays the syntax and an example for this utility.

Availability

This utility is located in one of the following default installation directories:

On AIX, Linux, and Solaris operating systems:/opt/PolicyDirector/bin

On Windows operating systems:C:\Program Files\Tivoli\Policy Director\bin

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 codes


1 The utility failed. When a utility fails, a description of the error and anerror status code in hexadecimal format is provided (for example,0x15c3a00c). See the IBM Security Access Manager for Web: Error MessageReference. This reference provides a list of the Security Access Managererror messages by decimal or hexadecimal codes.

Examplesv The following example backs up the Security Access Manager data on a

Windows operating system. The example uses default values for the archivefiles:pdbackup -a backup -list \C:\Program Files\Tivoli\Policy Director\etc\pdbackup.lst

If the command is run on 22 December 2011 at 10:22 AM, thepdbackup.lst_22dec2011.10_22.dar archive file is created and stored in theC:\Program Files\Tivoli\Policy Director\pdbackup\ directory.

v The following example:– Backs up the WebSEAL service information about an AIX, Linux, or Solaris

operating system.– Stores the archive in the /var/backup directory.


pdbackup -a backup -list \/opt/pdweb/etc/pdinfo-amwebbackup.lst \-path /var/backup

If the command is run on 22 December 2011 at 10:22 AM, thepdinfo-amwebbackup.lst_22dec2011.10_22.tar archive file is created and storedin the /var/pdbackup directory.

v The following example:– Backs up the plug-in for web servers files on a Linux operating system.– Creates the webpi.tar file in the /var/pdback directory.pdbackup -a backup -list \/opt/pdwebpi/etc/pdwebpi.lst \-f webpi -p /var/pdback

Independent of when the command is run, the webpi.tar file is created in the/var/pdback directory. The .tar file extension is added to file name during thebackup process.

v The following example restores the pdbackup.lst_22dec2011.10_22.dar archivefile on a Windows operating system from the default location.pdbackup -a restore -f C:\Program Files\Tivoli\Policy \Director\pdbackup\pdbackup.lst_22dec2011.10_22.dar

The file is restored to its original location. On Windows operating systems, filescannot be restored to another location.

v The following example restores the amwebbackup.lst_22dec2011.10_22.tararchive file that is stored in the /var/pdbackup directory to the /amwebtestdirectory:pdbackup -a restore -f \/var/pdbackup/amwebbackup.lst_22dec2011.10_22.tar \-p /amwebtest

v The following example extracts the amwebbackup.lst_22dec2011.10_22.tararchive file that is stored in the /var/pdbackup directory to the/amwebextracttest directory:pdbackup -a extract -f \/var/pdbackup/amwebbackup.lst_22dec2011.10_22.tar \-p /amwebextracttest

pdconfDisplays and modifies Security Access Manager configuration files.

Syntax

pdconf –f file [–v] command [arg]

Description

The pdconf utility displays or modifies a specified Security Access Managerconfiguration file. You can run this utility directly from the command line. Thisutility runs in single command mode.

For instructions on using pdconf to manage configuration options files, see the"Managing automated configuration passwords" appendix of the IBM SecurityAccess Manager for Web Installation Guide.


Parameters

–f fileSpecifies the name of a configuration file. For example, pd.conf. This namemust have a fully qualified path name, unless you are already working inthe directory where the file is located.

–v Displays the version number of the pdconf utility. If this option isspecified, all other valid options are ignored. (Optional)

The following example is the output that you might see when you use thisoption:Security Access Manager Configuration Tool v7.0.0.0 (Build 111215)Copyright (C) IBM Corporation 2012. All Rights Reserved.

command {addentry | addstanza | deleteentry | deletestanza | getentry |getstanza | setentry} [arg]

Command specifies the requested pdconf action. Arg specifies the requiredinformation to complete the command. Command and correspondingarguments include the following sets:

addentry [–obfuscate] stanza entry valueAdds an entry to the specified stanza in the configuration file.

addstanza stanzaAdds a stanza to the specified configuration file.

deleteentry stanza entryDeletes an entry in the specified stanza in the configuration file.

deletestanza stanzaDeletes a stanza in the specified configuration file.

getentry stanza entryDisplays the value of an entry for the specified stanza in theconfiguration file.

getstanza stanzaDisplays the entries of a stanza and the associated values for theconfiguration file.

setentry [–obfuscate] stanza entry valueSets the value of an entry for the specified stanza in theconfiguration file.

entry Specifies the entry in the specified configuration file andstanza.

–obfuscateIdentifies that a value (for example, a password) is notstored in clear text. When you use the -obfuscateparameter, an additional file, called file.obf, is created tostore the obfuscated value.

stanza Specifies the name of a stanza in the configuration file.

value Specifies the configuration value for the specified entry. Ifthe value is specified as a '-', the value is read fromstandard input (stdin).

Availability

The pdconf utility is in the following directory by default:


AIX, Linux, and Solaris/opt/PolicyDirector/sbin/

WindowsC:\Program Files\Tivoli\Policy Director\sbin\

When you select an installation directory other than the default, this utility is inthe sbin directory under the installation directory. For example, on Windows:installation_directory\sbin.

Return codes


1 The utility failed. When a utility fails, a description of the error displays.


Examplesv The following example retrieves the manager stanza from the pd.conf

configuration file on AIX, Linux, or Solaris./opt/PolicyDirector/sbin/pdconf -f /opt/PolicyDirector/etc/pd.conf getstanza managermaster-host =master-port = 7135management-domain = Default

v The following example retrieves the manager stanza from the pd.confconfiguration file on Windows.C:\Program Files\Tivoli\Policy Director\sbin\pdconf -f "C:\Program Files\Tivoli\Policy Director\etc\pd.conf" getstanza managermaster-host =master-port = 7135management-domain = Default

pdconfigConfigures and unconfigures Security Access Manager components.

Syntax

pdconfig

Note: Before you run the pdconfig utility, you must set the PATH environmentvariable to include the directory that contains the Java executable file. For example,you might specify the directory where you installed the IBM Java Runtime. See thetopics about installing IBM Java Runtime in the IBM Security Access Manager forWeb Installation Guide for information about setting this environment variable.

Description

When you configure Security Access Manager with the pdconfig utility, you areprompted for several options. Use the IBM Security Access Manager for WebInstallation Guide for option descriptions to help you provide correct values.


When a message displays that indicates a package was successfully configured,press Enter to configure another package, or select the x (Exit) option twice to closethe configuration utility.

If you must comply with security standards such as FIPS 140-2, NIST SP800-131aor NSA Suite B, the pdconfig utility prompts you to do the following steps:1. Stop the configuration process.2. Update the pd.conf file to set ssl-compliance to the required compliance type.3. Restart the configuration process.

If you configure the Security Access Manager security standard in thessl-compliance option to Suite B, NIST SP800-131, or FIPS, and not the default of"none," then during Web Portal Manager configuration, you must also configureWebSphere Application Server to enable the same security standard. If the securitystandard settings do not match, Web Portal Manager configuration fails. To enablethe same security setting in WebSphere Application Server, seehttp://pic.dhe.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=%2Fcom.ibm.websphere.nd.multiplatform.doc%2Finfo%2Fae%2Fae%2Fcsec_security_standards.html

Note:

Parameters

None.

Availability


/opt/PolicyDirector/bin

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


Return codes



pdjrtecfgConfigures or unconfigures IBM Security Access Manager Runtime for Java.

Syntax

Configure in full mode


http://pic.dhe.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=%2Fcom.ibm.websphere.nd.multiplatform.doc%2Finfo%2Fae%2Fae%2Fcsec_security_standards.html



pdjrtecfg –action config –host policy_server_host [–portpolicy_server_port] [–java_home jre_home] [–domain domain_name][–config_type full] [–enable_tcd [–tcd path]][–cfgfiles_pathpath_to_config_files [–alt_config]]

Configure in stand-alone mode

pdjrtecfg –action config –config_type standalone [–cfgfiles_pathpath_to_config_files [–alt_config]]

Configure in interactive modepdjrtecfg –action config –interactive

Configure with a response file

pdjrtecfg –action config –rspfile response_file

pdjrtecfg –action name

pdjrtecfg –action status [–java_home jre_home]

pdjrtecfg –action unconfig [–java_home {jre_home|all}]

pdjrtecfg –action unconfig –interactive

pdjrtecfg –operations

pdjrtecfg –help [options]

pdjrtecfg –usage

pdjrtecfg –?

Description

The IBM Security Access Manager Runtime for Java component enables Javaapplications to manage and use Security Access Manager security.

The pdjrtecfg utility adds or updates Security Access Manager .jar files in thejre_home\lib\ext directory and backs up the existing files. The utility does notmodify any other .jar files in this directory.

More than one Java runtime can exist on the same computer. Use the pdjrtecfgutility to configure IBM Security Access Manager Runtime for Java independentlyto each JRE.

WebSphere Application Server, version 8, does not permit modification to its JRE,so you must configure IBM Security Access Manager Runtime for Java to a locationoutside of the WebSphere JRE. With WebSphere Application Server, version 8, theIBM Security Access Manager Runtime for Java configuration files and .jar filesare in the WAS_Home/tivoli/tam directory.

You can configure IBM Security Access Manager Runtime for Java into WebSphereApplication Server, version 8, either the following ways:v On the command line with pdjrtecfg. This option requires two more

configuration options:– -cfgfiles_path

– -alt_config


v Interactively with either pdconfig or pdjrtecfg -action config -interactive.When pdjrtecfg runs with -interactive, the utility detects WebSphereApplication Server, version 8, and automatically provides the -cfgfiles_pathand -alt_config options.

Note: Use only the pdjrtecfg utility and not the PDJrteCfg Java class directly.

Parameters

–? Shows the syntax for this utility. (Optional)

–action {config|name|status|unconfig}Specifies the action that is one of the following values:

config Configures the IBM Security Access Manager Runtime for Javacomponent.

name Retrieves the IBM Security Access Manager Runtime for Javacomponent package name and returns the name value to thepdconfig utility. Only pdconfig uses this parameter. Do not use thisparameter from the command line.

status Determines and returns the IBM Security Access Manager Runtimefor Java component configuration status information to thepdconfig utility. Only pdconfig uses this parameter. Do not use thisparameter from the command line.

unconfigUnconfigures the IBM Security Access Manager Runtime for Javacomponent.

–alt_configSpecifies either to add the PD.jar to a specified directory or to update anexisting file. The –cfgfiles_path path_to_config_files option specifies adirectory instead of using the default JRE lib/ext/ directory. (Optional)

You must set the –cfgfiles_path parameter to use –alt_config.

The –alt_config option supports the WebSphere Application Server,version 8, restriction which does not permit modification of any files underthe WebSphere Application Server JRE directory.

WebSphere Application Server, version 8, adds the WAS_HOME/tivoli/tamdirectory to its java.ext.dirs property for use with Security AccessManager. To use the new directory, you must specify WAS_HOME/tivoli/tamfor the –cfgfiles_path path_to_config_files parameter along with–alt_config so that PD.jar is available to the WebSphere ApplicationServer JVM.

–cfgfiles_path path_to_config_filesSpecifies an alternative location for the PolicyDirector directory thatcontains the IBM Security Access Manager Runtime for Java configurationfiles. Typically, the PolicyDirector directory is at the root of the JREdirectory that is being configured. (See -java_home.) (Optional)

If you use this option, then applications that use the PD.jar API in thisJava Runtime must set the Java System property, pd.cfg.home with thesame path_to_config_files value.

This option supports the WebSphere Application Server, version 8,restriction which does not permit the modification of any files under theWebSphere Application Server JRE directory.


WebSphere Application Server, version 8, stores Security Access Managerconfiguration files in a unique directory: WAS_HOME/tivoli/tam/PolicyDirector. WebSphere Application Server version 8 also requires the–alt_config parameter.

The /opt/IBM/WebSphere/AppServer/tivoli/tam directory contains thePD.jar file. The PolicyDirector subdirectory contains the PD.propertiesfile.

For example, if you install WebSphere Application Server, version 8, at alocation such as /opt/IBM/WebSphere/AppServer, the value for the–cfgfiles_path variable, path_to_config_files, is /opt/IBM/WebSphere/AppServer/tivoli/tam. No other location can be used.

–config_type {full|standalone}Specifies the configuration mode. The default value is full. (Optional)

full Completes all the required configuration steps, which include thegeneration of the server-side certificate for the policy server.

standaloneCompletes all the required configuration steps, except for thegeneration of the server-side certificate for the policy server. Withthis configuration, you can use the Security Access Manager JavaAPIs without requiring a policy server. Typically, this configurationis used to configure a Security Access Manager developmentenvironment.

–domain domain_nameSpecifies the local domain name for the Java runtime. A local domain is aSecurity Access Manager secure domain that is used by programs when noexplicit domain is specified. If you do not specify this parameter, the localdomain defaults to the management domain. (Optional)

–enable_tcd [–tcd path]Enables Tivoli Common Directory (TCD) logging, if it is not alreadyenabled. It also specifies the fully qualified path location for commonlogging. When TCD is enabled, all Security Access Manager message logfiles are placed in this common location. (Optional)

–help [options]Provides online help for one or more utility options. It shows descriptionsof the valid command-line options. Alternatively, it provides online helpabout a specific command-line parameter. (Optional)

–host policy_server_hostSpecifies the Security Access Manager policy server host name. Validvalues include any valid IP host name. Examples:host = librahost = libra.example.ibm.com

–interactiveSpecifies the interactive mode in which the user is prompted forconfiguration information for the IBM Security Access Manager Runtimefor Java component. If not specified, the configuration program runs innon-interactive (silent) mode. (Optional)

–java_home jre_pathSpecifies the fully qualified path to the Java runtime, such as the directorythat ends in JRE. If you do not specify this parameter, the home directory


for the JRE in the PATH statement is used. If the home directory for theJRE is not in the PATH statement, this utility fails. (Optional)

During unconfiguration, you can specify the all parameter thatunconfigures all configured JREs.

–operationsPrints all the valid command-line options. (Optional)

–port policy_server_portSpecifies the Security Access Manager policy server port number. Thedefault value is 7135. (Optional)

–rspfile response_fileSpecifies the fully qualified path and file name of the silent configurationresponse file. You can use a response file for configuration. There is nodefault response file name. (Optional)

The response file contains parameter=value pairs. The following rulesapply to response files:v All slashes in the java_home parameter path must be either:

– Escaped with a second back slash (\)– A single front slash (/)

For example:java_home=c:\\Program Files\\IBM\\Java60

orjava_home=c:/Program Files/IBM/Java60


–usage Shows the syntax for this utility. (Optional)

Availability




When you select an installation directory other than the default, this utility is inthe /sbin directory under the installation directory. For example,installation_directory/sbin.

Return codes


1 The utility failed. When a utility fails, a description of the error and anerror status code in hexadecimal format is provided. For example,0x15c3a00c. See the IBM Security Access Manager for Web Error MessageReference. This reference provides a list of the Security Access Managererror messages by decimal or hexadecimal codes.

Examplesv The following example configures the IBM Security Access Manager Runtime for

Java component:


pdjrtecfg -action config -host sys123.acme.com -port 7135-java_home "C:\Program Files\IBM\Java60\jre"

v The following example unconfigures the IBM Security Access Manager Runtimefor Java component:pdjrtecfg -action unconfig -java_home "C:\Program Files\IBM\Java60\jre"

v The following example uses command-line configuration of WebSphereApplication Server, version 8, for the Security Access Manager Java API:# pdjrtecfg -action config -host mypolicyserverhostname \

-java_home /opt/IBM/WebSphere/AppServer/java/jre \-cfgfiles_path /opt/IBM/WebSphere/AppServer/tivoli/tam \-alt_config -config_type full -port 7135

pdjservicelevelReturns the service level of installed Security Access Manager files that use theIBM Security Access Manager Runtime for Java package.

Note: This utility is for use by support personnel.

Syntax

pdjservicelevel directory

Description

The pdjservicelevel utility recursively scans the specified directory and returnsthe name and service level for each file to standard output. Only executableprograms, shared libraries, archives, and other such files have a service level.

If the service level for a file cannot be determined, the string "Unknown" is writtento standard output. Generally, ASCII files and other such files do not have servicelevels.

Note: For this utility to determine the service level of a JAR file, the Java jarutility must exist in the system PATH statement. When the jar utility cannot befound, the service level that is reported for all JAR files is "Unknown".

Parameters

directorySpecifies the fully qualified name of the directory.

Availability

This utility is installed as part of the IBM Security Access Manager Runtime forJava package. It is in one of the following default installation directories:v On AIX, Linux, and Solaris operating systems:





Return codes



PDMgr_configConfigures the Security Access Manager policy server for AIX, Linux, and Solarisplatforms.

Syntax

PDMgr_config [–C compliance] [–d dn_ldap-admin] [–D ldap_dn] [–f response_file][–F use_fips{yes|no}] [–j standby_server {yes|no}] [–Jstandby_server_conf_file] [–k key_file] [–K key_file_password] [–lcertificate_life] [–L port] –m password [–N key_file_label] [–r port] [–ssilent{yes|no}] [–S ldap_suffix] [–v use_minimal_data_format {yes|no}] –wpassword [–Z use_ssl {yes|no}]

Description

The PDMgr_config utility configures the Security Access Manager policy server onAIX, Linux, and Solaris platforms. You can run this utility directly from thecommand line.

Parameters

–C complianceSpecifies the compliance value for the [ssl] ssl-compliance configurationfile setting. (Optional) If not specified, this value defaults to the [ssl]ssl-compliance value that is currently set in the pd.conf file. Thecompliance value must be one of the following settings:

fips Enforces FIPS 140-2 protocols and algorithms.

Security Access Manager servers and applications generate and useSHA1 with 2048-bit RSA certificates. Only TLS versions 1.0, 1.1,and 1.2 are available. SSL versions 2 and 3 are disabled andunavailable. This setting option is equivalent to the previousrelease setting [ssl] ssl-enable-fips = yes. This value iscompatible with previous Tivoli Access Manager releases.





sp800-131-transitionEnables NIST SP800-131a support at the transition level. This valueis valid until the end of the year 2013. This value has fewerrestrictions than the strict enforcement. Only TLS versions 1.0, 1.1,and 1.2 are available. SSL versions 2 and 3 are disabled andunavailable.


suite-b-128Enables NSA Suite B at 128-bit support. Security Access Managerservers and applications generate and use SHA256 with 256-bitECDSA certificates. This value is not compatible with previousTivoli Access Manager releases. Older Tivoli Access Managerclients cannot interact with Tivoli Access Manager 7.0 running withthis compliance setting. Only TLS version 1.2 is available; all othersare disabled.

suite-b-192Enables NSA Suite B at 192-bit support. Security Access Managerservers and applications generate and use SHA384 with 384-bitECDSA certificates. This value is not compatible with previousTivoli Access Manager releases. Older Tivoli Access Managerclients cannot interact with Security Access Manager 7.0 runningwith this compliance setting. Only TLS version 1.2 is available; allothers are disabled.


–D ldap_dnThe name of the management domain. Configuring the policy server in themanagement domain creates the initial administrative domain. Themanagement domain name must be unique within the LDAP server. Thename must be an alphanumeric string up to 64 characters long and notcase-sensitive. The default value is Default. (Optional)



–F use_fips {yes|no}Specifies whether to enable Federal Information Processing Standards(FIPS). If FIPS is enabled, the IBM Tivoli Directory Server is configured touse the appropriate FIPS secure communications protocol. The validresponses are yes or no. The default value is no. (Optional)

–j standby_server {yes|no}If a policy server is already configured to the LDAP server, a second policyserver might be configured for standby purposes only. Valid values are yesor no. The default value is no. This parameter applies only to the AIXplatform. (Optional)

–J standby_server_conf_fileThe fully qualified location of the ivmgrd.conf file, which is the existingprimary policy server configuration file. For example, if the shareddirectory is /share, enter /share/PolicyDirector/ivmgrd.conf. Thisparameter applies only to the AIX platform. (Optional)

–k key_fileSpecifies the fully qualified file name of the client-side key file. This keyfile holds the server-side certificates that are used in securecommunication. This parameter is required when use_ssl is set to yes,which enables SSL communication. (Optional)

–K key_file_passwordSpecifies the password that is associated with the specified key_file. Thispassword was set when the key file was created. This parameter isrequired if use_ssl is yes. (Optional)

–l certificate_lifeSpecifies the number of days that the SSL certificate file is valid. Thedefault number of days is 1460. (Optional)

–L portSpecifies the Secure Sockets Layer (SSL) port number of the LDAP server.Use the LDAP server-configured port number. The default port number is636. (Optional)

–m passwordSpecifies the password for the Security Access Manager administrator ID.The default administrator ID is sec_master.

–N key_file_labelSpecifies the server certificate label name that is in the key_file. This labelwas set when the server certificate was imported in the client-side key file.This parameter is required when use_ssl is set to yes, which enables SSLcommunication. (Optional)

–r portSpecifies the port number for the Security Access Manager policy server.The default value is 7135. (Optional)

–s silent{yes|no}Specifies silent configuration. The valid responses are yes or no. If set toyes, the utility runs in silent mode. If set to no, the utility runs ininteractive mode. (Optional)

–S ldap_suffixThe software creates the secAuthorityInfo object entry on the LDAP serverwhen you create:v ASecurity Access Manager domain.


v The initial management domain.

This object represents the Security Access Manager domain and is namedby using the secAuthority attribute with the name of the domain as itsvalue. For example: secAuthority=<domain_name>.

If you do not provide a different name, the default name of themanagement domain is Default, making the secAuthorityInfo object namesecAuthority=Default. (Optional)

–v use_minimal_data_format {yes|no}When you configure the policy server, you can select the LDAP dataformat for user and group tracking information. The two LDAP dataformats are minimal and standard. The valid responses are yes or no. Thedefault value is yes. (Optional)

–w passwordSpecifies the password for the dn_ldap_admin.

–Z use_ssl {yes|no}Specifies whether to enable SSL communication between the SecurityAccess Manager policy server and the registry server. The valid responsesare yes or no. The default value is no. (Optional)

Availability



Return codes



Examples

The following example configures the Security Access Manager policy server byusing LDAP as the user registry and the default management domain. SSLcommunication with the LDAP server is not enabled../PDMgr_config -Z no -F no -d "cn=root" -w password -v yes -m password-r 7135 -l 1460 -D Default -s yes

PDMgr_unconfigUnconfigures the Security Access Manager policy server on AIX, Linux, and Solarisplatforms.

Syntax

PDMgr_unconfig [–d dn_ldap-admin] [–f response_file] [–R remove_registry{yes|no}] [–s silent {yes|no}] [–w password]


Description

The PDMgr_unconfig utility unconfigures the Security Access Manager policy serveron AIX, Linux, and Solaris platforms. You can run this utility directly from thecommand line.

Parameters



–R remove_registry {yes|no}Specifies whether or not to permanently remove domain information fromthe registry. (Optional)

If set to yes If set to no

All domain, user, and group information isremoved

Domain information is removed.

User and group information is retained.

The domain might be re-created later if needed. Valid values are yes or no.The default value is no.

–s silent {yes|no}Specifies silent configuration. The valid responses are yes or no. If set toyes, the utility runs in silent mode. If set to no, the utility runs ininteractive mode. (Optional)

–w passwordSpecifies the password for the dn_ldap_admin. This parameter is requiredwhen you use an LDAP user registry.

Availability



Return codes




Examples

The following example unconfigures the Security Access Manager policy serverand removes all domain, user, and group information from the registry:./PDMgr_unconfig -d "cn=root" -w password -R yes -s yes

pdproxycfgConfigures or unconfigures a policy proxy server.

Syntax

pdproxycfg –action config [–admin_id administrator_id] –admin_pwdadministrator_password [policysvr policy_server_name] [–admin_portpolicy_server_port] [–host proxy_server_name] [–proxy_port proxy_server_port][–ssl_enabled {yes|no}] [–keyfile keyfile] [–key_pwd password] [–key_label label][–ssl_port ssl_port]

pdproxycfg –action config –rspfile response_file

pdproxycfg –action config –interactive {yes|no}

pdproxycfg –action unconfig –interactive {yes|no}

pdproxycfg –operations

pdproxycfg –help [options]

pdproxycfg –usage

pdproxycfg –?

Description

Use the pdproxycfg utility to configure a policy proxy server from the commandline. The utility can be run in interactive mode, command-line mode, or responsefile mode. In interactive mode, the user is prompted to supply the necessaryvalues. In command-line mode, all options can be specified from the commandline.

In response file mode, the utility obtains the necessary parameters from theresponse file. When the response file does not contain a necessary parameter, theuser is prompted to supply it. The response file must be created manually.

Parameters

–? Displays the syntax for this utility. (Optional)

–action {config | name | status | unconfig}This parameter takes one of the following arguments:

config Configures a policy proxy server.

name Retrieves the policy proxy server name and returns the name valueto the pdconfig utility. This parameter is used only by the pdconfigutility. Do not use this parameter from the command line.


status Returns the status value to the pdconfig utility. This parameter isused only by the pdconfig utility. Do not use this parameter fromthe command line.

unconfigUnconfigures a policy proxy server.

–admin_id administrator_idSpecifies the name of the administrative user in the Default domain. Thepolicy proxy server represents the policy server. Therefore, the policy proxyserver is able to represent all the defined domains at the policy server. Thepolicy proxy server must be configured into the Default domain. Thedefault value is sec_master. (Optional)

–admin_port policy_server_portSpecifies the port number of the Security Access Manager policy server.The default port number is 7139. (Optional)

–admin_pwd administrator_passwordSpecifies the password of the administrative user. The default value issec_master.

–help [options]Returns online help for one or more utility options by displayingdescriptions of the valid command-line options. Alternatively, providesonline help about a specific command-line option. (Optional)

–host proxy_server_nameSpecifies the host name that is used by the policy server to contact thepolicy proxy server. Valid values include any valid IP host name. Forexample:libra.example.ibm.com

The default value is the local host name. (Optional)

–interactive {yes|no}Specifies that the configuration is to be done interactively by theadministrator (yes) or silently (no). (Optional)

–key_label labelSpecifies the label of the SSL LDAP client certificate. This parameter isused only when SSL communication is enabled between the policy proxyserver and an LDAP server. (Optional)

–key_pwd passwordSpecifies the password of the LDAP SSL key file. This parameter isrequired only when SSL communication is enabled between the policyproxy server and the LDAP server. (Optional)

–keyfile keyfileSpecifies the LDAP SSL key file. This parameter is required only when SSLcommunication is enabled between the policy proxy server and an LDAPserver. (Optional)

–operationsPrints all the valid command-line options. (Optional)

-policysvr policy_server_nameSpecifies the host name of the Security Access Manager policy server orother policy proxy server that can be used for configuration andunconfiguration. (Optional)


–proxy_port proxy_server_portSpecifies the port on which the policy proxy server listens for incomingproxy requests. The default value is 7138. (Optional)

–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. (Optional)

The following rules apply to properties files:v All slashes in the java_home parameter path must be either:

– Escaped with a second back slash (\)– A single front (/)

For example:java_home=c:\\Program Files\\IBM\\Java60

or:java_home=c:/Program Files/IBM/Java60


–ssl_enabled {yes|no}Specifies whether to enable SSL communication between the policy proxyserver and the LDAP server. Valid indicators are yes or no. (Optional)

–ssl_port ssl_portThe port number on which SSL communication takes place between thepolicy proxy server and the LDAP server. This parameter is used onlywhen SSL communication is enabled between the policy proxy server andan LDAP server. (Optional)

–usage Displays the syntax for this utility. (Optional)

Availability


/opt/PolicyDirector/sbin/



Return codes




Example

The following example configures a policy proxy server with SSL communicationenabled with an LDAP server:pdproxycfg –action config –host diamond.subnet2.ibm.com \–proxy_port 7234 –admin_id sec_master –admin_pwd mypassw0rd \policysvr libra.subnet2.ibm.com -admin_port 7242 –ssl_enabled yes \–keyfile /tmp/client.kdb –key_pwd mypassw0rd –key_label ibm_cert \–ssl_port 636

PDRTE_configConfigures the Security Access Manager Runtime on AIX, Linux, and Solarisplatforms.

Syntax

PDRTE_config [–c certificate] [–d ad_domain] [–E use_ssl {yes|no}] [–f key_file][–F key_file_password] [–g key_file_label] [–G ad_multiple_domain {yes | no}][–h policy_server_host_name] –H LDAP_server_host_name [–i response_file] [–llocal_domain] [–P port] [–r port] [–R dnforaccess] [–s silent {yes | no}] [–Slocal_policy_server {yes | no}] –t registry_type {ldap |active_directory_ldap} [–T tivoli_common_directory] [–u ad_alt_upn {yes | no}][–v ad_gc_server]

Description

The PDRTE_config utility configures the Security Access Manager Runtime on AIX,Linux, and Solaris platforms. You can run this utility directly from the commandline.

Parameters

–c certificateSpecifies the name of the policy server base-64 encoded, self-signedcertificate. For example, /var/PolicyDirector/keytab/pdcacert.b64

If the certificate file is not specified, the certificate is downloaded from theSecurity Access Manager policy server. (Optional)

–d ad_domainSpecifies the Active Directory domain name. For example, dc=ibm,dc=com.

This parameter is required when Active Directory is the user registry.(Optional)

–E use_ssl {yes | no}Specifies whether to enable SSL communication between the runtime andthe registry server. The valid responses are yes and no. The default value isno. (Optional)

–f key_fileSpecifies the fully qualified file name of the client-side key file. The key fileholds the server-side certificates that are used in secure communication.This parameter is required when use_ssl is set to yes, which means thatSSL communication is enabled. (Optional)

–F key_file_passwordSpecifies the existing password that is associated with the specified


key_file. This password was set when the key file was created. Thisparameter is required if use_ssl is set to yes. (Optional)

–g key_file_labelSpecifies the server certificate label name that is in the key_file. The labelwas set when server certificate was imported in client-side key file. Thisparameter is required when use_ssl is set to yes, which means that SSLcommunication is enabled. (Optional)

–G ad_multiple_domain {yes|no}Configures Security Access Manager in Active Directory multiple domainenvironment. The valid responses are yes and no. The default value is no.(Optional)

–h policy_server_host_nameSpecifies the host name of the Security Access Manager policy server. Thisparameter is required if local_policy_server is no. You can specify anyvalid IP host name. For example: libra.example.ibm.com. (Optional)

–H LDAP_server_host_nameSpecifies the IP address or host name of the LDAP server. You can specifyany valid IP host name. For example:host = librahost = libra.dallas.ibm.com

–i 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 key=value pairs. For information about using response files, see the"Using response files" appendix in the IBM Security Access Manager for WebCommand Reference. (Optional)

–l local_domainSpecifies the local domain name for the Runtime that is being configured.(Optional)

A local domain is a Security Access Manager secure domain that is used byprograms when no explicit domain is specified. If the parameter is notspecified, the local domain defaults to the management domain.

A valid local domain name is an alphanumeric, case-sensitive string. Validcharacters are a-z, 0-9, -, and _.

–P portSpecifies the port number of the LDAP server. Use the LDAPserver-configured port number. The default port number is 636 if SecureSockets Layer (SSL) is used and 389 if SSL is not used. (Optional)

–r portSpecifies the port number for the Security Access Manager Policy server.This parameter is required if local_policy_server is no. The default valueis 7135. (Optional)

–R dnforaccessSpecifies the distinguished name (DN) for the data location on the ActiveDirectory server that stores Security Access Manager data.

The parameter is required if ad_multiple_domain is no. Ifad_multiple_domain is yes, then the default value is the value ofad_domain.


–s silent {yes | no}Specifies silent configuration. The valid responses are yes or no. If thevalue is yes, the utility runs in silent mode. If the value is no, the utilityruns in interactive mode. (Optional)

–S local_policy_server {yes | no}Indicates whether the policy server is installed on the same computer. Thevalid responses are yes or no. The default value is no. (Optional)

–t registry_type {ldap | active_directory_ldap}Specifies the type of registry server to be set up for Security AccessManager. The valid responses are ldap and active_directory_ldap.

–T tivoli_common_directoryEnables Tivoli Common Directory logging and specifies the fully qualifiedpath location for common logging. When Tivoli Common Directory isenabled, all of the Security Access Manager message log files are placed inthis common location. (Optional)

–u ad_alt_upn {yes | no}Security Access Manager supports an email address (alternative format) ofthe userPrincipalName attribute of the Active Directory user object as itsuser ID. The valid responses are yes and no. If set to no, only the defaultformat of the userPrincipalName can be used as the Security AccessManager user ID. The default value is no. (Optional)

–v ad_gc_serverSecurity Access Manager supports an email address (alternative format) ofthe userPrincipalName attribute of the Active Directory user object as itsuser ID. Specify the Global Catalog server host name, such asgcserver.us.ibm.com, to enable the support.

If not specified, only the default format of the userPrincipalName can beused as the Security Access Manager user ID. (Optional)

Availability



Return codes


1 The utility failed. When a utility fails, the software a description of theerror. See the IBM Security Access Manager for Web Error Message Reference.This reference provides a list of the Security Access Manager errormessages by decimal or hexadecimal codes.

Examples

The following example configures the Security Access Manager Runtime by usingLDAP as the user registry. The policy server is installed on the same computer:./PDRTE_config -S yes -t ldap -H libra.example.ibm.com -P 389 -s yes


PDRTE_unconfigUnconfigures the Security Access Manager Runtime on AIX, Linux, and Solarisplatforms.

Syntax

PDRTE_unconfig

Description

The PDRTE_unconfig utility unconfigures the Security Access Manager Runtime onAIX, Linux, and Solaris platforms. You can run this utility directly from thecommand line. The utility does not require any parameters.

Availability



Return codes



Examples

The following example unconfigures the Security Access Manager Runtime:./PDRTE_unconfig

pdservicelevel

Returns the service level of installed Security Access Manager files that use theSecurity Access Manager Runtime package.


Syntax

pdservicelevel directory

Description

The pdservicelevel utility recursively scans the specified directory and returns thename and service level for each file to standard output. Only executable programs,shared libraries, archives, and other such files have a service level.


If the service level for a file cannot be determined, the string "Unknown" is writtento standard output. Generally, ASCII files and other such files do not have servicelevels.

Note: For this utility to determine the service level of a JAR file, the Java jarutility must exist in the system PATH statement. When the jar utility cannot befound, the service level that is reported for all JAR files is "Unknown".

Parameters

directorySpecifies the fully qualified name of the directory.

Availability

This utility is installed as part of the Security Access Manager Runtime package. Itis located in one of the following default installation directories:v On AIX, Linux, and Solaris operating systems:



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

Return codes


1 The utility failed. When a utility fails, a description of the error and anerror status code in hexadecimal format is provided (for example,0x15c3a00c). See the IBM Security Access Manager for Web: Error MessageReference. This reference provides a list of the Security Access Managererror messages by decimal or hexadecimal codes.

pdsmsclicfgConfigures the command-line administration utility for the session managementserver.

Syntax

pdsmsclicfg –action config [–rspfile response_file] [–interactive {yes|no}][–sam_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


Description

The 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. The log file is in the:v /var/pdsms/log directory on AIX, Linux, and Solaris operating systems.v installation_directory\log directory on Windows operating systems.

This utility can be run in one of the following ways:v Interactively – the user is prompted to provide configuration information.v Silently – the utility accepts input from a response file or the command line.

Integration with Security Access Manager can be enabled during configuration.The program prompts the user to specify the path to the configuration file for aconfigured aznapi application. The program prompts the user to specify thelocation of the web service. The location of the web service is defined by a hostname and port that are separated by a semicolon.

The user can specify multiple locations, when each location is separated by acomma. If this web service uses a secure connection, the program prompts the userfor the SSL options. You must also specify the session management server instance.

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 program on Windows is pdsmsclicfg-cl.exe.

Parameters

–action {config|unconfig|upgrade|name|version}Specifies an action 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.

upgradeConfigures an upgrade from a previous version.

versionDisplays the version number for the currently installed SMS CLIpackage.



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

–sam_integration {yes|no}Specifies whether integration with the Security Access Manageradministration framework is required. The default value is no. (Optional)

–aznapi_app_config_file path_nameSpecifies the fully qualified name of the configuration file for the hostingauthorization server. Only required if Security Access Manager integrationis enabled. (Optional)

–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 is located. Multiple locations can be specified. Whenyou specify multiple locations, separate the locations with commas.(Optional)

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

-ssl_enable {yes|no}Indicates whether SSL communication with the web server must beenabled. (Optional)

–sslkeyfile pathSpecifies the fully qualified name of the SSL key file to use duringcommunication with the session management server web service. Use thisparameter only when the -ssl_enable parameter is set to yes. (Optional)

–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. (Optional)

–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. (Optional)

Availability


/opt/pdsms/bin

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

To start the command line under Windows, use pdsmsclicfg-cl.exe. Thepdsmsclicfg command starts the wizard.



Return codes


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). See the IBM Security Access Manager for Web Error MessageReference. This reference provides a list of the Security Access Managererror messages by decimal or hexadecimal codes.

pdversionLists the current version of Security Access Manager components that are installedon the system.

Syntax

pdversion [–key key1, key2...keyX] [–separator delimiter_character]

Parameters

–key key1, key2...keyXSpecifies the component or components of the current version. (Optional)The following are possible values of –key:v pdacld – Security Access Manager Authorization Serverv pdauthadk – Security Access Manager Application Developer Kitv pdjrte – Security Access Manager Runtime for Javav pdmgr – Security Access Manager Policy Serverv pdmgrprxy – Security Access Manager Policy Proxy Serverv pdrte – Security Access Manager Runtimev pdsms – Security Access Manager Session Manager Serverv pdweb – Security Access Manager WebSEALv pdwebars – Security Access Manager Attribute Retrieval Servicev pdwebadk – Security Access Manager Web Security ADKv pdwebrte – Security Access Manager Web Security Runtimev pdwebpi – Security Access Manager Plug-in for Web Serversv pdwebpi.apache – Security Access Manager Plug-in for Apachev pdwebpi.ihs – Security Access Manager Plug-in for IBM HTTP Serverv pdwpm – Security Access Manager Web Portal Managerv tivsecutl – IBM Tivoli Security Utilities

The version information for the various blades shows up when the blade packagesare installed on the system. The following components are basic components:v Security Access Manager Runtimev Security Access Manager Policy Serverv Security Access Manager Web Portal Managerv Security Access Manager Application Developer Kitv Security Access Manager Authorization Serverv Security Access Manager Runtime for Javav Security Access Manager Policy Proxy Server

The following components are blades:v Security Access Manager Plug-in for web Serversv Security Access Manager WebSEAL


v Security Access Manager web Security Runtimev Security Access Manager web Security ADKv Security Access Manager Session Manager Serverv Security Access Manager Attribute Retrieval Service

–separator delimiter_characterSpecifies the separator that is used to delimit the description of thecomponent from its version. (Optional)

Availability



v On Windows operating systems:C:\Program Files\Tivoli\Policy Director\bin

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

Return codes



Examplesv The following example lists the base components of Security Access Manager:

> pdversion

Security Access Manager Runtime 7.0.0.0

Security Access Manager Policy Server 7.0.0.0

Security Access Manager Web Portal Manager 7.0.0.0

Security Access Manager Application Developer Kit 7.0.0.0

Security Access Manager Authorization Server 7.0.0.0

Security Access Manager Runtime for Java 7.0.0.0

Security Access Manager Policy Proxy Server 7.0.0.0

IBM Tivoli Security Utilities 7.0.0.0

v The following example lists the Security Access Manager Runtime package(PDRTE) and specifies X as the delimiter to separate the component descriptionfrom its version:> pdversion -key pdrte -separator XSecurity Access ManagerRuntimeX7.0.0.0


pdwebStarts, stops, or restarts a WebSEAL server or displays server status on AIX, Linux,and Solaris operating systems.

Syntax

pdweb start [instance_name]

pdweb stop [instance_name]

pdweb restart [instance_name]

pdweb status [instance_name]

Description

The pdweb utility is supported only on AIX, Linux, and Solaris operating systems.

You can substitute the pdweb_start utility for the pdweb utility.

Note: On Windows operating systems, you can use the net utility to start and stopWebSEAL servers.

Parameters

instance_nameSpecifies the name of the WebSEAL instance in the formatserver_name–host_name.

For example, for a single WebSEAL server, server_name isdefault-webseald. For multiple WebSEAL instances on the same computer,server_name is the configured name of the WebSEAL instance followed by-webseald. For example, if the configured name of a WebSEAL instance iswebseal2, the server name is as follows: webseal2-webseald.

The following characters are allowed:v Any ASCII character (A-Z or a-z)v Period (.)v Dash (-)v Underscore (_)

(Optional) When no instance name is supplied, all instances are restarted.

restartSpecifies a WebSEAL server to restart. The instance name argument isoptional. When no instance name is supplied, all instances are restarted.

start Specifies a WebSEAL server to start. The instance name argument isoptional. When no instance name is supplied, all instances are started.

status Displays the status of all WebSEAL servers.

stop Specifies a WebSEAL server to stop. The instance name argument isoptional. When no instance name is supplied, all instances are stopped.

Availability

This utility is in the following default installation directories:v On AIX, Linux, and Solaris operating systems:


/opt/pdweb/bin

v On Windows operating systems:C:\Program Files\Tivoli\pdweb\bin


Return codes


1 The utility failed. When a utility fails, a description of the error and anerror status code in hexadecimal format is provided (for example,0x14c012f2). See the IBM Security Access Manager for Web Error MessageReference. This reference provides a list of the Security Access Managererror messages by decimal or hexadecimal codes.

Examplesv This example starts the initial WebSEAL server and all configured server

instances:/usr/bin/pdweb start

v This example starts a specific server instance only:/usr/bin/pdweb start webseal3

v This example restarts all configured WebSEAL instances:/usr/bin/pdweb restart

v This example stops all configured WebSEAL instances:/usr/bin/pdweb stop

v This example stops a specific server instance only:/usr/bin/pdweb stop webseal3

v This example shows the status of all configured servers:/opt/PolicyDirector/bin/pdweb status

Access Manager ServersServerEnabledRunning--------------------------------------websealdyesyeswebseald-webseal2yesyeswebseald-webseal3yesyes

pdwebpiReturns the current version of Security Access Manager plug-in for web servers.Also specifies whether to run plug-in for web servers as a service or run it in theforeground.

Syntax

pdwebpi [–foreground] [–version]

Description

The pdwebpi utility returns the current version of Security Access Manager plug-infor web servers. Also, specifies whether to run plug-in for web servers as adaemon or run it in the foreground.


Note: When you use Windows Remote Desktop Connection, you must run theplug-in as a service.

Parameters

–foregroundRuns the Plug-in for the binary file of the web server in the foreground asopposed to running it as a daemon. (Optional)

–versionSpecifies the version information for the plug-in for web serversinstallation. (Optional)

Availability

This utility is in the following default installation directories:v On AIX, Linux, and Solaris operating systems:

/opt/pdwebpi/bin

v On Windows operating systems:C:\Program Files\Tivoli\pdwebpi\bin


Return codes



pdwebpi_startControls the plug-in for web servers processes in AIX, Linux, and Solarisinstallations independently of Security Access Manager.

Syntax

pdwebpi_start start

pdwebpi_start stop

pdwebpi_start restart

pdwebpi_start status

Description

The pdwebpi_start utility starts, stops, restarts, or displays the status of the plug-infor web servers process in an AIX, Linux, or Solaris environment.

Note: To control the plug-in process in a Windows environment, use the ServicesControl Panel.


Parameters

restart Stops and restarts the plug-in process.

start Starts the plug-in process.

status Returns status information about the plug-in process.

stop Stops the plug-in process.

Availability

By default on AIX, Linux, and Solaris operating systems, this utility is in the/opt/pdwebpi/sbin directory.

When an installation directory other than the default is selected, this utility is inthe /sbin directory under the installation directory (for example, installationdirectory/sbin).

Return codes


1 An error occurred.

pdwpi-versionLists the version and copyright information for plug-in for web servers.

Syntax

pdwpi-version [–h] [–V] [–l|binary [binary ...]]

Parameters

–h Displays a help or usage message. (Optional)

–l Specifies the long list version of all installable files, not just the packageversion. (Optional)

–V Displays the version information for the pdwpi-version installable file.(Optional)

binary [binary]Displays version information for the specified installable files. If noinstallable file is specified, displays all files. (Optional)

Availability


/opt/pdwebpi/bin




Return codes


1 An error occurred.

pdwpicfgConfigures or unconfigures the plug-in for web servers.

Syntax

pdwpicfg –action config –admin_id admin_id –admin_pwd password [–auth_portport_number] [–web_server {iis|ihs|apache}] [–iis_filter {yes|no}]–web_directory installation_directory –vhosts virtual_host_id [–ssl_enable{yes|no}] [–keyfile keyfile] [–key_pwd password] [–key_label label] [–ssl_portport_number]

pdwpicfg –action config –interactive {yes|no}

pdwpicfg –action config –rspfile response_file

pdwpicfg –action unconfig –admin_id admin_id –admin_pwd password –force{yes|no} [–remove {none|acls|objspace|all}] –vhosts virtual_host_id

pdwpicfg –action unconfig –interactive {yes|no}

pdwpicfg –operations

pdwpicfg –help [options]

pdwpicfg –usage

pdwpicfg –?

Parameters

–? Displays the syntax and an example for this utility. (Optional)

–action {config|unconfig}Indicates the action to take. This parameter takes one of the followingvalues:

config Configures the Security Access Manager plug-in for web servers.

unconfigUnconfigures the Security Access Manager plug-in for web servers.

–admin_id admin_idSpecifies the administration user identifier (the administrative user isnormally sec_master).

–admin_pwd passwordSpecifies the password for the administrative user.

–auth_port port_numberSpecifies the port number of the authorization server. The default value is7237. (Optional)


–help [options]Lists the name of the parameter and a short description. If one or moreoptions are specified, it lists each parameter and a short description.(Optional)

–interactive {yes|no}Enables interactive mode for the utility if yes; otherwise, disablesinteractive mode for the utility. The default value is yes. (Optional)

–iis_filter {yes|no}Enables the Internet Information Server (IIS) filtering if yes; otherwise,disables the IIS filtering. (Optional)

–keyfile keyfileSpecifies the LDAP SSL key file. There is no default value. Specify thisparameter when:v You are not running the utility in interactive mode.v You enabled SSL between the plug-in for web servers and LDAP.

(Optional)

–key_label labelSpecifies the LDAP SSL key label. There is no default value. Specify thisparameter when:v You are not running the utility in interactive mode.v You enabled SSL between the plug-in for web servers and LDAP.

(Optional)

–key_pwd passwordSpecifies the LDAP SSL key file password. (Optional)

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

–remove {none|acls|objspace|all}Specifies whether to remove the object space or the ACLs or both as partof the unconfiguration process. The default value is none. (Optional)


–ssl_enable {yes|no}Enables SSL communications with LDAP if yes; otherwise, disables SSLcommunications with LDAP. The default value is yes. (Optional)

–ssl_port port_numberSpecifies the LDAP SSL port. The default value is 636. (Optional)

–usage Displays the syntax and an example for this utility. (Optional)

–vhosts virtual_host_idSpecifies the identifiers of the virtual hosts to protect. The value must be inthe format of a comma-separated list of virtual host IDs. There must be nospaces between the virtual host IDs.


–web_directory installation_directorySpecifies the web server installation directory.

–web_server {iis|ihs|apache}Specifies the web server type on which the plug-in for web servers is to beinstalled. This parameter defaults to the type and location of theconfigured web server. (Optional) The following choices are supported:

ihs For IBM HTTP Server

iis For Internet Information Server

apacheFor the Apache Server

Availability


/opt/pdwebpi/bin



Return codes



query_contentsReturns the contents of the root directory of a web space on a third-party webserver.

Syntax

query_contents

Description

Returns the contents of the specified web space on a third-party web server. Thecontents are used to construct a protected object space for use by Security AccessManager administrators.

The query_contents utility is distributed with WebSEAL. The typical usage of theutility is to copy it to a junctioned web server and run it there. The utility returns alist of the hierarchy of files that must be protected by Security Access Manager.This list enables the Security Access Manager administrative GUI (Web PortalManager) to display to the administrator a list of resources to be managed.


The utility is provided on AIX, Linux, and Solaris operating systems as a shellscript, query_contents.sh. On Windows operating systems, it is provided as aquery_contents.exe executable file. WebSEAL also includes source to the utility, asample configuration file, and an HTML help file. Administrators can use thesefiles to configure query_contents and, when needed, to modify its behavior.

Administrators must review the documentation on WebSEAL junctions andquery_contents before running this utility. For more information, see the IBMSecurity Access Manager for Web WebSEAL Administration Guide.

Parameters

None.

Availability


/opt/pdweb/query_contents

v On Windows operating systems:c:\Program Files\Tivoli\pdweb\query_contents

Return codes



Example

This example displays the contents of a web space hierarchy.http://server_name/cgi-bin/query_contents?dirlist=/

smsbackupGathers information to help IBM Software Support in problem determination.


Syntax

For local modesmsbackup –local [–was_home path] [–list list] [–path output]

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

Description

The 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 AIX, Linux, and Solaris operating systems as a shellscript, smsbackup.sh. On Windows operating systems, it is provided as a batchscript, smsbackup.bat.

When the utility runs in local mode, you must copy the following files to eachmember 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. (Optional)

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

–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. (Optional)

–wsadmin_options optionsSpecifies options to pass directory to the wsadmin utility. Use this parameterto pass non-default binding information before the backup operation runsthrough the WebSphere cluster. Examples of non-default bindinginformation include the user name and password. (Optional)

Availability


/opt/pdsms/bin




Return codes



smscfgDeploys and configures the session management server.

Syntax

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

Configurationsmscfg –action config [–interactive {yes|no}] [–rsp_file 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] [–keyfilefile_name] [–key_pwd password] [–instance instance_name] [–session_realmrealm:max_login=replica_set1_name,replica_set2_name,...][–session_realm_remove realm_name] [–enable_tcd {yes|no}] [–tcdfully_qualified_directory_name] [–enable_sam_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_idadministrator_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][–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] [–keyfilefile_name] [–key_pwd password] [–instance instance_name][–enable_database_storage {yes|no}][–database_namedatabase_name][–virtual_host host_name] [–clustered {yes|no}] [–was_nodenode_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] [–keyfilefile_name] [–key_pwd password] [–instance instance_name]

Extractsmscfg –action extract [–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] [–keyfilefile_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] [–keyfilefile_name] [–key_pwd password] [–instance instance_name]

Revertsmscfg –action revert [–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] [–keyfilefile_name] [–key_pwd password] [–instance instance_name]

Utility helpsmscfg –help option

smscfg –usage

smscfg –?

Description

The 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 fix pack upgrades.

A log of the configuration progress is written to msg_smscfg.log log file. This logfile is in:v The /var/pdsms/log directory on AIX, Linux, and Solaris operating systems.v The installation_directory\log directory on Windows operating systems.

This utility can be run in one of these ways:v Interactively – the user is prompted to provide configuration information.


v Silently – the utility accepts input from a response file.

Parameters

–? Displays the syntax and an example for this utility. (Optional)

–action {deploy|config|unconfig|undeploy|extract}Specifies the action 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.

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 fix pack.

revert Reverts to the previous session management server fix pack.

–admin_id administrator_idSpecifies the Security Access Manager administration ID. The default valueis sec_master. This parameter is required when –enable_sam_integrationis set to yes. (Optional)

–admin_pwd passwordSpecifies the password for the Security Access Manager administrator. Thisparameter is required when you specify the –admin_id parameter.(Optional)

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

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

A Security Access Manager authorization server is required to use either ofthese functionalities:v Session refresh capabilitiesv Certificates that are issued by the Security Access Manager policy server

to authenticate session management clients

The default value is localhost:7136:1. (Optional)

–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. (Optional)


–clustered {yes|no}Whether the application is deployed to a WebSphere cluster. The defaultvalue is no. (Optional)

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

–database_name databaseSpecifies the name of the WebSphere JDBC data source. The sessionmanagement server uses this data source to access the database where theserver stores its data. There is no default value. (Optional)

–domain domainSpecifies the name of the Security Access Manager policy domain. Thisparameter is required when –enable_sam_integration is set to yes. Thedefault value is Default. (Optional)

–enable_auditing {yes|no}Indicates whether auditing is required. The default value is no. (Optional)

–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. (Optional)

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

–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 you installinto a stand-alone application server. When you install into a cluster thisfield is not required. (Optional)

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

–enable_tam_integration {yes|no}Indicates whether to enable integration with Security 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. (Optional)


–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.(Optional)

–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.(Optional)

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

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

–key_lifetime lifecycleSpecifies the lifetime in seconds of the key for the session managementserver. After the defined lifecycle completes, a new key is generated. If thisvalue is set to zero, keys are not automatically generated. (Optional)

–key_pwd passwordSpecifies the password to access the server-side certificates. This parameteris required when you specify the –keyfile parameter. (Optional)

–keyfile file_nameSpecifies the fully qualified name for the keystore when a secureconnection is made to WebSphere Application Server. The keystore holdsthe server-side certificates. This parameter is required when you specifythe –was_admin_id parameter. (Optional)

–last_login_jsp server_jsp_nameThe server-side path for the last login JSP file. server_jsp_name is anoptional argument. (Optional)

–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. (Optional)

Note: Configuration of the lastLogin.jsp file can produce a long webbrowser URL, which can exceed the limits that are imposed by some proxyservers. Access the WebSphere ISC by using a direct connection to theInternet.

–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 when you install into astand-alone application server. When you install into a cluster, this field isnot required. (Optional)

–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.(Optional)


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

–policysvr_host host_nameSpecifies the host name of the Security Access Manager policy server. Thisparameter is required when –enable_sam_integration is set to yes.(Optional)

–policysvr_port portSpecifies the port of the Security Access Manager policy server. Thisparameter is required when you specify the –host parameter. (Optional)

–record file_nameSpecifies the name of the response file to which configuration parametersare recorded. (Optional)

–remove_last_login_db {yes|no}Indicates whether the last login database must be removed. The defaultvalue is no. (Optional)

–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 key=value pairs. For information about using response files, see the"Using response files" appendix in the IBM Security Access Manager for Web:Command Reference. (Optional)

–session_realm [realm[:max_logins]=replica_set1, replica_set2,...]Specifies a session realm to add to the configuration. If the session realmname or any of the replica set names contain spaces, the entire argumentmust be specified within quotation marks.

The max_logins parameter is used to specify the maximum number ofconcurrent login events that are permitted for the session realm. If themax_logins parameter is not supplied, there are an unlimited number ofconcurrent login events that are allowed for the session realm.

Replica set names must be separated by commas. (Optional)

–session_realm_remove realm=set_name[,...][;realm=set_name[,...]...]Specifies the name of a session realm to remove. If the session realm namecontain spaces, the entire argument must be specified within quotationmarks. (Optional)

–tcd path_nameSpecifies the fully qualified directory for Tivoli Common Directory logging.This parameter is required when –enable_tcd is set to yes. If the TivoliCommon Directory is configured on the target system, this option isignored. (Optional)

–trust_store file_nameSpecifies the fully qualified name for the truststore when a secureconnection is made to WebSphere Application Server. The truststore holdsthe client-side certificates. This parameter is required when you specify the–was_admin_id parameter. (Optional)

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


–usage Displays the syntax and an example for this utility. (Optional)

–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. (Optional)

–was_admin_id administrator_idSpecifies the name of the administrator to use when a secure connection ismade to WebSphere Application Server. In interactive mode, this parameteris optional unless you are making a secure connection. When you use thisparameter, you must specify the –was_admin_pwd parameter. When notmaking a secure connection, this parameter is optional. (Optional)

–was_admin_pwd passwordSpecifies the password to use when a secure connection is made toWebSphere Application Server. The administrator can use this password.(Optional)

–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. (Optional)

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

The application is deployed to that server when you are using WebSphereNetwork Deployment and:v –was_cluster is specified.v There is no cluster.v There is only one 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. (Optional)

–was_node node_nameSpecifies the name of the WebSphere node. (Optional)

–was_port portSpecifies the SOAP port to use on the WebSphere server. This parameter isalways 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. (Optional) The application is deployed to theserver to which this configuration utility is connected when:v WebSphere Application Server is in a single server deployment, and


v –was_server is not specified.

Availability


/opt/pdsms/bin



Return codes



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


Syntax

smsservicelevel [directory [directory] ...] [file [file] ...]

Description

The smsservicelevel utility recursively scans the specified directory. The utilityreturns to the standard output device the name and service level for sessionmanagement server files. The files match Security Access Manager conventions.

The utility is provided on AIX, Linux, and Solaris operating systems as a shellscript, smsservicelevel.sh. On Windows operating systems, it is provided as abatch script, smsservicelevel.bat.

Parameters

directorySpecifies the directories that the utility searches for service levelinformation. (Optional)

files Specifies particular files that the utility searches. (Optional)


Availability


/opt/pdsms/bin



Return codes



svrsslcfgConfigures, unconfigures, or modifies the configuration information of a resourcemanager to use an SSL connection for communicating with the policy server.

This utility is used for C application servers only. For Java application servers, usethe equivalent com.tivoli.pd.jcfg.SvrSslCfg Java class. For information aboutthis Java class, see the IBM Security Access Manager for Web Authorization JavaClasses Developer Reference.

Syntax

svrsslcfg –add_replica –f cfg_file –h host_name [–p server_port] [–kreplica_rank] [–rspfile response_file]

svrsslcfg –chg_replica –f cfg_file –h host_name [–p server_port] [–kreplica_rank] [–rspfile response_file]

svrsslcfg –chgcert –f cfg_file –P password [–A admin_id] [–rspfileresponse_file]

svrsslcfg –chgport –f cfg_file –r port_number [–rspfile response_file]

svrsslcfg –chgpwd –f cfg_file –e password_life [–rspfile response_file]

svrsslcfg –config –f cfg_file –d kdb_dir –s server_mode–r port_number –Ppassword [–S password] [–A admin_id] [–t ssl_timeout] [–e password_life] [–llistening_mode] [–a refresh_mode] [–C cert_file] [–h host_name] [–o login_domain][–g group_list] [–D description] [–rspfile response_file]

svrsslcfg –modify –f cfg_file [–t ssl_timeout] [–C cert_file] [–llistening_mode] [–rspfile response_file]


svrsslcfg –rmv_replica –f cfg_file –h host_name [–rspfile response_file]

svrsslcfg –unconfig –f cfg_file –n appl_name –P password [–A admin_id] [–hhost_name] [–o login_domain] [–rspfile response_file]

Parameters

–a refresh_modeSets the certificate and key file password auto-refresh entry in theconfiguration file. The default value is yes. (Optional)

–A admin_idSpecifies the name of the Security Access Manager administrator. Thedefault value is sec_master. (Optional)

A valid administrative ID is an alphanumeric, case-sensitive string. Stringvalues are expected to be characters that are part of the local code set. Youcannot use a space in the administrative ID.

For example, for US English, the valid characters are the letters a-Z, thenumbers 0-9, a period (.), an underscore (_), a plus sign (+), a hyphen (-),an at sign (@), an ampersand (&), and an asterisk (*). If there are limits, theminimum and maximum lengths of the ID are imposed by the underlyingregistry. See the information about user registry differences in the IBMSecurity Access Manager for Web Installation Guide.

–add_replicaAdds an authorization server replica to the configuration of a resourcemanager. A resource manager can contact a replica server for authorizationdecisions.

-C cert_fileSpecifies the fully qualified name of the file that contains the base-64encoded SSL certificate that is used when the server authenticates directlywith the user registry. (Optional)

–chg_replicaChanges attributes for the replica server. The replica host name is used toidentify the replica server and cannot be changed by this action.

–chgcertRenews the SSL certificate of the resource manager. Before you run thisaction, ensure that the policy server is running.

The certificate renewal process is as follows:v When an initial request for a certificate is made, a new public/private

key pair is generated for the resource manager along with the certificaterequest. The certificate request that contains the new public key for theresource manager is sent to the Security Access Manager policy server.The policy server signs the request and sends the newly signedcertificate back to the resource manager. The resource manager stores thesigned certificate in a secure keystore and also stores the new privatekey for the resource manager.The lifetime of the new certificate is determined by the policy serverssl-cert-life entry in the ivmgrd.conf configuration file. Thisparameter determines the number-of-days value for the lifetime of acertificate. Any issued or renewed certificates must use this value. Thedefault value is 1460.

v The certificate for a resource manager must be renewed if it expired or ifit was compromised. Also, the certificate must be renewed to adhere to


any changes in the security policy. If both the certificate and thepassword to the key database file that contains the certificate expire, thepassword must be refreshed first.

–chgportChanges the listening port for a resource manager. Before you run thisaction, ensure that the policy server is running.

–chgpwdChanges the key file password for a resource manager. Before you run thisaction, ensure that the policy server is running.

–configConfigures a resource manager.

–D descriptionSpecifies a description for the application. A valid description is analphanumeric string that is not case-sensitive. String values are expected tobe characters that are part of the local code set. Spaces are allowed. If thedescription contains a space, ensure that you enclose the description indouble quotation marks. (Optional)

–d kdb_dirSpecifies the directory that is to contain the key files for the server. A validdirectory name is determined by the operating system. Do not use relativedirectory names. For example:

On AIX, Linux, and Solaris operating systems/opt/PolicyDirector/keytab/ivmgrd.kdb

On Windows operating systemsC:\Program Files\Tivoli\Policy Director\keytab\ivmgrd.kdb

Make sure that the server user or all users have permission to access the.kdb file and the folder that contains the .kdb file. Example of a server useris ivmgr.

–e password_lifeSets the key file password expiration time in days. This parameter isrequired.v Specify 0 to use the currently configured value.v Specify 183 days if the currently configured value cannot be determined.v Otherwise, valid values are from 1 to 7299.

During a configuration action, such as –config, the default value is 183.

–f cfg_fileSpecifies the configuration path and file name. A file name must be anabsolute file name (fully qualified file name) to be valid. For example:

On AIX, Linux, and Solaris operating systems/opt/PolicyDirector/etc/activedir.conf

On Windows operating systemsC:\Program Files\Tivoli\Policy Director\etc\activedir.conf

–g group_listSpecifies a list of groups to which this server must be added. Thefollowing names are not supported in this list: ivacld_servers andremote_acl_users. The list of names must be separated by commas with noempty space. If a group name contains a space, the entire list must beenclosed in double quotation marks. (Optional)


–h host_nameFor a configuration action (–config) or an unconfiguration action(–unconfig), specifies the TCP host name that is used by the policy serverto contact this server.v During a configuration action, this name is saved in the configuration

file by using the azn-app-host key. The default is the local host namethat is returned by the operating system.

v If not specified during an unconfiguration action, the value is retrievedfrom the configuration file. The default value is used only if a valuecannot be determined from the configuration file. The default is the localhost name that is returned by the operating system.

For all other actions, specifies the TCP host name of an authorizationserver replica.

Valid values include any valid IP host name. Examples:host = librahost = libra.dallas.ibm.com

–k replica_rankSpecifies the replica order of preference among other replicas. Replicaservers with higher ranks are used preferentially. For example, a resourcemanager contacts a replica server with a ranking of 10 before it contacts areplica server with a ranking of 9. The default value is 10. (Optional)

–l listening_modeSets the listening-enabled entry in the configuration file. The value must beyes or no. If not specified, the default is no. A value of yes requires that the–r parameter has non-zero value. (Optional)

–modifyChanges the current configuration of a resource manager. Before you runthis action, ensure that the policy server is running.

This action fails only if you are not authorized to run the utility or thepolicy server cannot be contacted. This action is designed to clean up apartial or damaged configuration. The action also ensures that errors arenot reported for information that is not valid and that is missing.

–n appl_nameSpecifies the name of the application. The name is combined with the hostname to create unique names for Security Access Manager objects that arecreated for your application. The following names are reserved for SecurityAccess Manager applications: ivacld, secmgrd, ivnet, and ivweb.

–o login_domainSpecifies the domain name for the domain to which this server isconfigured. This domain must exist and an administrator ID and passwordmust be valid for this domain. (Optional)

If not specified, the local domain that is specified during IBM SecurityAccess Manager runtime configuration is used. The local domain value isretrieved from the configuration file.

A valid domain name is an alphanumeric, case-sensitive string. Stringvalues are expected to be characters that are part of the local code set. Youcannot use a space in the domain name.

For example, for US English the valid characters for domain names are theletters a-Z, the numbers 0-9, a period (.), an underscore (_), a plus sign (+),a hyphen (-), an at sign (@), an ampersand (&), and an asterisk (*). The


minimum and maximum lengths of the domain name, if there are limits,are imposed by the underlying registry. See the topic about user registrydifferences in the IBM Security Access Manager for Web Installation Guide.

–p server_portSpecifies the port number on which the replica server listens for requests.The default value is 7136. (Optional)

–P passwordSpecifies the password for the Security Access Manager administrator user(admin_id). If this parameter is not specified, the administrator isprompted, and the password is read from standard input (stdin).

–r port_numberSets the listening port number for the server. A value of 0 can be specifiedonly if the [aznapi-admin-services] stanza in the configuration file isempty.

During a configuration action, such as –config, this parameter is required.

–rmv_replicaRemoves an authorization server replica from the configuration of aresource manager.


–s server_modeSpecifies the mode in which the application operates. This value must beeither local or remote.

–S passwordSpecifies the server password. This parameter is required. A password iscreated by the system and the configuration file is updated with thepassword created by the system. It is saved as an obfuscated value byusing the pd-user-pwd stanza entry in the [aznapi-configuration] stanzain the configuration file that is specified with the –f parameter. If thisparameter is not specified, the server password is read from standardinput.

–t ssl_timeoutSpecifies the SSL session timeout in seconds. The value must be in therange 1 - 86400. The default value is 7200. (Optional)

–unconfigUnconfigures a resource manager. The key files are deleted, and the serveris removed from the user registry and Security Access Manager database.

Before you run this utility, start the server application.

Note: If you run svrsslcfg with an appsrv_id and host parameter with acombined length that exceeds 64 bytes, svrsslcfg truncates the appsrv_id portion ofthe name. This scenario happens when you create the account in an ActiveDirectory registry.


Availability



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


Return codes




Appendix A. Password limitations and characters allowed inobject names

When you specify Security Access Manager user names, group names,distinguished names, POP names, ACL policies, authorization rules, and domainnames, certain characters might be disallowed.

Some factors that affect which characters are allowed are restrictions of theunderlying user registry, server, or operating system.

This section describes the following limitations:v “General password policies”v “Character limitations for passwords and user names” on page 308v “Characters allowed for secure domain names” on page 308v “Characters disallowed for user and group name” on page 309v “Characters disallowed for distinguished names” on page 310v “Characters disallowed for GSO names” on page 311v “Characters disallowed for authorization rule names” on page 311v “Characters disallowed for ACL policy names” on page 312v “Characters disallowed for POP names” on page 313

General password policiesYou can change global user settings, such as password policies, login-failurepolicies, access policies, and account expiration policies. Additionally, you canoverride global password policies by setting individual password policies for thespecified user.

For example, you can change a password policy so that the password policy:v Is set only for a specific user.v Overrides any password policy that is set globally for all users.

Using Web Portal Manager or the pdadmin commands, you can provide thefollowing types of global password policies for all users:v Minimum length that is allowed for a passwordv Maximum age that is allowed for a passwordv Minimum number of alphanumeric characters that are allowed in a passwordv Minimum number of non-alphanumeric characters that are allowed in a

passwordv Maximum number of repeated characters that are allowed in a passwordv Whether spaces are allowed in the password

By default, passwords must meet the following criteria:v A minimum of eight alphanumeric characters, with a minimum of one number

and four letters.v A maximum of two repeated characters.


The valid range for minimum and maximum numbers can be any number.However, a reasonable number must be used for the task you are wanting tocomplete. For example, a minimum password length must:v Be long enough to protect your system.v Not be so short as to make it easy for someone to determine your password by

trying different combinations.

Character limitations for passwords and user namesThere are password characters that are valid, but must be treated differently whenyou run the pdadmin utility. These special characters have special meaning to theutility.

Enclose the password or user name in double quotation marks (") to escape thespecial character when:v Setting or changing user passwords by using user modify.v Logging in using login.

Otherwise, you receive an error message.

To escape the double quotation mark special character, enclose the password oruser name in double quotation marks and use the backward slash (\) escapecharacter. For example, to escape the password abc"123, type the string "abc\"123"in the pdadmin command when you type the password by using the –p option.When the interactive login command is used, no double quotation marks andescape character are needed.

The following special characters either must not be used or they must be escapedwhen using the pdadmin command:v Comma (,)v Double quotation (")v Left parenthesis (()v Number sign (#)v Right parenthesis ())

Avoid the use of these characters as the first character in the password whensetting or modifying the password with the user modify command:v Hyphen (-)v Left brace ({)v Number sign (#)

Characters allowed for secure domain namesA valid local domain name is an alphanumeric, case-sensitive string. Stringcharacters are expected to be characters that are part of the local code set.

The following characters, numbers, and special characters can be used for securedomain names during use of the pdadmin commands or Web Portal Manager.

For example, for US English, secure domain names can contain a combination ofthe following characters:v Letters (a-z A-Z)v Numbers (0–9)v Ampersand (&)v Asterisk (*)


v At sign (@)v Hyphen (-)v Period (.)v Plus sign (+)v Underscore (_)

You cannot use a space in the domain name. The minimum and maximum lengthsof the domain name, if there are limits, are imposed by the underlying registry. Seethe section on user registry differences in the IBM Security Access Manager for WebInstallation Guide.

Characters disallowed for user and group nameEnvironment aspects such as registries and command shells can affect specialcharacter handling. Because of the variability of special character handling ingeneral, avoid the use of special characters.

Avoid the following character in user and group names that are defined by usingdistinguished name strings:v Forward slash (/)

If Microsoft Active Directory is the user registry, care must be taken with usernames and group names that contain the following character:v Period (.)

A period (.) cannot be the last character of a user or group short name; forexample:jdoe and jdoe.@my_ad_domain.com are invalid user names.

If Microsoft Active Directory is the user registry, user names and group names cancontain all Unicode characters except for the following characters:v Asterisk (*)v At sign (@)v Colon (:)v Equal sign (=)v Forward slash (/)v Left square bracket ([)v Question mark (?)v Right square bracket (])v Vertical bar (|)v Backward slash (\)v Double quotation (")v Left angle bracket (<)v Right angle bracket (>)v Plus sign (+)v Semicolon (;)

Note: An at sign (@) is not allowed unless it is used to specify the domain. Forexample, [email protected] is allowed; user@[email protected] is not allowed.

The following characters are accepted in LDAP:v Comma (,)v Plus sign (+)v Double quotation (")

Appendix A. Password limitations and characters allowed in object names 309

Note: Add a prefix with a backward slash (\) to escape any double quotationcharacter in the user name.

v Backward slash (\)v Left angle bracket (<)v Right angle bracket (>)v Semicolon (;)

If you use special characters with the pdadmin utility, enclose each argument of theuser or group command with double quotation marks. The double quotationmarks allow the argument to be entered without being subject to interpretation bythe operating system shell command processor.

Because of the variability of special character handling in general, avoid the use ofspecial characters.

Characters disallowed for distinguished namesCertain characters are treated differently by the different user registries.

In general, you can use special characters within a distinguished name (DN).However, certain special characters require an additional escape character. Thefollowing special characters must be escaped when used in a distinguished name:v Comma (,)v Plus sign (+)v Semicolon (;)

Because of differences in registries and command shell processors, avoid thebackward slash (\) character in distinguished names.

Characters disallowed for Microsoft Active Directorydistinguished names

If Microsoft Active Directory is the user registry, certain special characters are notallowed in a distinguished name (DN). However, if the character is preceded by anadditional escape character or is encoded in hexadecimal, then, it is allowed in aDN.

To encode in hexadecimal, replace the character with a backward slash (\)followed by two hexadecimal digits.

The following characters must be escaped by using the backward slash (\)character before they are used in a distinguished name:v Number sign (#) at the beginning of the stringv A space at the end of the stringv Comma (,)v Double quotation (")v Left angle bracket (<)v Plus sign (+)v Right angle bracket (>)v Semicolon (;)

Because of differences in registries and command shell processors, avoid thebackward slash (\) character in distinguished names.


For other reserved characters, such as an equal sign (=), asterisk (*), or anon-UTF-8 character, the character must be encoded in hexadecimal.

Example 1To create a user with a distinguished name that contains a comma next tothe separator:pdadmin sec_master> user create "johndoe""cn=doe\,john,cn=users,dc=mydomain,dc=com" John Doe password1

Example 2To create a user with a distinguished name that contains a carriage return,which is a reserved character:pdadmin sec_master> user create "johndoe""cn=doe\ODJohn,cn=users,dc=mydomain,dc=com" John Doe password1

The hexadecimal representation of a carriage return is 0D.

Example 3To create a user with a distinguished name that contains a number sign (#):pdadmin sec_master>user create "#pounduser""cn=\#pounduser,cn=users,dc=mydomain,dc=com" "#pound" "user"password1

Characters disallowed for GSO namesCertain characters are disallowed for GSO names.

You cannot use the following characters to create a global sign-on (GSO) username, GSO resource name, or GSO resource group name:v Asterisk (*)v At sign (@)v Backward slash (\)v Colon (:)v Comma (,)v Double quotation (")v Equal sign (=)v Exclamation point (!)v Left angle bracket (<)v Left parenthesis (()v Plus sign (+)v Number sign (#)v Right angle bracket (>)v Right parenthesis ())v Semicolon (;)v Vertical bar (|)

It is possible to use most of these characters for other LDAP-related data. However,these characters have special meaning in LDAP DN syntax and filters. Examples ofother LDAP-related data are: common name (CN), distinguished name (DN), andshort name (SN) of a user.

Before you use any of these characters in user and group names, consult thedocumentation for your user registry to determine the effect of special characters.

Characters disallowed for authorization rule namesCertain characters are disallowed for authorization rule names.


These characters cannot be used in the name of an authorization rule when youuse the pdadmin commands or Web Portal Manager:v Ampersand (&)v Asterisk (*)v At sign (@)v Backward slash (\)v Colon (:)v Comma (,)v Double quotation (")v Equal sign (=)v Exclamation point (!)v Left angle bracket (<)v Left parenthesis (()v Plus sign (+)v Number sign (#)v Right angle bracket (>)v Right parenthesis ())v Semicolon (;)v Vertical bar (|)

A valid authorization rule name is an alphanumeric string that is notcase-sensitive. String values are expected to be characters that are part of the localcode set. Spaces are not allowed.

Characters disallowed for ACL policy namesCertain characters are disallowed for ACL policy names.

These characters cannot be used in the name of an access control list (ACL) policywhen you use the pdadmin commands or Web Portal Manager:v Ampersand (&)v Asterisk (*)v At sign (@)v Backward slash (\)v Colon (:)v Comma (,)v Double quotation (")v Equal sign (=)v Exclamation point (!)v Forward slash (/)v Left angle bracket (<)v Left parenthesis (()v Period (.)v Plus sign (+)v Number sign (#)v Right angle bracket (>)v Right parenthesis ())v Semicolon (;)v Vertical bar (|)

A valid ACL policy name is an alphanumeric string that is not case-sensitive.String values are expected to be characters that are part of the local code set.Spaces are not allowed.


Characters disallowed for POP namesCertain characters are disallowed for POP names.

Avoid the use of the following characters in the name of a protected object policy(POP) when you use the pdadmin commands or Web Portal Manager:v Ampersand (&)v Asterisk (*)v At sign (@)v Backward slash (\)v Colon (:)v Comma (,)v Double quotation (")v Equal sign (=)v Exclamation point (!)v Forward slash (/)v Left angle bracket (<)v Left parenthesis (()v Period (.)v Plus sign (+)v Number sign (#)v Right angle bracket (>)v Right parenthesis ())v Semicolon (;)v Vertical bar (|)

A valid POP name is an alphanumeric string that is not case-sensitive. Stringvalues are expected to be characters that are part of the local code set. Spaces arenot allowed.

Note: Although a POP name can contain 1 or more of these characters, the resultsof using such a POP are undefined.


Appendix B. Using response files

A response file is a text file that contains product and system information,sometimes used in configuration.

Some utilities can be run in either command-line mode or response file mode.v In command-line mode, all parameters must be specified from the command

line.v In response file mode, the utility obtains the necessary parameters from the

response file. You must manually create the response file by entering allparameters.

Within response files, stanza labels display within brackets, such as [stanza-name].Each stanza in a Security Access Manager response file contains one or more keyvalue pairs. Key value pairs express information as a paired set of parameters.Each stanza entry is a key-value pair in the following format:key = value

In the response file, the key is equal to the parameter in command-line mode. Thefollowing example shows that when there is a -parameter specified incommand-line mode, the key in response file mode is the same, but without thepreceding dash.

Examplesv The following example uses the /tmp/rspfile/cars_pdacld.rsp response file to

configure an audit server by using SSL and password authentication:amauditcfg –rspfile /tmp/rspfile/cars_pdacld.rsp

The /tmp/rspfile/cars_pdacld.rsp response file contains the following data:[amauditcfg]action = configsrv_cfg_file = /opt/PolicyDirector/etc/ivacld.confaudit_srv_url = https://hostname:9443/CommonAuditService/services/Emitterenable_ssl = yesaudit_key_file = /certs/WSclient.kdbaudit_stash_file = /certs/WSclient.sthenable_pwd_auth = yesaudit_id = administrator_idaudit_pwd = password

v In contrast, the following example uses command-line mode to configure anaudit server by using SSL and password authentication:amauditcfg -action config \

-srv_cfg_file /opt/PolicyDirector/etc/ivacld.conf \-audit_srv_url https://hostname:9443/CommonAuditService/services/Emitter \-enable_ssl yes -audit_key_file /certs/WSclient.kdb \-audit_stash_file /certs/WSclient.sth -enable_pwd_auth yes \-audit_id administrator_id -auditpwd password


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 reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not 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:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan, Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, 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.

All IBM prices shown are IBM's suggested retail prices, are current and are subjectto change without notice. Dealer prices may vary.

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 to


IBM, 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 notbeen 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.

Trademarks

IBM, the IBM logo, and ibm.com® are trademarks or registered trademarks ofInternational Business Machines Corp., registered in many jurisdictions worldwide.Other product and service names might be trademarks of IBM or other companies.A current list of IBM trademarks is available on the Web at "Copyright andtrademark information" at www.ibm.com/legal/copytrade.shtml.

Adobe, Acrobat, PostScript and all Adobe-based trademarks are either registeredtrademarks or trademarks of Adobe Systems Incorporated in the United States,other countries, or both.

IT Infrastructure Library is a registered trademark of the Central Computer andTelecommunications Agency which is now part of the Office of GovernmentCommerce.

Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo,Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks orregistered trademarks of Intel Corporation or its subsidiaries in the United Statesand other countries.

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.

ITIL is a registered trademark, and a registered community trademark of the Officeof Government Commerce, and is registered in the U.S. Patent and TrademarkOffice.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Cell Broadband Engine and Cell/B.E. are trademarks of Sony ComputerEntertainment, Inc., in the United States, other countries, or both and is used underlicense therefrom.

Notices 319

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Oracle and/or its affiliates.


Index

Aaccess control list (ACL) commands

acl attach 21acl create 22acl delete 23acl detach 24acl find 25acl list 26acl modify 26acl show 30

access control lists 242accessibility xiiiACL policy names

disallowed characters 312action

group create 34group delete 34group list 35

action commandsaction create 31action delete 33action group create 34action group delete 34action group list 35action list 35

adschema_update utility 212allowed character

secure domain names 308amauditcfg utility 213amwebcfg utility 217amwpmcfg utility 221attach

access control list (ACL) 21protected object policy (POP) 90

auditingconfiguring 213starting 213stopping 213

authorization commandsattach

authzrule 37authzrule

attach 37create 38delete 39detach 40find 40list 41modify 42show 43

createauthzrule 38

deleteauthzrule 39

detachauthzrule 40

findauthzrule 40

listauthzrule 41

authorization commands (continued)modify

authzrule 42show

authzrule 43authorization rule names

disallowed characters 312authorization server 230, 232

Bbassslcfg

change password 226configure 226get certificate 226get management domain 226modify 226ping server 226

bassslcfg utility 226

Ccaches, flushing HTML document 120CARS 213cdsso_key_gen utility 229character limitations

passwords 308user names 308

commandaccess control 10access control list 10action 10action commands 10authorization

rule 11authorization rule commands 11category 9configuration 11configuration commands 11context 12context commands 12domain 12domain commands 12group 12group commands 12list 10, 11, 12, 13, 14, 15, 16, 17, 18login 13login and logout commands 13logout 13object 13object commands 13object space 14object space commands 14policy 14policy commands 14POP 15protected object policy 15protected object policy (POP)

commands 15

command (continued)resource commands

list 15resource credential commands

list 15resource group commands

list 15server 16server commands 16server task

Session Management Server 17server task commands

Session Management Server 17WebSEAL 19

user 18user commands 18

user create 18user delete 18user import 18user list 18user modify 18user show 18

command modesinteractive 4multiple 5single 4

command option processing 9Common Audit Web service

configuring 213unconfiguring 213

config commandsmodify 44show 46

configuresmscfg utility 293

context commandsshow 48

createaccess control list (ACL) 22actions 31domain commands 49group 56object 69object space 81protected object policy (POP) 91rsrc 99rsrccred 102rsrcgroup 108user 197

credentialsrefreshing, WebSEAL 139

DDB2 xiidelete

access control list (ACL) 23actions 33domain commands 51group 57object 71


delete (continued)objectspace command 82protected object policy (POP) 92rsrc 100rsrccred 104rsrcgroup 109user 199

detachaccess control list (ACL) 24protected object policy (POP) 92

disallowed characterACL policy names 312authorization rule names 312distinguished names 310group names 309GSO names 311POPs 313user names 309

distinguished namesdisallowed characters 310

doAudit stanza entry 213document cache, HTML flushing 120domain

loginlocal 8other 8

domain commandscreate 49delete 51list 52modify 53show 54

domain namessecure

allowed characters 308dynamic URL, reloading 130

Eeducation xiverror messages

display 54error, errors

handle 6handling 6return code 6

errtext command 54exists

object 68, 72

Ffind

access control list (ACL) 25protected object policy (POP) 93

Ggroup commands

group create 56group delete 57group import 58group list 59group modify 61group show 62

group namesdisallowed characters 309

gskcapicmd xiigskikm.jar xiiGSKit

documentation xiiGSO names

disallowed characters 311

HHTML document cache, flushing 120

IIBM

Software Support xivSupport Assistant xiv

iKeyman xiiimport

group 58user 200

interactive command mode 3, 4ivacld_setup

configuring authorization server 230ivacld_uninst

unconfiguring authorizationserver 232

ivbase_setupconfiguring runtime server 233

ivbase_uninstunconfiguring runtime 236

ivmgrd_setupconfiguring policy server 237

ivmgrd_uninstunconfiguring policy server 240

ivrgy_tool utility 242

JJMT 133junction mapping table

clearing 133loading 133reloading 140

junctioned serveradding 117adding virtual host junctions 168creating 121creating virtual host junctions 171removing 141, 184virtual host offline 180virtual host online 182virtual host throttle 188

junctioned serversdeleting 128deleting virtual host junctions 177listing details 143listing details of virtual host

junctions 186restarting 190synchronizing 191transferring contents 196

junctionsadding junctioned server 117adding virtual host junctions 168

junctions (continued)creating junctioned server 121creating virtual host junctions 171deleting junctioned server 128deleting virtual host junctions 177listing 134listing details, junctioned servers 143listing virtual host junction

details 186listing virtual host junctions 179offline operational state 135online operational state 137removing junctioned server 141removing server from virtual host

junction 184throttle operational state 164virtual host offline 180virtual host online 182virtual host throttle 188

Kkey xiikeys

creating, session managementserver 144

displaying details, sessionmanagement server 145

LLDAP server 242

on z/OS xiilimitations, characters

passwords 308user names 308

listaccess control list (ACL) 26actions 35domain commands 52group 59object 73objectspace command 83protected object policy (POP) 94server tasks 113servers 112

locale, localesnon-English 6

Mmgrsslcfg

change certificate 245change password 245configure 245modify 245

Microsoft Active Directory, disalloweddistinguished names 310

modifyaccess control list (ACL) 26config commands 44domain commands 53group 61object 75protected object policy (POP) 95rsrccred 106


modify (continued)rsrcgroup 110user 203

multiple command mode 3, 5

Oobject

listandshow 74object commands

object create 69object delete 71object exists 68, 72object list 73object listandshow 74object modify 75object show 77

object namecharacters 307characters allowed 307

object space commandsobjectspace create 81objectspace delete 82objectspace list 83

onlinepublications ixterminology ix

Ppasswords

character limitations 308general policies 307limitations 307

pd_start utility 252pdacld_config

configuring authorization server 248pdacld_unconfig

unconfiguring authorizationserver 250

pdadmincommand 1command option processing 9help 63login 65modes 3syntax 1utility 1

pdadmin utilitiesexit command line mode 55logout 67quit command line mode 55

pdadmin_host 251pdbackup utility 254pdconf

configuring 258pdconfig utility 260pdinfo utility (deprecated) 254pdjrtecfg

configuring Java runtimecomponent 261

pdmgr_configconfiguring policy server 267

pdmgr_unconfigunconfiguring policy server 270

pdproxycfg utility 272

pdrte_configconfiguring runtime 275

pdrte_unconfigunconfiguring runtime 278

pdservicelevel utility 266, 278pdsmsclicfg

configure 279pdversion utility 282pdweb 284pdweb utility 290pdwebpi 285pdwebpi_start 286pdwpi-version 287pdwpicfg utility 288policy commands

policy get 84policy set 86

policy server 237, 240multiple 251unconfigure 270

POPsdisallowed characters 313

problem-determination xivprotected object policies 313protected object policy 313protected object policy (POP) commands

pop attach 90pop create 91pop delete 92pop detach 92pop find 93pop list 94pop modify 95pop show 98

publicationsaccessing online ixlist of for this product ix

Rread 1reading 1realms

displaying details, sessionmanagement server 147

listing, session managementserver 146

replica setsdisplaying details, session

management server 152listing, session management

server 151replicate server 115resource commands

rsrc create 99rsrc delete 100rsrc list 101rsrc show 102rsrccred create 102rsrccred delete 104rsrccred list user 105rsrccred modify 106rsrccred show 107rsrcgroup create 108rsrcgroup delete 109rsrcgroup list 110rsrcgroup modify 110

resource commands (continued)rsrcgroup show 112

response files 315restore data

backing up 254extracting 254restoring 254

return codecommand

interactive 7multiple 8single command 7

rsrclist 101

rsrccredlist user 105

rsrcgrouplist 110

runtime 236

Sschema

update 242secure domain names

allowed characters 308Security Access Manager

configurationutilities 209

configuration utilities 209installation

utilities 209installation utilities 209migration

utilities 210migration utilities 210Plug-in for Web servers

utilities 211Plug-in for Web servers utilities 211Problem determination

utilities 212Problem determination utilities 212Serviceability

utilities 212Serviceability and problem

determination utilities 212Serviceability utilities 212Session management server

utilities 211Session management server

utilities 211utilities 209Web servers 211WebSEAL

utilities 211WebSEAL utilities 211

server commandsadmin show conf 36server list 112server listtasks 113server replicate 115server show 116server task add 117server task cache flush all 120server task cfgdb export 194server task cfgdb import 195server task create 121

Index 323

server commands (continued)server task delete 128server task dynurl update 130server task file cat 196server task help 131server task jdb export 192server task jdb import 193server task jmt 133server task list 134server task offline 135server task online 137server task refresh all_sessions 139server task reload 140server task remove 141server task server restart 190server task server sync 191server task show 143server task sms key change 144server task sms key show 145server task sms realm list 146server task sms realm show 147server task sms refresh

all_sessions 149server task sms refresh session 150server task sms replica set list 151server task sms replica set show 152server task sms session list 153server task sms trace get 157server task sms trace set 158server task stats 159server task terminate

all_sessions 154, 162server task terminate session 156,

163server task throttle 164server task trace 166server task virtualhost add 168server task virtualhost create 171server task virtualhost delete 177server task virtualhost list 179server task virtualhost offline 180server task virtualhost online 182server task virtualhost remove 184server task virtualhost show 186server task virtualhost throttle 188

server list command 112server listtasks command 113server replicate command 115server show command 116server task commands

add 117cache flush all 120cfgdb export 194cfgdb import 195create 121delete 128dynurl update 130file cat 196help 131jdb export 192jdb import 193jmt 133list 134offline 135online 137refresh all_sessions 139refresh session 150

server task commands (continued)reload 140remove 141server restart 190server sync 191show 143stats 159terminate all_sessions 154, 162terminate session 156, 163throttle 164trace command 166trace get 157trace set 158virtualhost add 168virtualhost create 171virtualhost delete 177virtualhost list 179virtualhost offline 180virtualhost online 182virtualhost remove 184virtualhost show 186virtualhost throttle 188

server task session commandsrefresh all sessions 149

server task sms key commandchange 144show 145

server task sms realm commandlist 146show 147

server task sms replica commandset list 151set show 152

server task sms session commandlist 153

session management servercreating keys 144displaying details, keys 145displaying details, replica sets 152displaying replica sets in realms 147listing realms 146listing replica sets 151listing sessions 153refreshing credentials 149, 150

sessionslisting, session management

server 153show

access control list (ACL) 30config commands 46context commands 48domain commands 54group 62object

show 77protected object policy (POP) 98rsrc 102rsrccred 107rsrcgroup 112server 116user 205

single command mode 3, 4smsbackup utility 291smscfg utility 293smsservicelevel utility 300special characters, allowed

secure domain names 308

special characters, disallowedACL policy names 312authorization rule names 312distinguished names 310group names 309GSO names 311POPs 313user names 309

stanza entriesdoAudit 213

statement 1statistics 159svrsslcfg

add replica 301change certificate 301change password 301change port 301change replica 301configure 301modify 301remove replica 301unconfigure 301

syntax 1

Tterminology ixTivoli Directory Integrator xiiTivoli Directory Server xiitrace level

displaying 157setting 158

trace, enabling 166training xivtroubleshooting xiv

UURL, reloading dynamic 130user

list 201user commands

user create 197user delete 199user import 200user list 201user modify 203user show 205

user namescharacter limitations 308disallowed characters 309

user sessionsterminating 156, 163terminating all 154, 162

utilitiesadschema_update 212amauditcfg 213amwebcfg 217amwpmcfg 221bassslcfg 226cdsso_key_gen 229ivacld_setup 230ivacld_uninst 232ivbase_setup 233ivbase_uninst 236ivmgrd_setup 237


utilities (continued)ivmgrd_uninst 240ivrgy_tool 242mgrsslcfg 245pd_start 252pdacld_config 248pdacld_unconfig 250pdbackup 254pdconf 258pdconfig 260pdinfo (deprecated) 254pdjrtecfg 261pdmgr_config 267pdmgr_unconfig 270pdproxycfg 272pdrte_config 275pdrte_unconfig 278pdservicelevel 266, 278pdsmsclicfg 279pdversion 282pdweb 284, 290pdwebpi 285pdwebpi_start 286pdwpi-version 287pdwpicfg 288smsbackup 291smscfg 293smsservicelevel 300svrsslcfg 301

WWeb Portal Manager

configure using amwpmcfg 221WebSphere Application Server Network

Deployment xiiWebSphere eXtreme Scale xii

Index 325

��

Printed in USA

SC23-6512-02

ibm securityaccess manager forweb version 7 · v ibm security access manager for web installation...

Documents